@nestia/core 14.0.1 → 14.0.2

package/src/decorators/SwaggerExample.ts

@@ -9,30 +9,43 @@
  * The decorators only affect Swagger document generation. They do not change
  * runtime behavior, validation, or SDK function signatures.
  *
- * @author Jeongho Nam - https://github.com/samchon
- * @example
- *   ```typescript
- *   import core from "@nestia/core";
- *   import { Controller } from "@nestjs/common";
- *   import typia from "typia";
+ * Example:
+ *
+ * ```typescript
+ * import core from "@nestia/core";
+ * import { Controller } from "@nestjs/common";
+ * import typia from "typia";
  *
- *   @Controller("bbs/articles")
- *   export class BbsArticlesController {
- *     // Single response example.
- *     @core.SwaggerExample.Response(typia.random<IBbsArticle>())
- *     @core.TypedRoute.Post()
- *     public async create(
- *       // Multiple named parameter examples plus a default one.
- *       @core.SwaggerExample.Parameter(typia.random<IBbsArticle.ICreate>())
- *       @core.SwaggerExample.Parameter("x", typia.random<IBbsArticle.ICreate>())
- *       @core.SwaggerExample.Parameter("y", typia.random<IBbsArticle.ICreate>())
- *       @core.TypedBody()
- *       input: IBbsArticle.ICreate,
- *     ): Promise<IBbsArticle> {
- *       // ...
- *     }
+ * @Controller("bbs/articles")
+ * export class BbsArticlesController {
+ *   // Single response example.
+ *   @core.SwaggerExample.Response(typia.random<IBbsArticle>())
+ *   @core.TypedRoute.Post()
+ *   public async create(
+ *     // Multiple named parameter examples plus a default one.
+ *     @core.SwaggerExample.Parameter(typia.random<IBbsArticle.ICreate>())
+ *     @core.SwaggerExample.Parameter(
+ *       "x",
+ *       typia.random<IBbsArticle.ICreate>(),
+ *     )
+ *     @core.SwaggerExample.Parameter(
+ *       "y",
+ *       typia.random<IBbsArticle.ICreate>(),
+ *     )
+ *     @core.TypedBody()
+ *     input: IBbsArticle.ICreate,
+ *   ): Promise<IBbsArticle> {
+ *     // ...
  *   }
- *   ```;
+ * }
+ * ```
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @evidence contracts/common.md#principled-implementation Examples are stored as metadata on the method or on the parameter position; a call with one argument sets the single example, and a call with a key and a value adds a named example, so both OpenAPI forms are expressible.
+ * @evidence contracts/common.md#clear-and-simple-design Two decorators over three private metadata helpers that find or create the record.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The examples are caller data, and nothing is generated here.
+ * @evidence contracts/common.md#meaningful-documentation The comment documents both decorators and the two call forms.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Example metadata contains caller values and parameter indices without a native path or process boundary.
  */
 export namespace SwaggerExample {
   /**
@@ -51,6 +64,11 @@ export namespace SwaggerExample {
    * document.
    *
    * @template T Type of the example value (typically the route's response DTO).
+   * @evidence contracts/common.md#principled-implementation The value or the keyed value is recorded on the method's response example record, which the document generator reads.
+   * @evidence contracts/common.md#clear-and-simple-design One decorator with two overloads.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The value is stored as given.
+   * @evidence contracts/common.md#meaningful-documentation The comment documents the overloads with an example.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation Example metadata contains caller values and parameter indices without a native path or process boundary.
    */
   export function Response<T>(value: T): MethodDecorator;
   export function Response<T>(key: string, value: T): MethodDecorator;
@@ -81,6 +99,11 @@ export namespace SwaggerExample {
    * `@TypedParam()`, `@TypedQuery()`, etc.); decorator order does not matter.
    *
    * @template T Type of the example value (typically the parameter's DTO).
+   * @evidence contracts/common.md#principled-implementation The value or the keyed value is recorded on the record for that parameter index, so several parameters keep separate examples.
+   * @evidence contracts/common.md#clear-and-simple-design One decorator with two overloads.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The value is stored as given.
+   * @evidence contracts/common.md#meaningful-documentation The comment documents the overloads with an example.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation Example metadata contains caller values and parameter indices without a native path or process boundary.
    */
   export function Parameter<T>(value: T): ParameterDecorator;
   export function Parameter<T>(key: string, value: T): ParameterDecorator;
@@ -100,6 +123,12 @@ export namespace SwaggerExample {
    * Reflects the OpenAPI spec's two example fields: a single default `example`,
    * and/or a named map `examples`. `index` is used internally to associate
    * parameter examples with the right parameter position.
+   *
+   * @evidence contracts/common.md#principled-implementation The record holds the single example, the named examples, and the parameter index, which is everything the generator needs to attach examples.
+   * @evidence contracts/common.md#clear-and-simple-design A flat record whose members are all 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 the meaning of the members.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation Example metadata contains caller values and parameter indices without a native path or process boundary.
    */
   export interface IData<T> {
     examples?: Record<string, T>;

package/src/decorators/TypedBody.ts

@@ -16,14 +16,21 @@ import { validate_request_body } from "./internal/validate_request_body";
  *
  * `TypedBody` is a decorator function getting `application/json` typed data
  * from request body. Also, it validates the request body data type through
- * [typia](https://github.com/samchon/typia) and the validation speed is maximum
- * 20,000x times faster than `class-validator`.
+ * [typia](https://github.com/samchon/typia) using the declared TypeScript
+ * type.
  *
  * For reference, when the request body data is not following the promised type
  * `T`, `BadRequestException` error (status code: 400) would be thrown.
+ * Successful assert and validate callbacks supply the decorated argument; clone
+ * validators can therefore return a copy without replacing the raw body.
  *
  * @author Jeongho Nam - https://github.com/samchon
  * @param validator Custom validator if required. Default is `typia.validate()`
+ * @evidence contracts/common.md#principled-implementation An absent body with no content type is accepted only when the validator accepts undefined; any other body must be application/json. The checker returns explicitly tagged successful data or the existing validation error, so cloned values reach the argument while raw request.body retains its identity and errors retain their response priority.
+ * @evidence contracts/common.md#clear-and-simple-design One parameter decorator composes shared media/absence checks and tagged resolution. The shared internal runner owns descriptor selection and error translation; PlainBody uses the same successful-value protocol for its optional transformed text assertion, preserving raw text when no assertion exists and preserving its absent-input/media error priority.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The validator is generated from the type by the transform; without it the decorator throws the configuration error unless the guard is turned off.
+ * @evidence contracts/common.md#meaningful-documentation The comment documents the decorator, the media type rule, and the validation modes.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Parsed HTTP bodies and validation callbacks are independent of native filesystem and process representation.
  */
 export function TypedBody<T>(
   validator?: IRequestBodyValidator<T>,
@@ -36,9 +43,11 @@ export function TypedBody<T>(
     const request: express.Request | FastifyRequest = context
       .switchToHttp()
       .getRequest();
-    if (is_request_body_undefined(request) && checker(undefined as T) === null)
-      return undefined;
-    else if (
+    if (is_request_body_undefined(request)) {
+      const result = checker.resolve(undefined);
+      if (result.success) return result.data;
+    }
+    if (
       is_media_type(request.headers["content-type"], "application/json") ===
       false
     )
@@ -46,8 +55,8 @@ export function TypedBody<T>(
         `Request body type is not "application/json".`,
       );
 
-    const error: Error | null = checker(request.body);
-    if (error !== null) throw error;
-    return request.body;
+    const result = checker.resolve(request.body);
+    if (!result.success) throw result.error;
+    return result.data;
   })();
 }

package/src/decorators/TypedException.ts

@@ -117,6 +117,16 @@ export function TypedException<T>(...args: any[]): MethodDecorator {
     return descriptor;
   };
 }
+/**
+ * Types of {@link TypedException}: the response properties a declaration
+ * carries, and its named examples.
+ *
+ * @evidence contracts/common.md#principled-implementation The decorator records each declared status, description, and example on the method's metadata list, so the document generator can add the responses; the overloads without a type argument return `never` so a missing type argument is a compile error.
+ * @evidence contracts/common.md#clear-and-simple-design One decorator whose overloads split the property form and the positional form.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts It records declarations and never changes how the route responds.
+ * @evidence contracts/common.md#meaningful-documentation The comment documents the forms and that the status accepts range spellings.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Response declarations contain HTTP status codes and examples, without native files or subprocesses.
+ */
 export namespace TypedException {
   /** Properties for the exception. */
   export interface IProps<T> {

package/src/decorators/TypedFormData.ts

@@ -74,6 +74,11 @@ import { validate_request_form_data } from "./internal/validate_request_form_dat
  * ```
  *
  * @author Jeongho Nam - https://github.com/samchon
+ * @evidence contracts/common.md#principled-implementation The body must be multipart; multer parses it through the caller's factory into a `FormData` of fields and `File` objects, uploaded temp files are read and always removed afterwards, multer limits map to 413 or 400 responses, and the assembled form is checked by the transformed validator.
+ * @evidence contracts/common.md#clear-and-simple-design One decorator with the multipart decoding, the error mapping, and the file conversion as separate module-private functions, and the multer instance created once by a `Singleton`.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Errors are mapped by multer's documented codes and by exact busboy messages, and no file name is special-cased; a runtime without `File` is refused up front.
+ * @evidence contracts/common.md#meaningful-documentation The comment documents the factory, the memory and disk storage requirement, and the validation.
+ * @evidence contracts/portability.md#os-neutral-implementation Uploaded disk paths come from the storage engine and are consumed directly by Node fs readFile and rm; filename is File metadata rather than a reconstructed native path. Structural multer method signatures specify middleware rather than native path spelling.
  * @todo Change to ReadableStream through configuring storage engine of multer
  */
 export namespace TypedFormData {
@@ -134,12 +139,65 @@ export namespace TypedFormData {
     })();
   }
 
-  /** Base type of the `multer` or `fastify-multer`. */
+  /**
+   * Base type of the `multer` or `fastify-multer`.
+   *
+   * @evidence contracts/common.md#principled-implementation The interface names the multer methods that identify a multer instance structurally, so an application can pass its own instance without this package depending on a multer type at runtime.
+   * @evidence contracts/common.md#clear-and-simple-design Five method members 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 states its purpose as the structural stand-in for multer.
+   * @evidence contracts/portability.md#os-neutral-implementation Uploaded disk paths come from the storage engine and are consumed directly by Node fs readFile and rm; filename is File metadata rather than a reconstructed native path. Structural multer method signatures specify middleware rather than native path spelling.
+   */
   export interface IMulterBase {
+    /**
+     * Middleware factory for a single file field.
+     *
+     * @evidence contracts/common.md#principled-implementation The member mirrors multer's single-file middleware factory.
+     * @evidence contracts/common.md#clear-and-simple-design One method signature.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+     * @evidence contracts/common.md#meaningful-documentation The member is named after the multer method it mirrors.
+     * @evidence contracts/portability.md#os-neutral-implementation Uploaded disk paths come from the storage engine and are consumed directly by Node fs readFile and rm; filename is File metadata rather than a reconstructed native path. Structural multer method signatures specify middleware rather than native path spelling.
+     */
     single(fieldName: string): any;
+    /**
+     * Middleware factory for an array of files under one field.
+     *
+     * @evidence contracts/common.md#principled-implementation The member mirrors multer's array-of-files middleware factory.
+     * @evidence contracts/common.md#clear-and-simple-design One method signature.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+     * @evidence contracts/common.md#meaningful-documentation The member is named after the multer method it mirrors.
+     * @evidence contracts/portability.md#os-neutral-implementation Uploaded disk paths come from the storage engine and are consumed directly by Node fs readFile and rm; filename is File metadata rather than a reconstructed native path. Structural multer method signatures specify middleware rather than native path spelling.
+     */
     array(fieldName: string, maxCount?: number): any;
+    /**
+     * Middleware factory for several named file fields.
+     *
+     * @evidence contracts/common.md#principled-implementation The member mirrors multer's named-fields middleware factory, which is the one the decorator uses when the transform lists the file fields.
+     * @evidence contracts/common.md#clear-and-simple-design One method signature.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+     * @evidence contracts/common.md#meaningful-documentation The member is named after the multer method it mirrors.
+     * @evidence contracts/portability.md#os-neutral-implementation Uploaded disk paths come from the storage engine and are consumed directly by Node fs readFile and rm; filename is File metadata rather than a reconstructed native path. Structural multer method signatures specify middleware rather than native path spelling.
+     */
     fields(fields: readonly object[]): any;
+    /**
+     * Middleware factory that accepts every file field.
+     *
+     * @evidence contracts/common.md#principled-implementation The member mirrors multer's accept-any-file middleware factory, which the decorator uses when no transform names the file fields.
+     * @evidence contracts/common.md#clear-and-simple-design One method signature.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+     * @evidence contracts/common.md#meaningful-documentation The member is named after the multer method it mirrors.
+     * @evidence contracts/portability.md#os-neutral-implementation Uploaded disk paths come from the storage engine and are consumed directly by Node fs readFile and rm; filename is File metadata rather than a reconstructed native path. Structural multer method signatures specify middleware rather than native path spelling.
+     */
     any(): any;
+    /**
+     * Middleware factory that accepts text fields only.
+     *
+     * @evidence contracts/common.md#principled-implementation The member mirrors multer's text-fields-only middleware factory.
+     * @evidence contracts/common.md#clear-and-simple-design One method signature.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+     * @evidence contracts/common.md#meaningful-documentation The member is named after the multer method it mirrors.
+     * @evidence contracts/portability.md#os-neutral-implementation Uploaded disk paths come from the storage engine and are consumed directly by Node fs readFile and rm; filename is File metadata rather than a reconstructed native path. Structural multer method signatures specify middleware rather than native path spelling.
+     */
     none(): any;
   }
 }

package/src/decorators/TypedHeaders.ts

@@ -47,6 +47,11 @@ import { validate_request_headers } from "./internal/validate_request_headers";
  *
  * @author Jeongho Nam - https://github.com/samchon
  * @returns Parameter decorator
+ * @evidence contracts/common.md#principled-implementation The header record of the request is decoded by the transformed function into the typed object, whose failure is thrown as the response; header names arrive lower-cased from Node, which the generated decoder expects.
+ * @evidence contracts/common.md#clear-and-simple-design One parameter decorator built from the shared header validator runner.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The decoder is generated from the type by the transform; without it the request headers are passed through only when the configuration guard is off.
+ * @evidence contracts/common.md#meaningful-documentation The comment documents the decoding, the supported property types, and the validation modes.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Header names and decoded values belong to the HTTP protocol and are not native filesystem identities.
  */
 export function TypedHeaders<T extends object>(
   validator?: IRequestHeadersValidator<T>,

package/src/decorators/TypedParam.ts

@@ -30,7 +30,16 @@ import { NoTransformConfigurationError } from "./NoTransformConfigurationError";
  *
  * @author Jeongho Nam - https://github.com/samchon
  * @param name URL Parameter name
+ * @param assert Conversion and assertion supplied by the compile-time transform
+ * @param validate Emit an errors array on validation failure when true;
+ *   otherwise expose the first failure as flat path, reason, expected and value
+ *   fields.
  * @returns Parameter decorator
+ * @evidence contracts/common.md#principled-implementation The path parameter arrives as a string and is converted by the assertion function the transform generated for the declared type, so a value of the wrong type produces a 400 that names the parameter; the `validate` flag only changes the error body from the flat form to an `errors` array.
+ * @evidence contracts/common.md#clear-and-simple-design One decorator with one conversion function and one error-shaping branch.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The conversion is generated from the declared type; without the transform the raw string is returned only when the configuration guard is off.
+ * @evidence contracts/common.md#meaningful-documentation The comment documents the supported types and the two error shapes.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation The named path segment is an HTTP route parameter whose text is decoded by the generated validator; no native path is resolved.
  */
 export function TypedParam<T extends boolean | bigint | number | string | null>(
   name: string,

package/src/decorators/TypedQuery.ts

@@ -45,6 +45,11 @@ import { validate_request_query } from "./internal/validate_request_query";
  *
  * @author Jeongho Nam - https://github.com/samchon
  * @returns Parameter decorator
+ * @evidence contracts/common.md#principled-implementation The query string is read from the request URL after the first question mark, grouped by the transformed decoder into the typed object, and a failure is thrown as the 400 response; the decoder receives a `URLSearchParams`, so both Express and Fastify requests are handled by the same code.
+ * @evidence contracts/common.md#clear-and-simple-design One parameter decorator on top of the shared query validator runner.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The decoder is generated from the type by the transform; without it the grouped raw query is returned only when the configuration guard is off.
+ * @evidence contracts/common.md#meaningful-documentation The comment documents the supported property types and the validation modes.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Query decoding and response encoding operate on URLSearchParams and HTTP route metadata rather than native filesystem paths.
  */
 export function TypedQuery<T extends object>(
   validator?: IRequestQueryValidator<T>,
@@ -64,6 +69,17 @@ export function TypedQuery<T extends object>(
     return output;
   })();
 }
+/**
+ * Variants of {@link TypedQuery}: `TypedQuery.Body` reads an urlencoded body,
+ * and `TypedQuery.Get`, `Post`, `Put`, `Patch`, and `Delete` return the value
+ * as an urlencoded response.
+ *
+ * @evidence contracts/common.md#principled-implementation `Body` requires the `application/x-www-form-urlencoded` media type and decodes the parsed body, and the route decorators serialize the returned value through the querifier the transform chose and set the response content type.
+ * @evidence contracts/common.md#clear-and-simple-design One body decorator and one generator that creates the five route decorators, with a small adapter class for parsed bodies.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The route decorators copy typia's marker properties onto themselves exactly as `TypedRoute` does, which mutates only these exported functions.
+ * @evidence contracts/common.md#meaningful-documentation The comment documents the body decorator and the route decorators.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Query decoding and response encoding operate on URLSearchParams and HTTP route metadata rather than native filesystem paths.
+ */
 export namespace TypedQuery {
   /**
    * Request body decorator.

package/src/decorators/TypedRoute.ts

@@ -23,17 +23,21 @@ import { route_error } from "./internal/route_error";
 /**
  * Type safe router decorator functions.
  *
- * `TypedRoute` is a module containing router decorator functions which can
- * boost up JSON string conversion speed about 200x times faster than
- * `class-transformer`. Furthermore, such JSON string conversion is even type
- * safe through [typia](https://github.com/samchon/typia).
+ * `TypedRoute` provides router decorators that serialize response values with
+ * [typia](https://github.com/samchon/typia) functions generated from the
+ * declared return type.
  *
- * For reference, if you try to invalid data that is not following the promised
- * type `T`, 500 internal server error would be thrown. Also, as `TypedRoute`
- * composes JSON string through `typia.assertStringify<T>()` function, it is not
- * possible to modify response data through interceptors.
+ * The default assert serializer rejects a response outside the declared type
+ * with a 500 error. The configured stringify mode can choose a different
+ * validation policy; `validate.log` logs failures and returns JSON text.
+ * Interceptors that run after this serializer receive the serialized string.
  *
  * @author Jeongho Nam - https://github.com/samchon
+ * @evidence contracts/common.md#principled-implementation Each method decorator combines Nest's router decorator, a JSON content type, and an interceptor that stringifies the returned value with the function the transform selected, so the JSON text is produced by generated code; an error thrown by the handler is routed to the registered exception converters.
+ * @evidence contracts/common.md#clear-and-simple-design One generator function creates the five HTTP-method decorators, and the interceptor and the router table are module-private.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The loop after the namespace copies the marker properties of typia's stringify functions onto the decorators for the transform, which mutates only these exported functions; the logger is a module variable, not a patched global.
+ * @evidence contracts/common.md#meaningful-documentation The comment documents the decorator family, the path and stringify arguments, and the validation modes.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Routing paths and serialized response values are HTTP protocol data; the interceptor and logger do not define a native file or subprocess boundary.
  */
 export namespace TypedRoute {
   /**
@@ -53,7 +57,7 @@ export namespace TypedRoute {
   export const Post = Generator("Post");
 
   /**
-   * Router decorator function for the PATH method.
+   * Router decorator function for the PATCH method.
    *
    * @param path Path of the HTTP request
    * @returns Method decorator
@@ -82,7 +86,7 @@ export namespace TypedRoute {
    * If you've configured the transformation option to `validate.log` in the
    * `tsconfig.json` file, then the error log information of the response
    * validation failure would be logged through this function instead of
-   * throwing the 400 bad request error.
+   * throwing the 500 internal server error.
    *
    * By the way, be careful. If you've configured the response transformation
    * option to be `validate.log`, client may get wrong response data. Therefore,
@@ -90,6 +94,11 @@ export namespace TypedRoute {
    *
    * @default console.log
    * @param func Logger function
+   * @evidence contracts/common.md#principled-implementation It replaces the module's logger variable, which the `validate.log` mode calls when a response fails validation, and the default is `console.log`.
+   * @evidence contracts/common.md#clear-and-simple-design One assignment.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It changes only the logger variable.
+   * @evidence contracts/common.md#meaningful-documentation The comment states which mode uses the logger.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation Routing paths and serialized response values are HTTP protocol data; the interceptor and logger do not define a native file or subprocess boundary.
    */
   export function setValidateErrorLogger(
     func: (log: IValidateErrorLog) => void,
@@ -109,6 +118,12 @@ export namespace TypedRoute {
    * information `IValidateErrorLog` would be logged through the
    * {@link setValidateErrorLogger} function instead of throwing the 400 bad
    * request error.
+   *
+   * @evidence contracts/common.md#principled-implementation The record carries the method, the path, the validation errors, and the offending data, which is what a logger needs to report a response that failed its type.
+   * @evidence contracts/common.md#clear-and-simple-design A flat 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 Each member documents its meaning.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation Routing paths and serialized response values are HTTP protocol data; the interceptor and logger do not define a native file or subprocess boundary.
    */
   export interface IValidateErrorLog {
     /** HTTP method of the request. */

package/src/decorators/WebSocketRoute.ts

@@ -38,6 +38,11 @@ import { validate_request_query } from "./internal/validate_request_query";
  * @author Jeongho Nam - https://github.com/samchon
  * @param path Path(s) of the WebSocket request
  * @returns Method decorator
+ * @evidence contracts/common.md#principled-implementation The decorator records the route paths as metadata on the method, with an empty list for no path, and the adapter reads that metadata to build the route table.
+ * @evidence contracts/common.md#clear-and-simple-design One decorator function that writes one metadata object.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts It uses the reflect metadata API and does not touch the server.
+ * @evidence contracts/common.md#meaningful-documentation The comment documents the path forms and the required parameters.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation The route and parameter metadata describe WebSocket handshakes and HTTP URL fields; native files and processes are not represented.
  */
 export function WebSocketRoute(
   path?: undefined | string | string[],
@@ -57,6 +62,16 @@ export function WebSocketRoute(
     return descriptor;
   };
 }
+/**
+ * Parameter decorators of {@link WebSocketRoute}: `Acceptor`, `Driver`,
+ * `Header`, `Param`, and `Query`.
+ *
+ * @evidence contracts/common.md#principled-implementation Each decorator appends category and position metadata. Header registration stores the shared checker whose resolver preserves successful callback data for the decorated argument without replacing the acceptor header; legacy error-only callbacks retain raw input. Param and query keep their own decoder contracts, and every rejected handshake retains its original error handling.
+ * @evidence contracts/common.md#clear-and-simple-design Five decorators sharing one `emplace` helper for the metadata list.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The validators are generated from the types; without the transform the raw values are passed only when the configuration guard is off.
+ * @evidence contracts/common.md#meaningful-documentation Each decorator documents its meaning.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation The route and parameter metadata describe WebSocket handshakes and HTTP URL fields; native files and processes are not represented.
+ */
 export namespace WebSocketRoute {
   /**
    * Acceptor parameter decorator.
@@ -127,7 +142,9 @@ export namespace WebSocketRoute {
    *
    * Also, this `@WebSocketRoute.Header()` decorator is optional, and can be
    * substituted by `@WebSocketRoute.Acceptor()` decorated parameter by
-   * accessting to the {@link WebSocketAcceptor.header} property.
+   * accessing the {@link WebSocketAcceptor.header} property. Clone validators
+   * supply a separate decorated argument; the acceptor keeps its original
+   * header.
    */
   export function Header<T>(
     validator?: IRequestBodyValidator<T>,

package/src/decorators/doNotThrowTransformError.ts

@@ -1,5 +1,19 @@
 import { NoTransformConfigurationError } from "./NoTransformConfigurationError";
 
+/**
+ * Chooses whether a decorator called without the compile-time transform throws.
+ *
+ * The initial configuration throws with instructions to build with `ttsc`.
+ * Calling this setter with `false`, including its omitted-argument default,
+ * silences the error. Passing `true` restores throwing for subsequent decorator
+ * construction. Decorators already constructed keep their selected callbacks.
+ *
+ * @evidence contracts/common.md#principled-implementation The function sets the one flag that `NoTransformConfigurationError` reads, so the choice is made once for the process.
+ * @evidence contracts/common.md#clear-and-simple-design One setter with a boolean parameter.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts It changes an exported flag of this package and nothing foreign.
+ * @evidence contracts/common.md#meaningful-documentation The comment states the default and the effect of the flag.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation This setter changes an in-memory validation configuration flag and performs no filesystem or process operation.
+ */
 export const doNotThrowTransformError = (value: boolean = false) => {
   NoTransformConfigurationError.throws = value;
 };

package/src/decorators/internal/IMcpRouteReflect.ts

@@ -1,3 +1,5 @@
+import { IRequestBodyValidation } from "./IRequestBodyValidation";
+
 /**
  * Reflection metadata stored by the {@link McpRoute} decorator.
  *
@@ -29,12 +31,16 @@ export namespace IMcpRouteReflect {
    *
    * `validate` is the closure returned by `validate_request_body(...)`; it
    * returns `null` on success or an Error carrying validation details.
+   * Factory-owned callbacks additionally resolve successful data. The optional
+   * resolver preserves compatibility with existing error-only metadata
+   * callbacks.
    *
    * @internal
    */
   export interface IArgument {
     category: "params";
     index: number;
-    validate: (input: any) => Error | null;
+    validate: ((input: any) => Error | null) &
+      Pick<IRequestBodyValidation<any>, "resolve">;
   }
 }

package/src/decorators/internal/IRequestBodyValidation.ts

@@ -0,0 +1,65 @@
+/**
+ * Internal request validation callable with an optional successful-value
+ * resolver.
+ *
+ * The callable preserves the legacy error-or-null metadata contract. Factory
+ * validators also expose `resolve` so consumers can retain clone results
+ * without treating a valid Error, null or undefined value as a failure.
+ *
+ * @evidence contracts/common.md#principled-implementation Resolver input is untrusted unknown and only successful data is T. Existing public descriptor callbacks retain their input:T signature; the private adapter casts once at that compatibility boundary and relies on the callback's validation decision, without asserting input validity beforehand. Assert returns and validation.data are retained; is and legacy null success retain accepted input. Errors preserve 400 details and non-guard throws, and explicit tags permit successful Error/null/undefined.
+ * @evidence contracts/common.md#clear-and-simple-design One callable interface and namespace separate compatibility from successful data. The private factory installs both operations on one newly created function; descriptor adapters own their existing error translation, and the shared resolver chooses the supported protocol without request-result caching or double validation.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The private constructor composes an owned function and resolver without modifying foreign callbacks or public descriptors. Unknown descriptor tags reject; legacy error-only callbacks remain supported without an invented replacement value or data sentinel.
+ * @evidence contracts/common.md#meaningful-documentation This type explains optional resolution and tagged values; private factory/resolver native comments explain construction, single-call behavior and legacy fallback. The owning type reviews those internal operations rather than exposing them to obtain standalone documentation hosts.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation The callable and tagged result describe validated JavaScript values, not native file identities or process handles.
+ */
+export interface IRequestBodyValidation<T> {
+  (input: T): Error | null;
+
+  /**
+   * Resolves validation once, retaining its successful value when supported.
+   *
+   * @evidence contracts/common.md#principled-implementation The optional operation returns a discriminated result so successful Error, null or undefined data cannot be confused with validation failure; absence identifies legacy error-only callbacks.
+   * @evidence contracts/common.md#clear-and-simple-design One optional function supplements the existing callable without changing its failure protocol.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The member records a real factory-owned capability rather than requiring it on legacy callbacks or using raw-data sentinels.
+   * @evidence contracts/common.md#meaningful-documentation The comment states single validation and successful-value retention; the owning interface explains compatibility.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation The callable and tagged result describe validated JavaScript values, not native file identities or process handles.
+   */
+  resolve?: (input: unknown) => IRequestBodyValidation.IResult<T>;
+}
+
+export namespace IRequestBodyValidation {
+  /**
+   * Successful data or a validation error, distinguished independently of data.
+   *
+   * @evidence contracts/common.md#principled-implementation The success literal distinguishes a valid Error, null or undefined from a rejected value; failure alone carries the error consumers throw.
+   * @evidence contracts/common.md#clear-and-simple-design A two-variant union gives consumers one exhaustive success check.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The result uses no data sentinel or consumer-specific exception.
+   * @evidence contracts/common.md#meaningful-documentation The description states the distinction that the union preserves.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation The callable and tagged result describe validated JavaScript values, not native file identities or process handles.
+   */
+  export type IResult<T> =
+    | { success: true; data: T }
+    | { success: false; error: Error };
+
+  /**
+   * A factory-owned checker whose resolver is always present.
+   *
+   * @evidence contracts/common.md#principled-implementation Factory callers can resolve successful data directly because construction installs the resolver together with the legacy callable.
+   * @evidence contracts/common.md#clear-and-simple-design This interface strengthens only the optional member of the compatibility interface.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The required member describes the actual factory result rather than asserting a resolver exists on foreign legacy callbacks.
+   * @evidence contracts/common.md#meaningful-documentation The comment identifies which owner guarantees resolver availability.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation The callable and tagged result describe validated JavaScript values, not native file identities or process handles.
+   */
+  export interface IResolved<T> extends IRequestBodyValidation<T> {
+    /**
+     * Resolves validation and retains successful data.
+     *
+     * @evidence contracts/common.md#principled-implementation Factory construction installs this operation with its callable, making successful callback data available without running validation twice.
+     * @evidence contracts/common.md#clear-and-simple-design The required function strengthens only the compatibility interface's optional resolver.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The mandatory resolver applies only to the owned factory result, never to an arbitrary legacy callback.
+     * @evidence contracts/common.md#meaningful-documentation The description identifies the operation's result and the owning interface states its construction guarantee.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation The callable and tagged result describe validated JavaScript values, not native file identities or process handles.
+     */
+    resolve: (input: unknown) => IResult<T>;
+  }
+}