@zimic/fetch 0.4.1-canary.0 → 0.4.1-canary.2

package/src/client/types/public.ts

@@ -4,83 +4,14 @@ import { PossiblePromise, RequiredByKey } from '@zimic/utils/types';
 import FetchResponseError from '../errors/FetchResponseError';
 import { FetchRequest, FetchRequestConstructor, FetchRequestInit, FetchResponse } from './requests';
 
-/**
- * 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}
- */
+/** @see {@link  https://zimic.dev/docs/fetch/api/fetch `fetch` API reference} */
 export type FetchInput<
   Schema extends HttpSchema,
   Method extends HttpSchemaMethod<Schema>,
   Path extends HttpSchemaPath.NonLiteral<Schema, Method>,
 > = Path | URL | FetchRequest<Schema, Method, LiteralHttpSchemaPathFromNonLiteral<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}
- */
+/** @see {@link https://zimic.dev/docs/fetch/api/fetch `fetch` API reference} */
 export interface Fetch<Schema extends HttpSchema> extends Pick<FetchOptions<Schema>, 'onRequest' | 'onResponse'> {
   <
     Method extends HttpSchemaMethod<Schema>,
@@ -100,373 +31,30 @@ export interface Fetch<Schema extends HttpSchema> extends Pick<FetchOptions<Sche
     init?: FetchRequestInit<Schema, Method, LiteralHttpSchemaPathFromNonLiteral<Schema, Method, Path>, Redirect>,
   ): Promise<FetchResponse<Schema, Method, LiteralHttpSchemaPathFromNonLiteral<Schema, Method, Path>, false, Redirect>>;
 
-  /**
-   * 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
-   */
+  /** @see {@link https://zimic.dev/docs/fetch/api/fetch#fetchdefaults `fetch.defaults`} */
   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}
-   */
+  /** @see {@link https://zimic.dev/docs/fetch/api/fetch#fetchloose `fetch.loose`} */
   loose: Fetch.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`}
-   */
+  /** @see {@link https://zimic.dev/docs/fetch/api/fetch#fetchrequest `fetch.Request`} */
   Request: FetchRequestConstructor<Schema>;
 
-  /**
-   * 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.
-   */
+  /** @see {@link https://zimic.dev/docs/fetch/api/fetch#isrequest `fetch.isRequest`} */
   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.
-   */
+  /** @see {@link https://zimic.dev/docs/fetch/api/fetch#isresponseerror `fetch.isResponse`} */
   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.
-   */
+  /** @see {@link https://zimic.dev/docs/fetch/api/fetch#isresponseerror `fetch.isResponseError`} */
   isResponseError: <Method extends HttpSchemaMethod<Schema>, Path extends HttpSchemaPath.Literal<Schema, Method>>(
     error: unknown,
     method: Method,
@@ -482,112 +70,24 @@ export namespace Fetch {
   ) => 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}
- */
+/** @see {@link https://zimic.dev/docs/fetch/api/create-fetch `createFetch` API reference} */
 export interface FetchOptions<Schema extends HttpSchema> extends Omit<FetchRequestInit.Defaults, 'method'> {
-  /**
-   * 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.
-   */
+  /** @see {@link https://zimic.dev/docs/fetch/api/create-fetch#onrequest `createFetch.onRequest`} API reference */
   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.
-   */
+  /** @see {@link https://zimic.dev/docs/fetch/api/create-fetch#onresponse `createFetch.onResponse`} API reference */
   onResponse?: (this: Fetch<Schema>, response: FetchResponse.Loose) => PossiblePromise<Response>;
 }
 
 /**
  * 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}
+ * @see {@link https://zimic.dev/docs/fetch/api/fetch#fetchdefaults `fetch.defaults` API reference}
  */
 export type FetchDefaults = RequiredByKey<FetchRequestInit.Defaults, 'headers' | 'searchParams'>;
 
 /**
- * Infers the schema of a {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐fetch#fetch fetch instance}.
+ * Infers the schema of a {@link https://zimic.dev/docs/fetch/api/fetch fetch instance}.
  *
  * @example
  *   import { type HttpSchema } from '@zimic/http';
@@ -611,6 +111,6 @@ export type FetchDefaults = RequiredByKey<FetchRequestInit.Defaults, 'headers' |
  *   //    };
  *   // };
  *
- * @see {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐fetch#fetch `fetch` API reference}
+ * @see {@link https://zimic.dev/docs/fetch/api/fetch `fetch` API reference}
  */
 export type InferFetchSchema<FetchInstance> = FetchInstance extends Fetch<infer Schema> ? Schema : never;