@zimic/fetch 0.1.0-canary.2 → 0.1.0-canary.21

package/dist/index.d.ts

@@ -1,12 +1,13 @@
-import { HttpSchema, HttpSchemaPath, HttpSchemaMethod, HttpMethod, HttpSearchParams, HttpMethodSchema, HttpRequest, HttpRequestHeadersSchema, AllowAnyStringInPathParams, LiteralHttpSchemaPathFromNonLiteral, HttpRequestSchema, HttpStatusCode, HttpResponse, HttpResponseBodySchema, HttpResponseHeadersSchema, HttpHeaders, JSONValue, HttpResponseSchemaStatusCode } from '@zimic/http';
-
-type Default<Type, IfEmpty = never> = [undefined | void] extends [Type] ? IfEmpty : Exclude<Type, undefined | void>;
-type DefaultNoExclude<Type, IfEmpty = never> = [undefined | void] extends Type ? IfEmpty : Type;
-type IfNever<Type, Yes, No = Type> = [Type] extends [never] ? Yes : No;
-type PossiblePromise<Type> = Type | PromiseLike<Type>;
-type ReplaceBy<Type, Source, Target> = Type extends Source ? Target : Type;
+import { HttpSchema, HttpSchemaMethod, HttpSchemaPath, HttpRequestSchema, HttpHeaders, HttpSearchParams, JSONValue, HttpMethod, HttpHeadersSchema, HttpSearchParamsSchema, HttpMethodSchema, HttpStatusCode, HttpResponseSchemaStatusCode, HttpResponse, HttpResponseBodySchema, HttpResponseHeadersSchema, HttpRequest, HttpRequestHeadersSchema, AllowAnyStringInPathParams, LiteralHttpSchemaPathFromNonLiteral } from '@zimic/http';
 
 declare const value: unique symbol;
+/**
+ * Represents a value stringified by `JSON.stringify`, maintaining a reference to the original type.
+ *
+ * This type is used to validate that the expected stringified body is passed to `fetch`.
+ *
+ * @see {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐fetch#using-a-json-body}
+ */
 type JSONStringified<Value> = string & {
     [value]: Value;
 };
@@ -16,101 +17,927 @@ declare global {
     }
 }
 
+type Default<Type, IfEmpty = never> = [undefined | void] extends [Type] ? IfEmpty : Exclude<Type, undefined | void>;
+type DefaultNoExclude<Type, IfEmpty = never> = [undefined | void] extends Type ? IfEmpty : Type;
+type IfNever<Type, Yes, No = Type> = [Type] extends [never] ? Yes : No;
+type PossiblePromise<Type> = Type | PromiseLike<Type>;
+type ReplaceBy<Type, Source, Target> = Type extends Source ? Target : Type;
+type RequiredByKey<Type, Key extends keyof Type> = Omit<Type, Key> & Required<Pick<Type, Key>>;
+
+type FetchRequestInitHeaders<RequestSchema extends HttpRequestSchema> = RequestSchema['headers'] | HttpHeaders<Default<RequestSchema['headers']>>;
 type FetchRequestInitWithHeaders<RequestSchema extends HttpRequestSchema> = [RequestSchema['headers']] extends [never] ? {
     headers?: undefined;
 } : undefined extends RequestSchema['headers'] ? {
-    headers?: RequestSchema['headers'] | HttpHeaders<Default<RequestSchema['headers']>>;
+    headers?: FetchRequestInitHeaders<RequestSchema>;
 } : {
-    headers: RequestSchema['headers'] | HttpHeaders<Default<RequestSchema['headers']>>;
+    headers: FetchRequestInitHeaders<RequestSchema>;
 };
+type FetchRequestInitSearchParams<RequestSchema extends HttpRequestSchema> = RequestSchema['searchParams'] | HttpSearchParams<Default<RequestSchema['searchParams']>>;
 type FetchRequestInitWithSearchParams<RequestSchema extends HttpRequestSchema> = [
     RequestSchema['searchParams']
 ] extends [never] ? {
     searchParams?: undefined;
 } : undefined extends RequestSchema['searchParams'] ? {
-    searchParams?: RequestSchema['searchParams'] | HttpSearchParams<Default<RequestSchema['searchParams']>>;
+    searchParams?: FetchRequestInitSearchParams<RequestSchema>;
 } : {
-    searchParams: RequestSchema['searchParams'] | HttpSearchParams<Default<RequestSchema['searchParams']>>;
+    searchParams: FetchRequestInitSearchParams<RequestSchema>;
 };
 type FetchRequestInitWithBody<RequestSchema extends HttpRequestSchema> = [RequestSchema['body']] extends [never] ? {
     body?: null;
-} : undefined extends RequestSchema['body'] ? {
+} : RequestSchema['body'] extends string ? undefined extends RequestSchema['body'] ? {
     body?: ReplaceBy<RequestSchema['body'], undefined, null>;
-} : RequestSchema['body'] extends string ? {
+} : {
     body: RequestSchema['body'];
-} : RequestSchema['body'] extends JSONValue ? {
+} : RequestSchema['body'] extends JSONValue ? undefined extends RequestSchema['body'] ? {
+    body?: JSONStringified<ReplaceBy<RequestSchema['body'], undefined, null>>;
+} : {
     body: JSONStringified<RequestSchema['body']>;
+} : undefined extends RequestSchema['body'] ? {
+    body?: ReplaceBy<RequestSchema['body'], undefined, null>;
 } : {
     body: RequestSchema['body'];
 };
 type FetchRequestInitPerPath<RequestSchema extends HttpRequestSchema> = FetchRequestInitWithHeaders<RequestSchema> & FetchRequestInitWithSearchParams<RequestSchema> & FetchRequestInitWithBody<RequestSchema>;
