@zimic/http 0.0.1-canary.2

package/src/index.ts

@@ -0,0 +1,55 @@
+export type { JSONValue, JSONSerialized } from './types/json';
+
+export { default as HttpFormData } from './formData/HttpFormData';
+export type { HttpFormDataSchema, HttpFormDataSchemaName, HttpFormDataSerialized } from './formData/types';
+
+export type { HttpPathParamsSchema, HttpPathParamsSerialized } from './pathParams/types';
+
+export { default as HttpHeaders } from './headers/HttpHeaders';
+export type {
+  HttpHeadersInit,
+  HttpHeadersSchema,
+  HttpHeadersSchemaTuple,
+  HttpHeadersSchemaName,
+  HttpHeadersSerialized,
+} from './headers/types';
+
+export { default as HttpSearchParams } from './searchParams/HttpSearchParams';
+export type {
+  HttpSearchParamsInit,
+  HttpSearchParamsSchema,
+  HttpSearchParamsSchemaTuple,
+  HttpSearchParamsSchemaName,
+  HttpSearchParamsSerialized,
+} from './searchParams/types';
+
+export type {
+  HttpBody,
+  HttpRequest,
+  HttpResponse,
+  StrictHeaders,
+  StrictURLSearchParams,
+  StrictFormData,
+} from './types/requests';
+
+export type {
+  HttpSchema,
+  HttpMethod,
+  HttpMethodWithRequestBody,
+  HttpMethodWithResponseBody,
+  HttpStatusCode,
+  HttpRequestSchema,
+  HttpResponseSchema,
+  HttpResponseSchemaByStatusCode,
+  HttpResponseSchemaStatusCode,
+  HttpMethodSchema,
+  HttpMethodsSchema,
+  HttpSchemaMethod,
+  AllowAnyStringInPathParams,
+  LiteralHttpSchemaPathFromNonLiteral,
+  HttpSchemaPath,
+  InferPathParams,
+  MergeHttpResponsesByStatusCode,
+} from './types/schema';
+
+export { HTTP_METHODS, HTTP_METHODS_WITH_REQUEST_BODY, HTTP_METHODS_WITH_RESPONSE_BODY } from './types/schema';

package/src/pathParams/types.ts

@@ -0,0 +1,67 @@
+import { IfNever } from '@/types/utils';
+
+export interface HttpPathParamsSchema {
+  [paramName: string]: string | undefined;
+}
+
+export namespace HttpPathParamsSchema {
+  /** A schema for loose HTTP path parameters. Parameter values are not strictly typed. */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  export type Loose = Record<string, any>;
+}
+
+type PrimitiveHttpPathParamsSerialized<Type> = Type extends HttpPathParamsSchema[string]
+  ? Type
+  : Type extends (infer _ArrayItem)[]
+    ? never
+    : Type extends number
+      ? `${number}`
+      : Type extends boolean
+        ? `${boolean}`
+        : Type extends null
+          ? undefined
+          : never;
+/**
+ * Recursively converts a schema to its path parameters-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 HttpPathParamsSerialized } from '@zimic/http';
+ *
+ *   type Params = HttpPathParamsSerialized<{
+ *     userId: string;
+ *     notificationId: number | null;
+ *     full?: boolean;
+ *     from?: Date;
+ *     method: () => void;
+ *   }>;
+ *   // {
+ *   //   userId: string;
+ *   //   notificationId: `${number}` | undefined;
+ *   //   full?: "false" | "true";
+ *   // }
+ */
+export type HttpPathParamsSerialized<Type> = Type extends HttpPathParamsSchema
+  ? 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<
+                      PrimitiveHttpPathParamsSerialized<Type[Key]>,
+                      never,
+                      Key
+                    >]: PrimitiveHttpPathParamsSerialized<Type[Key]>;
+                  }
+                : never;

package/src/searchParams/HttpSearchParams.ts

