@nestia/fetcher 14.0.0 → 14.0.2

package/lib/IConnection.d.ts

@@ -3,23 +3,26 @@ import { IFetchEvent } from "./IFetchEvent";
 /**
  * Connection information.
  *
- * `IConnection` is an interface ttype who represents connection information of
- * the remote HTTP server. You can target the remote HTTP server by wring the
+ * `IConnection` is an interface type that represents connection information of
+ * the remote HTTP server. You can target the remote HTTP server by writing the
  * {@link IConnection.host} variable down. Also, you can configure special header
  * values by specializing the {@link IConnection.headers} variable.
  *
  * If the remote HTTP server encrypts or decrypts its body data through the
- * AES-128/256 algorithm, specify the {@link IConnection.encryption} with
+ * AES-128/192/256 algorithm, specify the {@link IConnection.encryption} with
  * {@link IEncryptionPassword} or {@link IEncryptionPassword.Closure} variable.
  *
- * @author Jenogho Nam - https://github.com/samchon
+ * @author Jeongho Nam - https://github.com/samchon
  * @author Seungjun We - https://github.com/SeungjunWe
  */
 export interface IConnection<Headers extends object | undefined = object | undefined> {
     /** Host address of the remote HTTP server. */
     host: string;
-    /** Header values delivered to the remote HTTP server. */
-    headers?: Record<string, IConnection.HeaderValue> & IConnection.Headerify<Headers>;
+    /**
+     * Header values delivered to the remote HTTP server; undefined entries are
+     * omitted.
+     */
+    headers?: Record<string, IConnection.HeaderValue | undefined> & IConnection.Headerify<Headers>;
     /**
      * Use simulation mode.
      *
@@ -30,7 +33,7 @@ export interface IConnection<Headers extends object | undefined = object | undef
      * By the way, to utilize this simulation mode, SDK library must be generated
      * with {@link INestiaConfig.simulate} option, too. Open `nestia.config.ts`
      * file, and configure {@link INestiaConfig.simulate} property to be `true`.
-     * Them, newly generated SDK library would have a built-in mock-up data
+     * Then, newly generated SDK library would have a built-in mock-up data
      * generator.
      *
      * @default false
@@ -39,9 +42,17 @@ export interface IConnection<Headers extends object | undefined = object | undef
     /**
      * Logger function.
      *
-     * This function is called when the fetch event is completed.
+     * This function is called and awaited after transport and response
+     * processing, whether they succeeded or failed. Configuration, body encoding
+     * and URL errors that occur before transport do not produce an event. Logger
+     * errors are ignored; event input and output share the caller's payload
+     * references, so a logger should treat them as read-only.
      *
      * @param event Event information of the fetch event.
+     * @evidence contracts/common.md#principled-implementation The callback receives the event from the transport finally block after completed_at is set. respond_at and status stay null without a response, and output stays undefined if body processing throws. Its rejection is ignored, but its argument includes mutable payload references and its awaiting can delay completion.
+     * @evidence contracts/common.md#clear-and-simple-design One optional callback with a single event argument.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The optional callback uses the connection's supported logging boundary; the pipeline catches its errors without replacing a transport or decoding failure.
+     * @evidence contracts/common.md#meaningful-documentation The comment states when the callback runs, which pretransport errors create no event, that it is awaited, and why shared payload references should be treated as read-only.
      */
     logger?: (event: IFetchEvent) => Promise<void>;
     /**
@@ -66,6 +77,15 @@ export interface IConnection<Headers extends object | undefined = object | undef
      */
     fetch?: typeof fetch;
 }