-type FetchRequestInit<Schema extends HttpSchema, Path extends HttpSchemaPath<Schema, Method>, Method extends HttpSchemaMethod<Schema>> = RequestInit & {
-    baseURL?: string;
+/**
+ * The options to create a {@link FetchRequest} instance, compatible with
+ * {@link https://developer.mozilla.org/docs/Web/API/RequestInit `RequestInit`}.
+ *
+ * @see {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐fetch#fetch `fetch` API reference}
+ * @see {@link https://developer.mozilla.org/docs/Web/API/RequestInit `RequestInit`}
+ */
+type FetchRequestInit<Schema extends HttpSchema, Method extends HttpSchemaMethod<Schema>, Path extends HttpSchemaPath<Schema, Method>, Redirect extends RequestRedirect = 'follow'> = Omit<RequestInit, 'method' | 'headers' | 'body'> & {
+    /** The HTTP method of the request. */
     method: Method;
+    /** The base URL to prefix the path of the request. */
+    baseURL?: string;
+    redirect?: Redirect;
 } & (Path extends Path ? FetchRequestInitPerPath<Default<Default<Schema[Path][Method]>['request']>> : never);
 declare namespace FetchRequestInit {
-    interface Defaults extends RequestInit {
+    /** The default options for each request sent by a fetch instance. */
+    interface Defaults extends Omit<RequestInit, 'headers'> {
         baseURL: string;
+        /** The HTTP method of the request. */
         method?: HttpMethod;
-        searchParams?: HttpSearchParams;
+        /** The headers of the request. */
+        headers?: HttpHeadersSchema;
+        /** The search parameters of the request. */
+        searchParams?: HttpSearchParamsSchema;
     }
+    /** A loosely typed version of {@link FetchRequestInit `FetchRequestInit`}. */
+    type Loose = Partial<Defaults>;
 }
 type AllFetchResponseStatusCode<MethodSchema extends HttpMethodSchema> = HttpResponseSchemaStatusCode<Default<MethodSchema['response']>>;
-type FetchResponseStatusCode<MethodSchema extends HttpMethodSchema, ErrorOnly extends boolean> = ErrorOnly extends true ? AllFetchResponseStatusCode<MethodSchema> & (HttpStatusCode.ClientError | HttpStatusCode.ServerError) : AllFetchResponseStatusCode<MethodSchema>;
+type FilterFetchResponseStatusCodeByError<StatusCode extends HttpStatusCode, ErrorOnly extends boolean> = ErrorOnly extends true ? Extract<StatusCode, HttpStatusCode.ClientError | HttpStatusCode.ServerError> : StatusCode;
+type FilterFetchResponseStatusCodeByRedirect<StatusCode extends HttpStatusCode, Redirect extends RequestRedirect> = Redirect extends 'error' ? FilterFetchResponseStatusCodeByRedirect<StatusCode, 'follow'> : Redirect extends 'follow' ? Exclude<StatusCode, Exclude<HttpStatusCode.Redirection, 304>> : StatusCode;
+type FetchResponseStatusCode<MethodSchema extends HttpMethodSchema, ErrorOnly extends boolean, Redirect extends RequestRedirect> = FilterFetchResponseStatusCodeByRedirect<FilterFetchResponseStatusCodeByError<AllFetchResponseStatusCode<MethodSchema>, ErrorOnly>, Redirect>;
 type HttpRequestBodySchema<MethodSchema extends HttpMethodSchema> = ReplaceBy<ReplaceBy<IfNever<DefaultNoExclude<Default<MethodSchema['request']>['body']>, null>, undefined, null>, ArrayBuffer, Blob>;
-interface FetchRequest<Path extends string = string, Method extends HttpMethod = HttpMethod, MethodSchema extends HttpMethodSchema = HttpMethodSchema> extends HttpRequest<HttpRequestBodySchema<MethodSchema>, HttpRequestHeadersSchema<MethodSchema>> {
+/**
+ * A request instance typed with an HTTP schema, closely compatible with the
+ * {@link https://developer.mozilla.org/docs/Web/API/Request native Request class}.
+ *
+ * On top of the properties available in native {@link https://developer.mozilla.org/docs/Web/API/Request `Request`}
+ * instances, fetch requests have their URL automatically prefixed with the base URL of their fetch instance. Default
+ * options are also applied, if present in the fetch instance.
+ *
+ * The path of the request is extracted from the URL, excluding the base URL, and is available in the `path` property.
+ *
+ * @example
+ *   import { type HttpSchema } from '@zimic/http';
+ *   import { createFetch } from '@zimic/fetch';
+ *
+ *   interface User {
+ *     id: string;
+ *     username: string;
+ *   }
+ *
+ *   type Schema = HttpSchema<{
+ *     '/users': {
+ *       POST: {
+ *         request: {
+ *           headers: { 'content-type': 'application/json' };
+ *           body: { username: string };
+ *         };
+ *         response: {
+ *           201: { body: User };
+ *         };
+ *       };
+ *     };
+ *   }>;
+ *
+ *   const fetch = createFetch<Schema>({
+ *     baseURL: 'http://localhost:3000',
+ *   });
+ *
+ *   const request = new fetch.Request('/users', {
+ *     method: 'POST',
+ *     headers: { 'content-type': 'application/json' },
+ *     body: JSON.stringify({ username: 'me' }),
+ *   });
+ *
+ *   console.log(request); // FetchRequest<Schema, 'POST', '/users'>
+ *   console.log(request.path); // '/users'
+ *
+ * @see {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐fetch#fetchrequest `FetchRequest` API reference}
+ * @see {@link https://developer.mozilla.org/docs/Web/API/Request}
+ */
+interface FetchRequest<Schema extends HttpSchema, Method extends HttpSchemaMethod<Schema>, Path extends HttpSchemaPath.Literal<Schema, Method>> extends HttpRequest<HttpRequestBodySchema<Default<Schema[Path][Method]>>, HttpRequestHeadersSchema<Default<Schema[Path][Method]>>> {
+    /** The path of the request, excluding the base URL. */
     path: AllowAnyStringInPathParams<Path>;
+    /** The HTTP method of the request. */
     method: Method;
 }
 declare namespace FetchRequest {
+    /** A loosely typed version of {@link FetchRequest `FetchRequest`}. */
     interface Loose extends Request {
+        /** The path of the request, excluding the base URL. */
         path: string;
+        /** The HTTP method of the request. */
         method: HttpMethod;
+        /** Clones the request instance, returning a new instance with the same properties. */
         clone: () => Loose;
     }
 }
-interface FetchResponsePerStatusCode<Path extends string = string, Method extends HttpMethod = HttpMethod, MethodSchema extends HttpMethodSchema = HttpMethodSchema, StatusCode extends HttpStatusCode = HttpStatusCode> extends HttpResponse<HttpResponseBodySchema<MethodSchema, StatusCode>, StatusCode, HttpResponseHeadersSchema<MethodSchema, StatusCode>> {
-    request: FetchRequest<Path, Method, MethodSchema>;
-    error: StatusCode extends HttpStatusCode.ClientError | HttpStatusCode.ServerError ? FetchResponseError<Path, Method, MethodSchema> : null;
+interface FetchResponsePerStatusCode<Schema extends HttpSchema, Method extends HttpSchemaMethod<Schema>, Path extends HttpSchemaPath.Literal<Schema, Method>, StatusCode extends HttpStatusCode = HttpStatusCode> extends HttpResponse<HttpResponseBodySchema<Default<Schema[Path][Method]>, StatusCode>, StatusCode, HttpResponseHeadersSchema<Default<Schema[Path][Method]>, StatusCode>> {
+    /** The request that originated the response. */
+    request: FetchRequest<Schema, Method, Path>;
+    /**
+     * An error representing a response with a failure status code (4XX or 5XX). It can be thrown to handle the error
+     * upper in the call stack.
+     *
+     * If the response has a success status code (1XX, 2XX or 3XX), this property will be null.
+     */
+    error: StatusCode extends HttpStatusCode.ClientError | HttpStatusCode.ServerError ? FetchResponseError<Schema, Method, Path> : null;
 }
-type FetchResponse<Path extends string = string, Method extends HttpMethod = HttpMethod, MethodSchema extends HttpMethodSchema = HttpMethodSchema, ErrorOnly extends boolean = false, StatusCode extends FetchResponseStatusCode<MethodSchema, ErrorOnly> = FetchResponseStatusCode<MethodSchema, ErrorOnly>> = StatusCode extends StatusCode ? FetchResponsePerStatusCode<Path, Method, MethodSchema, StatusCode> : never;
+/**
+ * A response instance typed with an HTTP schema, closely compatible with the
+ * {@link https://developer.mozilla.org/docs/Web/API/Response native Response class}.
+ *
+ * On top of the properties available in native Response instances, fetch responses have a reference to the request that
+ * originated them, available in the `request` property.
+ *
+ * If the response has a failure status code (4XX or 5XX), an error is available in the `error` property.
+ *
+ * @example
+ *   import { type HttpSchema } from '@zimic/http';
+ *   import { createFetch } from '@zimic/fetch';
+ *
+ *   interface User {
+ *     id: string;
+ *     username: string;
+ *   }
+ *
+ *   type Schema = HttpSchema<{
+ *     '/users/:userId': {
+ *       GET: {
+ *         response: {
+ *           200: { body: User };
+ *           404: { body: { message: string } };
+ *         };
+ *       };
+ *     };
+ *   }>;
+ *
+ *   const fetch = createFetch<Schema>({
+ *     baseURL: 'http://localhost:3000',
+ *   });
+ *
+ *   const response = await fetch(`/users/${userId}`, {
+ *     method: 'GET',
+ *   });
+ *
+ *   console.log(response); // FetchResponse<Schema, 'GET', '/users'>
+ *
+ *   if (response.status === 404) {
+ *     const errorBody = await response.json(); // { message: string }
+ *     console.error(errorBody.message);
+ *     return null;
+ *   } else {
+ *     const user = await response.json(); // User
+ *     return user;
+ *   }
+ *
+ * @see {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐fetch#fetchresponse `FetchResponse` API reference}
+ * @see {@link https://developer.mozilla.org/docs/Web/API/Response}
+ */
+type FetchResponse<Schema extends HttpSchema, Method extends HttpSchemaMethod<Schema>, Path extends HttpSchemaPath.Literal<Schema, Method>, ErrorOnly extends boolean = false, Redirect extends RequestRedirect = 'follow', StatusCode extends FetchResponseStatusCode<Default<Schema[Path][Method]>, ErrorOnly, Redirect> = FetchResponseStatusCode<Default<Schema[Path][Method]>, ErrorOnly, Redirect>> = StatusCode extends StatusCode ? FetchResponsePerStatusCode<Schema, Method, Path, StatusCode> : never;
 declare namespace FetchResponse {
+    /** A loosely typed version of {@link FetchResponse}. */
     interface Loose extends Response {
+        /** The request that originated the response. */
         request: FetchRequest.Loose;
+        /**
+         * An error representing a response with a failure status code (4XX or 5XX). It can be thrown to handle the error
+         * upper in the call stack.
+         *
+         * If the response has a success status code (1XX, 2XX or 3XX), this property will be null.
+         */
         error: AnyFetchRequestError | null;
+        /** Clones the request instance, returning a new instance with the same properties. */
         clone: () => Loose;
     }
 }
-type FetchRequestConstructor<Schema extends HttpSchema> = new <Path extends HttpSchemaPath.NonLiteral<Schema, Method>, Method extends HttpSchemaMethod<Schema>>(input: FetchInput<Schema, Path, Method>, init: FetchRequestInit<Schema, LiteralHttpSchemaPathFromNonLiteral<Schema, Method, Path>, Method>) => FetchRequest<LiteralHttpSchemaPathFromNonLiteral<Schema, Method, Path>, Method, Default<Schema[LiteralHttpSchemaPathFromNonLiteral<Schema, Method, Path>][Method]>>;
+/**
+ * A constructor for {@link FetchRequest} instances, typed with an HTTP schema and compatible with the
+ * {@link https://developer.mozilla.org/docs/Web/API/Request Request class constructor}.
+ *
+ * @example
+ *   import { type HttpSchema } from '@zimic/http';
+ *   import { createFetch } from '@zimic/fetch';
+ *
+ *   type Schema = HttpSchema<{
+ *     // ...
+ *   }>;
+ *
+ *   const fetch = createFetch<Schema>({
+ *     baseURL: 'http://localhost:3000',
+ *   });
+ *
+ *   const request = new fetch.Request('POST', '/users', {
+ *     body: JSON.stringify({ username: 'me' }),
+ *   });
+ *   console.log(request); // FetchRequest<Schema, 'POST', '/users'>
+ *
+ * @param input The resource to fetch, either a path, a URL, or a {@link FetchRequest request}. If a path is provided, it
+ *   is automatically prefixed with the base URL of the fetch instance when the request is sent. If a URL or a request
+ *   is provided, it is used as is.
+ * @param init The request options. If a path or a URL is provided as the first argument, this argument is required and
+ *   should contain at least the method of the request. If the first argument is a {@link FetchRequest request}, this
+ *   argument is optional.
+ * @returns A promise that resolves to the response to the request.
+ * @see {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐fetch#fetchresponse `FetchResponse` API reference}
+ * @see {@link https://developer.mozilla.org/docs/Web/API/Request}
+ */
+type FetchRequestConstructor<Schema extends HttpSchema> = new <Method extends HttpSchemaMethod<Schema>, Path extends HttpSchemaPath.NonLiteral<Schema, Method>>(input: FetchInput<Schema, Method, Path>, init: FetchRequestInit<Schema, Method, LiteralHttpSchemaPathFromNonLiteral<Schema, Method, Path>>) => FetchRequest<Schema, Method, LiteralHttpSchemaPathFromNonLiteral<Schema, Method, Path>>;
 
-declare class FetchResponseError<Path extends string = string, Method extends HttpMethod = HttpMethod, MethodSchema extends HttpMethodSchema = HttpMethodSchema> extends Error {
-    request: FetchRequest<Path, Method, MethodSchema>;
-    response: FetchResponse<Path, Method, MethodSchema, true>;
-    constructor(request: FetchRequest<Path, Method, MethodSchema>, response: FetchResponse<Path, Method, MethodSchema, true>);
-    get cause(): FetchResponse<Path, Method, MethodSchema, true>;
+/**
+ * An error representing a response with a failure status code (4XX or 5XX).
+ *
+ * @example
+ *   import { type HttpSchema } from '@zimic/http';
+ *   import { createFetch } from '@zimic/fetch';
+ *
+ *   interface User {
+ *     id: string;
+ *     username: string;
+ *   }
+ *
+ *   type Schema = HttpSchema<{
+ *     '/users/:userId': {
+ *       GET: {
+ *         response: {
+ *           200: { body: User };
+ *           404: { body: { message: string } };
+ *         };
+ *       };
+ *     };
+ *   }>;
+ *
+ *   const fetch = createFetch<Schema>({
+ *     baseURL: 'http://localhost:3000',
+ *   });
+ *
+ *   const response = await fetch(`/users/${userId}`, {
+ *     method: 'GET',
+ *   });
+ *
+ *   if (!response.ok) {
+ *     console.log(response.status); // 404
+ *
+ *     console.log(response.error); // FetchResponseError<Schema, 'GET', '/users'>
+ *     console.log(response.error.request); // FetchRequest<Schema, 'GET', '/users'>
+ *     console.log(response.error.response); // FetchResponse<Schema, 'GET', '/users'>
+ *   }
+ *
+ * @see {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐fetch#fetchresponseerror `FetchResponseError` API reference}
+ */
+declare class FetchResponseError<Schema extends HttpSchema, Method extends HttpSchemaMethod<Schema>, Path extends HttpSchemaPath.Literal<Schema, Method>> extends Error {
+    request: FetchRequest<Schema, Method, Path>;
+    response: FetchResponse<Schema, Method, Path, true, 'manual'>;
+    constructor(request: FetchRequest<Schema, Method, Path>, response: FetchResponse<Schema, Method, Path, true, 'manual'>);
+    get cause(): FetchResponse<Schema, Method, Path, true, "manual">;
 }
 type AnyFetchRequestError = FetchResponseError<any, any, any>;
 
-type FetchInput<Schema extends HttpSchema, Path extends HttpSchemaPath.NonLiteral<Schema, Method>, Method extends HttpSchemaMethod<Schema>> = Path | URL | FetchRequest<LiteralHttpSchemaPathFromNonLiteral<Schema, Method, Path>, Method, Default<Schema[LiteralHttpSchemaPathFromNonLiteral<Schema, Method, Path>][Method]>>;
+/**
+ * The input to fetch a resource, either a path, a URL, or a {@link FetchRequest request}.
+ *
+ * @see {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐fetch#fetch `fetch` API reference}
+ */
+type FetchInput<Schema extends HttpSchema, Method extends HttpSchemaMethod<Schema>, Path extends HttpSchemaPath.NonLiteral<Schema, Method>> = Path | URL | FetchRequest<Schema, Method, LiteralHttpSchemaPathFromNonLiteral<Schema, Method, Path>>;
 interface FetchFunction<Schema extends HttpSchema> {
-    <Path extends HttpSchemaPath.NonLiteral<Schema, Method>, Method extends HttpSchemaMethod<Schema>>(input: Path | URL, init: FetchRequestInit<Schema, LiteralHttpSchemaPathFromNonLiteral<Schema, Method, Path>, Method>): Promise<FetchResponse<LiteralHttpSchemaPathFromNonLiteral<Schema, Method, Path>, Method, Default<Schema[LiteralHttpSchemaPathFromNonLiteral<Schema, Method, Path>][Method]>>>;
-    <Path extends HttpSchemaPath.NonLiteral<Schema, Method>, Method extends HttpSchemaMethod<Schema>>(input: FetchRequest<LiteralHttpSchemaPathFromNonLiteral<Schema, Method, Path>, Method, Default<Schema[LiteralHttpSchemaPathFromNonLiteral<Schema, Method, Path>][Method]>>, init?: FetchRequestInit<Schema, LiteralHttpSchemaPathFromNonLiteral<Schema, Method, Path>, Method>): Promise<FetchResponse<LiteralHttpSchemaPathFromNonLiteral<Schema, Method, Path>, Method, Default<Schema[LiteralHttpSchemaPathFromNonLiteral<Schema, Method, Path>][Method]>>>;
+    <Method extends HttpSchemaMethod<Schema>, Path extends HttpSchemaPath.NonLiteral<Schema, Method>, Redirect extends RequestRedirect = 'follow'>(input: Path | URL, init: FetchRequestInit<Schema, Method, LiteralHttpSchemaPathFromNonLiteral<Schema, Method, Path>, Redirect>): Promise<FetchResponse<Schema, Method, LiteralHttpSchemaPathFromNonLiteral<Schema, Method, Path>, false, Redirect>>;
+    <Method extends HttpSchemaMethod<Schema>, Path extends HttpSchemaPath.NonLiteral<Schema, Method>, Redirect extends RequestRedirect = 'follow'>(input: FetchRequest<Schema, Method, LiteralHttpSchemaPathFromNonLiteral<Schema, Method, Path>>, init?: FetchRequestInit<Schema, Method, LiteralHttpSchemaPathFromNonLiteral<Schema, Method, Path>, Redirect>): Promise<FetchResponse<Schema, Method, LiteralHttpSchemaPathFromNonLiteral<Schema, Method, Path>, false, Redirect>>;
+}
+declare namespace FetchFunction {
+    type Loose = (input: string | URL | FetchRequest.Loose, init?: FetchRequestInit.Loose) => Promise<FetchResponse.Loose>;
 }
+/**
+ * The options to create a {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐fetch#fetch fetch instance}.
+ *
+ * @see {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐fetch#createfetch `createFetch(options)` API reference}
+ */
 interface FetchOptions<Schema extends HttpSchema> extends Omit<FetchRequestInit.Defaults, 'method'> {
-    onRequest?: (request: FetchRequest.Loose, fetch: Fetch<Schema>) => PossiblePromise<Request>;
-    onResponse?: (response: FetchResponse.Loose, fetch: Fetch<Schema>) => PossiblePromise<Response>;
+    /**
+     * A listener function that is called for each request. It can modify the requests before they are sent.
+     *
+     * @example
+     *   import { createFetch } from '@zimic/fetch';
+     *   import { type HttpSchema } from '@zimic/http';
+     *
+     *   interface User {
+     *     id: string;
+     *     username: string;
+     *   }
+     *
+     *   type Schema = HttpSchema<{
+     *     '/users': {
+     *       GET: {
+     *         request: {
+     *           searchParams: { page?: number; limit?: number };
+     *         };
+     *         response: {
+     *           200: { body: User[] };
+     *         };
+     *       };
+     *     };
+     *   }>;
+     *
+     *   const fetch = createFetch<Schema>({
+     *     baseURL: 'http://localhost:80',
+     *
+     *     onRequest(request) {
+     *       if (this.isRequest(request, 'GET', '/users')) {
+     *         const url = new URL(request.url);
+     *         url.searchParams.append('limit', '10');
+     *
+     *         const updatedRequest = new Request(url, request);
+     *         return updatedRequest;
+     *       }
+     *
+     *       return request;
+     *     },
+     *   });
+     *
+     * @param request The original request.
+     * @returns The request to be sent. It can be the original request or a modified version of it.
+     * @this {Fetch<Schema>} The fetch instance that is sending the request.
+     */
+    onRequest?: (this: Fetch<Schema>, request: FetchRequest.Loose) => PossiblePromise<Request>;
+    /**
+     * A listener function that is called after each response is received. It can modify the responses before they are
+     * returned to the fetch caller.
+     *
+     * @example
+     *   import { type HttpSchema } from '@zimic/http';
+     *   import { createFetch } from '@zimic/fetch';
+     *
+     *   interface User {
+     *     id: string;
+     *     username: string;
+     *   }
+     *
+     *   type Schema = HttpSchema<{
+     *     '/users': {
+     *       GET: {
+     *         response: {
+     *           200: {
+     *             headers: { 'content-encoding'?: string };
+     *             body: User[];
+     *           };
+     *         };
+     *       };
+     *     };
+     *   }>;
+     *
+     *   const fetch = createFetch<Schema>({
+     *     baseURL: 'http://localhost:80',
+     *
+     *     onResponse(response) {
+     *       if (this.isResponse(response, 'GET', '/users')) {
+     *         console.log(response.headers.get('content-encoding'));
+     *       }
+     *       return response;
+     *     },
+     *   });
+     *
+     * @param response The original response.
+     * @returns The response to be returned.
+     * @this {Fetch<Schema>} The fetch instance that received the response.
+     */
+    onResponse?: (this: Fetch<Schema>, response: FetchResponse.Loose) => PossiblePromise<Response>;
 }
-interface FetchClient<Schema extends HttpSchema> {
-    defaults: FetchRequestInit.Defaults;
+/**
+ * The default options for each request sent by the fetch instance.
+ *
+ * @see {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐fetch#fetchdefaults `fetch.defaults` API reference}
+ */
+type FetchDefaults = RequiredByKey<FetchRequestInit.Defaults, 'headers' | 'searchParams'>;
+interface FetchClient<Schema extends HttpSchema> extends Pick<FetchOptions<Schema>, 'onRequest' | 'onResponse'> {
+    /**
+     * The default options for each request sent by the fetch instance. The available options are the same as the
+     * {@link https://developer.mozilla.org/docs/Web/API/RequestInit `RequestInit`} options, plus `baseURL`.
+     *
+     * @example
+     *   import { type HttpSchema } from '@zimic/http';
+     *   import { createFetch } from '@zimic/fetch';
+     *
+     *   interface Post {
+     *     id: string;
+     *     title: string;
+     *   }
+     *
+     *   type Schema = HttpSchema<{
+     *     '/posts': {
+     *       POST: {
+     *         request: {
+     *           headers: { 'content-type': 'application/json' };
+     *           body: { title: string };
+     *         };
+     *         response: {
+     *           201: { body: Post };
+     *         };
+     *       };
+     *     };
+     *   }>;
+     *
+     *   const fetch = createFetch<Schema>({
+     *     baseURL: 'http://localhost:3000',
+     *     headers: { 'accept-language': 'en' },
+     *   });
+     *
+     *   // Set the authorization header for all requests
+     *   const { accessToken } = await authenticate();
+     *
+     *   fetch.defaults.headers.authorization = `Bearer ${accessToken}`;
+     *   console.log(fetch.defaults.headers);
+     *
+     *   const response = await fetch('/posts', {
+     *     method: 'POST',
+     *     headers: { 'content-type': 'application/json' },
+     *     body: JSON.stringify({ title: 'My post' }),
+     *   });
+     *
+     *   const post = await response.json(); // Post
+     */
+    defaults: FetchDefaults;
+    /**
+     * A loosely-typed version of {@link Fetch `fetch`}. This can be useful to make requests with fewer type constraints,
+     * such as in {@link onRequest `onRequest`} and {@link onResponse `onResponse`} listeners.
+     *
+     * @example
+     *   import { type HttpSchema } from '@zimic/http';
+     *   import { createFetch } from '@zimic/fetch';
+     *
+     *   interface User {
+     *     id: string;
+     *     username: string;
+     *   }
+     *
+     *   type Schema = HttpSchema<{
+     *     '/auth/login': {
+     *       POST: {
+     *         request: {
+     *           headers: { 'content-type': 'application/json' };
+     *           body: { username: string; password: string };
+     *         };
+     *         response: {
+     *           201: { body: { accessToken: string } };
+     *         };
+     *       };
+     *     };
+     *
+     *     '/auth/refresh': {
+     *       POST: {
+     *         response: {
+     *           201: { body: { accessToken: string } };
+     *         };
+     *       };
+     *     };
+     *
+     *     '/users': {
+     *       GET: {
+     *         request: {
+     *           headers: { authorization: string };
+     *         };
+     *         response: {
+     *           200: { body: User[] };
+     *           401: { body: { message: string } };
+     *           403: { body: { message: string } };
+     *         };
+     *       };
+     *     };
+     *   }>;
+     *
+     *   const fetch = createFetch<Schema>({
+     *     baseURL,
+     *
+     *     async onResponse(response) {
+     *       if (response.status === 401) {
+     *         const body = await response.clone().json();
+     *
+     *         if (body.message === 'Access token expired') {
+     *           // Refresh the access token
+     *           const refreshResponse = await this('/auth/refresh', { method: 'POST' });
+     *           const { accessToken } = await refreshResponse.json();
+     *
+     *           // Clone the original request and update its headers
+     *           const updatedRequest = response.request.clone();
+     *           updatedRequest.headers.set('authorization', `Bearer ${accessToken}`);
+     *
+     *           // Retry the original request with the updated headers
+     *           return this.loose(updatedRequest);
+     *         }
+     *       }
+     *
+     *       return response;
+     *     },
+     *   });
+     *
+     *   // Authenticate to your service before requests
+     *   const loginRequest = await fetch('/auth/login', {
+     *     method: 'POST',
+     *     headers: { 'content-type': 'application/json' },
+     *     body: JSON.stringify({ username: 'me', password: 'password' }),
+     *   });
+     *   const { accessToken } = await loginRequest.json();
+     *
+     *   // Set the authorization header for all requests
+     *   fetch.defaults.headers.authorization = `Bearer ${accessToken}`;
+     *
+     *   const request = await fetch('/users', {
+     *     method: 'GET',
+     *     searchParams: { query: 'u' },
+     *   });
+     *
+     *   const users = await request.json(); // User[]
+     *
+     * @param input The resource to fetch, either a path, a URL, or a {@link FetchRequest request}. If a path is provided,
+     *   it is automatically prefixed with the base URL of the fetch instance when the request is sent. If a URL or a
+     *   request is provided, it is used as is.
+     * @param init The request options. If a path or a URL is provided as the first argument, this argument is required
+     *   and should contain at least the method of the request. If the first argument is a {@link FetchRequest request},
+     *   this argument is optional.
+     * @returns A promise that resolves to the response to the request.
+     * @see {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐fetch#fetchloose `fetch.loose` API reference}
+     * @see {@link https://developer.mozilla.org/docs/Web/API/Fetch_API}
+     * @see {@link https://developer.mozilla.org/docs/Web/API/Request}
+     * @see {@link https://developer.mozilla.org/docs/Web/API/RequestInit}
+     * @see {@link https://developer.mozilla.org/docs/Web/API/Response}
+     */
+    loose: FetchFunction.Loose;
+    /**
+     * A constructor for creating
+     * {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐fetch#fetchrequest-1 `FetchRequest`}, closely compatible with
+     * the native {@link https://developer.mozilla.org/docs/Web/API/Request Request} constructor.
+     *
+     * @example
+     *   import { type HttpSchema } from '@zimic/http';
+     *   import { createFetch } from '@zimic/fetch';
+     *
+     *   interface User {
+     *     id: string;
+     *     username: string;
+     *   }
+     *
+     *   type Schema = HttpSchema<{
+     *     '/users': {
+     *       POST: {
+     *         request: {
+     *           headers: { 'content-type': 'application/json' };
+     *           body: { username: string };
+     *         };
+     *         response: {
+     *           201: { body: User };
+     *         };
+     *       };
+     *     };
+     *   }>;
+     *
+     *   const fetch = createFetch<Schema>({
+     *     baseURL: 'http://localhost:3000',
+     *   });
+     *
+     *   const request = new fetch.Request('/users', {
+     *     method: 'POST',
+     *     headers: { 'content-type': 'application/json' },
+     *     body: JSON.stringify({ username: 'me' }),
+     *   });
+     *
+     *   console.log(request); // FetchRequest<Schema, 'POST', '/users'>
+     *   console.log(request.path); // '/users'
+     *
+     * @see {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐fetch#fetchrequest-1 `FetchRequest`}
+     */
     Request: FetchRequestConstructor<Schema>;
-    onRequest?: FetchOptions<Schema>['onRequest'];
-    onResponse?: FetchOptions<Schema>['onResponse'];
-    isRequest: <Path extends HttpSchemaPath<Schema, Method>, Method extends HttpSchemaMethod<Schema>>(request: unknown, path: Path, method: Method) => request is FetchRequest<Path, Method, Default<Schema[Path][Method]>>;
-    isResponse: <Path extends HttpSchemaPath<Schema, Method>, Method extends HttpSchemaMethod<Schema>>(response: unknown, path: Path, method: Method) => response is FetchResponse<Path, Method, Default<Schema[Path][Method]>>;
-    isResponseError: <Path extends HttpSchemaPath<Schema, Method>, Method extends HttpSchemaMethod<Schema>>(error: unknown, path: Path, method: Method) => error is FetchResponseError<Path, Method, Default<Schema[Path][Method]>>;
+    /**
+     * A type guard that checks if a request is a {@link FetchRequest}, was created by the fetch instance, and has a
+     * specific method and path. This is useful to narrow down the type of a request before using it.
+     *
+     * @example
+     *   import { type HttpSchema } from '@zimic/http';
+     *   import { createFetch } from '@zimic/fetch';
+     *
+     *   interface User {
+     *     id: string;
+     *     username: string;
+     *   }
+     *
+     *   type Schema = HttpSchema<{
+     *     '/users': {
+     *       POST: {
+     *         request: {
+     *           headers: { 'content-type': 'application/json' };
+     *           body: { username: string };
+     *         };
+     *         response: {
+     *           201: { body: User };
+     *         };
+     *       };
+     *     };
+     *   }>;
+     *
+     *   const fetch = createFetch<Schema>({
+     *     baseURL: 'http://localhost:3000',
+     *   });
+     *
+     *   const request = new fetch.Request('/users', {
+     *     method: 'POST',
+     *     headers: { 'content-type': 'application/json' },
+     *     body: JSON.stringify({ username: 'me' }),
+     *   });
+     *
+     *   if (fetch.isRequest(request, 'POST', '/users')) {
+     *     // request is a FetchRequest<Schema, 'POST', '/users'>
+     *
+     *     const contentType = request.headers.get('content-type'); // 'application/json'
+     *     const body = await request.json(); // { username: string }
+     *   }
+     *
+     * @param request The request to check.
+     * @param method The method to check.
+     * @param path The path to check.
+     * @returns `true` if the request was created by the fetch instance and has the specified method and path; `false`
+     *   otherwise.
+     */
+    isRequest: <Method extends HttpSchemaMethod<Schema>, Path extends HttpSchemaPath.Literal<Schema, Method>>(request: unknown, method: Method, path: Path) => request is FetchRequest<Schema, Method, Path>;
+    /**
+     * A type guard that checks if a response is a {@link FetchResponse}, was received by the fetch instance, and has a
+     * specific method and path. This is useful to narrow down the type of a response before using it.
+     *
+     * @example
+     *   import { type HttpSchema } from '@zimic/http';
+     *   import { createFetch } from '@zimic/fetch';
+     *
+     *   interface User {
+     *     id: string;
+     *     username: string;
+     *   }
+     *
+     *   type Schema = HttpSchema<{
+     *     '/users': {
+     *       GET: {
+     *         request: {
+     *           searchParams: { query?: string };
+     *         };
+     *         response: {
+     *           200: { body: User[] };
+     *         };
+     *       };
+     *     };
+     *   }>;
+     *
+     *   const fetch = createFetch<Schema>({
+     *     baseURL: 'http://localhost:3000',
+     *   });
+     *
+     *   const response = await fetch('/users', {
+     *     method: 'GET',
+     *     searchParams: { query: 'u' },
+     *   });
+     *
+     *   if (fetch.isResponse(response, 'GET', '/users')) {
+     *     // response is a FetchResponse<Schema, 'GET', '/users'>
+     *
+     *     const users = await response.json(); // User[]
+     *   }
+     *
+     * @param response The response to check.
+     * @param method The method to check.
+     * @param path The path to check.
+     * @returns `true` if the response was received by the fetch instance and has the specified method and path; `false`
+     *   otherwise.
+     */
+    isResponse: <Method extends HttpSchemaMethod<Schema>, Path extends HttpSchemaPath.Literal<Schema, Method>>(response: unknown, method: Method, path: Path) => response is FetchResponse<Schema, Method, Path>;
+    /**
+     * A type guard that checks if an error is a {@link FetchResponseError} related to a {@link FetchResponse response}
+     * received by the fetch instance with a specific method and path. This is useful to narrow down the type of an error
+     * before handling it.
+     *
+     * @example
+     *   import { type HttpSchema } from '@zimic/http';
+     *   import { createFetch } from '@zimic/fetch';
+     *
+     *   interface User {
+     *     id: string;
+     *     username: string;
+     *   }
+     *
+     *   type Schema = HttpSchema<{
+     *     '/users': {
+     *       GET: {
+     *         request: {
+     *           searchParams: { query?: string };
+     *         };
+     *         response: {
+     *           200: { body: User[] };
+     *           400: { body: { message: string } };
+     *           500: { body: { message: string } };
+     *         };
+     *       };
+     *     };
+     *   }>;
+     *
+     *   const fetch = createFetch<Schema>({
+     *     baseURL: 'http://localhost:3000',
+     *   });
+     *
+     *   try {
+     *     const response = await fetch('/users', {
+     *       method: 'GET',
+     *       searchParams: { query: 'u' },
+     *     });
+     *
+     *     if (!response.ok) {
+     *       throw response.error; // FetchResponseError<Schema, 'GET', '/users'>
+     *     }
+     *   } catch (error) {
+     *     if (fetch.isResponseError(error, 'GET', '/users')) {
+     *       // error is a FetchResponseError<Schema, 'GET', '/users'>
+     *
+     *       const status = error.response.status; // 400 | 500
+     *       const { message } = await error.response.json(); // { message: string }
+     *
+     *       console.error('Could not fetch users:', { status, message });
+     *     }
+     *   }
+     *
+     * @param error The error to check.
+     * @param method The method to check.
+     * @param path The path to check.
+     * @returns `true` if the error is a response error received by the fetch instance and has the specified method and
+     *   path; `false` otherwise.
+     */
+    isResponseError: <Method extends HttpSchemaMethod<Schema>, Path extends HttpSchemaPath.Literal<Schema, Method>>(error: unknown, method: Method, path: Path) => error is FetchResponseError<Schema, Method, Path>;
 }
+/**
+ * A fetch instance typed with an HTTP schema, closely compatible with the
+ * {@link https://developer.mozilla.org/docs/Web/API/Fetch_API native Fetch API}. All requests and responses are typed by
+ * default with the schema, including methods, paths, status codes, parameters, and bodies.
+ *
+ * Requests sent by the fetch instance have their URL automatically prefixed with the base URL of the instance. Default
+ * options are also applied to the requests, if present in the instance.
+ *
+ * @example
+ *   import { type HttpSchema } from '@zimic/http';
+ *   import { createFetch } from '@zimic/fetch';
+ *
+ *   interface User {
+ *     id: string;
+ *     username: string;
+ *   }
+ *
+ *   type Schema = HttpSchema<{
+ *     '/users': {
+ *       GET: {
+ *         request: {
+ *           searchParams: { query?: string };
+ *         };
+ *         response: {
+ *           200: { body: User[] };
+ *           404: { body: { message: string } };
+ *           500: { body: { message: string } };
+ *         };
+ *       };
+ *     };
+ *   }>;
+ *
+ *   const fetch = createFetch<Schema>({
+ *     baseURL: 'http://localhost:3000',
+ *     headers: { 'accept-language': 'en' },
+ *   });
+ *
+ *   const response = await fetch('/users', {
+ *     method: 'GET',
+ *     searchParams: { query: 'u' },
+ *   });
+ *
+ *   if (response.status === 404) {
+ *     return null; // User not found
+ *   }
+ *
+ *   if (!response.ok) {
+ *     throw response.error;
+ *   }
+ *
+ *   const users = await response.json();
+ *   return users; // User[]
+ *
+ * @param input The resource to fetch, either a path, a URL, or a {@link FetchRequest request}. If a path is provided, it
+ *   is automatically prefixed with the base URL of the fetch instance when the request is sent. If a URL or a request
+ *   is provided, it is used as is.
+ * @param init The request options. If a path or a URL is provided as the first argument, this argument is required and
+ *   should contain at least the method of the request. If the first argument is a {@link FetchRequest request}, this
+ *   argument is optional.
+ * @returns A promise that resolves to the response to the request.
+ * @see {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐fetch#fetch `fetch` API reference}
+ * @see {@link https://developer.mozilla.org/docs/Web/API/Fetch_API}
+ * @see {@link https://developer.mozilla.org/docs/Web/API/Request}
+ * @see {@link https://developer.mozilla.org/docs/Web/API/RequestInit}
+ * @see {@link https://developer.mozilla.org/docs/Web/API/Response}
+ */
 type Fetch<Schema extends HttpSchema> = FetchFunction<Schema> & FetchClient<Schema>;
+/**
+ * Infers the schema of a {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐fetch#fetch fetch instance}.
+ *
+ * @example
+ *   import { type HttpSchema } from '@zimic/http';
+ *   import { createFetch, InferFetchSchema } from '@zimic/fetch';
+ *
+ *   const fetch = createFetch<{
+ *     '/users': {
+ *       GET: {
+ *         response: { 200: { body: User[] } };
+ *       };
+ *     };
+ *   }>({
+ *     baseURL: 'http://localhost:3000',
+ *   });
+ *
+ *   type Schema = InferFetchSchema<typeof fetch>;
+ *   // {
+ *   //   '/users': {
+ *   //     GET: {
+ *   //      response: { 200: { body: User[] } };
+ *   //    };
+ *   // };
+ *
+ * @see {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐fetch#fetch `fetch` API reference}
+ */
+type InferFetchSchema<FetchInstance> = FetchInstance extends Fetch<infer Schema> ? Schema : never;
 
-declare function createFetch<Schema extends HttpSchema>(options: FetchOptions<HttpSchema<Schema>>): Fetch<HttpSchema<Schema>>;
+/**
+ * Creates a {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐fetch#fetch fetch instance} typed with an HTTP
+ * schema, closely compatible with the {@link https://developer.mozilla.org/docs/Web/API/Fetch_API native Fetch API}. All
+ * requests and responses are typed by default with the schema, including methods, paths, status codes, parameters, and
+ * bodies.
+ *
+ * Requests sent by the fetch instance have their URL automatically prefixed with the base URL of the instance.
+ * {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐fetch#fetch.defaults Default options} are also applied to the
+ * requests, if provided.
+ *
+ * @example
+ *   import { type HttpSchema } from '@zimic/http';
+ *   import { createFetch } from '@zimic/fetch';
+ *
+ *   interface User {
+ *     id: string;
+ *     username: string;
+ *   }
+ *
+ *   type Schema = HttpSchema<{
+ *     '/users': {
+ *       POST: {
+ *         request: {
+ *           headers: { 'content-type': 'application/json' };
+ *           body: { username: string };
+ *         };
+ *         response: {
+ *           201: { body: User };
+ *         };
+ *       };
+ *
+ *       GET: {
+ *         request: {
+ *           searchParams: {
+ *             query?: string;
+ *             page?: number;
+ *             limit?: number;
+ *           };
+ *         };
+ *         response: {
+ *           200: { body: User[] };
+ *         };
+ *       };
+ *     };
+ *   }>;
+ *
+ *   const fetch = createFetch<Schema>({
+ *     baseURL: 'http://localhost:3000',
+ *   });
+ *
+ * @see {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐fetch#createfetch `createFetch(options)` API reference}
+ * @see {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐fetch#fetch `fetch` API reference}
+ */
+declare function createFetch<Schema extends HttpSchema>(options: FetchOptions<Schema>): Fetch<Schema>;
 
-export { type Fetch, type FetchClient, type FetchOptions as FetchClientOptions, type FetchFunction, type FetchInput, FetchRequest, type FetchRequestConstructor, FetchRequestInit, FetchResponse, FetchResponseError, createFetch };
+export { type Fetch, type FetchDefaults, type FetchInput, type FetchOptions, FetchRequest, type FetchRequestConstructor, FetchRequestInit, FetchResponse, FetchResponseError, type InferFetchSchema, type JSONStringified, createFetch };