@zimic/http 0.0.1-canary.2

package/src/formData/HttpFormData.ts

@@ -0,0 +1,300 @@
+import { ArrayItemIfArray, ReplaceBy } from '@/types/utils';
+import { fileEquals } from '@/utils/files';
+
+import { HttpFormDataSchema, HttpFormDataSchemaName } from './types';
+
+/**
+ * An extended 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.
+ *
+ * **IMPORTANT**: the input of `HttpFormData` and all of its internal types must be declared inline or as a type aliases
+ * (`type`). They cannot be interfaces.
+ *
+ * @example
+ *   import { HttpFormData } from '@zimic/http';
+ *
+ *   const formData = new HttpFormData<{
+ *     files: File[];
+ *     description?: string;
+ *   }>();
+ *
+ *   formData.append('file', new File(['content'], 'file.txt', { type: 'text/plain' }));
+ *   formData.append('description', 'My file');
+ *
+ *   const files = formData.getAll('file');
+ *   console.log(files); // [File { name: 'file.txt', type: 'text/plain' }]
+ *
+ *   const description = formData.get('description');
+ *   console.log(description); // 'My file'
+ *
+ * @see {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐http#httpformdata `HttpFormData` API reference}
+ */
+class HttpFormData<Schema extends HttpFormDataSchema = HttpFormDataSchema> extends FormData {
+  /** @see {@link https://developer.mozilla.org/docs/Web/API/FormData/set MDN Reference} */
+  set<Name extends HttpFormDataSchemaName<Schema>>(
+    name: Name,
+    value: Exclude<ArrayItemIfArray<NonNullable<Schema[Name]>>, Blob>,
+  ): void;
+  set<Name extends HttpFormDataSchemaName<Schema>>(
+    name: Name,
+    blob: Exclude<ArrayItemIfArray<NonNullable<Schema[Name]>>, string>,
+    fileName?: string,
+  ): void;
+  set<Name extends HttpFormDataSchemaName<Schema>>(
+    name: Name,
+    blobOrValue: ArrayItemIfArray<NonNullable<Schema[Name]>>,
+    fileName?: string,
+  ): void {
+    if (fileName === undefined) {
+      super.set(name, blobOrValue as Blob);
+    } else {
+      super.set(name, blobOrValue as Blob, fileName);
+    }
+  }
+
+  /** @see {@link https://developer.mozilla.org/docs/Web/API/FormData/append MDN Reference} */
+  append<Name extends HttpFormDataSchemaName<Schema>>(
+    name: Name,
+    value: Exclude<ArrayItemIfArray<NonNullable<Schema[Name]>>, Blob>,
+  ): void;
+  append<Name extends HttpFormDataSchemaName<Schema>>(
+    name: Name,
+    blob: Exclude<ArrayItemIfArray<NonNullable<Schema[Name]>>, string>,
+    fileName?: string,
+  ): void;
+  append<Name extends HttpFormDataSchemaName<Schema>>(
+    name: Name,
+    blobOrValue: ArrayItemIfArray<NonNullable<Schema[Name]>>,
+    fileName?: string,
+  ): void {
+    if (fileName === undefined) {
+      super.append(name, blobOrValue as Blob);
+    } else {
+      super.append(name, blobOrValue as Blob, fileName);
+    }
+  }
+
+  /**
+   * Get the value of the entry associated to a key name.
+   *
+   * If the key might have multiple values, use {@link HttpFormData#getAll} instead.
+   *
+   * @param name The name of the key to get the value of.
+   * @returns The value associated with the key name, or `null` if the key does not exist.
+   * @see {@link https://developer.mozilla.org/docs/Web/API/FormData/get MDN Reference}
+   */
+  get<Name extends HttpFormDataSchemaName.NonArray<Schema>>(
+    name: Name,
+  ): ReplaceBy<ReplaceBy<ArrayItemIfArray<Schema[Name]>, undefined, null>, Blob, File> {
+    return super.get(name) as ReplaceBy<ReplaceBy<ArrayItemIfArray<Schema[Name]>, undefined, null>, Blob, File>;
+  }
+
+  /**
+   * Get all the values of the entry associated with a key name.
+   *
+   * If the key has at most a single value, use {@link HttpFormData#get} instead.
+   *
+   * @param name The name of the key to get the values of.
+   * @returns An array of values associated with the key name, or an empty array if the key does not exist.
+   * @see {@link https://developer.mozilla.org/docs/Web/API/FormData/getAll MDN Reference}
+   */
+  getAll<Name extends HttpFormDataSchemaName.Array<Schema>>(
+    name: Name,
+  ): ReplaceBy<ArrayItemIfArray<NonNullable<Schema[Name]>>, Blob, File>[] {
+    return super.getAll(name) as ReplaceBy<ArrayItemIfArray<NonNullable<Schema[Name]>>, Blob, File>[];
+  }
+
+  /** @see {@link https://developer.mozilla.org/docs/Web/API/FormData/has MDN Reference} */
+  has<Name extends HttpFormDataSchemaName<Schema>>(name: Name): boolean {
+    return super.has(name);
+  }
+
+  /** @see {@link https://developer.mozilla.org/docs/Web/API/FormData/delete MDN Reference} */
+  delete<Name extends HttpFormDataSchemaName<Schema>>(name: Name): void {
+    super.delete(name);
+  }
+
+  forEach<This extends HttpFormData<Schema>>(
+    callback: <Key extends HttpFormDataSchemaName<Schema>>(
+      value: ReplaceBy<ArrayItemIfArray<NonNullable<Schema[Key]>>, Blob, File>,
+      key: Key,
+      parent: HttpFormData<Schema>,
+    ) => void,
+    thisArg?: This,
+  ): void {
+    super.forEach(callback as (value: FormDataEntryValue, key: string, parent: FormData) => void, thisArg);
+  }
+
+  /** @see {@link https://developer.mozilla.org/docs/Web/API/FormData/keys MDN Reference} */
+  keys(): FormDataIterator<HttpFormDataSchemaName<Schema>> {
+    return super.keys() as FormDataIterator<HttpFormDataSchemaName<Schema>>;
+  }
+
+  /** @see {@link https://developer.mozilla.org/docs/Web/API/FormData/values MDN Reference} */
+  values(): FormDataIterator<
+    ReplaceBy<ArrayItemIfArray<NonNullable<Schema[HttpFormDataSchemaName<Schema>]>>, Blob, File>
+  > {
+    return super.values() as FormDataIterator<
+      ReplaceBy<ArrayItemIfArray<NonNullable<Schema[HttpFormDataSchemaName<Schema>]>>, Blob, File>
+    >;
+  }
+
+  /** @see {@link https://developer.mozilla.org/docs/Web/API/FormData/entries MDN Reference} */
+  entries(): FormDataIterator<
+    [
+      HttpFormDataSchemaName<Schema>,
+      ReplaceBy<ArrayItemIfArray<NonNullable<Schema[HttpFormDataSchemaName<Schema>]>>, Blob, File>,
+    ]
+  > {
+    return super.entries() as FormDataIterator<
+      [
+        HttpFormDataSchemaName<Schema>,
+        ReplaceBy<ArrayItemIfArray<NonNullable<Schema[HttpFormDataSchemaName<Schema>]>>, Blob, File>,
+      ]
+    >;
+  }
+
+  [Symbol.iterator](): FormDataIterator<
+    [
+      HttpFormDataSchemaName<Schema>,
+      ReplaceBy<ArrayItemIfArray<NonNullable<Schema[HttpFormDataSchemaName<Schema>]>>, Blob, File>,
+    ]
+  > {
+    return super[Symbol.iterator]() as FormDataIterator<
+      [
+        HttpFormDataSchemaName<Schema>,
+        ReplaceBy<ArrayItemIfArray<NonNullable<Schema[HttpFormDataSchemaName<Schema>]>>, Blob, File>,
+      ]
+    >;
+  }
+
+  /**
+   * Checks if the data is equal to the other data. Equality is defined as having the same keys and values, regardless
+   * of the order of keys.
+   *
+   * @param otherData The other data to compare.
+   * @returns A promise that resolves with `true` if the data is equal to the other data, or `false` otherwise.
+   *   Important: both form data might be read while comparing.
+   */
+  async equals<OtherSchema extends Schema>(otherData: HttpFormData<OtherSchema>): Promise<boolean> {
+    for (const [otherKey, otherValue] of otherData.entries()) {
+      const values = super.getAll.call(this, otherKey);
+
+      const haveSameNumberOfValues = values.length === super.getAll.call(otherData, otherKey).length;
+      if (!haveSameNumberOfValues) {
+        return false;
+      }
+
+      let valueExists = false;
+
+      for (const value of values) {
+        if (
+          value === otherValue ||
+          (value instanceof Blob && otherValue instanceof Blob && (await fileEquals(value, otherValue)))
+        ) {
+          valueExists = true;
+          break;
+        }
+      }
+
+      if (!valueExists) {
+        return false;
+      }
+    }
+
+    for (const key of this.keys()) {
+      const otherHasKey = super.has.call(otherData, key);
+      if (!otherHasKey) {
+        return false;
+      }
+    }
+
+    return true;
+  }
+
+  /**
+   * Checks if the data contains the other data. This method is less strict than {@link HttpFormData#equals} and only
+   * requires that all keys and values in the other data are present in this data.
+   *
+   * @param otherData The other data to compare.
+   * @returns A promise that resolves with `true` if this data contains the other data, or `false` otherwise. Important:
+   *   both form data might be read while comparing.
+   */
+  async contains<OtherSchema extends Schema>(otherData: HttpFormData<OtherSchema>): Promise<boolean> {
+    for (const [otherKey, otherValue] of otherData.entries()) {
+      const values = super.getAll.call(this, otherKey);
+
+      const haveCompatibleNumberOfValues = values.length >= super.getAll.call(otherData, otherKey).length;
+      if (!haveCompatibleNumberOfValues) {
+        return false;
+      }
+
+      let valueExists = false;
+
+      for (const value of values) {
+        if (
+          value === otherValue ||
+          (typeof value === 'string' && typeof otherValue === 'string' && value === otherValue) ||
+          (value instanceof Blob && otherValue instanceof Blob && (await fileEquals(value, otherValue)))
+        ) {
+          valueExists = true;
+          break;
+        }
+      }
+
+      if (!valueExists) {
+        return false;
+      }
+    }
+
+    return true;
+  }
+
+  /**
+   * Converts this form data into a plain object. This method is useful for serialization and debugging purposes.
+   *
+   * **NOTE**: If a key has multiple values, the object will contain an array of values for that key. If the key has
+   * only one value, the object will contain its value directly, without an array, regardless of how the value was
+   * initialized when creating the form data.
+   *
+   * @example
+   *   const formData = new HttpFormData<{
+   *     title: string;
+   *     descriptions: string[];
+   *     content: Blob;
+   *   }>();
+   *
+   *   formData.set('title', 'My title');
+   *   formData.append('descriptions', 'Description 1');
+   *   formData.append('descriptions', 'Description 2');
+   *   formData.set('content', new Blob(['content'], { type: 'text/plain' }));
+   *
+   *   const object = formData.toObject();
+   *   console.log(object); // { title: 'My title', descriptions: ['Description 1', 'Description 2'], content: Blob { type: 'text/plain' } }
+   *
+   * @returns A plain object representation of this form data.
+   */
+  toObject() {
+    const object = {} as Schema;
+
+    type SchemaValue = Schema[HttpFormDataSchemaName<Schema>];
+
+    for (const [key, value] of this.entries()) {
+      if (key in object) {
+        const existingValue = object[key];
+
+        if (Array.isArray<SchemaValue>(existingValue)) {
+          existingValue.push(value as SchemaValue);
+        } else {
+          object[key] = [existingValue, value] as SchemaValue;
+        }
+      } else {
+        object[key] = value as SchemaValue;
+      }
+    }
+
+    return object;
+  }
+}
+
+export default HttpFormData;

