Class Request

HTTP client with interceptors, timeout, retry, cache, deduplication, and download progress.

Basic usage

const api = new Request('https://api.example.com')

// Directly awaitable
const user = await api.get<User>('/users/1')

// Lifecycle callbacks
await api.get('/users', {
  onSuccess: setUsers,
  onError: toast.error,
  onFinally: () => setLoading(false),
})

Composable best practice

Prefer small focused instances over one instance with all interceptors:

// ── Building blocks (pure functions, reusable) ──
const addAuth: RequestInterceptor = (config) => ({
  ...config,
  headers: { ...config.headers, Authorization: `Bearer ${getToken()}` }
})
const addLang: RequestInterceptor = (config) => ({
  ...config,
  headers: { ...config.headers, 'Accept-Language': 'zh-CN' }
})

// ── Compose: each instance handles one concern ──
const authApi = new Request('https://api.example.com')
authApi.useRequestInterceptor(addAuth)
authApi.useRequestInterceptor(addLang)

const publicApi = new Request('https://open.api.com')

// ── Or use per-request interceptors ──
api.get('/users', {}, {
  requestInterceptors: [addAuth],
  onSuccess: setUsers,
})

Constructors

constructor

Properties

baseUrl cacheMap errorInterceptors inflightMap requestInterceptors responseInterceptors

Methods

buildBody buildCacheKey buildRequestInit buildUrl clearCache delete execute executeSSE executeWithRetry get isCompleteUrl joinUrl normalizeHeaders parseResponse parseSSEStream patch post put readResponseWithProgress removeInterceptor request runErrorInterceptors runRequestInterceptors runResponseInterceptors sse useErrorInterceptor useRequestInterceptor useResponseInterceptor

Constructors

constructor

Properties

Private Readonly baseUrl

baseUrl: string = ''

Private cacheMap

cacheMap: Map<string, CacheEntry> = ...

Private errorInterceptors

errorInterceptors: ErrorInterceptor[] = []

Private inflightMap

inflightMap: Map<string, Promise<unknown>> = ...

Private requestInterceptors

requestInterceptors: RequestInterceptor[] = []

Private responseInterceptors

responseInterceptors: ResponseInterceptor<any, any>[] = []

Methods

Private buildBody

  • buildBody(data): string | Blob | FormData | URLSearchParams

  • Parameters

    • data: unknown

    Returns string | Blob | FormData | URLSearchParams

Private buildCacheKey

  • buildCacheKey(method, url): string

  • Parameters

    • method: string
    • url: string

    Returns string

Private buildRequestInit

  • buildRequestInit(method, data, config, controller): RequestInit

  • Parameters

    • method: string
    • data: unknown
    • config: RequestInit
    • controller: AbortController

    Returns RequestInit

Private buildUrl

  • buildUrl(url, method, params?): string

  • Parameters

    • url: string
    • method: string
    • Optional params: Record<PropertyKey, any>

    Returns string

clearCache

  • clearCache(): void

  • Clear the in-memory response cache.

    Returns void

delete

Private execute

  • execute<T>(url, config, controller): Promise<T>

  • Type Parameters

    • T

    Parameters

    Returns Promise<T>

Private executeSSE

Private executeWithRetry

  • executeWithRetry<T>(requestUrl, method, data, requestConfig, controller, requestInterceptors, responseInterceptors, errorInterceptors, onDownloadProgress, timeout, maxRetries, retryDelayMs, cache, cacheKey): Promise<T>

  • Type Parameters

    • T

    Parameters

    • requestUrl: string
    • method: string
    • data: unknown
    • requestConfig: RequestInit
    • controller: AbortController
    • requestInterceptors: RequestInterceptor[]
    • responseInterceptors: ResponseInterceptor<any, any>[]
    • errorInterceptors: ErrorInterceptor[]
    • onDownloadProgress: undefined | ((loaded, total) => void)
    • timeout: undefined | number
    • maxRetries: number
    • retryDelayMs: number
    • cache: undefined | boolean | CacheConfig
    • cacheKey: string

    Returns Promise<T>

get

Private isCompleteUrl

  • isCompleteUrl(url): boolean

  • Parameters

    • url: string

    Returns boolean

Private joinUrl

  • joinUrl(baseUrl, url): string

  • Parameters

    • baseUrl: string
    • url: string

    Returns string

Private normalizeHeaders

  • normalizeHeaders(headers?): Record<string, string>

  • Parameters

    • Optional headers: HeadersInit

    Returns Record<string, string>

Private parseResponse

  • parseResponse(response): Promise<any>

  • Parameters

    • response: Response

    Returns Promise<any>

Private parseSSEStream

  • parseSSEStream(response, callbacks, controller): void

  • Parameters

    • response: Response
    • callbacks: SSECallbacks
    • controller: AbortController

    Returns void

patch

post

put

Private readResponseWithProgress

  • readResponseWithProgress(response, onProgress): Promise<unknown>

  • Parameters

    • response: Response
    • onProgress: ((loaded, total) => void)
        • (loaded, total): void

        • Parameters

          • loaded: number
          • total: number

          Returns void

    Returns Promise<unknown>

Private removeInterceptor

  • removeInterceptor<T>(interceptors, interceptor): void

  • Type Parameters

    • T

    Parameters

    • interceptors: T[]
    • interceptor: T

    Returns void

request

Private runErrorInterceptors

Private runRequestInterceptors

  • runRequestInterceptors(config, interceptors): Promise<RequestInit>

  • Parameters

    Returns Promise<RequestInit>

Private runResponseInterceptors

sse

  • sse<T>(url, config?): RequestHandle<T>

  • Create an SSE (Server-Sent Events) connection.

    Uses Fetch API under the hood, so it supports:

    • Custom headers (unlike native EventSource)
    • POST requests
    • All HTTP methods

    Type Parameters

    • T = unknown

    Parameters

    Returns RequestHandle<T>

    Example

    const api = new Request('https://api.example.com')

    // GET SSE (default)
    const handle = api.sse('/events', {
      onMessage: (event) => console.log(event.data),
      onError: (err) => console.error(err),
    })

    // POST SSE with data
    const handle = api.sse('/chat/completions', {
      method: 'POST',
      data: { prompt: 'Hello' },
      onMessage: (event) => {
        const parsed = JSON.parse(event.data)
        console.log(parsed)
      },
    })

    // Cancel the connection
    handle.abort()
    ```n

useErrorInterceptor

useRequestInterceptor

useResponseInterceptor

  • useResponseInterceptor<T, U>(interceptor): (() => void)

  • Type Parameters

    • T = unknown
    • U = unknown

    Parameters

    Returns (() => void)

      • (): void

      • Returns void

Settings

Member Visibility

Theme

On This Page

constructorbaseUrlcacheMaperrorInterceptorsinflightMaprequestInterceptorsresponseInterceptorsbuildBodybuildCacheKeybuildRequestInitbuildUrlclearCachedeleteexecuteexecuteSSEexecuteWithRetrygetisCompleteUrljoinUrlnormalizeHeadersparseResponseparseSSEStreampatchpostputreadResponseWithProgressremoveInterceptorrequestrunErrorInterceptorsrunRequestInterceptorsrunResponseInterceptorssseuseErrorInterceptoruseRequestInterceptoruseResponseInterceptor