@askrjs/fetch

arrayBuffertype

arrayBuffer: () => Codec<ArrayBuffer>

Creates a codec that decodes any response body as an ArrayBuffer.

blobtype

blob: () => Codec<Blob>

Creates a codec that decodes any response body as a Blob.

ClientOptionstype

ClientOptions: any

Options controlling how a {@link createClient } or {@link createFetch } client makes requests.

baseUrl

baseUrl?: string;

fetch

Custom transport, defaulting to the global `fetch`.

headers

headers?: HeadersInit;

credentials

credentials?: RequestCredentials;

timeout

Request timeout in milliseconds.

middleware

Middleware chain applied to every request, in order.

Codectype

Codec: any

Describes how a request or response body is serialized/deserialized: which wire format (kind), which media types it matches, and optionally a {@link Validator} to parse/validate the decoded value.

kind

readonly kind: "json" | "text" | "urlEncoded" | "multipart" | "blob" | "arrayBuffer" | "stream" | "empty" | "content";

mediaTypes

readonly mediaTypes: readonly string[];

validator

readonly validator?: Validator<T>;

variants

For `kind: "content"`, the per-media-type codec variants.

contenttype

content: <T extends Record<string, Codec>>(variants: T) => Codec<{ [K in keyof T]: T[K] extends Codec<infer V> ? V : never; }[keyof T]>

Creates a content-negotiated codec that selects among variants by the response's media type, decoding with whichever variant matches.

createClienttype

createClient: <A extends ApiDefinition>(api: A, options?: ClientOptions) => ApiClient<A>

Builds a typed {@link ApiClient} from an {@link ApiDefinition}. Each endpoint becomes a method that fills in the path, query, header, and body parameters, executes the request via {@link createFetch}, and returns a {@link ClientResult}.

createFetchtype

createFetch: (options?: ClientOptions) => (call: AdHocCall) => Promise<FetchResult>

Creates a low-level fetch function that builds a Request from an {@link AdHocCall}, runs it through the configured middleware chain, and decodes the response with the matching codec. Used internally by {@link createClient}, and usable directly for requests without a full {@link EndpointDescriptor}.

defineApitype

defineApi: <E extends Record<string, AnyEndpointDescriptor | EndpointBuilder>>(endpoints: E, metadata?: ApiMetadata) => ApiDefinition<Defined<E>>

Finalizes a map of {@link EndpointBuilder}s and/or raw {@link EndpointDescriptor}s into a frozen {@link ApiDefinition}, stamping each endpoint's operationId from its key and deep-freezing its parameters, security, responses, and errors.

const api = defineApi({
  getUser: get("/users/{id}").returns(json()),
});

deltype

del: (path: string) => EndpointBuilder<undefined, undefined, undefined, undefined, {}, {}>

Starts building a DELETE endpoint at the given path.

emptytype

empty: () => Codec<undefined>

Creates a codec for bodies expected to be empty (e.g. 204 No Content), decoded as undefined.

FetchErrortype

FetchError: typeof FetchError

An Error thrown by {@link unwrap} that wraps a failed (non-ok) {@link FetchResult}.

result

readonly result: Exclude<FetchResult, { ok: true; }>;

FetchResulttype

FetchResult: SuccessResult<T> | HttpResult<T> | FailureResult

The outcome of a fetch call: success, an HTTP-level error, or another kind of failure.

gettype

get: (path: string) => EndpointBuilder<undefined, undefined, undefined, undefined, {}, {}>

Starts building a GET endpoint at the given path.

headtype

head: (path: string) => EndpointBuilder<undefined, undefined, undefined, undefined, {}, {}>

Starts building a HEAD endpoint at the given path.

jsontype

json: { <T = unknown>(): Codec<T>; <V extends Validator>(schema: V): Codec<InferValidator<V>>; }

Creates a JSON codec, matching application/json and +json suffixed media types. Creates a JSON codec that validates/parses the decoded value with the given schema.

Middlewaretype

Middleware: (context: RequestContext, next: Next) => Promise<FetchResult>

A function that can inspect/replace the request context and/or the result of calling next.

multiparttype

multipart: () => Codec<FormData>

Creates a codec for multipart/form-data bodies, decoded as FormData.

optionstype

options: (path: string) => EndpointBuilder<undefined, undefined, undefined, undefined, {}, {}>

Starts building an OPTIONS endpoint at the given path.

patchtype

patch: (path: string) => EndpointBuilder<undefined, undefined, undefined, undefined, {}, {}>

Starts building a PATCH endpoint at the given path.

posttype

post: (path: string) => EndpointBuilder<undefined, undefined, undefined, undefined, {}, {}>

Starts building a POST endpoint at the given path.

puttype

put: (path: string) => EndpointBuilder<undefined, undefined, undefined, undefined, {}, {}>

Starts building a PUT endpoint at the given path.

streamtype

stream: () => Codec<ReadableStream<Uint8Array>>

Creates a codec that exposes the raw response body as a ReadableStream, without buffering it.

texttype

text: () => Codec<string>

Creates a codec for plain text bodies (text/*), decoded as a string.

unwraptype

unwrap: <T>(result: FetchResult<T>) => T

Returns the data of a successful {@link FetchResult}, or throws a {@link FetchError} wrapping the result if it was not ok.

urlEncodedtype

urlEncoded: () => Codec<URLSearchParams>

Creates a codec for application/x-www-form-urlencoded bodies, decoded as URLSearchParams.

Validatortype

Validator: any

A minimal schema-validation contract, compatible with safeParse methods that report failures through either error or issues.

safeParse

safeParse(value: unknown): { readonly success: true; readonly data: T; } | { readonly success: false; readonly error: unknown; readonly issues?: unknown; } | { readonly success: false; readonly error?: unknown; readonly issues: unknown; };