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

package/src/client/types/requests.ts

@@ -66,13 +66,22 @@ type FetchRequestInitPerPath<RequestSchema extends HttpRequestSchema> = FetchReq
   FetchRequestInitWithSearchParams<RequestSchema> &
   FetchRequestInitWithBody<RequestSchema>;
 
+/**
+ * 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`}
+ */
 export 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);
@@ -81,11 +90,15 @@ export namespace FetchRequestInit {
   /** The default options for each request sent by a fetch instance. */
   export interface Defaults extends Omit<RequestInit, 'headers'> {
     baseURL: string;
+    /** The HTTP method of the request. */
     method?: HttpMethod;
+    /** The headers of the request. */
     headers?: HttpHeadersSchema;
+    /** The search parameters of the request. */
     searchParams?: HttpSearchParamsSchema;
   }
 
+  /** A loosely typed version of {@link FetchRequestInit `FetchRequestInit`}. */
   export type Loose = Partial<Defaults>;
 }
 
@@ -122,6 +135,55 @@ type HttpRequestBodySchema<MethodSchema extends HttpMethodSchema> = ReplaceBy<
   Blob
 >;
 
+/**
+ * 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}
+ */
 export interface FetchRequest<
   Schema extends HttpSchema,
   Method extends HttpSchemaMethod<Schema>,
@@ -130,14 +192,20 @@ export interface FetchRequest<
     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;
 }
 
 export namespace FetchRequest {
+  /** A loosely typed version of {@link FetchRequest `FetchRequest`}. */
   export 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;
   }
 }
@@ -152,13 +220,71 @@ export interface FetchResponsePerStatusCode<
     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;
 }
 
+/**
+ * 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}
+ */
 export type FetchResponse<
   Schema extends HttpSchema,
   Method extends HttpSchemaMethod<Schema>,
@@ -173,13 +299,55 @@ export type FetchResponse<
 > = StatusCode extends StatusCode ? FetchResponsePerStatusCode<Schema, Method, Path, StatusCode> : never;
 
 export namespace FetchResponse {
+  /** A loosely typed version of {@link FetchResponse}. */
   export 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;
   }
 }
 
+/**
+ * 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}
+ */
 export type FetchRequestConstructor<Schema extends HttpSchema> = new <
   Method extends HttpSchemaMethod<Schema>,
   Path extends HttpSchemaPath.NonLiteral<Schema, Method>,