@zimic/http 0.5.1-canary.1 → 0.5.1-canary.2

package/src/types/schema.ts

@@ -23,7 +23,6 @@ export type HttpMethod = (typeof HTTP_METHODS)[number];
 /**
  * A schema representing the structure of an HTTP request.
  *
- * @see {@link https://zimic.dev/docs/http/guides/schemas Declaring schemas}
  * @see {@link https://zimic.dev/docs/http/api/http-schema `HttpSchema` API reference}
  */
 export interface HttpRequestSchema {
@@ -35,7 +34,6 @@ export interface HttpRequestSchema {
 /**
  * A schema representing the structure of an HTTP response.
  *
- * @see {@link https://zimic.dev/docs/http/guides/schemas Declaring schemas}
  * @see {@link https://zimic.dev/docs/http/api/http-schema `HttpSchema` API reference}
  */
 export interface HttpResponseSchema {
@@ -161,7 +159,6 @@ export namespace HttpStatusCode {
 /**
  * A schema representing the structure of HTTP responses by status code.
  *
- * @see {@link https://zimic.dev/docs/http/guides/schemas Declaring schemas}
  * @see {@link https://zimic.dev/docs/http/api/http-schema `HttpSchema` API reference}
  */
 export type HttpResponseSchemaByStatusCode = {
@@ -171,7 +168,6 @@ export type HttpResponseSchemaByStatusCode = {
 /**
  * Extracts the status codes used in a response schema by status code.
  *
- * @see {@link https://zimic.dev/docs/http/guides/schemas Declaring schemas}
  * @see {@link https://zimic.dev/docs/http/api/http-schema `HttpSchema` API reference}
  */
 export type HttpResponseSchemaStatusCode<ResponseSchemaByStatusCode extends HttpResponseSchemaByStatusCode> =
@@ -180,7 +176,6 @@ export type HttpResponseSchemaStatusCode<ResponseSchemaByStatusCode extends Http
 /**
  * A schema representing the structure of an HTTP request and response for a given method.
  *
- * @see {@link https://zimic.dev/docs/http/guides/schemas Declaring schemas}
  * @see {@link https://zimic.dev/docs/http/api/http-schema `HttpSchema` API reference}
  */
 export interface HttpMethodSchema {
@@ -191,7 +186,6 @@ export interface HttpMethodSchema {
 /**
  * A schema representing the structure of HTTP request and response by method.
  *
- * @see {@link https://zimic.dev/docs/http/guides/schemas Declaring schemas}
  * @see {@link https://zimic.dev/docs/http/api/http-schema `HttpSchema` API reference}
  */
 export interface HttpMethodsSchema {
@@ -208,78 +202,44 @@ interface BaseHttpSchema {
   [path: string]: HttpMethodsSchema;
 }
 
-/**
- * @see {@link https://zimic.dev/docs/http/guides/schemas Declaring schemas}
- * @see {@link https://zimic.dev/docs/http/api/http-schema `HttpSchema` API reference}
- */
+/** @see {@link https://zimic.dev/docs/http/api/http-schema `HttpSchema` API reference} */
 export type HttpSchema<Schema extends BaseHttpSchema = BaseHttpSchema> = Branded<Schema, 'HttpSchema'>;
 
 export namespace HttpSchema {
-  /**
-   * @see {@link https://zimic.dev/docs/http/guides/schemas Declaring schemas}
-   * @see {@link https://zimic.dev/docs/http/api/http-schema#httpschemamethods `HttpSchema.Methods` API reference}
-   */
+  /** @see {@link https://zimic.dev/docs/http/api/http-schema#httpschemamethods `HttpSchema.Methods` API reference} */
   export type Methods<Schema extends HttpMethodsSchema> = Schema;
 
-  /**
-   * @see {@link https://zimic.dev/docs/http/guides/schemas Declaring schemas}
-   * @see {@link https://zimic.dev/docs/http/api/http-schema#httpschemamethod `HttpSchema.Method` API reference}
-   */
+  /** @see {@link https://zimic.dev/docs/http/api/http-schema#httpschemamethod `HttpSchema.Method` API reference} */
   export type Method<Schema extends HttpMethodSchema> = Schema;
 
-  /**
-   * @see {@link https://zimic.dev/docs/http/guides/schemas Declaring schemas}
-   * @see {@link https://zimic.dev/docs/http/api/http-schema#httpschemarequest `HttpSchema.Request` API reference}
-   */
+  /** @see {@link https://zimic.dev/docs/http/api/http-schema#httpschemarequest `HttpSchema.Request` API reference} */
   export type Request<Schema extends HttpRequestSchema> = Schema;
 
-  /**
-   * @see {@link https://zimic.dev/docs/http/guides/schemas Declaring schemas}
-   * @see {@link https://zimic.dev/docs/http/api/http-schema#httpschemaresponsebystatuscode `HttpSchema.ResponseByStatusCode` API reference}
-   */
+  /** @see {@link https://zimic.dev/docs/http/api/http-schema#httpschemaresponsebystatuscode `HttpSchema.ResponseByStatusCode` API reference} */
   export type ResponseByStatusCode<Schema extends HttpResponseSchemaByStatusCode> = Schema;
 
-  /**
-   * @see {@link https://zimic.dev/docs/http/guides/schemas Declaring schemas}
-   * @see {@link https://zimic.dev/docs/http/api/http-schema#httpschemaresponse  `HttpSchema.Response` API reference}
-   */
+  /** @see {@link https://zimic.dev/docs/http/api/http-schema#httpschemaresponse  `HttpSchema.Response` API reference} */
   export type Response<Schema extends HttpResponseSchema> = Schema;
 
-  /**
-   * @see {@link https://zimic.dev/docs/http/guides/schemas Declaring schemas}
-   * @see {@link https://zimic.dev/docs/http/api/http-schema#httpschemabody `HttpSchema.Body` API reference}
-   */
+  /** @see {@link https://zimic.dev/docs/http/api/http-schema#httpschemabody `HttpSchema.Body` API reference} */
   export type Body<Schema extends HttpBody.Loose> = Schema;
 
-  /**
-   * @see {@link https://zimic.dev/docs/http/guides/schemas Declaring schemas}
-   * @see {@link https://zimic.dev/docs/http/api/http-schema#httpschemaheaders `HttpSchema.Headers` API reference}
-   */
+  /** @see {@link https://zimic.dev/docs/http/api/http-schema#httpschemaheaders `HttpSchema.Headers` API reference} */
   export type Headers<Schema extends HttpHeadersSchema.Loose> = Schema;
 
-  /**
-   * @see {@link https://zimic.dev/docs/http/guides/schemas Declaring schemas}
-   * @see {@link https://zimic.dev/docs/http/api/http-schema#httpschemasearchparams `HttpSchema.SearchParams` API reference}
-   */
+  /** @see {@link https://zimic.dev/docs/http/api/http-schema#httpschemasearchparams `HttpSchema.SearchParams` API reference} */
   export type SearchParams<Schema extends HttpSearchParamsSchema.Loose> = Schema;
 
-  /**
-   * @see {@link https://zimic.dev/docs/http/guides/schemas Declaring schemas}
-   * @see {@link https://zimic.dev/docs/http/api/http-schema#httpschemapathparams `HttpSchema.PathParams` API reference}
-   */
+  /** @see {@link https://zimic.dev/docs/http/api/http-schema#httpschemapathparams `HttpSchema.PathParams` API reference} */
   export type PathParams<Schema extends HttpPathParamsSchema.Loose> = Schema;
 
-  /**
-   * @see {@link https://zimic.dev/docs/http/guides/schemas Declaring schemas}
-   * @see {@link https://zimic.dev/docs/http/api/http-schema#httpschemaformdata `HttpSchema.FormData` API reference}
-   */
+  /** @see {@link https://zimic.dev/docs/http/api/http-schema#httpschemaformdata `HttpSchema.FormData` API reference} */
   export type FormData<Schema extends HttpFormDataSchema.Loose> = Schema;
 }
 
 /**
  * Extracts the methods from an HTTP service schema.
  *
- * @see {@link https://zimic.dev/docs/http/guides/schemas Declaring schemas}
  * @see {@link https://zimic.dev/docs/http/api/http-schema `HttpSchema` API reference}
  */
 export type HttpSchemaMethod<Schema extends HttpSchema> = IfAny<
@@ -294,103 +254,19 @@ export type AllowAnyStringInPathParams<Path extends string> = Path extends `${in
     ? `${Prefix}${string}`
     : Path;
 
-/**
- * Extracts the paths from an HTTP service schema. Optionally receives a second argument with one or more methods to
- * filter the paths with. Only the methods defined in the schema are allowed.
- *
- * @example
- *   import { type HttpSchema, type HttpSchemaPath } from '@zimic/http';
- *
- *   type Schema = HttpSchema<{
- *     '/users': {
- *       GET: {
- *         response: { 200: { body: User[] } };
- *       };
- *     };
- *     '/users/:userId': {
- *       DELETE: {
- *         response: { 200: { body: User } };
- *       };
- *     };
- *   }>;
- *
- *   type Path = HttpSchemaPath<Schema>;
- *   // "/users" | "/users/:userId" | "/users/${string}"
- *
- *   type GetPath = HttpSchemaPath<Schema, 'GET'>;
- *   // "/users"
- *
- * @see {@link https://zimic.dev/docs/http/guides/schemas Declaring schemas}
- * @see {@link https://zimic.dev/docs/http/api/http-schema `HttpSchema` API reference}
- */
+/** @see {@link https://zimic.dev/docs/http/api/http-schema#httpschemapath `HttpSchemaPath` API reference} */
 export namespace HttpSchemaPath {
   type LooseLiteral<Schema extends HttpSchema, Method extends HttpMethod = HttpMethod> = {
     [Path in keyof Schema & string]: Method extends keyof Schema[Path] ? Path : never;
   }[keyof Schema & string];
 
-  /**
-   * Extracts the literal paths from an HTTP service schema. Optionally receives a second argument with one or more
-   * methods to filter the paths with. Only the methods defined in the schema are allowed.
-   *
-   * @example
-   *   import { type HttpSchema, type HttpSchemaPath } from '@zimic/http';
-   *
-   *   type Schema = HttpSchema<{
-   *     '/users': {
-   *       GET: {
-   *         response: { 200: { body: User[] } };
-   *       };
-   *     };
-   *     '/users/:userId': {
-   *       DELETE: {
-   *         response: { 200: { body: User } };
-   *       };
-   *     };
-   *   }>;
-   *
-   *   type LiteralPath = HttpSchemaPath.Literal<Schema>;
-   *   // "/users" | "/users/:userId"
-   *
-   *   type LiteralGetPath = HttpSchemaPath.Literal<Schema, 'GET'>;
-   *   // "/users"
-   *
-   * @see {@link https://zimic.dev/docs/http/guides/schemas Declaring schemas}
-   * @see {@link https://zimic.dev/docs/http/api/http-schema `HttpSchema` API reference} `}
-   */
+  /** @see {@link https://zimic.dev/docs/http/api/http-schema#httpschemapathliteral `HttpSchemaPath.Literal` API reference} */
   export type Literal<
     Schema extends HttpSchema,
     Method extends HttpSchemaMethod<Schema> = HttpSchemaMethod<Schema>,
   > = LooseLiteral<Schema, Method>;
 
-  /**
-   * Extracts the non-literal paths from an HTTP service schema. Optionally receives a second argument with one or more
-   * methods to filter the paths with. Only the methods defined in the schema are allowed.
-   *
-   * @example
-   *   import { type HttpSchema, type HttpSchemaPath } from '@zimic/http';
-   *
-   *   type Schema = HttpSchema<{
-   *     '/users': {
-   *       GET: {
-   *         response: { 200: { body: User[] } };
-   *       };
-   *     };
-   *     '/users/:userId': {
-   *       DELETE: {
-   *         response: { 200: { body: User } };
-   *       };
-   *     };
-   *   }>;
-   *
-   *   type NonLiteralPath = HttpSchemaPath.NonLiteral<Schema>;
-   *   // "/users" | "/users/${string}"
-   *
-   *   type NonLiteralGetPath = HttpSchemaPath.NonLiteral<Schema, 'GET'>;
-   *   // "/users"
-   *
-   * @see {@link https://zimic.dev/docs/http/guides/schemas Declaring schemas}
-   * @see {@link https://zimic.dev/docs/http/api/http-schema `HttpSchema` API reference} `}
-   */
+  /** @see {@link https://zimic.dev/docs/http/api/http-schema#httpschemapathnonliteral `HttpSchemaPath.NonLiteral` API reference} */
   export type NonLiteral<
     Schema extends HttpSchema,
     Method extends HttpSchemaMethod<Schema> = HttpSchemaMethod<Schema>,
@@ -439,34 +315,7 @@ type RecursiveInferPathParams<Path extends string> = Path extends `${infer _Pref
     ? { [Name in ParamName]: string }
     : {};
 
-/**
- * Infers the path parameters schema from a path string, optionally validating it against an {@link HttpSchema}.
- *
- * If the first argument is a {@link HttpSchema} (recommended), the second argument is checked to be a valid path in that
- * schema.
- *
- * @example
- *   import { HttpSchema, InferPathParams } from '@zimic/http';
- *
- *   type Schema = HttpSchema<{
- *     '/users/:userId': {
- *       GET: {
- *         response: { 200: { body: User } };
- *       };
- *     };
- *   }>;
- *
- *   // Using a schema to validate the path (recommended):
- *   type PathParams = InferPathParams<Schema, '/users/:userId'>;
- *   // { userId: string }
- *
- * @example
- *   import { InferPathParams } from '@zimic/http';
- *
- *   // Without using a schema to validate the path (works as `PathParamsSchemaFromPath`):
- *   type PathParams = InferPathParams<'/users/:userId'>;
- *   // { userId: string }
- */
+/** @see {@link https://zimic.dev/docs/http/api/http-schema#inferpathparams `InferPathParams` API reference} */
 export type InferPathParams<
   PathOrSchema extends string | HttpSchema,
   OptionalPath extends PathOrSchema extends HttpSchema ? HttpSchemaPath.Literal<PathOrSchema> : never = never,
@@ -484,39 +333,7 @@ type OmitPastHttpStatusCodes<
     ? Omit<Schema, keyof UnionToIntersection<PastSchemas[number]>>
     : Schema;
 
-/**
- * Merges multiple HTTP response schemas by status code into a single schema. When there are duplicate status codes, the
- * first declaration takes precedence.
- *
- * @example
- *   import { type HttpSchema, type HttpStatusCode, MergeHttpResponsesByStatusCode } from '@zimic/http';
- *
- *   // Overriding the 400 status code with a more specific schema
- *   // and using a generic schema for all other client errors.
- *   type MergedResponseByStatusCode = MergeHttpResponsesByStatusCode<
- *     [
- *       {
- *         400: { body: { message: string; issues: string[] } };
- *       },
- *       {
- *         [StatusCode in HttpStatusCode.ClientError]: { body: { message: string } };
- *       },
- *     ]
- *   >;
- *   // {
- *   //   400: { body: { message: string; issues: string[] } };
- *   //   401: { body: { message: string}; };
- *   //   402: { body: { message: string}; };
- *   //   403: { body: { message: string}; };
- *   //   ...
- *   // }
- *
- *   type Schema = HttpSchema<{
- *     '/users': {
- *       GET: { response: MergedResponseByStatusCode };
- *     };
- *   }>;
- */
+/** @see {@link https://zimic.dev/docs/http/api/http-schema#mergehttpresponsesbystatuscode `MergeHttpResponsesByStatusCode` API reference} */
 export type MergeHttpResponsesByStatusCode<
   Schemas extends HttpResponseSchemaByStatusCode[],
   PastSchemas extends HttpResponseSchemaByStatusCode[] = [],