@zimic/fetch 1.4.1 → 1.4.3-canary.0

package/src/client/response/types.ts

@@ -0,0 +1,111 @@
+import {
+  HttpBody,
+  HttpHeadersSchema,
+  HttpHeadersSerialized,
+  HttpMethodSchema,
+  HttpResponseHeadersSchema,
+  HttpResponseSchema,
+  HttpResponseSchemaStatusCode,
+  HttpSchema,
+  HttpSchemaMethod,
+  HttpSchemaPath,
+  HttpStatusCode,
+} from '@zimic/http';
+import { Default } from '@zimic/utils/types';
+
+import { FetchRequest } from '../request/FetchRequest';
+import { FetchRequestBodySchema, FetchRequestInitWithHeaders } from '../request/types';
+import { FetchResponse } from './FetchResponse';
+
+export type AllFetchResponseStatusCode<MethodSchema extends HttpMethodSchema> = HttpResponseSchemaStatusCode<
+  Default<MethodSchema['response']>
+>;
+
+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;
+
+/** @see {@link https://zimic.dev/docs/fetch/api/fetch-response `FetchResponse` API reference} */
+export type FetchResponseStatusCode<
+  MethodSchema extends HttpMethodSchema,
+  ErrorOnly extends boolean,
+  Redirect extends RequestRedirect,
+> = FilterFetchResponseStatusCodeByRedirect<
+  FilterFetchResponseStatusCodeByError<AllFetchResponseStatusCode<MethodSchema>, ErrorOnly>,
+  Redirect
+>;
+
+type FetchResponseInitWithHeaders<HeadersSchema extends HttpHeadersSchema | undefined> =
+  FetchRequestInitWithHeaders<HeadersSchema>;
+
+export type FetchResponseBodySchema<ResponseSchema extends HttpResponseSchema> = FetchRequestBodySchema<ResponseSchema>;
+
+type FetchResponseInitPerStatusCode<
+  MethodSchema extends HttpMethodSchema,
+  StatusCode extends AllFetchResponseStatusCode<MethodSchema>,
+> = { status: StatusCode } & FetchResponseInitWithHeaders<HttpResponseHeadersSchema<MethodSchema, StatusCode>>;
+
+/** @see {@link https://zimic.dev/docs/fetch/api/fetch-response `FetchResponse` API reference} */
+export type FetchResponseInit<
+  Schema extends HttpSchema,
+  Method extends HttpSchemaMethod<Schema>,
+  Path extends HttpSchemaPath<Schema, Method>,
+  /** @deprecated The type parameter `ErrorOnly` will be removed in the next major version. */
+  ErrorOnly extends boolean = false,
+  Redirect extends RequestRedirect = 'follow',
+  StatusCode extends FetchResponseStatusCode<Default<Schema[Path][Method]>, ErrorOnly, Redirect> =
+    FetchResponseStatusCode<Default<Schema[Path][Method]>, ErrorOnly, Redirect>,
+> = Omit<ResponseInit, 'headers' | 'status'> &
+  (StatusCode extends StatusCode ? FetchResponseInitPerStatusCode<Default<Schema[Path][Method]>, StatusCode> : never);
+
+/** @see {@link https://zimic.dev/docs/fetch/api/fetch-response `FetchResponse` API reference} */
+export interface FetchResponseConstructor {
+  new <
+    Schema extends HttpSchema,
+    Method extends HttpSchemaMethod<Schema>,
+    Path extends HttpSchemaPath.Literal<Schema, Method>,
+    /** @deprecated The type parameter `ErrorOnly` will be removed in the next major version. */
+    ErrorOnly extends boolean = false,
+    Redirect extends RequestRedirect = 'follow',
+    StatusCode extends FetchResponseStatusCode<Default<Schema[Path][Method]>, ErrorOnly, Redirect> =
+      FetchResponseStatusCode<Default<Schema[Path][Method]>, ErrorOnly, Redirect>,
+  >(
+    fetchRequest: FetchRequest<Schema, Method, Path>,
+    response?: Response,
+  ): FetchResponse<Schema, Method, Path, ErrorOnly, Redirect, StatusCode>;
+  new <
+    Schema extends HttpSchema,
+    Method extends HttpSchemaMethod<Schema>,
+    Path extends HttpSchemaPath.Literal<Schema, Method>,
+    /** @deprecated The type parameter `ErrorOnly` will be removed in the next major version. */
+    ErrorOnly extends boolean = false,
+    Redirect extends RequestRedirect = 'follow',
+    StatusCode extends FetchResponseStatusCode<Default<Schema[Path][Method]>, ErrorOnly, Redirect> =
+      FetchResponseStatusCode<Default<Schema[Path][Method]>, ErrorOnly, Redirect>,
+  >(
+    fetchRequest: FetchRequest<Schema, Method, Path>,
+    body?: FetchResponseBodySchema<Default<Default<Default<Schema[Path][Method]>['response']>[StatusCode]>>,
+    init?: FetchResponseInit<Schema, Method, Path, ErrorOnly, Redirect, StatusCode>,
+  ): FetchResponse<Schema, Method, Path, ErrorOnly, Redirect, StatusCode>;
+
+  [Symbol.hasInstance]: (instance: unknown) => boolean;
+}
+
+/** @see {@link https://zimic.dev/docs/fetch/api/fetch-response#responsetoobject `response.toObject()`} */
+export type FetchResponseObject = Pick<
+  FetchResponse.Loose,
+  'url' | 'type' | 'status' | 'statusText' | 'ok' | 'redirected'
+> & {
+  headers: HttpHeadersSerialized<HttpHeadersSchema>;
+  body?: HttpBody | null;
+};

