@nestia/core 14.0.0 → 14.0.2

package/src/decorators/TypedFormData.ts

@@ -1,10 +1,13 @@
 import {
   BadRequestException,
   ExecutionContext,
+  HttpException,
+  PayloadTooLargeException,
   createParamDecorator,
 } from "@nestjs/common";
 import type { HttpArgumentsHost } from "@nestjs/common/interfaces";
 import type express from "express";
+import fs from "fs";
 import type ExpressMulter from "multer";
 
 import type { IRequestFormDataProps } from "../options/IRequestFormDataProps";
@@ -35,10 +38,13 @@ import { validate_request_form_data } from "./internal/validate_request_form_dat
  *    types are allowed
  * 4. By the way, union type never be not allowed
  *
- * By the way, if you're using `fastify`, you have to setup `fastify-multer` and
- * configure like below when composing the NestJS application. If you don't do
- * that, `@TypedFormData.Body()` will not work properly, and throw 500 internal
- * server error when `Blob` or `File` type being utilized.
+ * By the way, if you're using `fastify`, pass a `fastify-multer` instance as
+ * the factory, and register a `multipart/form-data` content type parser that
+ * leaves the request stream to it when composing the NestJS application.
+ * Without the parser, Fastify rejects every multipart request with 415.
+ * `fastify-multer`'s own `contentParser` plugin declares the content type
+ * `multipart` without a subtype, which Fastify 5 (NestJS 11) refuses to
+ * register.
  *
  * ```typescript
  * import { NestFactory } from "@nestjs/core";
@@ -46,19 +52,33 @@ import { validate_request_form_data } from "./internal/validate_request_form_dat
  *   FastifyAdapter,
  *   NestFastifyApplication,
  * } from "@nestjs/platform-fastify";
- * import fastifyMulter from "fastify-multer";
  *
  * export async function main() {
  *   const app = await NestFactory.create<NestFastifyApplication>(
  *     AppModule,
  *     new FastifyAdapter(),
  *   );
- *   app.register(fastifyMulter.contentParser);
+ *   app
+ *     .getHttpAdapter()
+ *     .getInstance()
+ *     .addContentTypeParser("multipart/form-data", (_req, _payload, done) =>
+ *       done(null),
+ *     );
  *   await app.listen(3000);
  * }
+ *
+ * // in the controller, with `import FastifyMulter from "fastify-multer"`
+ * public async upload(
+ *   @TypedFormData.Body(() => FastifyMulter()) body: IMultipart,
+ * ): Promise<void> {}
  * ```
  *
  * @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 {
@@ -69,9 +89,11 @@ export namespace TypedFormData {
    *
    * Much easier and type safer than `@nest.UploadFile()` decorator.
    *
-   * @param factory Factory function ncreating the `multer` or `fastify-multer`
+   * @param factory Factory function creating the `multer` or `fastify-multer`
    *   instance. In the factory function, you also can specify the multer
-   *   composition options like `storage` engine.
+   *   composition options like `storage` engine: memory and disk storage
+   *   deliver the uploaded bytes, and an engine keeping neither the buffer nor
+   *   a file path is rejected.
    */
   export function Body<Multer extends IMulterBase>(
     factory: () => Multer | Promise<Multer>,
@@ -88,7 +110,7 @@ export namespace TypedFormData {
       );
     const checker = validate_request_form_data(props);
     const uploader = new Singleton(async () =>
-      decode((await factory()) as ExpressMulter.Multer, props!),
+      decode((await factory()) as ExpressMulter.Multer, props),
     );
     return createParamDecorator(async function TypedFormDataBody(
       _unknown: any,
@@ -117,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;
   }
 }
@@ -130,18 +205,22 @@ export namespace TypedFormData {
 /** @internal */
 const decode = <T>(
   multer: ExpressMulter.Multer,
-  props: IRequestFormDataProps<T>,
+  props: IRequestFormDataProps<T> | undefined,
 ) => {
-  const upload = multer.fields(
-    props!.files.map((file) => ({
-      name: file.name,
-      ...(file.limit === 1 ? { maxCount: 1 } : {}),
-    })),
-  );
+  // without the transform nothing names the file fields, so accept every file
+  const upload =
+    props === undefined
+      ? multer.any()
+      : multer.fields(
+          props.files.map((file) => ({
+            name: file.name,
+            ...(file.limit === 1 ? { maxCount: 1 } : {}),
+          })),
+        );
   const interceptor = (request: express.Request, response: express.Response) =>
     new Promise<void>((resolve, reject) =>
       upload(request, response, (error) => {
-        if (error) reject(error);
+        if (error) reject(transformMulterError(error));
         else resolve();
       }),
     );
@@ -151,35 +230,118 @@ const decode = <T>(
   }): Promise<FormData> => {
     await interceptor(socket.request, socket.response);
 
-    const data: FormData = new FormData();
-    for (const [key, value] of Object.entries(socket.request.body))
-      if (Array.isArray(value))
-        for (const elem of value) data.append(key, String(elem));
-      else data.append(key, String(value));
-    if (socket.request.files) parseFiles(data)(socket.request.files);
-    return data;
+    const files: Array<[string, Express.Multer.File]> = entries(
+      socket.request.files,
+    );
+    try {
+      const data: FormData = new FormData();
+      for (const [key, value] of Object.entries(socket.request.body))
+        if (Array.isArray(value))
+          for (const elem of value) data.append(key, String(elem));
+        else data.append(key, String(value));
+      for (const [key, file] of files) data.append(key, await toFile(file));
+      return data;
+    } finally {
+      // a disk storage engine leaves each file behind, and the handler only
+      // receives its contents as a File, never the path to remove it by
+      await Promise.all(
+        files.map(([, file]) =>
+          typeof file.path === "string"
+            ? fs.promises.rm(file.path, { force: true })
+            : undefined,
+        ),
+      );
+    }
   };
 };
 
+/**
+ * The client error NestJS's own `FileInterceptor` answers for a multipart
+ * request the multer configuration rejects: 413 for a file over
+ * `limits.fileSize`, 400 for the other limits, an unexpected field, and a
+ * malformed body. Anything else, an `HttpException` a `fileFilter` threw
+ * included, is left as it is.
+ *
+ * @internal
+ */
+const transformMulterError = (error: unknown): unknown => {
+  if (!(error instanceof Error) || error instanceof HttpException) return error;
+  const code: unknown = (error as { code?: unknown }).code;
+  const field: unknown = (error as { field?: unknown }).field;
+  if (code === "LIMIT_FILE_SIZE")
+    return new PayloadTooLargeException(error.message);
+  else if (typeof code === "string" && MULTER_BAD_REQUESTS.has(code))
+    return new BadRequestException(
+      typeof field === "string" ? `${error.message} - ${field}` : error.message,
+    );
+  else if (error.message === "Multipart: Boundary not found")
+    return new BadRequestException(error.message);
+  else if (
+    BUSBOY_BAD_REQUESTS.has(error.message) ||
+    error.message.endsWith(
+      " terminated early due to unexpected end of multipart data",
+    )
+  )
+    return new BadRequestException(`Multipart: ${error.message}`);
+  return error;
+};
+
 /** @internal */
-const parseFiles =
-  (data: FormData) =>
-  (files: Express.Multer.File[] | Record<string, Express.Multer.File[]>) => {
-    if (Array.isArray(files))
-      for (const file of files)
-        data.append(
-          file.fieldname,
-          new File([file.buffer as any], file.originalname, {
-            type: file.mimetype,
-          }),
+const MULTER_BAD_REQUESTS: Set<string> = new Set([
+  "LIMIT_PART_COUNT",
+  "LIMIT_FILE_COUNT",
+  "LIMIT_FIELD_KEY",
+  "LIMIT_FIELD_VALUE",
+  "LIMIT_FIELD_COUNT",
+  "LIMIT_UNEXPECTED_FILE",
+  "MISSING_FIELD_NAME",
+]);
+
+/**
+ * A malformed body, as `busboy` (under `multer`) and `@fastify/busboy` (under
+ * `fastify-multer`) word it.
+ *
+ * @internal
+ */
+const BUSBOY_BAD_REQUESTS: Set<string> = new Set([
+  "Malformed part header",
+  "Unexpected end of form",
+  "Unexpected end of file",
+  "Unexpected end of multipart data",
+]);
+
+/** @internal */
+const entries = (
+  files:
+    | Express.Multer.File[]
+    | Record<string, Express.Multer.File[]>
+    | undefined,
+): Array<[string, Express.Multer.File]> =>
+  files === undefined
+    ? []
+    : Array.isArray(files)
+      ? files.map((file) => [file.fieldname, file])
+      : Object.entries(files).flatMap(([key, value]) =>
+          value.map((file): [string, Express.Multer.File] => [key, file]),
         );
-    else
-      for (const [key, value] of Object.entries(files))
-        for (const file of value)
-          data.append(
-            key,
-            new File([file.buffer as any], file.originalname, {
-              type: file.mimetype,
-            }),
-          );
-  };
+
+/**
+ * The uploaded file as a `File`: memory storage keeps its bytes in `buffer`,
+ * disk storage in the file at `path`. An engine keeping neither cannot deliver
+ * it, which must not pass as an empty or placeholder file.
+ *
+ * @internal
+ */
+const toFile = async (file: Express.Multer.File): Promise<File> => {
+  const bytes: Buffer | undefined =
+    file.buffer !== undefined
+      ? file.buffer
+      : typeof file.path === "string"
+        ? await fs.promises.readFile(file.path)
+        : undefined;
+  if (bytes === undefined)
+    throw new Error(
+      `Error on TypedFormData.Body(): the multer storage engine kept neither the buffer nor the path of the uploaded file ${JSON.stringify(file.fieldname)}, so it cannot be read as a File. Use memory or disk storage.`,
+    );
+  return new File([bytes as any], file.originalname, { type: file.mimetype });
+};

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

@@ -22,15 +22,24 @@ import { NoTransformConfigurationError } from "./NoTransformConfigurationError";
  *
  * \@TypedRoute.Get("shopping/sales/:id/:no/:paused")
  * public async pause(
- *   \@TypedParam("id", "uuid"), id: string & tags.Format<"uuid">,
- *   \@TypedParam("no") id: number & tags.Type<"uint32">
- *   \@TypedParam("paused") paused: boolean | null
+ *   \@TypedParam("id") id: string & tags.Format<"uuid">,
+ *   \@TypedParam("no") no: number & tags.Type<"uint32">,
+ *   \@TypedParam("paused") paused: boolean | null,
  * ): Promise<void>;
  * ```
  *
  * @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

@@ -15,11 +15,12 @@ import {
 import { HttpArgumentsHost } from "@nestjs/common/interfaces";
 import type express from "express";
 import type { FastifyRequest } from "fastify";
-import { catchError, map } from "rxjs";
+import { catchError, map } from "rxjs/operators";
 import typia from "typia";
 
 import { IRequestQueryValidator } from "../options/IRequestQueryValidator";
 import { IResponseBodyQuerifier } from "../options/IResponseBodyQuerifier";
+import { TypedRoute } from "./TypedRoute";
 import { get_path_and_querify } from "./internal/get_path_and_querify";
 import { is_media_type } from "./internal/is_media_type";
 import { route_error } from "./internal/route_error";
@@ -44,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>,
@@ -63,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.
@@ -117,7 +134,7 @@ export namespace TypedQuery {
   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
@@ -150,9 +167,9 @@ export namespace TypedQuery {
     ): MethodDecorator;
 
     function route(...args: any[]): MethodDecorator {
-      const [path, stringify] = get_path_and_querify(`TypedQuery.${method}`)(
-        ...args,
-      );
+      const [path, stringify] = get_path_and_querify(() => TypedRoute.__logger)(
+        `TypedQuery.${method}`,
+      )(...args);
       return applyDecorators(
         ROUTERS[method](path),
         UseInterceptors(new TypedQueryRouteInterceptor(stringify)),
@@ -186,6 +203,10 @@ class FakeURLSearchParams {
     return this.target[key] !== undefined;
   }
 
+  public keys(): string[] {
+    return Object.keys(this.target).filter((key) => this.has(key));
+  }
+
   public get(key: string): string | null {
     const value = this.target[key];
     return value === undefined
@@ -204,16 +225,23 @@ class FakeURLSearchParams {
 /** @internal */
 class TypedQueryRouteInterceptor implements NestInterceptor {
   public constructor(
-    private readonly toSearchParams: (input: any) => URLSearchParams,
+    private readonly toSearchParams: (
+      input: any,
+      method: string,
+      path: string,
+    ) => URLSearchParams,
   ) {}
 
   public intercept(context: ExecutionContext, next: CallHandler) {
     const http: HttpArgumentsHost = context.switchToHttp();
+    const request: express.Request = http.getRequest();
     const response: express.Response = http.getResponse();
     response.header("Content-Type", "application/x-www-form-urlencoded");
 
     return next.handle().pipe(
-      map((value) => this.toSearchParams(value).toString()),
+      map((value) =>
+        this.toSearchParams(value, request.method, request.url).toString(),
+      ),
       catchError((err) => route_error(http.getRequest(), err)),
     );
   }

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/EncryptedConstant.ts

@@ -1,2 +1,15 @@
-/** @internal */
+/**
+ * The password an {@link EncryptedModule} gives each controller it reaches.
+ *
+ * @internal
+ */
 export const ENCRYPTION_METADATA_KEY = "nestia:core:encryption:password";
+
+/**
+ * The password an {@link EncryptedController} declares for its own class, kept
+ * apart from the module's so that the module never replaces it.
+ *
+ * @internal
+ */
+export const ENCRYPTION_CONTROLLER_METADATA_KEY =
+  "nestia:core:encryption:controller-password";