docs: v0.3.0 (#24) (#117)

### Documentation
- [#zimic] Improved the examples using headers and search params.
- [#zimic] Added a link to the examples section to the headline.
- [#zimic] Documented the new APIs `tracker.with(restriction)` and
`tracker.clear()`.
- [#zimic] Improved notes using [Markdown
Alerts](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts).

Closes #24.

packages/zimic/src/http/headers/HttpHeaders.ts

@@ -12,7 +12,7 @@ function pickPrimitiveProperties<Schema extends HttpHeadersSchema>(schema: Schem
 }
 
 /**
- * An HTTP headers object with a strictly-typed schema. Fully compatible with the built-in
+ * 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.
  */
 class HttpHeaders<Schema extends HttpHeadersSchema = HttpHeadersSchema> extends Headers {
@@ -73,6 +73,13 @@ class HttpHeaders<Schema extends HttpHeadersSchema = HttpHeadersSchema> extends
     >;
   }
 
+  /**
+   * 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, value] of otherHeaders.entries()) {
       const otherValue = super.get.call(this, key);
@@ -91,6 +98,14 @@ class HttpHeaders<Schema extends HttpHeadersSchema = HttpHeadersSchema> extends
     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, value] of otherHeaders.entries()) {
       const otherValue = super.get.call(this, key);

packages/zimic/src/http/headers/types.ts

@@ -12,6 +12,7 @@ export type HttpHeadersSchemaTuple<Schema extends HttpHeadersSchema> = {
   [Key in keyof Schema & string]: [Key, Defined<Schema[Key]>];
 }[keyof Schema & string];
 
+/** An initialization value for {@link HttpHeaders}. */
 export type HttpHeadersInit<Schema extends HttpHeadersSchema> =
   | Headers
   | Schema

packages/zimic/src/http/searchParams/HttpSearchParams.ts

@@ -16,7 +16,7 @@ function pickPrimitiveProperties<Schema extends HttpSearchParamsSchema>(schema:
 }
 
 /**
- * An HTTP search params object with a strictly-typed schema. Fully compatible with the built-in
+ * 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.
  */
 class HttpSearchParams<Schema extends HttpSearchParamsSchema = never> extends URLSearchParams {
@@ -98,10 +98,25 @@ class HttpSearchParams<Schema extends HttpSearchParamsSchema = never> extends UR
     >;
   }
 
+  /**
+   * Checks if the current search parameters 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 {
     return this.contains(otherParams) && this.size === otherParams.size;
   }
 
+  /**
+   * Checks if the current search parameters 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, value] of otherParams.entries()) {
       if (!super.has.call(this, key, value)) {

packages/zimic/src/http/searchParams/types.ts

@@ -12,6 +12,7 @@ export type HttpSearchParamsSchemaTuple<Schema extends HttpSearchParamsSchema> =
   [Key in keyof Schema & string]: [Key, ArrayItemIfArray<Defined<Schema[Key]>>];
 }[keyof Schema & string];
 
+/** An initialization value for {@link HttpSearchParams}. */
 export type HttpSearchParamsInit<Schema extends HttpSearchParamsSchema> =
   | string
   | URLSearchParams

packages/zimic/src/http/types/requests.ts

@@ -8,8 +8,16 @@ import { HttpSearchParamsSchema } from '../searchParams/types';
 /** The default body type (JSON) for HTTP requests and responses. */
 export type HttpBody = JSONValue;
 
+/**
+ * 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> = 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> = Pick<
   HttpSearchParams<Schema>,
   keyof URLSearchParams

packages/zimic/src/http/types/schema.ts

@@ -7,60 +7,82 @@ import { HttpBody } from './requests';
 export const HTTP_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS'] as const;
 export type HttpMethod = (typeof HTTP_METHODS)[number];
 
+/** A schema representing the structure of an HTTP request. */
 export interface HttpServiceRequestSchema {
   headers?: HttpHeadersSchema;
   searchParams?: HttpSearchParamsSchema;
   body?: HttpBody;
 }
 
+/** A schema representing the structure of an HTTP response. */
 export interface HttpServiceResponseSchema {
   headers?: HttpHeadersSchema;
   body?: HttpBody;
 }
 
+/** A schema representing the structures of HTTP responses by status code. */
 export interface HttpServiceResponseSchemaByStatusCode {
   [statusCode: number]: HttpServiceResponseSchema;
 }
 
+/** Extracts the status codes used in response schema by status code. */
 export type HttpServiceResponseSchemaStatusCode<
   ResponseSchemaByStatusCode extends HttpServiceResponseSchemaByStatusCode,
 > = Extract<keyof ResponseSchemaByStatusCode, number>;
 
+/** A schema representing the structures of an HTTP request and response for a given method. */
 export interface HttpServiceMethodSchema {
   request?: HttpServiceRequestSchema;
   response?: HttpServiceResponseSchemaByStatusCode;
 }
 
+/** A schema representing the structures of HTTP request and response by method. */
 export type HttpServiceMethodsSchema = {
   [Method in HttpMethod]?: HttpServiceMethodSchema;
 };
 
+/** A schema representing the structures of paths, methods, requests, and responses for an HTTP service. */
 export interface HttpServiceSchema {
   [path: string]: HttpServiceMethodsSchema;
 }
 
+/** A namespace containing utility types for validating HTTP type schemas. */
 export namespace HttpSchema {
+  /** Validates that a type is a valid HTTP service schema. */
   export type Paths<Schema extends HttpServiceSchema> = Schema;
+  /** Validates that a type is a valid HTTP service methods schema. */
   export type Methods<Schema extends HttpServiceMethodsSchema> = Schema;
+  /** Validates that a type is a valid HTTP service method schema. */
   export type Method<Schema extends HttpServiceMethodSchema> = Schema;
+  /** Validates that a type is a valid HTTP service request schema. */
   export type Request<Schema extends HttpServiceRequestSchema> = Schema;
+  /** Validates that a type is a valid HTTP service response schema by status code. */
   export type ResponseByStatusCode<Schema extends HttpServiceResponseSchemaByStatusCode> = Schema;
+  /** Validates that a type is a valid HTTP service response schema. */
   export type Response<Schema extends HttpServiceResponseSchema> = Schema;
+  /** Validates that a type is a valid HTTP headers schema. */
   export type Headers<Schema extends HttpHeadersSchema> = Schema;
+  /** Validates that a type is a valid HTTP search params schema. */
   export type SearchParams<Schema extends HttpSearchParamsSchema> = Schema;
 }
 
+/** Extracts the methods from an HTTP service schema. */
 export type HttpServiceSchemaMethod<Schema extends HttpServiceSchema> = IfAny<
   Schema,
   any, // eslint-disable-line @typescript-eslint/no-explicit-any
   Extract<keyof UnionToIntersection<Schema[keyof Schema]>, HttpMethod>
 >;
 
+/**
+ * Extracts the literal paths from an HTTP service schema containing certain methods. Only the methods defined in the
+ * schema are allowed.
+ */
 export type LiteralHttpServiceSchemaPath<
   Schema extends HttpServiceSchema,
   Method extends HttpServiceSchemaMethod<Schema>,
 > = LooseLiteralHttpServiceSchemaPath<Schema, Method>;
 
+/** Extracts the literal paths from an HTTP service schema containing certain methods. Any method is allowed. */
 export type LooseLiteralHttpServiceSchemaPath<Schema extends HttpServiceSchema, Method extends HttpMethod> = {
   [Path in Extract<keyof Schema, string>]: Method extends keyof Schema[Path] ? Path : never;
 }[Extract<keyof Schema, string>];
@@ -72,11 +94,13 @@ export type AllowAnyStringInPathParameters<Path extends string> =
       ? `${Prefix}${string}`
       : Path;
 
+/** Extracts the non-literal paths from an HTTP service schema containing certain methods. */
 export type NonLiteralHttpServiceSchemaPath<
   Schema extends HttpServiceSchema,
   Method extends HttpServiceSchemaMethod<Schema>,
 > = AllowAnyStringInPathParameters<LiteralHttpServiceSchemaPath<Schema, Method>>;
 
+/** Extracts the paths from an HTTP service schema containing certain methods. */
 export type HttpServiceSchemaPath<Schema extends HttpServiceSchema, Method extends HttpServiceSchemaMethod<Schema>> =
   | LiteralHttpServiceSchemaPath<Schema, Method>
   | NonLiteralHttpServiceSchemaPath<Schema, Method>;

packages/zimic/src/interceptor/http/interceptor/factory.ts

@@ -7,8 +7,9 @@ import { HttpInterceptor as PublicHttpInterceptor } from './types/public';
 /**
  * Creates an HTTP interceptor.
  *
- * @param {HttpInterceptorOptions} options The options for the interceptor.
- * @returns {HttpInterceptor} The created HTTP interceptor.
+ * @param options The options for the interceptor.
+ * @returns The created HTTP interceptor.
+ * @throws {InvalidHttpInterceptorWorkerPlatform} When the worker platform is invalid.
  * @see {@link https://github.com/diego-aquino/zimic#createhttpinterceptor}
  */
 export function createHttpInterceptor<Schema extends HttpServiceSchema>(

packages/zimic/src/interceptor/http/interceptor/types/options.ts

@@ -1,5 +1,6 @@
 import { HttpInterceptorWorker } from '../../interceptorWorker/types/public';
 
+/** Options to create an HTTP interceptor. */
 export interface HttpInterceptorOptions {
   /**
    * The {@link https://github.com/diego-aquino/zimic#httpinterceptorworker HttpInterceptorWorker} instance for the

packages/zimic/src/interceptor/http/interceptor/types/public.ts

@@ -20,72 +20,71 @@ export interface HttpInterceptor<Schema extends HttpServiceSchema> {
   baseURL: () => string;
 
   /**
+   * @param path The path to intercept. Paths with dynamic parameters, such as `/users/:id`, are supported, but you need
+   *   to specify the original path as a type parameter to get type-inference and type-validation.
    * @returns A GET {@link https://github.com/diego-aquino/zimic#httprequesttracker HttpRequestTracker} for the provided
    *   path. The path and method must be declared in the interceptor schema.
-   *
-   *   Paths with dynamic parameters, such as `/users/:id`, are supported, but you need to specify the original
-   *
-   *   Path as a type parameter to get type-inference and type-validation.
+   * @throws {NotStartedHttpInterceptorWorkerError} If the worker is not running.
    * @see {@link https://github.com/diego-aquino/zimic#interceptormethodpath}
    */
   get: HttpInterceptorMethodHandler<Schema, 'GET'>;
 
   /**
+   * @param path The path to intercept. Paths with dynamic parameters, such as `/users/:id`, are supported, but you need
+   *   to specify the original path as a type parameter to get type-inference and type-validation.
    * @returns A POST {@link https://github.com/diego-aquino/zimic#httprequesttracker HttpRequestTracker} for the provided
    *   path. The path and method must be declared in the interceptor schema.
-   *
-   *   Paths with dynamic parameters, such as `/users/:id`, are supported, but you need to specify the original path as a
-   *   type parameter to get type-inference and type-validation.
+   * @throws {NotStartedHttpInterceptorWorkerError} If the worker is not running.
    * @see {@link https://github.com/diego-aquino/zimic#interceptormethodpath}
    */
   post: HttpInterceptorMethodHandler<Schema, 'POST'>;
 
   /**
+   * @param path The path to intercept. Paths with dynamic parameters, such as `/users/:id`, are supported, but you need
+   *   to specify the original path as a type parameter to get type-inference and type-validation.
    * @returns A PATCH {@link https://github.com/diego-aquino/zimic#httprequesttracker HttpRequestTracker} for the
    *   provided path. The path and method must be declared in the interceptor schema.
-   *
-   *   Paths with dynamic parameters, such as `/users/:id`, are supported, but you need to specify the original path as a
-   *   type parameter to get type-inference and type-validation.
+   * @throws {NotStartedHttpInterceptorWorkerError} If the worker is not running.
    * @see {@link https://github.com/diego-aquino/zimic#interceptormethodpath}
    */
   patch: HttpInterceptorMethodHandler<Schema, 'PATCH'>;
 
   /**
+   * @param path The path to intercept. Paths with dynamic parameters, such as `/users/:id`, are supported, but you need
+   *   to specify the original path as a type parameter to get type-inference and type-validation.
    * @returns A PUT {@link https://github.com/diego-aquino/zimic#httprequesttracker HttpRequestTracker} for the provided
    *   path. The path and method must be declared in the interceptor schema.
-   *
-   *   Paths with dynamic parameters, such as `/users/:id`, are supported, but you need to specify the original path as a
-   *   type parameter to get type-inference and type-validation.
+   * @throws {NotStartedHttpInterceptorWorkerError} If the worker is not running.
    * @see {@link https://github.com/diego-aquino/zimic#interceptormethodpath}
    */
   put: HttpInterceptorMethodHandler<Schema, 'PUT'>;
 
   /**
+   * @param path The path to intercept. Paths with dynamic parameters, such as `/users/:id`, are supported, but you need
+   *   to specify the original path as a type parameter to get type-inference and type-validation.
    * @returns A DELETE {@link https://github.com/diego-aquino/zimic#httprequesttracker HttpRequestTracker} for the
    *   provided path. The path and method must be declared in the interceptor schema.
-   *
-   *   Paths with dynamic parameters, such as `/users/:id`, are supported, but you need to specify the original path as a
-   *   type parameter to get type-inference and type-validation.
+   * @throws {NotStartedHttpInterceptorWorkerError} If the worker is not running.
    * @see {@link https://github.com/diego-aquino/zimic#interceptormethodpath}
    */
   delete: HttpInterceptorMethodHandler<Schema, 'DELETE'>;
 
   /**
+   * @param path The path to intercept. Paths with dynamic parameters, such as `/users/:id`, are supported, but you need
+   *   to specify the original path as a type parameter to get type-inference and type-validation.
    * @returns A HEAD {@link https://github.com/diego-aquino/zimic#httprequesttracker HttpRequestTracker} for the provided
    *   path. The path and method must be declared in the interceptor schema.
-   *
-   *   Paths with dynamic parameters, such as `/users/:id`, are supported, but you need to specify the original path as a
-   *   type parameter to get type-inference and type-validation.
+   * @throws {NotStartedHttpInterceptorWorkerError} If the worker is not running.
    * @see {@link https://github.com/diego-aquino/zimic#interceptormethodpath}
    */
   head: HttpInterceptorMethodHandler<Schema, 'HEAD'>;
 
   /**
+   * @param path The path to intercept. Paths with dynamic parameters, such as `/users/:id`, are supported, but you need
+   *   to specify the original path as a type parameter to get type-inference and type-validation.
    * @returns An OPTIONS {@link https://github.com/diego-aquino/zimic#httprequesttracker HttpRequestTracker} for the
    *   provided path. The path and method must be declared in the interceptor schema.
-   *
-   *   Paths with dynamic parameters, such as `/users/:id`, are supported, but you need to specify the original path as a
-   *   type parameter to get type-inference and type-validation.
+   * @throws {NotStartedHttpInterceptorWorkerError} If the worker is not running.
    * @see {@link https://github.com/diego-aquino/zimic#interceptormethodpath}
    */
   options: HttpInterceptorMethodHandler<Schema, 'OPTIONS'>;

packages/zimic/src/interceptor/http/interceptorWorker/errors/OtherHttpInterceptorWorkerRunningError.ts

@@ -1,3 +1,4 @@
+/** Error thrown when trying to start a new HTTP interceptor worker while another one is already running. */
 class OtherHttpInterceptorWorkerRunningError extends Error {
   constructor() {
     super(

packages/zimic/src/interceptor/http/interceptorWorker/factory.ts

@@ -5,8 +5,8 @@ import { HttpInterceptorWorker as PublicHttpInterceptorWorker } from './types/pu
 /**
  * Creates an HTTP interceptor worker.
  *
- * @param {HttpInterceptorWorkerOptions} options The options for the worker.
- * @returns {HttpInterceptorWorker} The created HTTP interceptor worker.
+ * @param options The options for the worker.
+ * @returns The created HTTP interceptor worker.
  * @see {@link https://github.com/diego-aquino/zimic#createhttpinterceptorworker}
  */
 export function createHttpInterceptorWorker(options: HttpInterceptorWorkerOptions): PublicHttpInterceptorWorker {

packages/zimic/src/interceptor/http/interceptorWorker/types/options.ts

@@ -9,6 +9,7 @@ type HttpInterceptorWorkerPlatformUnion = `${HttpInterceptorWorkerPlatformEnum}`
 export type HttpInterceptorWorkerPlatform = HttpInterceptorWorkerPlatformEnum | HttpInterceptorWorkerPlatformUnion;
 export const HttpInterceptorWorkerPlatform = HttpInterceptorWorkerPlatformEnum; // eslint-disable-line @typescript-eslint/no-redeclare
 
+/** Options to create an HTTP interceptor worker. */
 export interface HttpInterceptorWorkerOptions {
   /**
    * The platform used by the worker (`browser` or `node`).