@@ -0,0 +1,258 @@
+import { ReplaceBy, ArrayItemIfArray } from '@/types/utils';
+
+import { HttpSearchParamsSchema, HttpSearchParamsInit, HttpSearchParamsSchemaName } from './types';
+
+function pickPrimitiveProperties<Schema extends HttpSearchParamsSchema>(schema: Schema) {
+  const schemaWithPrimitiveProperties = Object.entries(schema).reduce<Record<string, string>>(
+    (accumulated, [key, value]) => {
+      if (value !== undefined && !Array.isArray(value)) {
+        accumulated[key] = value;
+      }
+      return accumulated;
+    },
+    {},
+  );
+  return schemaWithPrimitiveProperties;
+}
+
+/**
+ * An extended 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.
+ *
+ * **IMPORTANT**: the input of `HttpSearchParams` and all of its internal types must be declared inline or as a type
+ * aliases (`type`). They cannot be interfaces.
+ *
+ * @example
+ *   import { HttpSearchParams } from '@zimic/http';
+ *
+ *   const searchParams = new HttpSearchParams<{
+ *     names?: string[];
+ *     page?: `${number}`;
+ *   }>({
+ *     names: ['user 1', 'user 2'],
+ *     page: '1',
+ *   });
+ *
+ *   const names = searchParams.getAll('names');
+ *   console.log(names); // ['user 1', 'user 2']
+ *
+ *   const page = searchParams.get('page');
+ *   console.log(page); // '1'
+ *
+ * @see {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐http#httpsearchparams `HttpSearchParams` API reference}
+ */
+class HttpSearchParams<Schema extends HttpSearchParamsSchema = HttpSearchParamsSchema> extends URLSearchParams {
+  constructor(init?: HttpSearchParamsInit<Schema>) {
+    if (init instanceof URLSearchParams || Array.isArray(init) || typeof init === 'string' || !init) {
+      super(init);
+    } else {
+      super(pickPrimitiveProperties(init));
+      this.populateInitArrayProperties(init);
+    }
+  }
+
+  private populateInitArrayProperties(init: Schema) {
+    for (const [key, value] of Object.entries(init)) {
+      if (Array.isArray(value)) {
+        for (const item of value) {
+          super.append(key, item);
+        }
+      }
+    }
+  }
+
+  /** @see {@link https://developer.mozilla.org/docs/Web/API/URLSearchParams/set MDN Reference} */
+  set<Name extends HttpSearchParamsSchemaName<Schema>>(
+    name: Name,
+    value: ArrayItemIfArray<NonNullable<Schema[Name]>>,
+  ): void {
+    super.set(name, value);
+  }
+
+  /** @see {@link https://developer.mozilla.org/docs/Web/API/URLSearchParams/append MDN Reference} */
+  append<Name extends HttpSearchParamsSchemaName<Schema>>(
+    name: Name,
+    value: ArrayItemIfArray<NonNullable<Schema[Name]>>,
+  ): void {
+    super.append(name, value);
+  }
+
+  /**
+   * Get the value of the entry associated to a key name.
+   *
+   * If the key might have multiple values, use {@link HttpSearchParams#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/URLSearchParams/get MDN Reference}
+   */
+  get<Name extends HttpSearchParamsSchemaName.NonArray<Schema>>(
+    name: Name,
+  ): ReplaceBy<ArrayItemIfArray<Schema[Name]>, undefined, null> {
+    return super.get(name) as ReplaceBy<ArrayItemIfArray<Schema[Name]>, undefined, null>;
+  }
+
+  /**
+   * Get all the values of the entry associated with a key name.
+   *
+   * If the key has at most one value, use {@link HttpSearchParams#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/URLSearchParams/getAll MDN Reference}
+   */
+  getAll<Name extends HttpSearchParamsSchemaName.Array<Schema>>(
+    name: Name,
+  ): ArrayItemIfArray<NonNullable<Schema[Name]>>[] {
+    return super.getAll(name) as ArrayItemIfArray<NonNullable<Schema[Name]>>[];
+  }
+
+  /** @see {@link https://developer.mozilla.org/docs/Web/API/URLSearchParams/has MDN Reference} */
+  has<Name extends HttpSearchParamsSchemaName<Schema>>(
+    name: Name,
+    value?: ArrayItemIfArray<NonNullable<Schema[Name]>>,
+  ): boolean {
+    return super.has(name, value);
+  }
+
+  /** @see {@link https://developer.mozilla.org/docs/Web/API/URLSearchParams/delete MDN Reference} */
+  delete<Name extends HttpSearchParamsSchemaName<Schema>>(
+    name: Name,
+    value?: ArrayItemIfArray<NonNullable<Schema[Name]>>,
+  ): void {
+    super.delete(name, value);
+  }
+
+  forEach<This extends HttpSearchParams<Schema>>(
+    callback: <Key extends HttpSearchParamsSchemaName<Schema>>(
+      value: ArrayItemIfArray<NonNullable<Schema[Key]>>,
+      key: Key,
+      parent: HttpSearchParams<Schema>,
+    ) => void,
+    thisArg?: This,
+  ): void {
+    super.forEach(callback as (value: string, key: string, parent: URLSearchParams) => void, thisArg);
+  }
+
+  /** @see {@link https://developer.mozilla.org/docs/Web/API/URLSearchParams/keys MDN Reference} */
+  keys(): URLSearchParamsIterator<HttpSearchParamsSchemaName<Schema>> {
+    return super.keys() as URLSearchParamsIterator<HttpSearchParamsSchemaName<Schema>>;
+  }
+
+  /** @see {@link https://developer.mozilla.org/docs/Web/API/URLSearchParams/values MDN Reference} */
+  values(): URLSearchParamsIterator<ArrayItemIfArray<NonNullable<Schema[HttpSearchParamsSchemaName<Schema>]>>> {
+    return super.values() as URLSearchParamsIterator<
+      ArrayItemIfArray<NonNullable<Schema[HttpSearchParamsSchemaName<Schema>]>>
+    >;
+  }
+
+  /** @see {@link https://developer.mozilla.org/docs/Web/API/URLSearchParams/entries MDN Reference} */
+  entries(): URLSearchParamsIterator<
+    [HttpSearchParamsSchemaName<Schema>, ArrayItemIfArray<NonNullable<Schema[HttpSearchParamsSchemaName<Schema>]>>]
+  > {
+    return super.entries() as URLSearchParamsIterator<
+      [HttpSearchParamsSchemaName<Schema>, ArrayItemIfArray<NonNullable<Schema[HttpSearchParamsSchemaName<Schema>]>>]
+    >;
+  }
+
+  [Symbol.iterator](): URLSearchParamsIterator<
+    [HttpSearchParamsSchemaName<Schema>, ArrayItemIfArray<NonNullable<Schema[HttpSearchParamsSchemaName<Schema>]>>]
+  > {
+    return super[Symbol.iterator]() as URLSearchParamsIterator<
+      [HttpSearchParamsSchemaName<Schema>, ArrayItemIfArray<NonNullable<Schema[HttpSearchParamsSchemaName<Schema>]>>]
+    >;
+  }
+
+  /**
+   * Checks if these search params are equal to another set of search parameters. Equality is defined as having the same
+   * keys and values, regardless of the order of the keys.
+   *
+   * @param otherParams The other search parameters to compare against.
+   * @returns `true` if the search parameters are equal, `false` otherwise.
+   */
+  equals<OtherSchema extends Schema>(otherParams: HttpSearchParams<OtherSchema>): boolean {
+    for (const [key, otherValue] of otherParams.entries()) {
+      const values = super.getAll.call(this, key);
+
+      const haveSameNumberOfValues = values.length === super.getAll.call(otherParams, key).length;
+      if (!haveSameNumberOfValues) {
+        return false;
+      }
+
+      const valueExists = values.includes(otherValue);
+      if (!valueExists) {
+        return false;
+      }
+    }
+
+    return this.size === otherParams.size;
+  }
+
+  /**
+   * Checks if these search params contain another set of search parameters. This method is less strict than
+   * {@link HttpSearchParams#equals} and only requires that all keys and values in the other search parameters are
+   * present in these search parameters.
+   *
+   * @param otherParams The other search parameters to check for containment.
+   * @returns `true` if these search parameters contain the other search parameters, `false` otherwise.
+   */
+  contains<OtherSchema extends Schema>(otherParams: HttpSearchParams<OtherSchema>): boolean {
+    for (const [key, otherValue] of otherParams.entries()) {
+      const values = super.getAll.call(this, key);
+
+      const haveCompatibleNumberOfValues = values.length >= super.getAll.call(otherParams, key).length;
+      if (!haveCompatibleNumberOfValues) {
+        return false;
+      }
+
+      const valueExists = values.includes(otherValue);
+      if (!valueExists) {
+        return false;
+      }
+    }
+
+    return true;
+  }
+
+  /**
+   * Converts these search params 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 search params object.
+   *
+   * @example
+   *   const searchParams = new HttpSearchParams({
+   *     names: ['user 1', 'user 2'],
+   *     name: ['user 3'],
+   *     page: '1',
+   *   });
+   *   const object = searchParams.toObject();
+   *   console.log(object); // { names: ['user 1', 'user 2'], name: 'user 3', page: '1' }
+   *
+   * @returns A plain object representation of these search params.
+   */
+  toObject() {
+    const object = {} as Schema;
+
+    type SchemaValue = Schema[HttpSearchParamsSchemaName<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 HttpSearchParams;

package/src/searchParams/types.ts

@@ -0,0 +1,133 @@
+import { ArrayItemIfArray, IfNever, NonArrayKey, ArrayKey } from '@/types/utils';
+
+import HttpSearchParams from './HttpSearchParams';
+
+/** A schema for strict HTTP URL search parameters. */
+export interface HttpSearchParamsSchema {
+  [paramName: string]: string | string[] | undefined;
+}
+
+export namespace HttpSearchParamsSchema {
+  /** A schema for loose HTTP URL search parameters. Parameter 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 HttpSearchParamsSchema}. */
+export type HttpSearchParamsSchemaTuple<Schema extends HttpSearchParamsSchema = HttpSearchParamsSchema> = {
+  [Key in keyof Schema & string]: [Key, ArrayItemIfArray<NonNullable<Schema[Key]>>];
+}[keyof Schema & string];
+
+/**
+ * An initialization value for
+ * {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐http#httpsearchparams `HttpSearchParams`}.
+ */
+export type HttpSearchParamsInit<Schema extends HttpSearchParamsSchema = HttpSearchParamsSchema> =
+  | string
+  | URLSearchParams
+  | Schema
+  | HttpSearchParams<Schema>
+  | HttpSearchParamsSchemaTuple<Schema>[];
+
+export namespace HttpSearchParamsSchemaName {
+  /** Extracts the names of the search params defined in a {@link HttpSearchParamsSchema} that are arrays. */
+  export type Array<Schema extends HttpSearchParamsSchema> = IfNever<Schema, never, ArrayKey<Schema> & string>;
+
+  /** Extracts the names of the search params defined in a {@link HttpSearchParamsSchema} that are not arrays. */
+  export type NonArray<Schema extends HttpSearchParamsSchema> = IfNever<Schema, never, NonArrayKey<Schema> & string>;
+}
+
+/**
+ * Extracts the names of the search params defined in a {@link HttpSearchParamsSchema}. Each key is considered a search
+ * param name. `HttpSearchParamsSchemaName.Array` can be used to extract the names of array search params, whereas
+ * `HttpSearchParamsSchemaName.NonArray` extracts the names of non-array search params.
+ *
+ * @example
+ *   import { type HttpSearchParamsSchemaName } from '@zimic/http';
+ *
+ *   type SearchParamsName = HttpSearchParamsSchemaName<{
+ *     query?: string[];
+ *     page?: `${number}`;
+ *     perPage?: `${number}`;
+ *   }>;
+ *   // "query" | "page" | "perPage"
+ *
+ *   type ArraySearchParamsName = HttpSearchParamsSchemaName.Array<{
+ *     query?: string[];
+ *     page?: `${number}`;
+ *     perPage?: `${number}`;
+ *   }>;
+ *   // "query"
+ *
+ *   type NonArraySearchParamsName = HttpSearchParamsSchemaName.NonArray<{
+ *     query?: string[];
+ *     page?: `${number}`;
+ *     perPage?: `${number}`;
+ *   }>;
+ *   // "page" | "perPage"
+ */
+export type HttpSearchParamsSchemaName<Schema extends HttpSearchParamsSchema> = IfNever<
+  Schema,
+  never,
+  keyof Schema & string
+>;
+
+type PrimitiveHttpSearchParamsSerialized<Type> = Type extends HttpSearchParamsSchema[string]
+  ? Type
+  : Type extends (infer ArrayItem)[]
+    ? ArrayItem extends (infer _InternalArrayItem)[]
+      ? never
+      : PrimitiveHttpSearchParamsSerialized<ArrayItem>[]
+    : Type extends number
+      ? `${number}`
+      : Type extends boolean
+        ? `${boolean}`
+        : Type extends null
+          ? undefined
+          : never;
+
+/**
+ * Recursively converts a schema to its
+ * {@link https://developer.mozilla.org/docs/Web/API/URLSearchParams URLSearchParams}-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 HttpSearchParamsSerialized } from '@zimic/http';
+ *
+ *   type Params = HttpSearchParamsSerialized<{
+ *     query: string | null;
+ *     page?: number;
+ *     full?: boolean;
+ *     date: Date;
+ *     method: () => void;
+ *   }>;
+ *   // {
+ *   //   query: string | undefined;
+ *   //   page?: `${number}`;
+ *   //   full?: "false" | "true";
+ *   // }
+ */
+export type HttpSearchParamsSerialized<Type> = Type extends HttpSearchParamsSchema
+  ? 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<
+                      PrimitiveHttpSearchParamsSerialized<Type[Key]>,
+                      never,
+                      Key
+                    >]: PrimitiveHttpSearchParamsSerialized<Type[Key]>;
+                  }
+                : never;

package/src/typegen/index.ts

@@ -0,0 +1,12 @@
+import TypegenNamespace from './namespace/TypegenNamespace';
+
+export type { OpenAPITypegenOptions } from './openapi/generate';
+
+/**
+ * A namespace of type generation resources.
+ *
+ * @see {@link https://github.com/zimicjs/zimic/wiki/cli‐zimic‐typegen `zimic typegen` API reference}
+ */
+export const typegen = Object.freeze(new TypegenNamespace());
+
+export type { TypegenNamespace };

package/src/typegen/namespace/TypegenNamespace.ts

@@ -0,0 +1,18 @@
+import generateTypesFromOpenAPI from '../openapi/generate';
+
+/**
+ * A namespace of type generation resources.
+ *
+ * @see {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐typegen `zimic/typegen` API reference}
+ */
+class TypegenNamespace {
+  /**
+   * Generates TypeScript types from an OpenAPI schema.
+   *
+   * @param options The options to use when generating the types.
+   * @see {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐typegen#typegengeneratefromopenapioptions `typegen.generateFromOpenAPI(options)` API reference}
+   */
+  generateFromOpenAPI = generateTypesFromOpenAPI;
+}
+
+export default TypegenNamespace;