@zimic/http 0.5.0 → 0.5.1-canary.1

package/src/types/schema.ts

@@ -23,7 +23,8 @@ export type HttpMethod = (typeof HTTP_METHODS)[number];
 /**
  * A schema representing the structure of an HTTP request.
  *
- * @see {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐http‐schemas Declaring HTTP interceptor schemas}
+ * @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 {
   headers?: HttpHeadersSchema.Loose;
@@ -34,7 +35,8 @@ export interface HttpRequestSchema {
 /**
  * A schema representing the structure of an HTTP response.
  *
- * @see {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐http‐schemas Declaring HTTP interceptor schemas}
+ * @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 {
   headers?: HttpHeadersSchema.Loose;
@@ -159,7 +161,8 @@ export namespace HttpStatusCode {
 /**
  * A schema representing the structure of HTTP responses by status code.
  *
- * @see {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐http‐schemas Declaring HTTP interceptor schemas}
+ * @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 = {
   [StatusCode in HttpStatusCode]?: HttpResponseSchema;
@@ -168,7 +171,8 @@ export type HttpResponseSchemaByStatusCode = {
 /**
  * Extracts the status codes used in a response schema by status code.
  *
- * @see {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐http‐schemas Declaring HTTP interceptor schemas}
+ * @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> =
   keyof ResponseSchemaByStatusCode & HttpStatusCode;
@@ -176,7 +180,8 @@ export type HttpResponseSchemaStatusCode<ResponseSchemaByStatusCode extends Http
 /**
  * A schema representing the structure of an HTTP request and response for a given method.
  *
- * @see {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐http‐schemas Declaring HTTP interceptor schemas}
+ * @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 {
   request?: HttpRequestSchema;
@@ -186,7 +191,8 @@ export interface HttpMethodSchema {
 /**
  * A schema representing the structure of HTTP request and response by method.
  *
- * @see {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐http‐schemas Declaring HTTP interceptor schemas}
+ * @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 {
   GET?: HttpMethodSchema;
@@ -203,271 +209,69 @@ interface BaseHttpSchema {
 }
 
 /**
- * Declares an HTTP service schema.
- *
- * @example
- *   import { type HttpSchema } from '@zimic/http';
- *
- *   interface UserListHeaders {
- *     accept: string;
- *   }
- *
- *   interface UserListSearchParams {
- *     name?: string;
- *     limit?: number;
- *   }
- *
- *   type Schema = HttpSchema<{
- *     '/users': {
- *       GET: {
- *         request: {
- *           headers: UserListHeaders;
- *           searchParams: UserListSearchParams;
- *         };
- *         response: {
- *           200: {
- *             // Inline headers declaration
- *             headers: { 'content-type': string };
- *             body: User[];
- *           };
- *         };
- *       };
- *     };
- *   }>;
- *
- * @see {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐http‐schemas Declaring HTTP interceptor schemas}
+ * @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 HttpSchema<Schema extends BaseHttpSchema = BaseHttpSchema> = Branded<Schema, 'HttpSchema'>;
 
 export namespace HttpSchema {
   /**
-   * Declares an HTTP service methods schema.
-   *
-   * @example
-   *   import { type HttpSchema } from '@zimic/http';
-   *
-   *   type UserMethods = HttpSchema.Methods<{
-   *     GET: {
-   *       response: {
-   *         200: { body: User[] };
-   *       };
-   *     };
-   *   }>;
-   *
-   *   type Schema = HttpSchema<{
-   *     '/users': UserMethods;
-   *   }>;
+   * @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}
    */
   export type Methods<Schema extends HttpMethodsSchema> = Schema;
 
   /**
-   * Declares an HTTP service method schema.
-   *
-   * @example
-   *   import { type HttpSchema } from '@zimic/http';
-   *
-   *   type UserListMethod = HttpSchema.Method<{
-   *     response: {
-   *       200: { body: User[] };
-   *     };
-   *   }>;
-   *
-   *   type Schema = HttpSchema<{
-   *     '/users': {
-   *       GET: UserListMethod;
-   *     };
-   *   }>;
+   * @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}
    */
   export type Method<Schema extends HttpMethodSchema> = Schema;
 
   /**
-   * Declares an HTTP service request schema.
-   *
-   * @example
-   *   import { type HttpSchema } from '@zimic/http';
-   *
-   *   type UserCreationRequest = HttpSchema.Request<{
-   *     headers: { 'content-type': 'application/json' };
-   *     body: User;
-   *   }>;
-   *
-   *   type Schema = HttpSchema<{
-   *     '/users': {
-   *       POST: {
-   *         request: UserCreationRequest;
-   *         response: {
-   *           201: { body: User };
-   *         };
-   *       };
-   *     };
-   *   }>;
+   * @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}
    */
   export type Request<Schema extends HttpRequestSchema> = Schema;
 
   /**
-   * Declares an HTTP service response schema by status code.
-   *
-   * @example
-   *   import { type HttpSchema } from '@zimic/http';
-   *
-   *   type UserListResponseByStatusCode = HttpSchema.ResponseByStatusCode<{
-   *     200: { body: User[] };
-   *     400: { body: { message: string } };
-   *   }>;
-   *
-   *   type Schema = HttpSchema<{
-   *     '/users': {
-   *       GET: {
-   *         response: UserListResponseByStatusCode;
-   *       };
-   *     };
-   *   }>;
+   * @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}
    */
   export type ResponseByStatusCode<Schema extends HttpResponseSchemaByStatusCode> = Schema;
 
   /**
-   * Declares an HTTP service response schema.
-   *
-   * @example
-   *   import { type HttpSchema } from '@zimic/http';
-   *
-   *   type UserListSuccessResponse = HttpSchema.Response<{
-   *     body: User[];
-   *   }>;
-   *
-   *   type Schema = HttpSchema<{
-   *     '/users': {
-   *       GET: {
-   *         response: {
-   *           200: UserListSuccessResponse;
-   *         };
-   *       };
-   *     };
-   *   }>;
+   * @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}
    */
   export type Response<Schema extends HttpResponseSchema> = Schema;
 
   /**
-   * Declares an HTTP body schema.
-   *
-   * @example
-   *   import { type HttpSchema } from '@zimic/http';
-   *
-   *   type UserListSuccessResponseBody = HttpSchema.Body<User[]>;
-   *
-   *   type Schema = HttpSchema<{
-   *     '/users': {
-   *       GET: {
-   *         response: {
-   *           200: { body: UserListSuccessResponseBody };
-   *         };
-   *       };
-   *     };
-   *   }>;
+   * @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}
    */
   export type Body<Schema extends HttpBody.Loose> = Schema;
 
   /**
-   * Declares an HTTP headers schema.
-   *
-   * @example
-   *   import { type HttpSchema } from '@zimic/http';
-   *
-   *   type UserListHeaders = HttpSchema.Headers<{
-   *     accept: 'application/json';
-   *   }>;
-   *
-   *   type Schema = HttpSchema<{
-   *     '/users': {
-   *       GET: {
-   *         request: {
-   *           headers: UserListHeaders;
-   *         };
-   *         response: {
-   *           200: { body: User[] };
-   *         };
-   *       };
-   *     };
-   *   }>;
+   * @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}
    */
   export type Headers<Schema extends HttpHeadersSchema.Loose> = Schema;
 
   /**
-   * Declares an HTTP search params schema.
-   *
-   * @example
-   *   import { type HttpSchema } from '@zimic/http';
-   *
-   *   type UserListSearchParams = HttpSchema.SearchParams<{
-   *     limit: `${number}`;
-   *     offset: `${number}`;
-   *   }>;
-   *
-   *   type Schema = HttpSchema<{
-   *     '/users': {
-   *       GET: {
-   *         request: {
-   *           searchParams: UserListSearchParams;
-   *         };
-   *         response: {
-   *           200: { body: User[] };
-   *         };
-   *       };
-   *     };
-   *   }>;
+   * @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}
    */
   export type SearchParams<Schema extends HttpSearchParamsSchema.Loose> = Schema;
 
   /**
-   * Declares an HTTP path params schema.
-   *
-   * @example
-   *   import { type HttpSchema, InferPathParams } from '@zimic/http';
-   *
-   *   type Schema = HttpSchema<{
-   *     '/users/:userId': {
-   *       GET: {
-   *         response: {
-   *           200: { body: User };
-   *         };
-   *       };
-   *     };
-   *   }>;
-   *
-   *   type UserByIdPathParams = HttpSchema.PathParams<{
-   *     userId: string;
-   *   }>;
-   *
-   *   // Or infer from the path string
-   *   type UserByIdPathParams = InferPathParams<Schema, '/users/:userId'>;
+   * @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}
    */
   export type PathParams<Schema extends HttpPathParamsSchema.Loose> = Schema;
 
   /**
-   * Declares an HTTP form data schema.
-   *
-   * @example
-   *   import { HttpFormData, type HttpSchema } from '@zimic/http';
-   *
-   *   type UserCreationFormData = HttpFormData<
-   *     HttpSchema.FormData<{
-   *       name: string;
-   *       email: string;
-   *     }>
-   *   >;
-   *
-   *   type Schema = HttpSchema<{
-   *     '/users': {
-   *       POST: {
-   *         request: {
-   *           body: UserCreationFormData;
-   *         };
-   *         response: {
-   *           201: { body: User };
-   *         };
-   *       };
-   *     };
-   *   }>;
+   * @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}
    */
   export type FormData<Schema extends HttpFormDataSchema.Loose> = Schema;
 }
