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

package/src/client/types/public.ts

@@ -4,6 +4,11 @@ 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}
+ */
 export type FetchInput<
   Schema extends HttpSchema,
   Method extends HttpSchemaMethod<Schema>,
@@ -37,32 +42,478 @@ export namespace FetchFunction {
   ) => 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}
+ */
 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.
+   */
   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>;
 }
 
+/**
+ * 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}
+ */
 export type FetchDefaults = RequiredByKey<FetchRequestInit.Defaults, 'headers' | 'searchParams'>;
 
 export 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>;
 
+  /**
+   * 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,
@@ -70,6 +521,99 @@ export interface FetchClient<Schema extends HttpSchema> extends Pick<FetchOption
   ) => 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}
+ */
 export 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}
+ */
 export type InferFetchSchema<FetchInstance> = FetchInstance extends Fetch<infer Schema> ? Schema : never;