@nestia/core 14.0.0 → 14.0.2

package/src/decorators/EncryptedController.ts

@@ -1,13 +1,13 @@
 import { IEncryptionPassword } from "@nestia/fetcher";
 import { Controller } from "@nestjs/common";
 
-import { ENCRYPTION_METADATA_KEY } from "./internal/EncryptedConstant";
+import { ENCRYPTION_CONTROLLER_METADATA_KEY } from "./internal/EncryptedConstant";
 
 /**
  * Encrypted controller.
  *
  * `EncryptedController` is an extension of the {@link nest.Controller} class
- * decorator function who configures encryption password of the AES-128/256
+ * decorator function who configures encryption password of the AES-128/192/256
  * algorithm. The encryption algorithm and password would be used by
  * {@link EncryptedRoute} and {@link EncryptedBody} to encrypt the request and
  * response body of the HTTP protocol.
@@ -28,13 +28,22 @@ import { ENCRYPTION_METADATA_KEY } from "./internal/EncryptedConstant";
  * @param path Path of the HTTP request
  * @param password Encryption password or its getter function
  * @returns Class decorator
+ * @evidence contracts/common.md#principled-implementation The decorator stores the password as metadata on the class and then applies Nest's `Controller(path)`, so the encrypted decorators can find the password by reading the class.
+ * @evidence contracts/common.md#clear-and-simple-design One decorator that composes a metadata write with the standard decorator.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts It uses Nest's public `Controller` decorator and the reflect metadata API.
+ * @evidence contracts/common.md#meaningful-documentation The comment states the password forms and the encrypted decorators it enables.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Controller paths are HTTP routing metadata and passwords are in-memory values; neither is a native filesystem path.
  */
 export function EncryptedController(
   path: string,
   password: IEncryptionPassword | IEncryptionPassword.Closure,
 ): ClassDecorator {
   return function (target: any) {
-    Reflect.defineMetadata(ENCRYPTION_METADATA_KEY, password, target);
+    Reflect.defineMetadata(
+      ENCRYPTION_CONTROLLER_METADATA_KEY,
+      password,
+      target,
+    );
     Controller(path)(target);
   };
 }

package/src/decorators/EncryptedModule.ts

@@ -9,16 +9,20 @@ import { load_controllers } from "./internal/load_controller";
  * Encrypted module.
  *
  * `EncryptedModule` is an extension of the {@link Module} class decorator
- * function who configures encryption password of the AES-128/256 algorithm. The
- * encryption algorithm and password would be used by {@link EncryptedRoute} and
- * {@link EncryptedBody} to encrypt the request and response bod of the HTTP
+ * function who configures encryption password of the AES-128/192/256 algorithm.
+ * The encryption algorithm and password would be used by {@link EncryptedRoute}
+ * and {@link EncryptedBody} to encrypt the request and response bod of the HTTP
  * protocol.
  *
  * By using this `EncryptedModule` decorator function, all of the
  * {@link Controller controllers} configured in the _metadata_ would be
- * automatically changed to the {@link EncryptedController} with the _password_.
- * If there're some original {@link EncryptedController} decorated classes in the
- * _metadata_, their encryption password would be kept.
+ * automatically changed to the {@link EncryptedController} with the _password_,
+ * and so would the controllers of every module it imports: module classes,
+ * dynamic modules (`{ module, imports, controllers }`), `forwardRef()`s, and
+ * promises of them, however deep and even when cyclic. If there're some
+ * original {@link EncryptedController} decorated classes in the _metadata_,
+ * their encryption password would be kept, as would a subclass's that inherits
+ * one.
  *
  * Therefore, if you're planning to place original {@link EncryptedController}
  * decorated classes in the _metadata_, I hope them to have different encryption
@@ -34,6 +38,11 @@ import { load_controllers } from "./internal/load_controller";
  * @param metadata Module configuration metadata
  * @param password Encryption password or its getter function
  * @returns Class decorator
