joinURL

The main fetch interface with method shortcuts, raw access, and factory methods

interface $Fetch<Plugins extends readonly FetchPlugin[] = []>

Options for a fetch request, extending native RequestInit with additional features

interface FetchOptions<R extends ResponseType = 'json', T = unknown> extends Omit<RequestInit, 'body'>, FetchHooks<T, R>

FetchOptions after merging defaults — headers are always a Headers instance

interface ResolvedFetchOptions<R extends ResponseType = 'json', T = unknown> extends FetchOptions<R, T>

Global options for createFetch

interface CreateFetchOptions<Plugins extends readonly FetchPlugin[] = []>

A reusable bundle of defaults and lifecycle hooks that extends a fetch instance. Plugins are composed once at `createFetch` time — their defaults and hooks are flattened into the instance closure, so attaching plugins adds zero per-request overhead beyond the contributed hooks themselves.

interface FetchPlugin<Name extends string = string, OptionsExt = unknown, ContextExt = unknown>

Mutable context object passed to all hooks and the core fetch pipeline

interface FetchContext<T = unknown, R extends ResponseType = 'json'>

Lifecycle hooks for the fetch pipeline

interface FetchHooks<T = unknown, R extends ResponseType = 'json'>

Maps response type keys to their parsed value types

interface ResponseMap

Extended Response with a parsed `_data` field

interface FetchResponse<T> extends Response

Shape of errors thrown by $fetch

interface IFetchError<T = unknown> extends Error

Onion-style wrapper around a single fetch attempt. Invoking `next()` delegates to the next middleware in the chain or, at the innermost layer, performs the actual `fetch` call and response body parsing. `context.response` / `context.error` are populated by the time `next()` resolves. Middlewares may call `next()` zero, one, or many times (retries).

export type FetchExecuteMiddleware = (
  context: FetchContext,
  next: () => Promise<void>,
) => Promise<void>;

Intersection of all `OptionsExt` carried by a plugin tuple. Empty tuple resolves to `unknown`.

export type MergePluginOptions<Plugins extends readonly FetchPlugin[]>
  = [Plugins[number]] extends [never]
    ? unknown
    : UnionToIntersection<PluginOptionsOf<Plugins[number]>>;

Intersection of all `ContextExt` carried by a plugin tuple. Empty tuple resolves to `unknown`.

export type MergePluginContext<Plugins extends readonly FetchPlugin[]>
  = [Plugins[number]] extends [never]
    ? unknown
    : UnionToIntersection<PluginContextOf<Plugins[number]>>;

A function invoked at a specific point in the fetch lifecycle

export type FetchHook<C = FetchContext> = (context: C) => MaybePromise<void>;

Supported response body parsing modes

export type ResponseType = keyof ResponseMap | 'json';

Resolves the response value type from a ResponseType key

export type MappedResponseType<R extends ResponseType, T = unknown> = R extends keyof ResponseMap
  ? ResponseMap[R]
  : T;

Subset of FetchOptions stored on FetchError — strips lifecycle hooks, parseResponse, and retryDelay callback that are invariant in T/R

export type FetchErrorOptions = Omit<
  FetchOptions<ResponseType>,
  keyof FetchHooks | 'parseResponse' | 'retryDelay'
>;

The native fetch function signature

export type Fetch = typeof globalThis.fetch;

A fetch request — URL string, URL object, or Request object

export type FetchRequest = string | URL | Request;