package/src/client/types/public.ts

@@ -1,14 +1,49 @@
 import { HttpSchemaPath, HttpSchemaMethod, LiteralHttpSchemaPathFromNonLiteral, HttpSchema } from '@zimic/http';
 import { PossiblePromise, RequiredByKey } from '@zimic/utils/types';
 
-import FetchResponseError from '../errors/FetchResponseError';
-import { FetchRequest, FetchRequestConstructor, FetchRequestInit, FetchResponse } from './requests';
+import { FetchRequest } from '../request/FetchRequest';
+import { FetchRequestInit } from '../request/types';
+import FetchResponseError from '../response/error/FetchResponseError';
+import { FetchResponse } from '../response/FetchResponse';
+
+/** @see {@link https://zimic.dev/docs/fetch/api/fetch#fetchrequest `fetch.Request` API reference} */
+export interface FetchRequestConstructor<Schema extends HttpSchema> {
+  new <
+    Method extends HttpSchemaMethod<Schema>,
+    Path extends HttpSchemaPath.NonLiteral<Schema, Method>,
+    Redirect extends RequestRedirect = 'follow',
+  >(
+    input: Path | URL,
+    init: FetchRequestInit<Schema, Method, LiteralHttpSchemaPathFromNonLiteral<Schema, Method, Path>, Redirect>,
+  ): FetchRequest<Schema, Method, LiteralHttpSchemaPathFromNonLiteral<Schema, Method, Path>>;
+
+  new <
+    Method extends HttpSchemaMethod<Schema>,
+    Path extends HttpSchemaPath.NonLiteral<Schema, Method>,
+    Redirect extends RequestRedirect = 'follow',
+  >(
+    input: FetchRequest<Schema, Method, LiteralHttpSchemaPathFromNonLiteral<Schema, Method, Path>>,
+    init?: Omit<
+      FetchRequestInit<Schema, Method, LiteralHttpSchemaPathFromNonLiteral<Schema, Method, Path>, Redirect>,
+      'baseURL' | 'searchParams'
+    >,
+  ): FetchRequest<Schema, Method, LiteralHttpSchemaPathFromNonLiteral<Schema, Method, Path>>;
+
+  new <
+    Method extends HttpSchemaMethod<Schema>,
+    Path extends HttpSchemaPath.NonLiteral<Schema, Method>,
+    Redirect extends RequestRedirect = 'follow',
+  >(
+    input: FetchInput<Schema, Method, Path>,
+    init?: FetchRequestInit<Schema, Method, LiteralHttpSchemaPathFromNonLiteral<Schema, Method, Path>, Redirect>,
+  ): FetchRequest<Schema, Method, LiteralHttpSchemaPathFromNonLiteral<Schema, Method, Path>>;
+}
 
 /** @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 extends HttpSchemaPath<Schema, Method>,
 > = Path | URL | FetchRequest<Schema, Method, LiteralHttpSchemaPathFromNonLiteral<Schema, Method, Path>>;
 
 /** @see {@link https://zimic.dev/docs/fetch/api/fetch `fetch` API reference} */

