@vobs/http

HTTP client for vobs with retry, timeout, in-flight dedupe, interceptors, pluggable transports, and signal-based cancellation.

Install

npm install @vobs/http

Quick start

import { createHTTPClient, HTTPError } from '@vobs/http'

const client = createHTTPClient({
  baseURL: '/api',
  timeout: 10_000,
  retry: 2,
  retryDelay: attempt => attempt * 500
})

const { data, status } = await client.get<{ id: number }>('/users/1', {
  params: { expand: 'profile' }
})

await client.post('/users', { name: 'Ada' })

try {
  await client.get('/private')
} catch (error) {
  if (error instanceof HTTPError) console.log(error.status, error.data)
}

Non-2xx responses throw HTTPError carrying status, data, and the request config. Requests exceeding timeout throw TimeoutError (code ETIMEDOUT) and are not retried. Other failures retry up to retry times when shouldRetry allows (default: 429 and 5xx), waiting retryDelay between attempts. Pass signal to cancel a request; dedupe: true shares one in-flight GET or HEAD per URL.

API

| Signature | Description | | --- | --- | | createHTTPClient(options?: HTTPClientOptions): HTTPClient | Defaults for baseURL, headers, timeout, retry, adapter, concurrency, and dedupe. | | client.get / delete / head(url, options?) | Body-less methods returning HTTPResponse<T>. | | client.post / put / patch(url, body?, options?) | FormData, Blob, and string bodies pass through; other values are JSON-encoded. | | client.request(options) | Full RequestOptions control, including params, responseType, and progress handlers. | | client.interceptors.request / response | use / eject / clear; request interceptors run in order, response interceptors in reverse. | | createConcurrencyLimiter(limit): ConcurrencyLimiter | Queue tasks behind a maximum parallel count. | | createFetchAdapter() / createXHRAdapter() / createAxiosAdapter(request?) / createMockAdapter(handler) | Swap the transport; the XHR adapter adds upload and download progress events. | | toResourceFetcher(request) | Adapt an HTTP request to the ResourceFetcher contract of @vobs/resource. | | httpPlugin(options?) | Provide the client as HTTP_KEY in a vobs app. | | createSSE(url, options?) | EventSource wrapper exposing source and close(). | | createWebSocket(url, options?) | WebSocket client with typed on() events and optional auto-reconnect. | | subscribeHTTPDebug(listener) / setHTTPDebugHooks(hooks) / getHTTPDebugHooks() | Observe request traces for DevTools; sensitive headers are redacted. |

Types

HTTPMethod, HTTPResponseType, HTTPHeaders, RetryDelay, HTTPProgress, HTTPProgressHandler, RequestOptions, RequestConfig, HTTPResponse, HTTPResourceRequest, HTTPAdapter, AxiosRequest, AxiosRequestConfigLike, AxiosResponseLike, HTTPClientOptions, HTTPClient, HTTPInterceptors, InterceptorManager, ConcurrencyLimiter, HTTPPluginOptions, HTTPDebugRequest, HTTPDebugStatus, HTTPDebugContext, HTTPDebugHooks, HTTPDebugCacheStatus, SSEClient, SSEConstructor, SSEOptions, WebSocketClient, WebSocketConstructor, WebSocketEventListener, WebSocketEventName, WebSocketOptions, WebSocketState