@zimic/fetch 0.1.0-canary.0

package/src/client/types/public.ts

@@ -0,0 +1,83 @@
+import { HttpSchemaPath, HttpSchemaMethod, LiteralHttpSchemaPathFromNonLiteral, HttpSchema } from '@zimic/http';
+
+import { Default, PossiblePromise } from '@/types/utils';
+
+import FetchResponseError from '../errors/FetchResponseError';
+import { FetchRequest, FetchRequestConstructor, FetchRequestInit, FetchResponse } from './requests';
+
+export type FetchInput<
+  Schema extends HttpSchema,
+  Path extends HttpSchemaPath.NonLiteral<Schema, Method>,
+  Method extends HttpSchemaMethod<Schema>,
+> =
+  | Path
+  | URL
+  | FetchRequest<
+      LiteralHttpSchemaPathFromNonLiteral<Schema, Method, Path>,
+      Method,
+      Default<Schema[LiteralHttpSchemaPathFromNonLiteral<Schema, Method, Path>][Method]>
+    >;
+
+export interface FetchFunction<Schema extends HttpSchema> {
+  <Path extends HttpSchemaPath.NonLiteral<Schema, Method>, Method extends HttpSchemaMethod<Schema>>(
+    input: Path | URL,
+    init: FetchRequestInit<Schema, LiteralHttpSchemaPathFromNonLiteral<Schema, Method, Path>, Method>,
+  ): Promise<
+    FetchResponse<
+      LiteralHttpSchemaPathFromNonLiteral<Schema, Method, Path>,
+      Method,
+      Default<Schema[LiteralHttpSchemaPathFromNonLiteral<Schema, Method, Path>][Method]>
+    >
+  >;
+
+  <Path extends HttpSchemaPath.NonLiteral<Schema, Method>, Method extends HttpSchemaMethod<Schema>>(
+    input: FetchRequest<
+      LiteralHttpSchemaPathFromNonLiteral<Schema, Method, Path>,
+      Method,
+      Default<Schema[LiteralHttpSchemaPathFromNonLiteral<Schema, Method, Path>][Method]>
+    >,
+    init?: FetchRequestInit<Schema, LiteralHttpSchemaPathFromNonLiteral<Schema, Method, Path>, Method>,
+  ): Promise<
+    FetchResponse<
+      LiteralHttpSchemaPathFromNonLiteral<Schema, Method, Path>,
+      Method,
+      Default<Schema[LiteralHttpSchemaPathFromNonLiteral<Schema, Method, Path>][Method]>
+    >
+  >;
+}
+
+export interface FetchOptions<Schema extends HttpSchema> extends Omit<FetchRequestInit.Defaults, 'method'> {
+  onRequest?: (request: FetchRequest.Loose, fetch: Fetch<Schema>) => PossiblePromise<Request>;
+  onResponse?: (response: FetchResponse.Loose, fetch: Fetch<Schema>) => PossiblePromise<Response>;
+}
+
+export interface FetchClient<Schema extends HttpSchema> {
+  defaults: FetchRequestInit.Defaults;
+
+  Request: FetchRequestConstructor<Schema>;
+
+  onRequest?: FetchOptions<Schema>['onRequest'];
+  onResponse?: FetchOptions<Schema>['onResponse'];
+
+  isRequest: <Path extends HttpSchemaPath<Schema, Method>, Method extends HttpSchemaMethod<Schema>>(
+    request: unknown,
+    path: Path,
+    method: Method,
+  ) => request is FetchRequest<Path, Method, Default<Schema[Path][Method]>>;
+
+  isResponse: <Path extends HttpSchemaPath<Schema, Method>, Method extends HttpSchemaMethod<Schema>>(
+    response: unknown,
+    path: Path,
+    method: Method,
+  ) => response is FetchResponse<Path, Method, Default<Schema[Path][Method]>>;
+
+  isResponseError: <Path extends HttpSchemaPath<Schema, Method>, Method extends HttpSchemaMethod<Schema>>(
+    error: unknown,
+    path: Path,
+    method: Method,
+  ) => error is FetchResponseError<Path, Method, Default<Schema[Path][Method]>>;
+}
+
+export type Fetch<Schema extends HttpSchema> = FetchFunction<Schema> & FetchClient<Schema>;
+
+export type InferFetchSchema<FetchInstance> = FetchInstance extends Fetch<infer Schema> ? Schema : never;

package/src/client/types/requests.ts