package/src/client/utils/objects.ts

@@ -0,0 +1,71 @@
+import { parseHttpBody } from '@zimic/http';
+import { PossiblePromise } from '@zimic/utils/types';
+
+import { FetchRequestObject } from '../request/types';
+import { FetchResponseObject } from '../response/types';
+
+const BODY_METHOD = ['json', 'formData', 'text', 'arrayBuffer', 'blob', 'bytes'] satisfies (keyof Body)[];
+type BodyMethod = (typeof BODY_METHOD)[number];
+
+export function isBodyMethod(property: string | symbol, value: unknown): value is Body[BodyMethod] {
+  return BODY_METHOD.includes(property as BodyMethod) && typeof value === 'function';
+}
+
+export function getOrSetBoundBodyMethod(
+  resource: Request | Response,
+  property: string | symbol,
+  value: Body[BodyMethod],
+) {
+  // We cache the bound function on the proxy instance to avoid re-binding it on every access.
+  const isValueAlreadyBound = Object.prototype.hasOwnProperty.call(resource, property);
+
+  if (isValueAlreadyBound) {
+    return value;
+  }
+
+  const boundValue = value.bind(resource) as unknown;
+
+  Object.defineProperty(resource, property, {
+    value: boundValue,
+    configurable: true,
+    enumerable: false,
+    writable: true,
+  });
+
+  return boundValue;
+}
+
+export function withIncludedBodyIfAvailable(
+  resource: Request,
+  resourceObject: FetchRequestObject,
+): PossiblePromise<FetchRequestObject>;
+export function withIncludedBodyIfAvailable(
+  resource: Response,
+  resourceObject: FetchResponseObject,
+): PossiblePromise<FetchResponseObject>;
+export function withIncludedBodyIfAvailable(
+  resource: Request | Response,
+  resourceObject: FetchRequestObject | FetchResponseObject,
+): PossiblePromise<FetchRequestObject | FetchResponseObject> {
+  const resourceType = resource instanceof Request ? 'request' : 'response';
+
+  if (resource.bodyUsed) {
+    console.warn(
+      '[@zimic/fetch]',
+      `Could not include the ${resourceType} body because it is already used. ` +
+        'If you access the body before calling `toObject()`, consider reading it from a cloned ' +
+        `${resourceType}.\n\nLearn more: https://zimic.dev/docs/fetch/api/fetch-response-error#errortoobject`,
+    );
+    return resourceObject;
+  }
+
+  return parseHttpBody(resource.clone())
+    .then((body) => {
+      resourceObject.body = body;
+      return resourceObject;
+    })
+    .catch((error: unknown) => {
+      console.error('[@zimic/fetch]', `Failed to parse ${resourceType} body:`, error);
+      return resourceObject;
+    });
+}

package/src/index.ts

@@ -1,18 +1,27 @@
 export type { JSONStringified } from '@zimic/utils/types';
 
-export type { Fetch, InferFetchSchema, FetchOptions, FetchDefaults, FetchInput } from './client/types/public';
-
 export type {
+  Fetch,
+  InferFetchSchema,
+  FetchOptions,
+  FetchDefaults,
+  FetchInput,
   FetchRequestConstructor,
-  FetchRequest,
-  FetchRequestObject,
-  FetchRequestInit,
-  FetchResponse,
-  FetchResponsePerStatusCode,
+} from './client/types/public';
+
+export { FetchRequest } from './client/request/FetchRequest';
+export type { FetchRequestInit, FetchRequestObject } from './client/request/types';
+
+export { FetchResponse } from './client/response/FetchResponse';
+export type { FetchResponsePerStatusCode } from './client/response/FetchResponse';
+export type {
   FetchResponseObject,
-} from './client/types/requests';
+  FetchResponseConstructor,
+  FetchResponseInit,
+  FetchResponseStatusCode,
+} from './client/response/types';
 
