Fetch HTTP client API Documentation

@alt-stack/http-client-fetch binds the core client to the standard Fetch API and exposes native Response objects as result.raw.

pnpm add @alt-stack/http-client-fetch zod

Use a runtime with fetch, Response, Headers, and AbortController globals. In this repository that means Node.js 18 or newer; modern browsers and Bun also provide these APIs.

createApiClient

function createApiClient<
  TRequest extends ApiRequestSchema,
  TResponse extends ApiResponseSchema,
>(options: FetchClientOptions<TRequest, TResponse>): FetchApiClient<TRequest, TResponse>;

Creates a FetchExecutor, then constructs the core ApiClient. FetchApiClient<TRequest, TResponse> is an alias for ApiClient<TRequest, TResponse, Response>.

FetchClientOptions

Property	Type	Required
baseUrl	string	yes
Request	TRequest	yes
Response	TResponse	yes
headers	ApiClientOptions<TRequest, TResponse, Response>["headers"]	no
fetch	typeof globalThis.fetch	no
fetchOptions	FetchExecutorOptions["fetchOptions"]	no
onValidationError	ApiClientValidationErrorHandler<Response>	no
logger	Logger	no

See the core API for shared request, response, retry, validation, logging, and error behavior.

fetch supplies a transport for proxies, React Native polyfills, instrumentation, or tests. The same implementation is used on every attempt, including retries. When omitted, globalThis.fetch is resolved at execution time, so installing or replacing a polyfill after client construction works. The selected function is invoked as fetch(input, init) without binding it to the client, executor, or options object.

headers accepts a static record or a sync/async provider. Core evaluates a provider once per attempt before per-request headers overlay it. See the custom fetch and auth headers pattern.

FetchExecutor

class FetchExecutor implements HttpExecutor<Response> {
  constructor(options?: FetchExecutorOptions);
  execute(request: ExecuteRequest): Promise<ExecuteResponse<Response>>;
}

FetchExecutorOptions has two optional properties:

interface FetchExecutorOptions {
  fetch?: typeof globalThis.fetch;
  fetchOptions?: Omit<RequestInit, "method" | "headers" | "body" | "signal">;
}

The executor spreads fetchOptions first. It then owns method, headers, signal, and an optional body, so callers cannot override those fields through adapter-wide options. Useful forwarded options include credentials, cache, mode, redirect, referrer, and keepalive where the runtime supports them.

Response decoding

• Status 204 or 205, and content-length: 0, become undefined without reading the body.
• Other bodies are read once as text; a zero-length body becomes undefined.
• A nonempty body whose content type contains application/json is parsed as JSON; invalid JSON remains text for schema validation.
• Every other nonempty content type is returned as text. JSON null remains null.

The raw native Response is returned alongside decoded data. Because body readers consume the stream, callers should not assume result.raw.json() or .text() remains usable; headers, status, URL, and other metadata remain available.

Timeouts and errors

When ExecuteRequest.timeout is defined, the executor creates an AbortController and aborts after that many milliseconds. An AbortError becomes TimeoutError with the configured timeout (or zero when absent) and method. Every other thrown value becomes UnexpectedApiClientError with the fixed message Network request failed. Original exception fields, the original cause, and the request URL are discarded; they are unavailable programmatically and cannot enter error serialization or internal logs. The timer is cleared in finally.

A caller-supplied signal cannot be passed through fetchOptions; the executor reserves signal for timeout handling.

Exports

Adapter-specific exports are createApiClient, FetchClientOptions, FetchApiClient, FetchExecutor, and FetchExecutorOptions.

The package also re-exports all public core values and types: ApiClient, HTTP_CLIENT_DEBUG_NAMESPACE, ApiClientError, UnexpectedApiClientError, ValidationError, TimeoutError, ApiClientOptions, ApiClientValidationErrorLocation, ApiClientValidationErrorContext, ApiClientValidationErrorHandler, ApiRequestSchema, ApiResponseSchema, LogLevel, LogMeta, LogHandler, Logger, ApiClientLoggingOptions, HttpExecutor, ExecuteRequest, ExecuteResponse, ExtractPathParams, ExtractRequestParams, ExtractRequestQuery, ExtractRequestBody, ParamsRequired, BodyRequired, EndpointsWithMethod, RequestOptions, RetryContext, ExtractStatusCodes, ExtractSuccessCodes, ExtractErrorCodes, ExtractResponseSchema, ExtractSuccessBody, SuccessResponse, ErrorResponse, UnexpectedErrorResponse, and ApiResponse.