+ * @evidence contracts/common.md#principled-implementation A visited set breaks import cycles, the controllers of each visited module get the password as metadata, asynchronous modules are awaited through the same promise Nest awaits, and a forward reference is resolved once its class exists.
+ * @evidence contracts/common.md#clear-and-simple-design One decorator whose traversal is a private function; the dynamic-module helper is in the merged namespace.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The traversal uses the public metadata keys of Nest modules; no module name is special-cased.
+ * @evidence contracts/common.md#meaningful-documentation The comment states which module shapes are followed.
+ * @evidence contracts/portability.md#os-neutral-implementation The decorator traverses Nest module metadata in memory; its dynamic helper delegates native paths and file-URL imports to load_controllers instead of composing platform-specific import strings.
  */
 export function EncryptedModule(
   metadata: Parameters<typeof Module>[0],
@@ -45,6 +54,16 @@ export function EncryptedModule(
   };
 }
 
+/**
+ * Helpers of {@link EncryptedModule}, namely `dynamic`, which builds an
+ * encrypted module from controller paths.
+ *
+ * @evidence contracts/common.md#principled-implementation `dynamic` loads the controllers with the shared loader, wraps an object password into a closure, and returns a class decorated by `EncryptedModule`.
+ * @evidence contracts/common.md#clear-and-simple-design One function that reuses the loader and the decorator.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Paths and password are caller input.
+ * @evidence contracts/common.md#meaningful-documentation The comment documents the path forms and the password argument.
+ * @evidence contracts/portability.md#os-neutral-implementation The decorator traverses Nest module metadata in memory; its dynamic helper delegates native paths and file-URL imports to load_controllers instead of composing platform-specific import strings.
+ */
 export namespace EncryptedModule {
   /**
    * Dynamic encrypted module.
@@ -81,18 +100,70 @@ export namespace EncryptedModule {
   }
 }
 
-/** @internal */
-const iterate =
-  (password: IEncryptionPassword.Closure) =>
-  (modulo: any): void => {
-    const imports = Reflect.getMetadata("imports", modulo);
-    if (Array.isArray(imports))
-      for (const imp of imports)
-        if (typeof imp === "function") iterate(password)(imp);
-
-    const controllers = Reflect.getMetadata("controllers", modulo);
-    if (Array.isArray(controllers))
-      for (const c of controllers)
+/**
+ * Gives every controller the module reaches the module's password: those of the
+ * module itself and of each import, whether a module class, a dynamic module
+ * (its `module`, and its own `imports` and `controllers`), a `forwardRef()`, or
+ * a promise of one. Each module is visited once, so a cyclic import graph
+ * terminates.
+ *
+ * @internal
+ */
+const iterate = (password: IEncryptionPassword.Closure) => {
+  const visited: Set<object> = new Set();
+  const controllers = (list: unknown): void => {
+    if (Array.isArray(list))
+      for (const c of list)
         if (typeof c === "function")
           Reflect.defineMetadata(ENCRYPTION_METADATA_KEY, password, c);
   };
+  const imports = (list: unknown): void => {
+    if (Array.isArray(list)) for (const imp of list) visit(imp);
+  };
+  const visit = (input: unknown): void => {
+    if (
+      typeof input !== "function" &&
+      (typeof input !== "object" || input === null)
+    )
+      return;
+    if (visited.has(input)) return;
+    visited.add(input);
+
+    if (typeof input === "function") {
+      imports(Reflect.getMetadata("imports", input));
+      controllers(Reflect.getMetadata("controllers", input));
+    } else if (typeof (input as PromiseLike<unknown>).then === "function")
+      // an asynchronous dynamic module; NestJS awaits the same promise while
+      // scanning, after this callback, registered first, has run
+      (input as PromiseLike<unknown>).then(visit, () => {});
+    else if (typeof (input as IForwardReference).forwardRef === "function") {
+      // the class a forward reference names may not be defined yet while the
+      // decorators run; it is once the synchronous module graph has loaded
+      const resolve = (): unknown => {
+        try {
+          return (input as IForwardReference).forwardRef();
+        } catch {
+          return undefined;
+        }
+      };
+      const target: unknown = resolve();
+      if (target !== undefined) visit(target);
+      else void Promise.resolve().then(() => visit(resolve()));
+    } else {
+      const dynamic = input as {
+        module?: unknown;
+        imports?: unknown;
+        controllers?: unknown;
+      };
+      visit(dynamic.module);
+      imports(dynamic.imports);
+      controllers(dynamic.controllers);
+    }
+  };
+  return visit;
+};
+
+/** @internal */
+interface IForwardReference {
+  forwardRef: () => unknown;
+}

package/src/decorators/EncryptedRoute.ts

@@ -20,7 +20,7 @@ import typia from "typia";
 import { IResponseBodyStringifier } from "../options/IResponseBodyStringifier";
 import { Singleton } from "../utils/Singleton";
 import { TypedRoute } from "./TypedRoute";
-import { ENCRYPTION_METADATA_KEY } from "./internal/EncryptedConstant";
+import { get_encryption_password } from "./internal/get_encryption_password";
 import { get_path_and_stringify } from "./internal/get_path_and_stringify";
 import { headers_to_object } from "./internal/headers_to_object";
 import { route_error } from "./internal/route_error";
@@ -29,22 +29,26 @@ import { route_error } from "./internal/route_error";
  * Encrypted router decorator functions.
  *
  * `EncryptedRoute` is a module containing router decorator functions which
- * encrypts response body data through AES-128/256 encryption. Furthermore, they
- * can boost up JSON string conversion speed about 50x times faster than
- * `class-transformer`, even type safe through
- * [typia](https://github.com/samchon/typia).
+ * encrypts response body data through AES-128/192/256 encryption after
+ * serializing it with a [typia](https://github.com/samchon/typia) function
+ * 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
- * `EncryptedRoute` 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 chooses the validation policy
+ * before encryption; `validate.log` logs failures and serializes the original
+ * value. Interceptors running afterwards receive ciphertext.
  *
- * - AES-128/256
+ * - AES-128/192/256
  * - CBC mode
  * - PKCS #5 Padding
  * - Base64 Encoding
  *
  * @author Jeongho Nam - https://github.com/samchon
+ * @evidence contracts/common.md#principled-implementation Each route method decorates Nest's router decorator with an interceptor that serializes the value as the transform chose, encrypts it with the password of the controller or module, and answers `text/plain` on success only, so an error keeps its own JSON type.
+ * @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 password lookup and the serializer come from shared modules; the loop after the namespace copies the marker properties of typia's stringify functions onto the five decorators as the transform expects, which mutates only these exported functions.
+ * @evidence contracts/common.md#meaningful-documentation The comment documents the decorator family and its password requirement.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Route paths and serialized ciphertext are HTTP protocol values; response interception does not access native files or launch a process.
  */
 export namespace EncryptedRoute {
   /**
@@ -56,7 +60,7 @@ export namespace EncryptedRoute {
   export const Get = Generator("Get");
 
   /**
-   * Encrypted router decorator function for the GET method.
+   * Encrypted router decorator function for the POST method.
    *
    * @param paths Path(s) of the HTTP request
    * @returns Method decorator
@@ -93,7 +97,7 @@ export namespace EncryptedRoute {
    * 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,
@@ -101,6 +105,11 @@ export namespace EncryptedRoute {
    *
    * @default console.log
    * @param func Logger function
+   * @evidence contracts/common.md#principled-implementation It stores the logger in `TypedRoute`, which owns the single logger both route families use.
+   * @evidence contracts/common.md#clear-and-simple-design A one-line delegation, so the logger has one owner.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It changes only the logger variable.
+   * @evidence contracts/common.md#meaningful-documentation The comment states which validate mode uses the logger.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation Route paths and serialized ciphertext are HTTP protocol values; response interception does not access native files or launch a process.
    */
   export function setValidateErrorLogger(
     func: (log: IValidateErrorLog) => void,
@@ -168,10 +177,7 @@ class EncryptedRouteInterceptor implements NestInterceptor {
         const param:
           | IEncryptionPassword
           | IEncryptionPassword.Closure
-          | undefined = Reflect.getMetadata(
-          ENCRYPTION_METADATA_KEY,
-          context.getClass(),
-        );
+          | undefined = get_encryption_password(context.getClass());
         if (!param)
           throw new Error(
             `Error on EncryptedRoute.${this.method}(): no password found.`,
@@ -196,6 +202,11 @@ class EncryptedRouteInterceptor implements NestInterceptor {
             : param;
 
         if (body === undefined) return body;
+        // the ciphertext is text/plain, as the document declares; set on the
+        // success path alone, so an error keeps its JSON body's type (Express
+        // would otherwise send a string as text/html)
+        const response: express.Response = http.getResponse();
+        response.header("Content-Type", "text/plain");
         return AesPkcs5.encrypt(body, password.key, password.iv);
       }),
       catchError((err) => route_error(http.getRequest(), err)),

package/src/decorators/HumanRoute.ts

@@ -13,6 +13,11 @@ import { SwaggerCustomizer } from "./SwaggerCustomizer";
  *
  * @author Jeongho Nam - https://github.com/samchon
  * @returns Method decorator
+ * @evidence contracts/common.md#principled-implementation The decorator marks the operation with the `x-samchon-human` extension through `SwaggerCustomizer`, so the generated document carries the mark without another metadata path.
+ * @evidence contracts/common.md#clear-and-simple-design One call to the customizer.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The extension name is the documented contract of the generated document.
+ * @evidence contracts/common.md#meaningful-documentation The comment states that a marked API is left out of the LLM function calling schema.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation The OpenAPI extension is an in-memory document property and has no native path or process representation.
  */
 export function HumanRoute(): MethodDecorator {
   return SwaggerCustomizer((props) => {

package/src/decorators/McpRoute.ts

@@ -25,27 +25,28 @@ import { validate_request_body } from "./internal/validate_request_body";
  * the {@link INestApplication} instance at bootstrap. The decorator alone only
  * stores reflection metadata.
  *
- * @author wildduck - https://github.com/wildduck2
- * @example
- *   ```typescript
- *   import core from "@nestia/core";
+ * Example:
+ *
+ * ```typescript
+ * import core from "@nestia/core";
  *
- *   @Controller()
- *   export class WeatherController {
- *     /**
- *      * Return current weather for a city.
- *      *
- *      * @title Get weather
- *      *\/
- *     @core.McpRoute("get_weather")
- *     public async get(
- *       @core.McpRoute.Params() params: { city: string },
- *     ): Promise<{ temp: number }> {
- *       return { temp: 22 };
- *     }
+ * @Controller()
+ * export class WeatherController {
+ *   /**
+ *    * Return current weather for a city.
+ *    *
+ *    * @title Get weather
+ *    *\/
+ *   @core.McpRoute("get_weather")
+ *   public async get(
+ *     @core.McpRoute.Params() params: { city: string },
+ *   ): Promise<{ temp: number }> {
+ *     return { temp: 22 };
  *   }
- *   ```;
+ * }
+ * ```
  *
+ * @author wildduck - https://github.com/wildduck2
  * @param name Unique tool identifier exposed to MCP clients via `tools/list`.
  * @returns Method decorator.
  */
@@ -78,6 +79,16 @@ export function McpRoute(input: string | McpRoute.IConfig): MethodDecorator {
   };
 }
 
+/**
+ * Types and parameter decorator of {@link McpRoute}: the tool configuration and
+ * `McpRoute.Params`.
+ *
+ * @evidence contracts/common.md#principled-implementation Tool metadata retains its definition and default empty-object schema. Params records its argument position and shared checker; successful assert/validate data becomes the tool argument, while errors retain InvalidParams mapping and legacy error-only callbacks retain raw input. The adaptor reads the same metadata field names when registering tools.
+ * @evidence contracts/common.md#clear-and-simple-design Two decorators and one config type in one namespace, sharing one `emplace` helper for parameter metadata.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts It uses the reflect metadata API and no NestJS internals; the input schema is filled by the generator, not hardcoded here.
+ * @evidence contracts/common.md#meaningful-documentation The comment documents the two call forms, the configuration fields, and the parameter decorator.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Tool schemas and parameter metadata are protocol data held on controller methods, without native filesystem access.
+ */
 export namespace McpRoute {
   /**
    * Configuration object emitted by the nestia transformer at compile time.
@@ -104,7 +115,8 @@ export namespace McpRoute {
    * `tools/call` request against the TypeScript type `T` using typia. A failed
    * validation surfaces to the client as a JSON-RPC `-32602` (`InvalidParams`)
    * error with structured diagnostics, giving the LLM precise feedback to
-   * self-correct.
+   * self-correct. Successful assert and validate data becomes the tool
+   * argument, so clone validators can supply a copy of the incoming arguments.
    *
    * MCP tools accept exactly one arguments object; applying this decorator more
    * than once on a single method is a compile-time error. The decorated type

package/src/decorators/PlainBody.ts

@@ -15,7 +15,8 @@ import { validate_request_body } from "./internal/validate_request_body";
  * Plain body decorator.
  *
  * `PlainBody` is a decorator function getting full body text from the HTTP
- * request.
+ * request. The transformed assertion's successful string is the decorated
+ * argument.
  *
  * If you adjust the regular {@link Body} decorator function to the body
  * parameter, you can't get the full body text because the {@link Body} tries to
@@ -32,10 +33,18 @@ import { validate_request_body } from "./internal/validate_request_body";
  *
  * @author Jeongho Nam - https://github.com/samchon
  * @returns Parameter decorator
+ * @evidence contracts/common.md#principled-implementation The decorator reads text only for text/plain requests; an installed assertion resolves the argument value through the shared body checker, while no assertion retains raw text. Absent input is accepted when its assertion accepts undefined and otherwise continues through the media-type error path.
+ * @evidence contracts/common.md#clear-and-simple-design One parameter decorator shares body absence, media recognition, text reading and successful-value resolution with the other request decorators.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Text comes from the request parser or shared raw-body reader, not a fabricated value; no runtime controller or body identity is special-cased.
+ * @evidence contracts/common.md#meaningful-documentation The comment distinguishes full body text from JSON parsing and states that the transformed assertion supplies the argument.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation HTTP text bodies and decoded string values carry no native filesystem or subprocess boundary.
  */
 export function PlainBody(): ParameterDecorator;
 
-/** @internal */
+/**
+ * Registers the transformed text assertion and binds its successful value. The
+ * public overload accepts no runtime assertion; the transform supplies it.
+ */
 export function PlainBody(
   assert?: (input: unknown) => string,
 ): ParameterDecorator {
@@ -52,17 +61,18 @@ export function PlainBody(
     const request: express.Request | FastifyRequest = context
       .switchToHttp()
       .getRequest();
-    if (
-      is_request_body_undefined(request) &&
-      (checker ?? (() => null))(undefined as any) === null
-    )
-      return undefined;
-    else if (!is_media_type(request.headers["content-type"], "text/plain"))
+    if (is_request_body_undefined(request)) {
+      if (checker === null) return undefined;
+      const result = checker.resolve(undefined);
+      if (result.success) return result.data;
+    }
+    if (!is_media_type(request.headers["content-type"], "text/plain"))
       throw new BadRequestException(`Request body type is not "text/plain".`);
     const value: string = await get_text_body(request);
     if (checker) {
-      const error: Error | null = checker(value);
-      if (error !== null) throw error;
+      const result = checker.resolve(value);
+      if (!result.success) throw result.error;
+      return result.data;
     }
     return value;
   })();

package/src/decorators/SwaggerCustomizer.ts

@@ -13,6 +13,11 @@ import { OpenApi } from "@typia/interface";
  * @author Jeongho Nam - https://github.com/samchon
  * @param closure Callback function which can customize the swagger data
  * @returns Method decorator
+ * @evidence contracts/common.md#principled-implementation Each use appends the closure to an array of metadata owned by the method, created on first use, so several customizers on one method run in order.
+ * @evidence contracts/common.md#clear-and-simple-design One decorator function with one metadata list per method.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts It uses the reflect metadata API; the closure is the caller's.
+ * @evidence contracts/common.md#meaningful-documentation The comment documents that the closure receives the document, the operation, and lookup helpers.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation The callback and endpoint accessors edit an OpenAPI document; their path fields are HTTP routes rather than native file identities.
  */
 export function SwaggerCustomizer(
   closure: (props: SwaggerCustomizer.IProps) => unknown,
@@ -44,6 +49,16 @@ export function SwaggerCustomizer(
     return descriptor;
   };
 }
+/**
+ * Types of {@link SwaggerCustomizer}: the properties the closure receives and
+ * the endpoint accessors.
+ *
+ * @evidence contracts/common.md#principled-implementation The types describe the document, the current operation, and lookups by function or by path and method, which is what a customization needs to edit the generated document.
+ * @evidence contracts/common.md#clear-and-simple-design Three types with no runtime members.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts It contains types only.
+ * @evidence contracts/common.md#meaningful-documentation Each type and member documents its meaning.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation The callback and endpoint accessors edit an OpenAPI document; their path fields are HTTP routes rather than native file identities.
+ */
 export namespace SwaggerCustomizer {
   /**
    * Properties for the `SwaggerCustomizer` decorator.

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.assert()`
+ * @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> {