-export { default as FetchResponseError } from './client/errors/FetchResponseError';
-export type { FetchResponseErrorObject, FetchResponseErrorObjectOptions } from './client/errors/FetchResponseError';
+export { default as FetchResponseError } from './client/response/error/FetchResponseError';
+export type { FetchResponseErrorObject, FetchResponseErrorObjectOptions } from './client/response/error/types';
 
 export { default as createFetch } from './client/factory';

package/src/client/errors/FetchResponseError.ts

@@ -1,185 +0,0 @@
-import {
-  HttpHeaders,
-  HttpHeadersSchema,
-  HttpSchema,
-  HttpSchemaMethod,
-  HttpSchemaPath,
-  parseHttpBody,
-} from '@zimic/http';
-import { PossiblePromise } from '@zimic/utils/types';
-
-import { FetchRequest, FetchRequestObject, FetchResponse, FetchResponseObject } from '../types/requests';
-
-/** @see {@link https://zimic.dev/docs/fetch/api/fetch-response-error#errortoobject `fetchResponseError.toObject()` API reference} */
-export interface FetchResponseErrorObjectOptions {
-  /** @see {@link https://zimic.dev/docs/fetch/api/fetch-response-error#errortoobject `fetchResponseError.toObject()` API reference} */
-  includeRequestBody?: boolean;
-  /** @see {@link https://zimic.dev/docs/fetch/api/fetch-response-error#errortoobject `fetchResponseError.toObject()` API reference} */
-  includeResponseBody?: boolean;
-}
-
-export namespace FetchResponseErrorObjectOptions {
-  /**
-   * Options for converting a {@link FetchResponseError `FetchResponseError`} into a plain object, including the body of
-   * the request and/or response.
-   */
-  export type WithBody = FetchResponseErrorObjectOptions &
-    ({ includeRequestBody: true } | { includeResponseBody: true });
-
-  /**
-   * Options for converting a {@link FetchResponseError `FetchResponseError`} into a plain object, excluding the body of
-   * the request and/or response.
-   */
-  export type WithoutBody = FetchResponseErrorObjectOptions &
-    ({ includeRequestBody?: false } | { includeResponseBody?: false });
-}
-
-/**
- * A plain object representation of a {@link FetchResponseError `FetchResponseError`}, compatible with JSON. It is useful
- * for serialization, debugging, and logging purposes.
- *
- * @see {@link https://zimic.dev/docs/fetch/api/fetch-response-error#errortoobject `fetchResponseError.toObject()` API reference}
- */
-export interface FetchResponseErrorObject {
-  name: string;
-  message: string;
-  request: FetchRequestObject;
-  response: FetchResponseObject;
-}
-
-/** @see {@link https://zimic.dev/docs/fetch/api/fetch-response-error `FetchResponseError` API reference} */
-class FetchResponseError<
-  Schema extends HttpSchema,
-  Method extends HttpSchemaMethod<Schema>,
-  Path extends HttpSchemaPath.Literal<Schema, Method>,
-> extends Error {
-  constructor(
-    public request: FetchRequest<Schema, Method, Path>,
-    public response: FetchResponse<Schema, Method, Path>,
-  ) {
-    super(`${request.method} ${request.url} failed with status ${response.status}: ${response.statusText}`);
-    this.name = 'FetchResponseError';
-  }
-
-  /** @see {@link https://zimic.dev/docs/fetch/api/fetch-response-error#errortoobject `fetchResponseError.toObject()` API reference} */
-  toObject(options: FetchResponseErrorObjectOptions.WithBody): Promise<FetchResponseErrorObject>;
-  toObject(options?: FetchResponseErrorObjectOptions.WithoutBody): FetchResponseErrorObject;
-  toObject(options?: FetchResponseErrorObjectOptions): PossiblePromise<FetchResponseErrorObject>;
-  toObject({
-    includeRequestBody = false,
-    includeResponseBody = false,
-  }: FetchResponseErrorObjectOptions = {}): PossiblePromise<FetchResponseErrorObject> {
-    const partialObject = {
-      name: this.name,
-      message: this.message,
-    } satisfies Partial<FetchResponseErrorObject>;
-
-    if (!includeRequestBody && !includeResponseBody) {
-      return {
-        ...partialObject,
-        request: this.requestToObject({ includeBody: false }),
-        response: this.responseToObject({ includeBody: false }),
-      };
-    }
-
-    return Promise.all([
-      Promise.resolve(this.requestToObject({ includeBody: includeRequestBody })),
-      Promise.resolve(this.responseToObject({ includeBody: includeResponseBody })),
-    ]).then(([request, response]) => ({ ...partialObject, request, response }));
-  }
-
-  private requestToObject(options: { includeBody: true }): Promise<FetchRequestObject>;
-  private requestToObject(options: { includeBody: false }): FetchRequestObject;
-  private requestToObject(options: { includeBody: boolean }): PossiblePromise<FetchRequestObject>;
-  private requestToObject(options: { includeBody: boolean }): PossiblePromise<FetchRequestObject> {
-    const request = this.request;
-
-    const requestObject: FetchRequestObject = {
-      url: request.url,
-      path: request.path,
-      method: request.method,
-      headers: this.convertHeadersToObject(request),
-      cache: request.cache,
-      destination: request.destination,
-      credentials: request.credentials,
-      integrity: request.integrity,
-      keepalive: request.keepalive,
-      mode: request.mode,
-      redirect: request.redirect,
-      referrer: request.referrer,
-      referrerPolicy: request.referrerPolicy,
-    };
-
-    if (!options.includeBody) {
-      return requestObject;
-    }
-
-    return this.withIncludedBodyIfAvailable('request', requestObject);
-  }
-
-  private responseToObject(options: { includeBody: true }): Promise<FetchResponseObject>;
-  private responseToObject(options: { includeBody: false }): FetchResponseObject;
-  private responseToObject(options: { includeBody: boolean }): PossiblePromise<FetchResponseObject>;
-  private responseToObject(options: { includeBody: boolean }): PossiblePromise<FetchResponseObject> {
-    const response = this.response;
-
-    const responseObject: FetchResponseObject = {
-      url: response.url,
-      type: response.type,
-      status: response.status,
-      statusText: response.statusText,
-      ok: response.ok,
-      headers: this.convertHeadersToObject(response),
-      redirected: response.redirected,
-    };
-
-    if (!options.includeBody) {
-      return responseObject;
-    }
-
-    return this.withIncludedBodyIfAvailable('response', responseObject);
-  }
-
-  private convertHeadersToObject(
-    resource: FetchRequest<Schema, Method, Path> | FetchResponse<Schema, Method, Path>,
-  ): HttpHeadersSchema {
-    return HttpHeaders.prototype.toObject.call(resource.headers) as HttpHeadersSchema;
-  }
-
-  private withIncludedBodyIfAvailable(
-    resourceType: 'request',
-    resourceObject: FetchRequestObject,
-  ): PossiblePromise<FetchRequestObject>;
-  private withIncludedBodyIfAvailable(
-    resourceType: 'response',
-    resourceObject: FetchResponseObject,
-  ): PossiblePromise<FetchResponseObject>;
-  private withIncludedBodyIfAvailable(
-    resourceType: 'request' | 'response',
-    resourceObject: FetchRequestObject | FetchResponseObject,
-  ): PossiblePromise<FetchRequestObject | FetchResponseObject> {
-    const resource = this[resourceType] as Request | Response;
-
-    if (resource.bodyUsed) {
-      console.warn(
-        '[@zimic/fetch]',
-        `Could not include the ${resourceType} body because it is already used. ` +
-          'If you access the body before calling `error.toObject()`, consider reading it from a cloned ' +
-          `${resourceType}.\n\nLearn more: https://zimic.dev/docs/fetch/api/fetch-response-error#errortoobject`,
-      );
-      return resourceObject;
-    }
-
-    return parseHttpBody(resource)
-      .then((body) => {
-        resourceObject.body = body;
-        return resourceObject;
-      })
-      .catch((error: unknown) => {
-        console.error('[@zimic/fetch]', `Failed to parse ${resourceType} body:`, error);
-        return resourceObject;
-      });
-  }
-}
-
-export default FetchResponseError;