package/src/formData/types.ts

@@ -0,0 +1,110 @@
+import { ArrayKey, IfNever, NonArrayKey } from '@/types/utils';
+
+/** A schema for strict HTTP form data. */
+export interface HttpFormDataSchema {
+  [fieldName: string]: string | string[] | Blob | Blob[] | null | undefined;
+}
+
+export namespace HttpFormDataSchema {
+  /** A schema for loose HTTP form data. Field values are not strictly typed. */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  export type Loose = Record<string, any>;
+}
+
+export namespace HttpFormDataSchemaName {
+  /** Extracts the names of the form data fields defined in a {@link HttpFormDataSchema} that are arrays. */
+  export type Array<Schema extends HttpFormDataSchema> = IfNever<Schema, never, ArrayKey<Schema> & string>;
+
+  /** Extracts the names of the form data fields defined in a {@link HttpFormDataSchema} that are not arrays. */
+  export type NonArray<Schema extends HttpFormDataSchema> = IfNever<Schema, never, NonArrayKey<Schema> & string>;
+}
+
+/**
+ * Extracts the names of the form data fields defined in a {@link HttpFormDataSchema}. Each key is considered a field
+ * name. `HttpFormDataSchemaName.Array` can be used to extract the names of array form data fields, whereas
+ * `HttpFormDataSchemaName.NonArray` extracts the names of non-array form data fields.
+ *
+ * @example
+ *   import { type HttpFormDataSchemaName } from '@zimic/http';
+ *
+ *   type FormDataName = HttpFormDataSchemaName<{
+ *     title: string;
+ *     descriptions: string[];
+ *     content: Blob;
+ *   }>;
+ *   // "title" | "descriptions" | "content"
+ *
+ *   type ArrayFormDataName = HttpFormDataSchemaName.Array<{
+ *     title: string;
+ *     descriptions: string[];
+ *     content: Blob;
+ *   }>;
+ *   // "descriptions"
+ *
+ *   type NonArrayFormDataName = HttpFormDataSchemaName.NonArray<{
+ *     title: string;
+ *     descriptions: string[];
+ *     content: Blob;
+ *   }>;
+ *   // "title" | "content"
+ */
+export type HttpFormDataSchemaName<Schema extends HttpFormDataSchema> = IfNever<Schema, never, keyof Schema & string>;
+
+type PrimitiveHttpFormDataSerialized<Type> = Type extends HttpFormDataSchema[string]
+  ? Type
+  : Type extends (infer ArrayItem)[]
+    ? ArrayItem extends (infer _InternalArrayItem)[]
+      ? never
+      : PrimitiveHttpFormDataSerialized<ArrayItem>[]
+    : Type extends number
+      ? `${number}`
+      : Type extends boolean
+        ? `${boolean}`
+        : never;
+
+/**
+ * Recursively converts a schema to its {@link https://developer.mozilla.org/docs/Web/API/FormData FormData}-serialized
+ * version. Numbers and booleans are converted to `${number}` and `${boolean}` respectively, and not serializable values
+ * are excluded, such as functions and dates.
+ *
+ * @example
+ *   import { type HttpFormDataSerialized } from '@zimic/http';
+ *
+ *   type Schema = HttpFormDataSerialized<{
+ *     contentTitle: string | null;
+ *     contentSize: number;
+ *     content: Blob;
+ *     full?: boolean;
+ *     date: Date;
+ *     method: () => void;
+ *   }>;
+ *   // {
+ *   //   contentTitle: string | null;
+ *   //   contentSize? `${number}`;
+ *   //   content: Blob;
+ *   //   full?: "false" | "true";
+ *   // }
+ */
+export type HttpFormDataSerialized<Type> = Type extends HttpFormDataSchema
+  ? Type
+  : Type extends (infer _ArrayItem)[]
+    ? never
+    : Type extends Date
+      ? never
+      : Type extends (...parameters: never[]) => unknown
+        ? never
+        : Type extends symbol
+          ? never
+          : Type extends Map<infer _Key, infer _Value>
+            ? never
+            : Type extends Set<infer _Value>
+              ? never
+              : Type extends object
+                ? {
+                    [Key in keyof Type as IfNever<
+                      PrimitiveHttpFormDataSerialized<Type[Key]>,
+                      never,
+                      Key
+                    >]: PrimitiveHttpFormDataSerialized<Type[Key]>;
+                  }
+                : never;

