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

package/src/client/types/requests.ts

@@ -17,133 +17,341 @@ import {
   HttpResponseBodySchema,
   HttpResponseHeadersSchema,
   HttpRequestHeadersSchema,
+  HttpHeadersSchema,
+  HttpSearchParamsSchema,
 } from '@zimic/http';
-
-import { Default, DefaultNoExclude, IfNever, ReplaceBy } from '@/types/utils';
+import { Default, DefaultNoExclude, IfNever, ReplaceBy } from '@zimic/utils/types';
 
 import FetchResponseError, { AnyFetchRequestError } from '../errors/FetchResponseError';
 import { JSONStringified } from './json';
 import { FetchInput } from './public';
 
+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: RequestSchema['headers'] | HttpHeaders<Default<RequestSchema['headers']>> };
+    ? { headers?: FetchRequestInitHeaders<RequestSchema> }
+    : { 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: RequestSchema['searchParams'] | HttpSearchParams<Default<RequestSchema['searchParams']>> };
+    ? { searchParams?: FetchRequestInitSearchParams<RequestSchema> }
+    : { searchParams: FetchRequestInitSearchParams<RequestSchema> };
 
 type FetchRequestInitWithBody<RequestSchema extends HttpRequestSchema> = [RequestSchema['body']] extends [never]
   ? { body?: null }
-  : undefined extends RequestSchema['body']
-    ? { body?: ReplaceBy<RequestSchema['body'], undefined, null> }
-    : RequestSchema['body'] extends string
-      ? { body: RequestSchema['body'] }
-      : RequestSchema['body'] extends JSONValue
-        ? { body: JSONStringified<RequestSchema['body']> }
+  : RequestSchema['body'] extends string
+    ? undefined extends RequestSchema['body']
+      ? { body?: ReplaceBy<RequestSchema['body'], undefined, null> }
+      : { body: RequestSchema['body'] }
+    : 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>;
 
+/**
+ * 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,
-  Path extends HttpSchemaPath<Schema, Method>,
   Method extends HttpSchemaMethod<Schema>,
-> = RequestInit & { baseURL?: string; method: Method } & (Path extends Path
-    ? FetchRequestInitPerPath<Default<Default<Schema[Path][Method]>['request']>>
-    : never);
+  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);
 
 export namespace FetchRequestInit {
-  export interface Defaults extends RequestInit {
+  /** 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;
-    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`}. */
+  export 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;
 
-export type HttpRequestBodySchema<MethodSchema extends HttpMethodSchema> = ReplaceBy<
+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
 >;
 
+/**
+ * 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<
-  Path extends string = string,
-  Method extends HttpMethod = HttpMethod,
-  MethodSchema extends HttpMethodSchema = HttpMethodSchema,
-> extends HttpRequest<HttpRequestBodySchema<MethodSchema>, HttpRequestHeadersSchema<MethodSchema>> {
+  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;
 }
 
 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;
   }
 }
 
 export interface FetchResponsePerStatusCode<
-  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>,
   StatusCode extends HttpStatusCode = HttpStatusCode,
 > extends HttpResponse<
-    HttpResponseBodySchema<MethodSchema, StatusCode>,
+    HttpResponseBodySchema<Default<Schema[Path][Method]>, StatusCode>,
     StatusCode,
-    HttpResponseHeadersSchema<MethodSchema, StatusCode>
+    HttpResponseHeadersSchema<Default<Schema[Path][Method]>, StatusCode>
   > {
-  request: FetchRequest<Path, Method, MethodSchema>;
+  /** 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<Path, Method, MethodSchema>
+    ? 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<
-  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>,
   ErrorOnly extends boolean = false,
-  StatusCode extends FetchResponseStatusCode<MethodSchema, ErrorOnly> = FetchResponseStatusCode<
-    MethodSchema,
-    ErrorOnly
-  >,
-> = StatusCode extends StatusCode ? FetchResponsePerStatusCode<Path, Method, MethodSchema, StatusCode> : never;
+  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;
 
 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 <
-  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>,
-) => FetchRequest<
-  LiteralHttpSchemaPathFromNonLiteral<Schema, Method, Path>,
-  Method,
-  Default<Schema[LiteralHttpSchemaPathFromNonLiteral<Schema, Method, Path>][Method]>
->;
+  input: FetchInput<Schema, Method, Path>,
+  init: FetchRequestInit<Schema, Method, LiteralHttpSchemaPathFromNonLiteral<Schema, Method, Path>>,
+) => FetchRequest<Schema, Method, LiteralHttpSchemaPathFromNonLiteral<Schema, Method, Path>>;

package/src/index.ts

@@ -1,12 +1,8 @@
-export type {
-  Fetch,
-  FetchFunction,
-  FetchClient,
-  FetchOptions as FetchClientOptions,
-  FetchInput,
-} from './client/types/public';
-
-export type { FetchRequestInit, FetchRequest, FetchRequestConstructor, FetchResponse } from './client/types/requests';
+export type { JSONStringified } from './client/types/json';
+
+export type { Fetch, InferFetchSchema, FetchOptions, FetchDefaults, FetchInput } from './client/types/public';
+
+export type { FetchRequest, FetchRequestInit, FetchResponse, FetchRequestConstructor } from './client/types/requests';
 
 export { default as FetchResponseError } from './client/errors/FetchResponseError';
 

package/src/types/requests.ts

@@ -9,8 +9,7 @@ import {
   JSONValue,
   HttpStatusCode,
 } from '@zimic/http';
-
-import { ReplaceBy } from '@/types/utils';
+import { ReplaceBy } from '@zimic/utils/types';
 
 /** The body type for HTTP requests and responses. */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any