@@ -475,7 +279,8 @@ export namespace HttpSchema {
 /**
  * Extracts the methods from an HTTP service schema.
  *
- * @see {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐http‐schemas Declaring HTTP interceptor schemas}
+ * @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<
   Schema,
@@ -515,7 +320,8 @@ export type AllowAnyStringInPathParams<Path extends string> = Path extends `${in
  *   type GetPath = HttpSchemaPath<Schema, 'GET'>;
  *   // "/users"
  *
- * @see {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐http‐schemas Declaring HTTP interceptor schemas}
+ * @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 namespace HttpSchemaPath {
   type LooseLiteral<Schema extends HttpSchema, Method extends HttpMethod = HttpMethod> = {
@@ -548,7 +354,8 @@ export namespace HttpSchemaPath {
    *   type LiteralGetPath = HttpSchemaPath.Literal<Schema, 'GET'>;
    *   // "/users"
    *
-   * @see {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐http‐schemas Declaring HTTP interceptor schemas}
+   * @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 Literal<
     Schema extends HttpSchema,
@@ -581,7 +388,8 @@ export namespace HttpSchemaPath {
    *   type NonLiteralGetPath = HttpSchemaPath.NonLiteral<Schema, 'GET'>;
    *   // "/users"
    *
-   * @see {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐http‐schemas Declaring HTTP interceptor schemas}
+   * @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 NonLiteral<
     Schema extends HttpSchema,