$fetch

v0.0.1

Default $fetch instance backed by globalThis.fetch

Examples

const data = await $fetch<User>('https://api.example.com/users/1');

const user = await $fetch.post<User>('https://api.example.com/users', {
  body: { name: 'Alice' },
});

Signature

const $fetch: $Fetch<[]>

Related Types

ComposedPlugins

Flattened hook lists and merged defaults produced by composePlugins.

interface ComposedPlugins

Property	Type	Default	Description
`defaults`	`FetchOptions`	—	Merged defaults — plugin defaults first, then user defaults (user wins)
`hooks`readonly	`{ readonly onRequest: readonly FetchHook[] \| undefined; readonly onRequestError: readonly FetchHook[] \| undefined; readonly onResponse: readonly FetchHook[] \| undefined; readonly onResponseError: readonly FetchHook[] \| undefined; }`	—	Pre-flattened readonly hook arrays; undefined when no plugin contributed a phase
`execute`readonly	`FetchExecuteMiddleware \| undefined`	—	Pre-composed onion chain of plugin `execute` middlewares, or `undefined` when no plugin contributed one (fast path: caller invokes the core executor directly without constructing a `next` closure).

$Fetch

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

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

Property	Type	Default	Description
`native`	`Fetch`	—	Access to the underlying native fetch function

FetchOptions

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>

Property	Type	Default	Description
`baseURL`?	`string`	—	Base URL prepended to all relative request URLs
`body`?	`RequestInit['body'] \| object \| null`	—	Request body. `BodyInit` values (string, Blob, FormData, streams, …) are sent as-is; any other object or array is JSON-serialized. Typed as `object` rather than `Record<string, unknown>` so a named `interface` assigns directly — interfaces carry no implicit index signature and would otherwise force every caller to cast the body.
`ignoreResponseError`?	`boolean`	—	Suppress throwing on 4xx/5xx responses
`query`?	`Record<string, string \| number \| boolean \| null \| undefined>`	—	URL query parameters serialized and appended to the request URL
`params`?	`Record<string, string \| number \| boolean \| null \| undefined>`	—	—
`parseResponse`?	`(responseText: string) => T`	—	Custom response parser — overrides built-in JSON.parse
`responseType`?	`R`	—	Expected response format — drives body parsing
`duplex`?	`'half'`	—	Enable duplex streaming. Automatically set to "half" when a ReadableStream is used as body.
`timeout`?	`number`	—	Request timeout in milliseconds. Uses AbortSignal.timeout internally.
`retry`?	`number \| false`	—	Number of retry attempts on failure, or false to disable. Defaults to 1 for non-payload methods.
`retryDelay`?	`number \| ((context: FetchContext<T, R>) => number)`	—	Delay in milliseconds between retries, or a function receiving the context
`retryStatusCodes`?	`readonly number[]`	—	HTTP status codes that trigger a retry. Defaults to [408, 409, 425, 429, 500, 502, 503, 504].

ResolvedFetchOptions

FetchOptions after merging defaults — headers are always a Headers instance

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

Property	Type	Default	Description
`headers`	`Headers`	—	—

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>

Property	Type	Default	Description
`name`readonly	`Name`	—	Plugin identifier
`defaults`?readonly	`FetchOptions`	—	Default options contributed by the plugin — merged under user defaults
`hooks`?readonly	`FetchHooks`	—	Lifecycle hooks executed before any user per-request hooks
`execute`?readonly	`FetchExecuteMiddleware`	—	Onion-style middleware wrapping the fetch attempt + response parse. Plugins compose in registration order; calling `next()` invokes the next middleware or ultimately the core executor. May call `next()` multiple times (e.g. to implement retries).
`setup`?readonly	`(context: { readonly defaults: FetchOptions }) => void`	—	Invoked once per createFetch, after all plugin defaults are merged
`__types`?readonly	`{ options: OptionsExt; context: ContextExt }`	—	Phantom marker for type-only option/context extensions — never present at runtime. Populated via dummy field in `definePlugin` generics.

FetchContext

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

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

Property	Type	Default	Description
`request`	`FetchRequest`	—	—
`options`	`ResolvedFetchOptions<R, T>`	—	—
`response`?	`FetchResponse<T>`	—	—
`error`?	`Error`	—	—

FetchHooks

Lifecycle hooks for the fetch pipeline

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

Property	Type	Default	Description
`onRequest`?	`ReadonlyArrayable<FetchHook<FetchContext<T, R>>>`	—	Called before the request is sent
`onRequestError`?	`ReadonlyArrayable<FetchHook<FetchContext<T, R> & { error: Error }>>`	—	Called when the request itself throws (e.g. network error, timeout)
`onResponse`?	`ReadonlyArrayable<FetchHook<FetchContext<T, R> & { response: FetchResponse<T> }>>`	—	Called after a successful response is received and parsed
`onResponseError`?	`ReadonlyArrayable<FetchHook<FetchContext<T, R> & { response: FetchResponse<T> }>>`	—	Called when the response status is 4xx or 5xx

ResponseMap

Maps response type keys to their parsed value types

interface ResponseMap

Property	Type	Default	Description
`blob`	`Blob`	—	—
`text`	`string`	—	—
`arrayBuffer`	`ArrayBuffer`	—	—
`stream`	`ReadableStream<Uint8Array>`	—	—

FetchResponse

Extended Response with a parsed _data field

interface FetchResponse<T> extends Response

Property	Type	Default	Description
`_data`?	`T`	—	—

IFetchError

Shape of errors thrown by $fetch

interface IFetchError<T = unknown> extends Error

Property	Type	Default	Description
`request`?	`FetchRequest`	—	—
`options`?	`FetchErrorOptions`	—	—
`response`?	`FetchResponse<T>`	—	—
`data`?	`T`	—	—
`status`?	`number`	—	—
`statusText`?	`string`	—	—
`statusCode`?	`number`	—	—
`statusMessage`?	`string`	—	—

FetchExecuteMiddleware

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>;

MergePluginOptions

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]>>;

MergePluginContext

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]>>;

FetchHook

A function invoked at a specific point in the fetch lifecycle

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

ResponseType

Supported response body parsing modes

export type ResponseType = keyof ResponseMap | 'json';

MappedResponseType

Resolves the response value type from a ResponseType key

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

Fetch

The native fetch function signature

export type Fetch = typeof globalThis.fetch;

FetchRequest

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

export type FetchRequest = string | URL | Request;