Skip to content
rhttp.io

Client Methods

HttpClientInstance is the object returned by createHttp(), createClientHttp(), and createServerHttp(). It exposes typed HTTP methods, cache control, observability, and lifecycle management.

HTTP methods

get

get<T = any>(url: string, options?: HttpRequestOptions): Promise<HttpResponse<T>>;

post

post<T = any>(url: string, body?: any, options?: HttpRequestOptions): Promise<HttpResponse<T>>;
post<B = any, T = any>(url: string, body: B, options?: HttpRequestOptions): Promise<HttpResponse<T>>;

put

put<T = any>(url: string, body?: any, options?: HttpRequestOptions): Promise<HttpResponse<T>>;
put<B = any, T = any>(url: string, body: B, options?: HttpRequestOptions): Promise<HttpResponse<T>>;

patch

patch<T = any>(url: string, body?: any, options?: HttpRequestOptions): Promise<HttpResponse<T>>;
patch<B = any, T = any>(url: string, body: B, options?: HttpRequestOptions): Promise<HttpResponse<T>>;

delete

delete<T = any>(url: string, options?: HttpRequestOptions): Promise<HttpResponse<T>>;
delete<B = any, T = any>(url: string, body: B, options?: HttpRequestOptions): Promise<HttpResponse<T>>;

customFetch

customFetch<T = any>(url: string, options?: RequestInit & HttpRequestOptions): Promise<HttpResponse<T>>;

A low-level escape hatch. Merges RequestInit with HttpRequestOptions for maximum flexibility (e.g., streaming, file uploads).

Batch requests

batchRequests

batchRequests<T extends ReadonlyArray<() => Promise<HttpResponse<any>>>>(
  requests: T,
): Promise<{
  -readonly [K in keyof T]: T[K] extends () => Promise<HttpResponse<infer R>> ? HttpResponse<R> : any
}>;

Runs an array of request functions in parallel via Promise.all, preserving the response types.

const [users, posts, stats] = await http.batchRequests([
  () => http.get<User[]>("/users"),
  () => http.get<Post[]>("/posts"),
  () => http.get<Stats>("/stats"),
]);

Cache control

invalidateCache

invalidateCache(urlPattern: string): void;

Removes all cache entries whose key contains the given pattern.

http.invalidateCache("/orders"); // removes all entries matching "/orders"

clearCache

clearCache(): void;

Clears the entire in-memory cache.

Observability

getMetrics

getMetrics(): HttpMetrics;

Returns a shallow copy of collected metrics.

const m = http.getMetrics();
// {
//   totalRequests: 42,
//   successfulRequests: 39,
//   failedRequests: 3,
//   durations: [45, 38, 52, ...],
//   statusCodes: { 200: 39, 500: 2, 503: 1 },
// }

getHistory

getHistory(): Array<{
  requestId: string;
  url: string;
  method: string;
  status: number;
  durationMs: number;
  timestamp: number;
}>;

Returns the request history ring buffer (default max size: 100).

Lifecycle & context

withRequest

withRequest<R>(request: any, callback: () => Promise<R> | R): Promise<R>;

Wraps the execution of callbacks within a request context (used for SSR cookie forwarding with async_hooks).

await http.withRequest(incomingRequest, async () => {
  const { data } = await http.get("/protected"); // cookies forwarded automatically
});

use

use(plugin: PluginConfig): void;

Registers a plugin at runtime. See PluginConfig.

Polling

poll

poll<T = any>(
  url: string,
  options?: HttpRequestOptions & { polling?: Partial<PollingConfig> },
): Promise<HttpResponse<T>>;

Polls a URL at a fixed interval until maxAttempts or a stopCondition is met.

const result = await http.poll("/jobs/123/status", {
  polling: {
    interval: 2_000,           // poll every 2s
    maxAttempts: 30,           // stop after 30 polls
    stopCondition: (data) => data.status === "completed", 
  },
});

Cancellation

cancel

cancel(requestId?: string): void;

Aborts in-flight requests. Without an argument, cancels all active requests and polling.

// Cancel a specific request.
http.cancel("req_abc123"); 
 
// Cancel everything.
http.cancel();

Circuit breaker

getCircuitBreakerStatus

getCircuitBreakerStatus(): {
  state: "closed" | "open" | "half-open";
  failures: number;
  successes: number;
};

resetCircuitBreaker

resetCircuitBreaker(): void;

getCircuitBreaker

getCircuitBreaker?(): any;

Returns the raw CircuitBreaker instance (optional — use when you need direct access to getStatus() with additional fields like rejectedCount and timeUntilHalfOpen).

Request pool

getPoolStats

getPoolStats?(): { activeRequests: number; queueLength: number };

Returns current pool statistics when requestPool.enabled is true.

Interceptors

interceptors.request / interceptors.response

interceptors: {
  request: InterceptorManager<HttpRequestOptions & { url: string; method: string; body?: any }>;
  response: InterceptorManager<HttpResponse<any>>;
};

See Interceptors in the Advanced Features guide.

Suggest changes to this page