@@ -0,0 +1,149 @@
+import {
+  HttpRequestSchema,
+  HttpMethod,
+  HttpSchema,
+  HttpSchemaPath,
+  HttpSchemaMethod,
+  HttpMethodSchema,
+  HttpResponseSchemaStatusCode,
+  HttpStatusCode,
+  HttpResponse,
+  HttpRequest,
+  HttpSearchParams,
+  HttpHeaders,
+  AllowAnyStringInPathParams,
+  LiteralHttpSchemaPathFromNonLiteral,
+  JSONValue,
+  HttpResponseBodySchema,
+  HttpResponseHeadersSchema,
+  HttpRequestHeadersSchema,
+} from '@zimic/http';
+
+import { Default, DefaultNoExclude, IfNever, ReplaceBy } from '@/types/utils';
+
+import FetchResponseError, { AnyFetchRequestError } from '../errors/FetchResponseError';
+import { JSONStringified } from './json';
+import { FetchInput } from './public';
+
+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']>> };
+
+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']>> };
+
+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']> }
+        : { body: RequestSchema['body'] };
+
+type FetchRequestInitPerPath<RequestSchema extends HttpRequestSchema> = FetchRequestInitWithHeaders<RequestSchema> &
+  FetchRequestInitWithSearchParams<RequestSchema> &
+  FetchRequestInitWithBody<RequestSchema>;
+
+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);
+
+export namespace FetchRequestInit {
+  export interface Defaults extends RequestInit {
+    baseURL: string;
+    method?: HttpMethod;
+    searchParams?: HttpSearchParams;
+  }
+}
+
+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>;
+
+export type HttpRequestBodySchema<MethodSchema extends HttpMethodSchema> = ReplaceBy<
+  ReplaceBy<IfNever<DefaultNoExclude<Default<MethodSchema['request']>['body']>, null>, undefined, null>,
+  ArrayBuffer,
+  Blob
+>;
+
+export interface FetchRequest<
+  Path extends string = string,
+  Method extends HttpMethod = HttpMethod,
+  MethodSchema extends HttpMethodSchema = HttpMethodSchema,
+> extends HttpRequest<HttpRequestBodySchema<MethodSchema>, HttpRequestHeadersSchema<MethodSchema>> {
+  path: AllowAnyStringInPathParams<Path>;
+  method: Method;
+}
+
+export namespace FetchRequest {
+  export interface Loose extends Request {
+    path: string;
+    method: HttpMethod;
+    clone: () => Loose;
+  }
+}
+
+export interface FetchResponsePerStatusCode<
+  Path extends string = string,
+  Method extends HttpMethod = HttpMethod,
+  MethodSchema extends HttpMethodSchema = HttpMethodSchema,
+  StatusCode extends HttpStatusCode = HttpStatusCode,
+> extends HttpResponse<
+    HttpResponseBodySchema<MethodSchema, StatusCode>,
+    StatusCode,
+    HttpResponseHeadersSchema<MethodSchema, StatusCode>
+  > {
+  request: FetchRequest<Path, Method, MethodSchema>;
+
+  error: StatusCode extends HttpStatusCode.ClientError | HttpStatusCode.ServerError
+    ? FetchResponseError<Path, Method, MethodSchema>
+    : null;
+}
+
+export type FetchResponse<
+  Path extends string = string,
+  Method extends HttpMethod = HttpMethod,
+  MethodSchema extends HttpMethodSchema = HttpMethodSchema,
+  ErrorOnly extends boolean = false,
+  StatusCode extends FetchResponseStatusCode<MethodSchema, ErrorOnly> = FetchResponseStatusCode<
+    MethodSchema,
+    ErrorOnly
+  >,
+> = StatusCode extends StatusCode ? FetchResponsePerStatusCode<Path, Method, MethodSchema, StatusCode> : never;
+
+export namespace FetchResponse {
+  export interface Loose extends Response {
+    request: FetchRequest.Loose;
+    error: AnyFetchRequestError | null;
+    clone: () => Loose;
+  }
+}
+
+export type FetchRequestConstructor<Schema extends HttpSchema> = new <
+  Path extends HttpSchemaPath.NonLiteral<Schema, Method>,
+  Method extends HttpSchemaMethod<Schema>,
+>(
+  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]>
+>;

package/src/index.ts

@@ -0,0 +1,13 @@
+export type {
+  Fetch,
+  FetchFunction,
+  FetchClient,
+  FetchOptions as FetchClientOptions,
+  FetchInput,
+} from './client/types/public';
+
+export type { FetchRequestInit, FetchRequest, FetchRequestConstructor, FetchResponse } from './client/types/requests';
+
+export { default as FetchResponseError } from './client/errors/FetchResponseError';
+
+export { default as createFetch } from './client/factory';

package/src/types/requests.ts