+/**
+ * Support types of {@link IConnection}: the fetch options, the allowed header
+ * values, and the header mapping.
+ *
+ * @evidence contracts/common.md#principled-implementation The merged connection interface and namespace share one public identity for addressing, transport settings and support types. Header entries accept HeaderValue or undefined omission, while Headerify retains name-specific constraints; the HeaderValue union continues to exclude null and objects.
+ * @evidence contracts/common.md#clear-and-simple-design The interface separates addressing, header input, simulation, observation, encryption and fetch options; three supporting types organize their representations without runtime members.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts It contains types only.
+ * @evidence contracts/common.md#meaningful-documentation The interface member comments explain addressing, omitted headers and optional transport settings; the logger separately documents completion, awaiting and ignored errors. Each support type has its own documentation.
+ */
 export declare namespace IConnection {
     /**
      * Additional options for the `fetch` function.
@@ -73,9 +93,14 @@ export declare namespace IConnection {
      * Almost same with {@link RequestInit} type of the {@link fetch} function, but
      * `body`, `headers` and `method` properties are omitted.
      *
-     * The reason why defining duplicated definition of {@link RequestInit} is for
-     * legacy NodeJS environments, which does not have the {@link fetch} function
-     * type.
+     * The explicit option record exposes the supported subset independently of
+     * changes to {@link RequestInit}. DOM types are still required by the
+     * connection's custom fetch and abort signal members.
+     *
+     * @evidence contracts/common.md#principled-implementation The record exposes a subset of RequestInit options while omitting body, headers and method, whose construction belongs to the route pipeline; AbortSignal and the connection's fetch member still depend on DOM declarations.
+     * @evidence contracts/common.md#clear-and-simple-design A flat option record, with each member mirroring one field of the standard request options.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type; the fetcher spreads the options into the request and then sets the method and headers itself.
+     * @evidence contracts/common.md#meaningful-documentation The comment explains the supported subset and remaining DOM type dependency, and each member documents the standard field's meaning.
      */
     interface IOptions {
         /**
@@ -126,8 +151,13 @@ export declare namespace IConnection {
      * Type of allowed header values.
      *
      * Only atomic or array of atomic values are allowed.
+     *
+     * @evidence contracts/common.md#principled-implementation A header value is a string, boolean, number, or bigint, or an array of the non-string atomic types or of strings, which the request pipeline stringifies, one header line per array element.
+     * @evidence contracts/common.md#clear-and-simple-design A single union of the allowed atomic and array values.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+     * @evidence contracts/common.md#meaningful-documentation The comment states that only atomic values and arrays of them are allowed.
      */
-    type HeaderValue = string | boolean | number | bigint | string | Array<boolean> | Array<number> | Array<bigint> | Array<number> | Array<string>;
+    type HeaderValue = string | boolean | number | bigint | Array<boolean> | Array<number> | Array<bigint> | Array<string>;
     /**
      * Type of headers
      *
@@ -136,7 +166,7 @@ export declare namespace IConnection {
      *
      * Below are list of prohibited in HTTP headers.
      *
-     * 1. Value type one of {@link HeaderValue}
+     * 1. Value type is neither {@link HeaderValue} nor omitted `undefined`
      * 2. Key is "set-cookie", but value is not an Array type
      * 3. Key is one of them, but value is Array type
      *
@@ -158,8 +188,13 @@ export declare namespace IConnection {
      * - "retry-after"
      * - "server"
      * - "user-agent"
+     *
+     * @evidence contracts/common.md#principled-implementation Each key admits only HeaderValue or omitted undefined. Classifying the defined value domain preserves optional array set-cookie inputs; singleton headers reject any array member even in a scalar/array union. An undefined-only domain transmits nothing and stays permitted. Lowercase keys follow HTTP's case-insensitive names, and ordinary keys retain their type.
+     * @evidence contracts/common.md#clear-and-simple-design One mapped type that rejects an entry by turning it into `never`, with the rule spelled out in the comment.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+     * @evidence contracts/common.md#meaningful-documentation The comment lists the prohibited cases and the singleton headers.
      */
     type Headerify<T extends object | undefined> = {
-        [P in keyof T]?: T[P] extends HeaderValue | undefined ? P extends string ? Lowercase<P> extends "set-cookie" ? T[P] extends Array<HeaderValue> ? T[P] | undefined : never : Lowercase<P> extends "age" | "authorization" | "content-length" | "content-type" | "etag" | "expires" | "from" | "host" | "if-modified-since" | "if-unmodified-since" | "last-modified" | "location" | "max-forwards" | "proxy-authorization" | "referer" | "retry-after" | "server" | "user-agent" ? T[P] extends Array<HeaderValue> ? never : T[P] | undefined : T[P] | undefined : never : never;
+        [P in keyof T]?: T[P] extends HeaderValue | undefined ? P extends string ? Lowercase<P> extends "set-cookie" ? Exclude<T[P], undefined> extends Array<HeaderValue> ? T[P] | undefined : never : Lowercase<P> extends "age" | "authorization" | "content-length" | "content-type" | "etag" | "expires" | "from" | "host" | "if-modified-since" | "if-unmodified-since" | "last-modified" | "location" | "max-forwards" | "proxy-authorization" | "referer" | "retry-after" | "server" | "user-agent" ? Extract<Exclude<T[P], undefined>, Array<HeaderValue>> extends never ? T[P] | undefined : never : T[P] | undefined : never : never;
     };
 }

package/lib/IEncryptionPassword.d.ts

@@ -3,11 +3,15 @@ import { IConnection } from "./IConnection";
  * Encryption password.
  *
  * `IEncryptionPassword` is a type of interface who represents encryption
- * password used by the {@link Fetcher} with AES-128/256 algorithm. If your
+ * password used by the {@link Fetcher} with AES-128/192/256 algorithm. If your
  * encryption password is not fixed but changes according to the input content,
  * you can utilize the {@link IEncryptionPassword.Closure} function type.
  *
  * @author Jeongho Nam - https://github.com/samchon
+ * @evidence contracts/common.md#principled-implementation A key and an initialization vector are the two inputs of AES-CBC, so the interface holds exactly them, as strings that `AesPkcs5` reads as UTF-8 bytes.
+ * @evidence contracts/common.md#clear-and-simple-design A two-field record whose namespace adds the closure form for passwords that depend on the message.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+ * @evidence contracts/common.md#meaningful-documentation The comment says what the object represents and links the closure form.
  */
 export interface IEncryptionPassword {
     /** Secret key. */
@@ -22,6 +26,11 @@ export declare namespace IEncryptionPassword {
      * `IEncryptionPassword.Closure` is a type of closure function who are
      * returning the {@link IEncryptionPassword} object. It would be used when your
      * encryption password be changed according to the input content.
+     *
+     * @evidence contracts/common.md#principled-implementation A call signature from the message context to a password lets a server-driven scheme choose the key from the headers, the body, and the direction of each call.
+     * @evidence contracts/common.md#clear-and-simple-design A callable interface with one signature and no members.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+     * @evidence contracts/common.md#meaningful-documentation The comment states when to use it and documents the parameter and the return value.
      */
     interface Closure {
         /**
@@ -32,7 +41,14 @@ export declare namespace IEncryptionPassword {
          */
         (props: IProps): IEncryptionPassword;
     }
-    /** Properties for the closure. */
+    /**
+     * Properties for the closure.
+     *
+     * @evidence contracts/common.md#principled-implementation The record carries what a password closure can choose by: the request or response headers, the body text, and whether the body is being encoded or decoded.
+     * @evidence contracts/common.md#clear-and-simple-design A three-field record with no behavior.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+     * @evidence contracts/common.md#meaningful-documentation The comment names it as the closure's properties; the direction values are self-descriptive.
+     */
     interface IProps {
         headers: Record<string, IConnection.HeaderValue | undefined>;
         body: string;

package/lib/IFetchEvent.d.ts

@@ -1,11 +1,36 @@
 import { IFetchRoute } from "./IFetchRoute";
+/**
+ * Event of one completed fetch, passed to {@link IConnection.logger}.
+ *
+ * `status` and `respond_at` are `null` when no response arrived, and
+ * `completed_at` is set after response processing or transport failure. Binary
+ * success streams are handed to the caller without reading their bytes, so this
+ * timestamp does not measure the duration of their consumption. `input` is the
+ * value the caller passed and `output` is the response data, the error body for
+ * a failed status, or `undefined` when the request threw. These values retain
+ * their original references. Errors before transport, such as encoding or URL
+ * construction failures, do not create a logged event.
+ *
+ * @evidence contracts/common.md#principled-implementation The event records the route, the request input, the observed status and output, and the three instants of the exchange, which is what a logger or a benchmark needs to compute latency and to group by endpoint.
+ * @evidence contracts/common.md#clear-and-simple-design A flat record; the two nullable members mark the states with no response.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Every value is measured by the pipeline; none is defaulted to a plausible value.
+ * @evidence contracts/common.md#meaningful-documentation The comment states the states with no response and what input and output hold.
+ */
 export interface IFetchEvent {
+    /** Metadata used to execute the request. */
     route: IFetchRoute<"DELETE" | "GET" | "HEAD" | "PATCH" | "POST" | "PUT">;
+    /** Route path normalized to one leading slash. */
     path: string;
+    /** Received HTTP status, or null when transport produced no response. */
     status: number | null;
+    /** Original request value; no defensive copy is made. */
     input: any;
+    /** Decoded payload or transferred binary stream, absent on processing error. */
     output: any;
+    /** Start of the transport operation, after request preparation. */
     started_at: Date;
+    /** Response arrival, before response body processing; null without a response. */
     respond_at: Date | null;
+    /** End of response processing, before the logger is awaited. */
     completed_at: Date;
 }

package/lib/IFetchEvent.js

@@ -1,21 +1,3 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-// export namespace IFetchEvent {
-//   export interface IFunction {
-//     (connection: IConnection, ...args: any[]): Promise<any>;
-//     METADATA: {
-//       method: "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "HEAD" | "OPTIONS";
-//       path: string;
-//       request: null | {
-//         type: string;
-//         encrypted: boolean;
-//       };
-//       response: null | {
-//         type: string;
-//         encrypted: boolean;
-//       };
-//     };
-//     status: null | number;
-//   }
-// }
 //# sourceMappingURL=IFetchEvent.js.map

package/lib/IFetchEvent.js.map

@@ -1 +1 @@
-{"version":3,"file":"IFetchEvent.js","sourceRoot":"","sources":["../src/IFetchEvent.ts"],"names":[],"mappings":";;AAaA,iCAAiC;AACjC,iCAAiC;AACjC,+DAA+D;AAC/D,kBAAkB;AAClB,kFAAkF;AAClF,sBAAsB;AACtB,0BAA0B;AAC1B,wBAAwB;AACxB,8BAA8B;AAC9B,WAAW;AACX,2BAA2B;AAC3B,wBAAwB;AACxB,8BAA8B;AAC9B,WAAW;AACX,SAAS;AACT,6BAA6B;AAC7B,MAAM;AACN,IAAI"}
+{"version":3,"file":"IFetchEvent.js","sourceRoot":"","sources":["../src/IFetchEvent.ts"],"names":[],"mappings":""}

package/lib/IFetchRoute.d.ts

@@ -29,15 +29,34 @@ export interface IFetchRoute<Method extends "HEAD" | "GET" | "POST" | "PUT" | "P
      * If you've forgotten to configuring this `parseQuery` property about the
      * `application/x-www-form-urlencoded` typed response body data, then only the
      * `URLSearchParams` typed instance would be returned instead.
+     *
+     * @evidence contracts/common.md#principled-implementation A response of type `application/x-www-form-urlencoded` is parsed with the route's function when there is one and is returned as `URLSearchParams` otherwise.
+     * @evidence contracts/common.md#clear-and-simple-design One optional method with one argument.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The parser is route data supplied by the generated SDK, with no default guess about the shape.
+     * @evidence contracts/common.md#meaningful-documentation The comment states when it is called and what happens without it.
      */
     parseQuery?(input: URLSearchParams): any;
 }
+/**
+ * Support types of {@link IFetchRoute}: the metadata of a request or response
+ * body.
+ *
+ * @evidence contracts/common.md#principled-implementation The conditional member types encode HTTP: only `DELETE`, `POST`, `PUT`, and `PATCH` requests may have a body, and `HEAD` responses have none, so a route that contradicts its method does not compile.
+ * @evidence contracts/common.md#clear-and-simple-design A record of the route facts the pipeline needs (method, path, optional template, bodies, status, query parser), with the nested body metadata in the namespace.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+ * @evidence contracts/common.md#meaningful-documentation Each member documents its meaning, including that the template exists since version 3.2.2.
+ */
 export declare namespace IFetchRoute {
     /**
      * Metadata of body.
      *
      * Describes how content-type being used in body, and whether encrypted or
      * not.
+     *
+     * @evidence contracts/common.md#principled-implementation A body is described by its content type, which selects the encoding, and by whether it is encrypted, which selects the fetcher; the union keeps the common types visible while allowing any other string.
+     * @evidence contracts/common.md#clear-and-simple-design Two fields, one of them optional.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+     * @evidence contracts/common.md#meaningful-documentation The comment states that it describes the content type and the encryption.
      */
     interface IBody {
         type: "application/json" | "application/x-www-form-urlencoded" | "multipart/form-data" | "text/plain" | (string & {});

package/lib/IPropagation.d.ts

@@ -7,20 +7,21 @@
  *
  * ```typescript
  * type Output = IPropagation<{
- *    200: ISeller.IAuthorized;
- *    400: TypeGuardError.IProps;
- * >};
+ *   200: ISeller.IAuthorized;
+ *   400: TypeGuardError.IProps;
+ * }>;
  *
  * const output: Output = await sdk.sellers.authenticate.join(input);
  * if (output.success) {
- *     // automatically casted to "ISeller.IAuthorized" type
- *     const authorized: ISeller.IAuthorized = output.data;
+ *   // automatically casted to "ISeller.IAuthorized" type
+ *   const authorized: ISeller.IAuthorized = output.data;
  * } else if (output.status === 400) {
- *     // automatically casted to "TypeGuardError.IProps" type
- *     const error: TypeGuardError.IProps = output.data;
+ *   // The unknown-status fallback overlaps numeric statuses. Validate the
+ *   // body before treating it as TypeGuardError.IProps.
+ *   const error: unknown = output.data;
  * } else {
- *     // unknown type when out of pre-defined status codes
- *     const result: unknown = output.data;
+ *   // unknown type when out of pre-defined status codes
+ *   const result: unknown = output.data;
  * }
  * ```
  *
@@ -33,6 +34,10 @@
  * @author Jeongho Nam - https://github.com/samchon
  * @template StatusMap Map of status code and its body data type.
  * @template Success Default success status code.
+ * @evidence contracts/common.md#principled-implementation Each configured status becomes a branch whose success flag is true for configured success statuses, 200 and 201 by default. A false-success fallback with numeric status and unknown data represents unconfigured responses; TypeScript cannot subtract numeric literals from number, so this fallback also overlaps configured failure statuses and status-only narrowing cannot prove their payload shape.
+ * @evidence contracts/common.md#clear-and-simple-design One mapped type indexed into a union, plus the fallback branch.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+ * @evidence contracts/common.md#meaningful-documentation The comment gives an example of narrowing and says which generated SDK option uses the type.
  */
 export type IPropagation<StatusMap extends {
     [P in IPropagation.Status]?: any;
@@ -46,6 +51,11 @@ export declare namespace IPropagation {
      * The special characters like `2XX`, `3XX`, `4XX`, `5XX` are meaning the
      * range of status codes. If `5XX` is specified, it means the status code is
      * in the range of `500` to `599`.
+     *
+     * @evidence contracts/common.md#principled-implementation A status is a number or one of the four range spellings, which is enough to configure both exact and ranged branches.
+     * @evidence contracts/common.md#clear-and-simple-design A single union.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+     * @evidence contracts/common.md#meaningful-documentation The comment defines the range spellings.
      */
     export type Status = number | "2XX" | "3XX" | "4XX" | "5XX";
     /**
@@ -54,6 +64,11 @@ export declare namespace IPropagation {
      * `IPropagation.IBranch` is a branch type composing `IPropagation` type,
      * which is gathering all possible status codes and their body data types as a
      * union type.
+     *
+     * @evidence contracts/common.md#principled-implementation A branch pairs a literal success flag with the status, the data, and the headers, and turns a range spelling into the union of its integers, so a narrowed status is a number the caller can compare.
+     * @evidence contracts/common.md#clear-and-simple-design One record with a conditional on the status member.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+     * @evidence contracts/common.md#meaningful-documentation The comment explains that it is the element of the propagation union.
      */
     export interface IBranch<Success extends boolean, StatusValue, BodyData> {
         success: Success;
@@ -61,8 +76,16 @@ export declare namespace IPropagation {
         data: BodyData;
         headers: Record<string, string | string[]>;
     }
-    /** Range of status codes by the first digit. */
-    export type StatusRange<T extends "2XX" | "3XX" | "4XX" | "5XX"> = T extends 0 ? IntRange<200, 299> : T extends 3 ? IntRange<300, 399> : T extends 4 ? IntRange<400, 499> : IntRange<500, 599>;
+    /**
+     * Range of status codes by the first digit, `"4XX"` for `400` to `499`.
+     *
+     * @evidence contracts/common.md#principled-implementation The first-digit spelling maps to the integers from its hundred up to the next hundred, computed by excluding a smaller enumeration from a larger one.
+     * @evidence contracts/common.md#clear-and-simple-design One conditional over the four spellings, using two private helper types.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+     * @evidence contracts/common.md#meaningful-documentation The comment gives the range rule with an example.
+     */
+    export type StatusRange<T extends "2XX" | "3XX" | "4XX" | "5XX"> = T extends "2XX" ? IntRange<200, 300> : T extends "3XX" ? IntRange<300, 400> : T extends "4XX" ? IntRange<400, 500> : IntRange<500, 600>;
+    /** Integers from `F` up to, not including, `T`. */
     type IntRange<F extends number, T extends number> = Exclude<Enumerate<T>, Enumerate<F>>;
     type Enumerate<N extends number, Acc extends number[] = []> = Acc["length"] extends N ? Acc[number] : Enumerate<N, [...Acc, Acc["length"]]>;
     export {};

package/lib/NestiaSimulator.d.ts

@@ -1,13 +1,56 @@
+/**
+ * Request validation for the mockup simulator of a generated SDK.
+ *
+ * A simulated function does not call a server. It validates its input with
+ * typia and, when the input is wrong, throws the `HttpError` with status 400
+ * that the real server would answer with.
+ *
+ * @evidence contracts/common.md#principled-implementation Each validator runs the caller's assertion and converts a readable typia `TypeGuardError` shape into an `HttpError` 400 whose JSON body carries the method, path, expected type and value plus a message naming the failing part. A shared snapshot reads each needed property once; malformed or unreadable shapes rethrow the caller's original value. Payload values must support JSON serialization, whose errors still propagate.
+ * @evidence contracts/common.md#clear-and-simple-design One public entry point, `assert`, returns four validators that differ only in their message, sharing one private conversion; the shape snapshot reader and the error interface are module-private.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Classification checks the readable error structure (method, path, expected type, name, message and stack) rather than its class, then captures the payload value. A value that lacks any of those fields with the expected types, or whose property access throws, is not classified as a type guard failure and is rethrown unchanged; unrelated task errors are neither replaced nor swallowed.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what the simulator validates and what it throws.
+ */
 export declare namespace NestiaSimulator {
+    /**
+     * Route facts the simulator needs to build its 400 error: the host, the path,
+     * and the method.
+     *
+     * `contentType` is the content type of the route's success response, which
+     * the generated code answers with; the simulated 400 is JSON whatever it is.
+     *
+     * @evidence contracts/common.md#principled-implementation The host, path, and method identify the request in the error, and the content type describes the success response of the generated function, which the generated code answers with.
+     * @evidence contracts/common.md#clear-and-simple-design A four-field record with no behavior.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The values are supplied by the generated SDK for its own route.
+     * @evidence contracts/common.md#meaningful-documentation The comment says what each part is used for, with the `contentType` member documenting when it is `null`.
+     */
     interface IProps {
         host: string;
         path: string;
-        method: "GET" | "POST" | "PATCH" | "PUT" | "DELETE";
-        contentType: string;
+        method: "GET" | "POST" | "PATCH" | "PUT" | "DELETE" | "HEAD";
+        /**
+         * Content type of the route's success response, `null` for one without a
+         * body such as `HEAD`'s. The simulated 400 is JSON whatever it is, as the
+         * server's is.
+         */
+        contentType: string | null;
     }
+    /**
+     * Creates the validators of one simulated route: `param(name)`, `query`,
+     * `body`, and `headers`.
+     *
+     * Each validator takes the closure that performs the typia assertion. A
+     * failed assertion throws an `HttpError` with status 400 and a JSON body; any
+     * other error is rethrown as it is.
+     *
+     * @evidence contracts/common.md#principled-implementation The four validators share the conversion in `validate` and differ in the message they attach, which names the URL parameter or states that the query, body, or headers do not follow the promised type.
+     * @evidence contracts/common.md#clear-and-simple-design One function returning the four validators as an object, so a generated simulator has one import.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The HTTP error is the one the real server returns; nothing is simulated beyond running the assertion.
+     * @evidence contracts/common.md#meaningful-documentation The comment states what it returns and what each validator throws.
+     */
     const assert: (props: IProps) => {
         param: (name: string) => <T>(task: () => T) => void;
         query: <T>(task: () => T) => void;
         body: <T>(task: () => T) => void;
+        headers: <T>(task: () => T) => void;
     };
 }

package/lib/NestiaSimulator.js

@@ -3,13 +3,39 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.NestiaSimulator = void 0;
 const HttpError_1 = require("./HttpError");
 const join_host_and_path_1 = require("./internal/join_host_and_path");
+/**
+ * Request validation for the mockup simulator of a generated SDK.
+ *
+ * A simulated function does not call a server. It validates its input with
+ * typia and, when the input is wrong, throws the `HttpError` with status 400
+ * that the real server would answer with.
+ *
+ * @evidence contracts/common.md#principled-implementation Each validator runs the caller's assertion and converts a readable typia `TypeGuardError` shape into an `HttpError` 400 whose JSON body carries the method, path, expected type and value plus a message naming the failing part. A shared snapshot reads each needed property once; malformed or unreadable shapes rethrow the caller's original value. Payload values must support JSON serialization, whose errors still propagate.
+ * @evidence contracts/common.md#clear-and-simple-design One public entry point, `assert`, returns four validators that differ only in their message, sharing one private conversion; the shape snapshot reader and the error interface are module-private.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Classification checks the readable error structure (method, path, expected type, name, message and stack) rather than its class, then captures the payload value. A value that lacks any of those fields with the expected types, or whose property access throws, is not classified as a type guard failure and is rethrown unchanged; unrelated task errors are neither replaced nor swallowed.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what the simulator validates and what it throws.
+ */
 var NestiaSimulator;
 (function (NestiaSimulator) {
+    /**
+     * Creates the validators of one simulated route: `param(name)`, `query`,
+     * `body`, and `headers`.
+     *
+     * Each validator takes the closure that performs the typia assertion. A
+     * failed assertion throws an `HttpError` with status 400 and a JSON body; any
+     * other error is rethrown as it is.
+     *
+     * @evidence contracts/common.md#principled-implementation The four validators share the conversion in `validate` and differ in the message they attach, which names the URL parameter or states that the query, body, or headers do not follow the promised type.
+     * @evidence contracts/common.md#clear-and-simple-design One function returning the four validators as an object, so a generated simulator has one import.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The HTTP error is the one the real server returns; nothing is simulated beyond running the assertion.
+     * @evidence contracts/common.md#meaningful-documentation The comment states what it returns and what each validator throws.
+     */
     NestiaSimulator.assert = (props) => {
         return {
             param: param(props),
             query: query(props),
             body: body(props),
+            headers: headers(props),
         };
     };
     const param = (props) => (name) => (task) => {
@@ -17,29 +43,54 @@ var NestiaSimulator;
     };
     const query = (props) => (task) => validate(() => "Request query parameters are not following the promised type.")(props)(task);
     const body = (props) => (task) => validate(() => "Request body is not following the promised type.")(props)(task);
-    const validate = (message, path) => (props) => (task) => {
+    const headers = (props) => (task) => validate(() => "Request headers are not following the promised type.")(props)(task);
+    const validate = (message) => (props) => (task) => {
         try {
             task();
         }
         catch (exp) {
-            if (isTypeGuardError(exp))
+            const guard = readTypeGuardError(exp);
+            if (guard !== null)
                 throw new HttpError_1.HttpError(props.method, (0, join_host_and_path_1.join_host_and_path)(props.host, props.path), 400, {
-                    "Content-Type": props.contentType,
+                    "Content-Type": "application/json",
                 }, JSON.stringify({
-                    method: exp.method,
-                    path: path !== null && path !== void 0 ? path : exp.path,
-                    expected: exp.expected,
-                    value: exp.value,
-                    message: message(exp),
+                    method: guard.method,
+                    path: guard.path,
+                    expected: guard.expected,
+                    value: guard.value,
+                    message: message(guard),
                 }));
             throw exp;
         }
     };
 })(NestiaSimulator || (exports.NestiaSimulator = NestiaSimulator = {}));
-const isTypeGuardError = (input) => "string" === typeof input.method &&
-    (undefined === input.path || "string" === typeof input.path) &&
-    "string" === typeof input.expected &&
-    "string" === typeof input.name &&
-    "string" === typeof input.message &&
-    (undefined === input.stack || "string" === typeof input.stack);
+const readTypeGuardError = (input) => {
+    if (typeof input !== "object" || input === null)
+        return null;
+    try {
+        const method = input.method;
+        if (typeof method !== "string")
+            return null;
+        const path = input.path;
+        if (path !== undefined && typeof path !== "string")
+            return null;
+        const expected = input.expected;
+        if (typeof expected !== "string")
+            return null;
+        const name = input.name;
+        if (typeof name !== "string")
+            return null;
+        const message = input.message;
+        if (typeof message !== "string")
+            return null;
+        const stack = input.stack;
+        if (stack !== undefined && typeof stack !== "string")
+            return null;
+        const value = input.value;
+        return { method, path, expected, name, message, stack, value };
+    }
+    catch (_a) {
+        return null;
+    }
+};
 //# sourceMappingURL=NestiaSimulator.js.map

package/lib/NestiaSimulator.js.map

@@ -1 +1 @@
-{"version":3,"file":"NestiaSimulator.js","sourceRoot":"","sources":["../src/NestiaSimulator.ts"],"names":[],"mappings":";;;AAAA,2CAAwC;AACxC,sEAAmE;AAEnE,IAAiB,eAAe,CAgE/B;AAhED,WAAiB,eAAe;IAQjB,sBAAM,GAAG,CAAC,KAAa,EAAE,EAAE;QACtC,OAAO;YACL,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC;YACnB,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC;YACnB,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC;SAClB,CAAC;IACJ,CAAC,CAAC;IACF,MAAM,KAAK,GACT,CAAC,KAAa,EAAE,EAAE,CAClB,CAAC,IAAY,EAAE,EAAE,CACjB,CAAI,IAAa,EAAQ,EAAE;QACzB,QAAQ,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,kBAAkB,IAAI,YAAY,GAAG,CAAC,QAAQ,QAAQ,CAAC,CACvE,KAAK,CACN,CAAC,IAAI,CAAC,CAAC;IACV,CAAC,CAAC;IAEJ,MAAM,KAAK,GACT,CAAC,KAAa,EAAE,EAAE,CAClB,CAAI,IAAa,EAAQ,EAAE,CACzB,QAAQ,CACN,GAAG,EAAE,CAAC,+DAA+D,CACtE,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC;IAEnB,MAAM,IAAI,GACR,CAAC,KAAa,EAAE,EAAE,CAClB,CAAI,IAAa,EAAQ,EAAE,CACzB,QAAQ,CAAC,GAAG,EAAE,CAAC,kDAAkD,CAAC,CAAC,KAAK,CAAC,CACvE,IAAI,CACL,CAAC;IAEN,MAAM,QAAQ,GACZ,CAAC,OAAwC,EAAE,IAAa,EAAE,EAAE,CAC5D,CAAC,KAAa,EAAE,EAAE,CAClB,CAAI,IAAa,EAAQ,EAAE;QACzB,IAAI,CAAC;YACH,IAAI,EAAE,CAAC;QACT,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,gBAAgB,CAAC,GAAG,CAAC;gBACvB,MAAM,IAAI,qBAAS,CACjB,KAAK,CAAC,MAAM,EACZ,IAAA,uCAAkB,EAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,EAC1C,GAAG,EACH;oBACE,cAAc,EAAE,KAAK,CAAC,WAAW;iBAClC,EACD,IAAI,CAAC,SAAS,CAAC;oBACb,MAAM,EAAE,GAAG,CAAC,MAAM;oBAClB,IAAI,EAAE,IAAI,aAAJ,IAAI,cAAJ,IAAI,GAAI,GAAG,CAAC,IAAI;oBACtB,QAAQ,EAAE,GAAG,CAAC,QAAQ;oBACtB,KAAK,EAAE,GAAG,CAAC,KAAK;oBAChB,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC;iBACtB,CAAC,CACH,CAAC;YACJ,MAAM,GAAG,CAAC;QACZ,CAAC;IACH,CAAC,CAAC;AACN,CAAC,EAhEgB,eAAe,aAAf,eAAe,GAAf,eAAe,QAgE/B;AAED,MAAM,gBAAgB,GAAG,CAAC,KAAU,EAA2B,EAAE,CAC/D,QAAQ,KAAK,OAAO,KAAK,CAAC,MAAM;IAChC,CAAC,SAAS,KAAK,KAAK,CAAC,IAAI,IAAI,QAAQ,KAAK,OAAO,KAAK,CAAC,IAAI,CAAC;IAC5D,QAAQ,KAAK,OAAO,KAAK,CAAC,QAAQ;IAClC,QAAQ,KAAK,OAAO,KAAK,CAAC,IAAI;IAC9B,QAAQ,KAAK,OAAO,KAAK,CAAC,OAAO;IACjC,CAAC,SAAS,KAAK,KAAK,CAAC,KAAK,IAAI,QAAQ,KAAK,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC"}
+{"version":3,"file":"NestiaSimulator.js","sourceRoot":"","sources":["../src/NestiaSimulator.ts"],"names":[],"mappings":"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"}

package/lib/NestiaSimulator.mjs

@@ -7,7 +7,8 @@ let NestiaSimulator;
 		return {
 			param: param(props),
 			query: query(props),
-			body: body(props)
+			body: body(props),
+			headers: headers(props)
 		};
 	};
 	const param = (props) => (name) => (task) => {
@@ -15,22 +16,51 @@ let NestiaSimulator;
 	};
 	const query = (props) => (task) => validate(() => "Request query parameters are not following the promised type.")(props)(task);
 	const body = (props) => (task) => validate(() => "Request body is not following the promised type.")(props)(task);
-	const validate = (message, path) => (props) => (task) => {
+	const headers = (props) => (task) => validate(() => "Request headers are not following the promised type.")(props)(task);
+	const validate = (message) => (props) => (task) => {
 		try {
 			task();
 		} catch (exp) {
-			if (isTypeGuardError(exp)) throw new HttpError(props.method, join_host_and_path(props.host, props.path), 400, { "Content-Type": props.contentType }, JSON.stringify({
-				method: exp.method,
-				path: path ?? exp.path,
-				expected: exp.expected,
-				value: exp.value,
-				message: message(exp)
+			const guard = readTypeGuardError(exp);
+			if (guard !== null) throw new HttpError(props.method, join_host_and_path(props.host, props.path), 400, { "Content-Type": "application/json" }, JSON.stringify({
+				method: guard.method,
+				path: guard.path,
+				expected: guard.expected,
+				value: guard.value,
+				message: message(guard)
 			}));
 			throw exp;
 		}
 	};
 })(NestiaSimulator || (NestiaSimulator = {}));
-const isTypeGuardError = (input) => "string" === typeof input.method && (void 0 === input.path || "string" === typeof input.path) && "string" === typeof input.expected && "string" === typeof input.name && "string" === typeof input.message && (void 0 === input.stack || "string" === typeof input.stack);
+const readTypeGuardError = (input) => {
+	if (typeof input !== "object" || input === null) return null;
+	try {
+		const method = input.method;
+		if (typeof method !== "string") return null;
+		const path = input.path;
+		if (path !== void 0 && typeof path !== "string") return null;
+		const expected = input.expected;
+		if (typeof expected !== "string") return null;
+		const name = input.name;
+		if (typeof name !== "string") return null;
+		const message = input.message;
+		if (typeof message !== "string") return null;
+		const stack = input.stack;
+		if (stack !== void 0 && typeof stack !== "string") return null;
+		return {
+			method,
+			path,
+			expected,
+			name,
+			message,
+			stack,
+			value: input.value
+		};
+	} catch {
+		return null;
+	}
+};
 //#endregion
 export { NestiaSimulator };