@zimic/fetch 0.1.0-canary.7 → 0.1.0

package/src/client/FetchClient.ts

@@ -4,35 +4,54 @@ import {
   HttpSearchParams,
   LiteralHttpSchemaPathFromNonLiteral,
   HttpSchema,
+  HttpHeaders,
 } from '@zimic/http';
-
-import { Default } from '@/types/utils';
-import { createRegexFromURL, excludeNonPathParams, joinURL } from '@/utils/urls';
+import createRegexFromURL from '@zimic/utils/url/createRegExpFromURL';
+import excludeURLParams from '@zimic/utils/url/excludeURLParams';
+import joinURL from '@zimic/utils/url/joinURL';
 
 import FetchResponseError from './errors/FetchResponseError';
-import { FetchInput, FetchOptions, Fetch } from './types/public';
+import {
+  FetchInput,
+  FetchOptions,
+  Fetch,
+  FetchClient as PublicFetchClient,
+  FetchDefaults,
+  FetchFunction,
+} from './types/public';
 import { FetchRequestConstructor, FetchRequestInit, FetchRequest, FetchResponse } from './types/requests';
 
-class FetchClient<Schema extends HttpSchema> {
+class FetchClient<Schema extends HttpSchema>
+  implements Omit<PublicFetchClient<Schema>, 'defaults' | 'loose' | 'Request'>
+{
   fetch: Fetch<Schema>;
 
   constructor({ onRequest, onResponse, ...defaults }: FetchOptions<Schema>) {
     this.fetch = this.createFetchFunction();
-    this.fetch.defaults = defaults;
-    this.fetch.Request = this.createRequestClass(defaults);
+
+    this.fetch.defaults = {
+      ...defaults,
+      headers: defaults.headers ?? {},
+      searchParams: defaults.searchParams ?? {},
+    };
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    this.fetch.loose = this.fetch as Fetch<any> as FetchFunction.Loose;
+
+    this.fetch.Request = this.createRequestClass(this.fetch.defaults);
     this.fetch.onRequest = onRequest;
     this.fetch.onResponse = onResponse;
   }
 
   private createFetchFunction() {
     const fetch = async <
-      Path extends HttpSchemaPath.NonLiteral<Schema, Method>,
       Method extends HttpSchemaMethod<Schema>,
+      Path extends HttpSchemaPath.NonLiteral<Schema, Method>,
     >(
-      input: FetchInput<Schema, Path, Method>,
-      init: FetchRequestInit<Schema, LiteralHttpSchemaPathFromNonLiteral<Schema, Method, Path>, Method>,
+      input: FetchInput<Schema, Method, Path>,
+      init: FetchRequestInit<Schema, Method, LiteralHttpSchemaPathFromNonLiteral<Schema, Method, Path>>,
     ) => {
-      const request = await this.createFetchRequest<Path, Method>(input, init);
+      const request = await this.createFetchRequest<Method, Path>(input, init);
       const requestClone = request.clone();
 
       const rawResponse = await globalThis.fetch(
@@ -40,8 +59,8 @@ class FetchClient<Schema extends HttpSchema> {
         requestClone as Request,
       );
       const response = await this.createFetchResponse<
-        LiteralHttpSchemaPathFromNonLiteral<Schema, Method, Path>,
-        Method
+        Method,
+        LiteralHttpSchemaPathFromNonLiteral<Schema, Method, Path>
       >(request, rawResponse);
 
       return response;
@@ -53,11 +72,11 @@ class FetchClient<Schema extends HttpSchema> {
   }
 
   private async createFetchRequest<
-    Path extends HttpSchemaPath.NonLiteral<Schema, Method>,
     Method extends HttpSchemaMethod<Schema>,
+    Path extends HttpSchemaPath.NonLiteral<Schema, Method>,
   >(
-    input: FetchInput<Schema, Path, Method>,
-    init: FetchRequestInit<Schema, LiteralHttpSchemaPathFromNonLiteral<Schema, Method, Path>, Method>,
+    input: FetchInput<Schema, Method, Path>,
+    init: FetchRequestInit<Schema, Method, LiteralHttpSchemaPathFromNonLiteral<Schema, Method, Path>>,
   ) {
     let request = input instanceof Request ? input : new this.fetch.Request(input, init);
 
@@ -65,7 +84,6 @@ class FetchClient<Schema extends HttpSchema> {
       const requestAfterInterceptor = await this.fetch.onRequest(
         // Optimize type checking by narrowing the type of request
         request as FetchRequest.Loose,
-        this.fetch,
       );
 
       if (requestAfterInterceptor !== request) {
@@ -73,7 +91,7 @@ class FetchClient<Schema extends HttpSchema> {
 
         request = isFetchRequest
           ? (requestAfterInterceptor as Request as typeof request)
-          : new this.fetch.Request(requestAfterInterceptor as FetchInput<Schema, Path, Method>, init);
+          : new this.fetch.Request(requestAfterInterceptor as FetchInput<Schema, Method, Path>, init);
       }
     }
 
@@ -81,16 +99,15 @@ class FetchClient<Schema extends HttpSchema> {
   }
 
   private async createFetchResponse<
-    Path extends HttpSchemaPath<Schema, Method>,
     Method extends HttpSchemaMethod<Schema>,
-  >(fetchRequest: FetchRequest<Path, Method, Default<Schema[Path][Method]>>, rawResponse: Response) {
-    let response = this.defineFetchResponseProperties<Path, Method>(fetchRequest, rawResponse);
+    Path extends HttpSchemaPath.Literal<Schema, Method>,
+  >(fetchRequest: FetchRequest<Schema, Method, Path>, rawResponse: Response) {
+    let response = this.defineFetchResponseProperties<Method, Path>(fetchRequest, rawResponse);
 
     if (this.fetch.onResponse) {
       const responseAfterInterceptor = await this.fetch.onResponse(
         // Optimize type checking by narrowing the type of response
         response as FetchResponse.Loose,
-        this.fetch,
       );
 
       const isFetchResponse =
@@ -100,17 +117,17 @@ class FetchClient<Schema extends HttpSchema> {
 
       response = isFetchResponse
         ? (responseAfterInterceptor as typeof response)
-        : this.defineFetchResponseProperties<Path, Method>(fetchRequest, responseAfterInterceptor);
+        : this.defineFetchResponseProperties<Method, Path>(fetchRequest, responseAfterInterceptor);
     }
 
     return response;
   }
 
   private defineFetchResponseProperties<
-    Path extends HttpSchemaPath<Schema, Method>,
     Method extends HttpSchemaMethod<Schema>,
-  >(fetchRequest: FetchRequest<Path, Method, Default<Schema[Path][Method]>>, response: Response) {
-    const fetchResponse = response as FetchResponse<Path, Method, Default<Schema[Path][Method]>>;
+    Path extends HttpSchemaPath.Literal<Schema, Method>,
+  >(fetchRequest: FetchRequest<Schema, Method, Path>, response: Response) {
+    const fetchResponse = response as FetchResponse<Schema, Method, Path>;
 
     Object.defineProperty(fetchResponse, 'request', {
       value: fetchRequest satisfies FetchResponse.Loose['request'],
@@ -119,13 +136,20 @@ class FetchClient<Schema extends HttpSchema> {
       configurable: false,
     });
 
-    const responseError = (
-      fetchResponse.ok ? null : new FetchResponseError(fetchRequest, fetchResponse)
-    ) satisfies FetchResponse.Loose['error'];
+    let responseError: FetchResponse.Loose['error'] | undefined;
 
     Object.defineProperty(fetchResponse, 'error', {
-      value: responseError,
-      writable: false,
+      get() {
+        if (responseError === undefined) {
+          responseError = fetchResponse.ok
+            ? null
+            : new FetchResponseError(
+                fetchRequest,
+                fetchResponse as FetchResponse<Schema, Method, Path, true, 'manual'>,
+              );
+        }
+        return responseError;
+      },
       enumerable: true,
       configurable: false,
     });
@@ -133,53 +157,76 @@ class FetchClient<Schema extends HttpSchema> {
     return fetchResponse;
   }
 
-  private createRequestClass(defaults: FetchRequestInit.Defaults) {
+  private createRequestClass(defaults: FetchDefaults) {
     class Request<
-      Path extends HttpSchemaPath.NonLiteral<Schema, Method>,
       Method extends HttpSchemaMethod<Schema>,
+      Path extends HttpSchemaPath.NonLiteral<Schema, Method>,
     > extends globalThis.Request {
       path: LiteralHttpSchemaPathFromNonLiteral<Schema, Method, Path>;
 
       constructor(
-        input: FetchInput<Schema, Path, Method>,
-        rawInit: FetchRequestInit<Schema, LiteralHttpSchemaPathFromNonLiteral<Schema, Method, Path>, Method>,
+        input: FetchInput<Schema, Method, Path>,
+        init: FetchRequestInit<Schema, Method, LiteralHttpSchemaPathFromNonLiteral<Schema, Method, Path>>,
       ) {
-        const init = { ...defaults, ...rawInit };
+        const initWithDefaults = { ...defaults, ...init };
+
+        const headersFromDefaults = new HttpHeaders(defaults.headers);
+        const headersFromInit = new HttpHeaders((init satisfies RequestInit as RequestInit).headers);
 
         let url: URL;
+        const baseURL = new URL(initWithDefaults.baseURL);
 
         if (input instanceof globalThis.Request) {
-          super(
-            // Optimize type checking by narrowing the type of input
-            input as globalThis.Request,
-            init,
-          );
+          // Optimize type checking by narrowing the type of input
+          const request = input as globalThis.Request;
+          const headersFromRequest = new HttpHeaders(input.headers);
+
+          initWithDefaults.headers = {
+            ...headersFromDefaults.toObject(),
+            ...headersFromRequest.toObject(),
+            ...headersFromInit.toObject(),
+          };
+
+          super(request, initWithDefaults);
 
           url = new URL(input.url);
         } else {
-          url = input instanceof URL ? new URL(input) : new URL(joinURL(init.baseURL, input));
+          initWithDefaults.headers = {
+            ...headersFromDefaults.toObject(),
+            ...headersFromInit.toObject(),
+          };
+
+          url = input instanceof URL ? new URL(input) : new URL(joinURL(baseURL, input));
 
-          if (init.searchParams) {
-            url.search = new HttpSearchParams(init.searchParams).toString();
-          }
+          const searchParamsFromDefaults = new HttpSearchParams(defaults.searchParams);
+          const searchParamsFromInit = new HttpSearchParams(initWithDefaults.searchParams);
 
-          super(url, init);
+          initWithDefaults.searchParams = {
+            ...searchParamsFromDefaults.toObject(),
+            ...searchParamsFromInit.toObject(),
+          };
+
+          url.search = new HttpSearchParams(initWithDefaults.searchParams).toString();
+
+          super(url, initWithDefaults);
         }
 
-        this.path = excludeNonPathParams(url)
+        const baseURLWithoutTrailingSlash = baseURL.toString().replace(/\/$/, '');
+
+        this.path = excludeURLParams(url)
           .toString()
-          .replace(init.baseURL, '') as LiteralHttpSchemaPathFromNonLiteral<Schema, Method, Path>;
+          .replace(baseURLWithoutTrailingSlash, '') as LiteralHttpSchemaPathFromNonLiteral<Schema, Method, Path>;
       }
 
-      clone(): Request<Path, Method> {
+      clone(): Request<Method, Path> {
         const rawClone = super.clone();
 
-        return new Request<Path, Method>(
-          rawClone as unknown as FetchInput<Schema, Path, Method>,
+        return new Request<Method, Path>(
+          rawClone as unknown as FetchInput<Schema, Method, Path>,
           rawClone as unknown as FetchRequestInit<
             Schema,
-            LiteralHttpSchemaPathFromNonLiteral<Schema, Method, Path>,
-            Method
+            Method,
+            LiteralHttpSchemaPathFromNonLiteral<Schema, Method, Path>
           >,
         );
       }
@@ -188,11 +235,11 @@ class FetchClient<Schema extends HttpSchema> {
     return Request as FetchRequestConstructor<Schema>;
   }
 
-  isRequest<Path extends HttpSchemaPath<Schema, Method>, Method extends HttpSchemaMethod<Schema>>(
+  isRequest<Path extends HttpSchemaPath.Literal<Schema, Method>, Method extends HttpSchemaMethod<Schema>>(
     request: unknown,
-    path: Path,
     method: Method,
-  ): request is FetchRequest<Path, Method, Default<Schema[Path][Method]>> {
+    path: Path,
+  ): request is FetchRequest<Schema, Method, Path> {
     return (
       request instanceof Request &&
       request.method === method &&
@@ -202,29 +249,29 @@ class FetchClient<Schema extends HttpSchema> {
     );
   }
 
-  isResponse<Path extends HttpSchemaPath<Schema, Method>, Method extends HttpSchemaMethod<Schema>>(
+  isResponse<Path extends HttpSchemaPath.Literal<Schema, Method>, Method extends HttpSchemaMethod<Schema>>(
     response: unknown,
-    path: Path,
     method: Method,
-  ): response is FetchResponse<Path, Method, Default<Schema[Path][Method]>> {
+    path: Path,
+  ): response is FetchResponse<Schema, Method, Path> {
     return (
       response instanceof Response &&
       'request' in response &&
+      this.isRequest(response.request, method, path) &&
       'error' in response &&
-      this.isRequest(response.request, path, method)
+      (response.error === null || response.error instanceof FetchResponseError)
     );
   }
 
-  isResponseError<Path extends HttpSchemaPath<Schema, Method>, Method extends HttpSchemaMethod<Schema>>(
+  isResponseError<Path extends HttpSchemaPath.Literal<Schema, Method>, Method extends HttpSchemaMethod<Schema>>(
     error: unknown,
-    path: Path,
     method: Method,
-  ): error is FetchResponseError<Path, Method, Default<Schema[Path][Method]>> {
+    path: Path,
+  ): error is FetchResponseError<Schema, Method, Path> {
     return (
       error instanceof FetchResponseError &&
-      error.request.method === method &&
-      typeof error.request.path === 'string' &&
-      createRegexFromURL(path).test(error.request.path)
+      this.isRequest(error.request, method, path) &&
+      this.isResponse(error.response, method, path)
     );
   }
 }

package/src/client/errors/FetchResponseError.ts

@@ -1,15 +1,56 @@
-import { HttpMethod, HttpMethodSchema } from '@zimic/http';
+import { HttpSchema, HttpSchemaMethod, HttpSchemaPath } from '@zimic/http';
 
 import { FetchRequest, FetchResponse } from '../types/requests';
 
+/**
+ * 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}
+ */
 class FetchResponseError<
-  Path extends string = string,
-  Method extends HttpMethod = HttpMethod,
-  MethodSchema extends HttpMethodSchema = HttpMethodSchema,
+  Schema extends HttpSchema,
+  Method extends HttpSchemaMethod<Schema>,
+  Path extends HttpSchemaPath.Literal<Schema, Method>,
 > extends Error {
   constructor(
-    public request: FetchRequest<Path, Method, MethodSchema>,
-    public response: FetchResponse<Path, Method, MethodSchema, true>,
+    public request: FetchRequest<Schema, Method, Path>,
+    public response: FetchResponse<Schema, Method, Path, true, 'manual'>,
   ) {
     super(`${request.method} ${request.url} failed with status ${response.status}: ${response.statusText}`);
     this.name = 'FetchResponseError';

package/src/client/factory.ts

@@ -1,12 +1,63 @@
 import { HttpSchema } from '@zimic/http';
 
 import FetchClient from './FetchClient';
-import { FetchOptions, Fetch as PublicFetch } from './types/public';
+import { FetchOptions, Fetch } from './types/public';
 
-function createFetch<Schema extends HttpSchema>(
-  options: FetchOptions<HttpSchema<Schema>>,
-): PublicFetch<HttpSchema<Schema>> {
-  const { fetch } = new FetchClient<HttpSchema<Schema>>(options);
+/**
+ * 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}
+ */
+function createFetch<Schema extends HttpSchema>(options: FetchOptions<Schema>): Fetch<Schema> {
+  const { fetch } = new FetchClient<Schema>(options);
   return fetch;
 }
 

package/src/client/types/json.ts

@@ -1,5 +1,12 @@
 const value = Symbol.for('JSONStringified.value');
 
+/**
+ * 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}
+ */
 export type JSONStringified<Value> = string & { [value]: Value };
 
 declare global {