package/src/utils/environment.ts

@@ -0,0 +1,3 @@
+export function isClientSide() {
+  return typeof window !== 'undefined';
+}

package/src/utils/files.ts

@@ -1,23 +1,8 @@
-import { createCachedDynamicImport } from './imports';
-
-export const importBuffer = createCachedDynamicImport(
-  /* istanbul ignore next -- @preserve
-   * Ignoring as Node.js >=20 provides a global file and the buffer import won't run. */
-  () => import('buffer'),
-);
-
-let FileSingleton: typeof File | undefined;
-
-export async function importFile() {
-  /* istanbul ignore if -- @preserve
-   * Ignoring as this will only run if this function is called more than once. */
-  if (FileSingleton) {
-    return FileSingleton;
-  }
+import createCachedDynamicImport from '@zimic/utils/import/createCachedDynamicImport';
 
+export const importFile = createCachedDynamicImport(
   /* istanbul ignore next -- @preserve
    * Ignoring as Node.js >=20 provides a global File and the import fallback won't run. */
   // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-  FileSingleton = globalThis.File ?? (await importBuffer()).File;
-  return FileSingleton;
-}
+  async () => globalThis.File ?? (await import('buffer')).File,
+);

package/src/types/strings.d.ts

@@ -1,9 +0,0 @@
-interface String {
-  // Using the original method signature style to correctly apply the overload.
-  // eslint-disable-next-line @typescript-eslint/method-signature-style
-  toLowerCase<Type = string>(): Lowercase<Type>;
-
-  // Using the original method signature style to correctly apply the overload.
-  // eslint-disable-next-line @typescript-eslint/method-signature-style
-  toUpperCase<Type = string>(): Uppercase<Type>;
-}

package/src/types/utils.ts

@@ -1,11 +0,0 @@
-export type Default<Type, IfEmpty = never> = [undefined | void] extends [Type]
-  ? IfEmpty
-  : Exclude<Type, undefined | void>;
-
-export type DefaultNoExclude<Type, IfEmpty = never> = [undefined | void] extends Type ? IfEmpty : Type;
-
-export type IfNever<Type, Yes, No = Type> = [Type] extends [never] ? Yes : No;
-
-export type PossiblePromise<Type> = Type | PromiseLike<Type>;
-
-export type ReplaceBy<Type, Source, Target> = Type extends Source ? Target : Type;

package/src/utils/imports.ts

@@ -1,14 +0,0 @@
-/* istanbul ignore next -- @preserve
- * Ignoring as Node.js >=20 provides globals that may cause this dynamic import to not run. */
-export function createCachedDynamicImport<ImportType>(
-  importModuleDynamically: () => Promise<ImportType>,
-): () => Promise<ImportType> {
-  let cachedImportResult: ImportType | undefined;
-
-  return async function importModuleDynamicallyWithCache() {
-    if (cachedImportResult === undefined) {
-      cachedImportResult = await importModuleDynamically();
-    }
-    return cachedImportResult;
-  };
-}

package/src/utils/urls.ts

@@ -1,43 +0,0 @@
-export function excludeNonPathParams(url: URL) {
-  url.hash = '';
-  url.search = '';
-  url.username = '';
-  url.password = '';
-  return url;
-}
-
-function prepareURLForRegex(url: string) {
-  const encodedURL = encodeURI(url);
-  return encodedURL.replace(/([.()*?+$\\])/g, '\\$1');
-}
-
-const URL_PATH_PARAM_REGEX = /\/:([^/]+)/g;
-
-export function createRegexFromURL(url: string) {
-  const urlWithReplacedPathParams = prepareURLForRegex(url)
-    .replace(URL_PATH_PARAM_REGEX, '/(?<$1>[^/]+)')
-    .replace(/(\/+)$/, '(?:/+)?');
-
-  return new RegExp(`^${urlWithReplacedPathParams}$`);
-}
-
-export function joinURL(...parts: (string | URL)[]) {
-  return parts
-    .map((part, index) => {
-      const isFirstPart = index === 0;
-      const isLastPart = index === parts.length - 1;
-
-      let partAsString = part.toString();
-
-      if (!isFirstPart) {
-        partAsString = partAsString.replace(/^\//, '');
-      }
-      if (!isLastPart) {
-        partAsString = partAsString.replace(/\/$/, '');
-      }
-
-      return partAsString;
-    })
-    .filter((part) => part.length > 0)
-    .join('/');
-}