@@ -0,0 +1,99 @@
+import {
+  HttpFormData,
+  HttpFormDataSchema,
+  HttpHeaders,
+  HttpHeadersSchema,
+  HttpSearchParams,
+  HttpSearchParamsSchema,
+  JSONSerialized,
+  JSONValue,
+  HttpStatusCode,
+} from '@zimic/http';
+
+import { ReplaceBy } from '@/types/utils';
+
+/** The body type for HTTP requests and responses. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type HttpBody = JSONValue | HttpFormData<any> | HttpSearchParams<any> | Blob | ArrayBuffer;
+
+export namespace HttpBody {
+  /** A loose version of the HTTP body type. JSON values are not strictly typed. */
+  export type Loose = ReplaceBy<HttpBody, JSONValue, JSONValue.Loose>;
+
+  /** Convert a possibly loose HTTP body to be strictly typed. JSON values are serialized to their strict form. */
+  export type ConvertToStrict<Type> = Type extends Exclude<HttpBody, JSONValue> ? Type : JSONSerialized<Type>;
+}
+
+/**
+ * An HTTP headers object with a strictly-typed schema. Fully compatible with the built-in
+ * {@link https://developer.mozilla.org/docs/Web/API/Headers `Headers`} class.
+ */
+export type StrictHeaders<Schema extends HttpHeadersSchema = HttpHeadersSchema> = Pick<
+  HttpHeaders<Schema>,
+  keyof Headers
+>;
+
+/**
+ * An HTTP search params object with a strictly-typed schema. Fully compatible with the built-in
+ * {@link https://developer.mozilla.org/docs/Web/API/URLSearchParams `URLSearchParams`} class.
+ */
+export type StrictURLSearchParams<Schema extends HttpSearchParamsSchema = HttpSearchParamsSchema> = Pick<
+  HttpSearchParams<Schema>,
+  keyof URLSearchParams
+>;
+
+/**
+ * An HTTP form data object with a strictly-typed schema. Fully compatible with the built-in
+ * {@link https://developer.mozilla.org/docs/Web/API/FormData `FormData`} class.
+ */
+export type StrictFormData<Schema extends HttpFormDataSchema = HttpFormDataSchema> = Pick<
+  HttpFormData<Schema>,
+  keyof FormData
+>;
+
+/**
+ * An HTTP request with a strictly-typed JSON body. Fully compatible with the built-in
+ * {@link https://developer.mozilla.org/docs/Web/API/Request `Request`} class.
+ */
+export interface HttpRequest<
+  StrictBody extends HttpBody.Loose = HttpBody,
+  StrictHeadersSchema extends HttpHeadersSchema = HttpHeadersSchema,
+> extends Request {
+  headers: StrictHeaders<StrictHeadersSchema>;
+  text: () => Promise<StrictBody extends string ? StrictBody : string>;
+  json: () => Promise<StrictBody extends string | Exclude<HttpBody, JSONValue> ? never : StrictBody>;
+  formData: () => Promise<
+    StrictBody extends HttpFormData<infer HttpFormDataSchema>
+      ? StrictFormData<HttpFormDataSchema>
+      : StrictBody extends HttpSearchParams<infer HttpSearchParamsSchema>
+        ? StrictFormData<HttpSearchParamsSchema>
+        : FormData
+  >;
+  clone: () => this;
+}
+
+/**
+ * An HTTP response with a strictly-typed JSON body and status code. Fully compatible with the built-in
+ * {@link https://developer.mozilla.org/docs/Web/API/Response `Response`} class.
+ */
+export interface HttpResponse<
+  StrictBody extends HttpBody.Loose = HttpBody,
+  StatusCode extends number = number,
+  StrictHeadersSchema extends HttpHeadersSchema = HttpHeadersSchema,
+> extends Response {
+  ok: StatusCode extends HttpStatusCode.Information | HttpStatusCode.Success | HttpStatusCode.Redirection
+    ? true
+    : false;
+  status: StatusCode;
+  headers: StrictHeaders<StrictHeadersSchema>;
+  text: () => Promise<StrictBody extends string ? StrictBody : string>;
+  json: () => Promise<StrictBody extends string | Exclude<HttpBody, JSONValue> ? never : StrictBody>;
+  formData: () => Promise<
+    StrictBody extends HttpFormData<infer HttpFormDataSchema>
+      ? StrictFormData<HttpFormDataSchema>
+      : StrictBody extends HttpSearchParams<infer HttpSearchParamsSchema>
+        ? StrictFormData<HttpSearchParamsSchema>
+        : FormData
+  >;
+  clone: () => this;
+}

package/src/types/strings.d.ts

@@ -0,0 +1,9 @@
+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

@@ -0,0 +1,11 @@
+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/files.ts

@@ -0,0 +1,23 @@
+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;
+  }
+
+  /* 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;
+}

package/src/utils/imports.ts

@@ -0,0 +1,14 @@
+/* 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

@@ -0,0 +1,43 @@
+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('/');
+}