package/src/headers/HttpHeaders.ts

@@ -0,0 +1,217 @@
+import { Default, ReplaceBy } from '@/types/utils';
+
+import { HttpHeadersSchema, HttpHeadersInit, HttpHeadersSchemaName } from './types';
+
+function pickPrimitiveProperties<Schema extends HttpHeadersSchema>(schema: Schema) {
+  return Object.entries(schema).reduce<Record<string, string>>((accumulated, [key, value]) => {
+    if (value !== undefined) {
+      accumulated[key] = value;
+    }
+    return accumulated;
+  }, {});
+}
+
+/**
+ * An extended 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.
+ *
+ * **IMPORTANT**: the input of `HttpHeaders` and all of its internal types must be declared inline or as a type aliases
+ * (`type`). They cannot be interfaces.
+ *
+ * @example
+ *   import { HttpHeaders } from '@zimic/http';
+ *
+ *   const headers = new HttpHeaders<{
+ *     accept?: string;
+ *     'content-type'?: string;
+ *   }>({
+ *     accept: '*',
+ *     'content-type': 'application/json',
+ *   });
+ *
+ *   const contentType = headers.get('content-type');
+ *   console.log(contentType); // 'application/json'
+ *
+ * @see {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐http#httpheaders `HttpHeaders` API reference}
+ */
+class HttpHeaders<Schema extends HttpHeadersSchema = HttpHeadersSchema> extends Headers {
+  constructor(init?: HttpHeadersInit<Schema>) {
+    if (init instanceof Headers || Array.isArray(init) || !init) {
+      super(init);
+    } else {
+      super(pickPrimitiveProperties(init));
+    }
+  }
+
+  /** @see {@link https://developer.mozilla.org/docs/Web/API/Headers/set MDN Reference} */
+  set<Name extends HttpHeadersSchemaName<Schema>>(name: Name, value: NonNullable<Schema[Name]>): void {
+    super.set(name, value);
+  }
+
+  /** @see {@link https://developer.mozilla.org/docs/Web/API/Headers/append MDN Reference} */
+  append<Name extends HttpHeadersSchemaName<Schema>>(name: Name, value: NonNullable<Schema[Name]>): void {
+    super.append(name, value);
+  }
+
+  /** @see {@link https://developer.mozilla.org/docs/Web/API/Headers/get MDN Reference} */
+  get<Name extends HttpHeadersSchemaName<Schema>>(name: Name): ReplaceBy<Schema[Name], undefined, null> {
+    return super.get(name) as ReplaceBy<Schema[Name], undefined, null>;
+  }
+
+  /** @see {@link https://developer.mozilla.org/docs/Web/API/Headers/has MDN Reference} */
+  getSetCookie(): NonNullable<Default<Schema['Set-Cookie'], string>>[] {
+    return super.getSetCookie() as NonNullable<Default<Schema['Set-Cookie'], string>>[];
+  }
+
+  /** @see {@link https://developer.mozilla.org/docs/Web/API/Headers/has MDN Reference} */
+  has<Name extends HttpHeadersSchemaName<Schema>>(name: Name): boolean {
+    return super.has(name);
+  }
+
+  /** @see {@link https://developer.mozilla.org/docs/Web/API/Headers/delete MDN Reference} */
+  delete<Name extends HttpHeadersSchemaName<Schema>>(name: Name): void {
+    super.delete(name);
+  }
+
+  forEach<This extends HttpHeaders<Schema>>(
+    callback: <Key extends HttpHeadersSchemaName<Schema>>(
+      value: NonNullable<Schema[Key]>,
+      key: Key,
+      parent: Headers,
+    ) => void,
+    thisArg?: This,
+  ): void {
+    super.forEach(callback as (value: string, key: string, parent: Headers) => void, thisArg);
+  }
+
+  /** @see {@link https://developer.mozilla.org/docs/Web/API/Headers/keys MDN Reference} */
+  keys(): HeadersIterator<HttpHeadersSchemaName<Schema>> {
+    return super.keys() as HeadersIterator<HttpHeadersSchemaName<Schema>>;
+  }
+
+  /** @see {@link https://developer.mozilla.org/docs/Web/API/Headers/values MDN Reference} */
+  values(): HeadersIterator<NonNullable<Schema[HttpHeadersSchemaName<Schema>]>> {
+    return super.values() as HeadersIterator<NonNullable<Schema[HttpHeadersSchemaName<Schema>]>>;
+  }
+
+  /** @see {@link https://developer.mozilla.org/docs/Web/API/Headers/entries MDN Reference} */
+  entries(): HeadersIterator<[HttpHeadersSchemaName<Schema>, NonNullable<Schema[HttpHeadersSchemaName<Schema>]>]> {
+    return super.entries() as HeadersIterator<
+      [HttpHeadersSchemaName<Schema>, NonNullable<Schema[HttpHeadersSchemaName<Schema>]>]
+    >;
+  }
+
+  [Symbol.iterator](): HeadersIterator<
+    [HttpHeadersSchemaName<Schema>, NonNullable<Schema[HttpHeadersSchemaName<Schema>]>]
+  > {
+    return super[Symbol.iterator]() as HeadersIterator<
+      [HttpHeadersSchemaName<Schema>, NonNullable<Schema[HttpHeadersSchemaName<Schema>]>]
+    >;
+  }
+
+  /**
+   * Checks if this headers object is equal to another set of headers. Equality is defined as having the same keys and
+   * values, regardless of the order of keys.
+   *
+   * @param otherHeaders The other headers object to compare against.
+   * @returns `true` if the headers are equal, `false` otherwise.
+   */
+  equals<OtherSchema extends Schema>(otherHeaders: HttpHeaders<OtherSchema>): boolean {
+    for (const [key, otherValue] of otherHeaders.entries()) {
+      const value = super.get.call(this, key);
+
+      if (value === null) {
+        return false;
+      }
+
+      const valueItems = this.splitHeaderValues(value);
+      const otherValueItems = this.splitHeaderValues(otherValue);
+
+      const haveCompatibleNumberOfValues = valueItems.length === otherValueItems.length;
+      if (!haveCompatibleNumberOfValues) {
+        return false;
+      }
+
+      for (const otherValueItem of otherValueItems) {
+        if (!valueItems.includes(otherValueItem)) {
+          return false;
+        }
+      }
+    }
+
+    for (const key of this.keys()) {
+      const otherHasKey = super.has.call(otherHeaders, key);
+      if (!otherHasKey) {
+        return false;
+      }
+    }
+
+    return true;
+  }
+
+  /**
+   * Checks if this headers object contains another set of headers. This method is less strict than
+   * {@link HttpHeaders#equals} and only requires that all keys and values in the other headers are present in these
+   * headers.
+   *
+   * @param otherHeaders The other headers object to compare against.
+   * @returns `true` if these headers contain the other headers, `false` otherwise.
+   */
+  contains<OtherSchema extends Schema>(otherHeaders: HttpHeaders<OtherSchema>): boolean {
+    for (const [key, otherValue] of otherHeaders.entries()) {
+      const value = super.get.call(this, key);
+
+      if (value === null) {
+        return false;
+      }
+
+      const valueItems = this.splitHeaderValues(value);
+      const otherValueItems = this.splitHeaderValues(otherValue);
+
+      const haveCompatibleNumberOfValues = valueItems.length >= otherValueItems.length;
+      if (!haveCompatibleNumberOfValues) {
+        return false;
+      }
+
+      for (const otherValueItem of otherValueItems) {
+        if (!valueItems.includes(otherValueItem)) {
+          return false;
+        }
+      }
+    }
+
+    return true;
+  }
+
+  /**
+   * Converts these headers into a plain object. This method is useful for serialization and debugging purposes.
+   *
+   * @example
+   *   const headers = new HttpHeaders({
+   *     accept: 'application/json',
+   *     'content-type': 'application/json',
+   *   });
+   *   const object = headers.toObject();
+   *   console.log(object); // { accept: 'application/json', 'content-type': 'application/json' }
+   *
+   * @returns A plain object representation of these headers.
+   */
+  toObject(): Schema {
+    const object = {} as Schema;
+
+    for (const [key, value] of this.entries()) {
+      object[key] = value;
+    }
+
+    return object;
+  }
+
+  private splitHeaderValues(value: string) {
+    return value
+      .split(',')
+      .map((item) => item.trim())
+      .filter((item) => item.length > 0);
+  }
+}
+
+export default HttpHeaders;

package/src/headers/types.ts

@@ -0,0 +1,65 @@
+import { IfNever } from '@/types/utils';
+
+import { HttpPathParamsSerialized } from '../pathParams/types';
+import HttpHeaders from './HttpHeaders';
+
+/** A schema for strict HTTP headers. */
+export interface HttpHeadersSchema {
+  [headerName: string]: string | undefined;
+}
+
+export namespace HttpHeadersSchema {
+  /** A schema for loose HTTP headers. Header values are not strictly typed. */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  export type Loose = Record<string, any>;
+}
+
+/** A strict tuple representation of a {@link HttpHeadersSchema}. */
+export type HttpHeadersSchemaTuple<Schema extends HttpHeadersSchema = HttpHeadersSchema> = {
+  [Key in keyof Schema & string]: [Key, NonNullable<Schema[Key]>];
+}[keyof Schema & string];
+
+/** An initialization value for {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐http#httpheaders `HttpHeaders`}. */
+export type HttpHeadersInit<Schema extends HttpHeadersSchema = HttpHeadersSchema> =
+  | Headers
+  | Schema
+  | HttpHeaders<Schema>
+  | HttpHeadersSchemaTuple<Schema>[];
+
+/**
+ * Extracts the names of the headers defined in a {@link HttpHeadersSchema}. Each key is considered a header name.
+ *
+ * @example
+ *   import { type HttpHeadersSchemaName } from '@zimic/http';
+ *
+ *   type HeaderName = HttpHeadersSchemaName<{
+ *     'content-type': string;
+ *     'content-length'?: string;
+ *   }>;
+ *   // "content-type" | "content-length"
+ */
+export type HttpHeadersSchemaName<Schema extends HttpHeadersSchema> = IfNever<Schema, never, keyof Schema & string>;
+
+/**
+ * Recursively converts a schema to its
+ * {@link https://developer.mozilla.org/docs/Web/API/Headers HTTP headers}-serialized version. Numbers and booleans are
+ * converted to `${number}` and `${boolean}` respectively, null becomes undefined and not serializable values are
+ * excluded, such as functions and dates.
+ *
+ * @example
+ *   import { type HttpHeadersSerialized } from '@zimic/http';
+ *
+ *   type Params = HttpHeadersSerialized<{
+ *     'content-type': string;
+ *     'x-remaining-tries': number;
+ *     'x-full'?: boolean;
+ *     'x-date': Date;
+ *     method: () => void;
+ *   }>;
+ *   // {
+ *   //   'content-type': string;
+ *   //   'x-remaining-tries': `${number}`;
+ *   //   'x-full'?: "false" | "true";
+ *   // }
+ */
+export type HttpHeadersSerialized<Type> = HttpPathParamsSerialized<Type>;