@nestia/core 14.0.1 → 14.0.2

package/src/decorators/internal/IWebSocketRouteReflect.ts

@@ -1,18 +1,112 @@
+import { IRequestBodyValidation } from "./IRequestBodyValidation";
+
+/**
+ * The metadata `@WebSocketRoute()` writes on a method: its route paths.
+ *
+ * @evidence contracts/common.md#principled-implementation The record holds the paths, which the adapter turns into the route table; the parameter records are a separate metadata list.
+ * @evidence contracts/common.md#clear-and-simple-design A one-member record and a namespace of the parameter record types.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+ * @evidence contracts/common.md#meaningful-documentation The comment states which metadata the type describes.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Handshake paths, parameter positions and callback signatures describe protocol metadata without native filesystem identities.
+ */
 export interface IWebSocketRouteReflect {
   paths: string[];
 }
 export namespace IWebSocketRouteReflect {
+  /**
+   * A parameter record: one of acceptor, driver, header, param, or query.
+   *
+   * @evidence contracts/common.md#principled-implementation The union is discriminated by the `category` literal, so the adapter can build the argument list with one comparison per parameter.
+   * @evidence contracts/common.md#clear-and-simple-design A union of five records.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+   * @evidence contracts/common.md#meaningful-documentation The comment lists the categories.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation Handshake paths, parameter positions and callback signatures describe protocol metadata without native filesystem identities.
+   */
   export type IArgument = IAcceptor | IDriver | IHeader | IParam | IQuery;
+  /**
+   * The record of an acceptor parameter, which receives the WebSocket acceptor.
+   *
+   * @evidence contracts/common.md#principled-implementation The record has only the category and the position, because the adapter supplies the acceptor itself.
+   * @evidence contracts/common.md#clear-and-simple-design It extends the shared base and adds nothing.
+   * @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 which argument it stands for.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation Handshake paths, parameter positions and callback signatures describe protocol metadata without native filesystem identities.
+   */
   export interface IAcceptor extends IBase<"acceptor"> {}
+  /**
+   * The record of a driver parameter, which receives the remote driver of the
+   * connection.
+   *
+   * @evidence contracts/common.md#principled-implementation The record has only the category and the position, because the adapter supplies the driver from the acceptor.
+   * @evidence contracts/common.md#clear-and-simple-design It extends the shared base and adds nothing.
+   * @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 which argument it stands for.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation Handshake paths, parameter positions and callback signatures describe protocol metadata without native filesystem identities.
+   */
   export interface IDriver extends IBase<"driver"> {}
+  /**
+   * The record of a header parameter: the position and the validator of the
+   * handshake header.
+   *
+   * @evidence contracts/common.md#principled-implementation The callable retains its error-or-null signature. An optional resolver carries successful callback data to the route argument; legacy callbacks without it preserve the raw header and any validation error rejects the handshake.
+   * @evidence contracts/common.md#clear-and-simple-design It extends the shared base with one function member.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+   * @evidence contracts/common.md#meaningful-documentation The comment states which argument it stands for and what the validator returns.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation Handshake paths, parameter positions and callback signatures describe protocol metadata without native filesystem identities.
+   */
   export interface IHeader extends IBase<"header"> {
-    validate: (input?: any) => Error | null;
+    /**
+     * Validates the handshake header and returns an error, or `null` when it is
+     * valid. Factory-owned callbacks also resolve successful data for the
+     * decorated argument without replacing the acceptor's raw header.
+     */
+    validate: ((input?: any) => Error | null) &
+      Pick<IRequestBodyValidation<any>, "resolve">;
   }
+  /**
+   * The record of a path parameter: its position, the field name, and the
+   * conversion function.
+   *
+   * @evidence contracts/common.md#principled-implementation The field names the placeholder of the path, and the function converts the matched text to the declared type.
+   * @evidence contracts/common.md#clear-and-simple-design It extends the shared base with two members.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+   * @evidence contracts/common.md#meaningful-documentation The comment states which argument it stands for.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation Handshake paths, parameter positions and callback signatures describe protocol metadata without native filesystem identities.
+   */
   export interface IParam extends IBase<"param"> {
     field: string;
+    /**
+     * Converts the matched path text to the declared type, or throws.
+     *
+     * @evidence contracts/common.md#principled-implementation The function is the assertion the transform generated for the declared type, and a throw rejects the handshake.
+     * @evidence contracts/common.md#clear-and-simple-design One function member.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+     * @evidence contracts/common.md#meaningful-documentation The comment states the conversion and the failure.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation Handshake paths, parameter positions and callback signatures describe protocol metadata without native filesystem identities.
+     */
     assert: (value: string) => any;
   }
+  /**
+   * The record of a query parameter: the position and the validator of the
+   * query string.
+   *
+   * @evidence contracts/common.md#principled-implementation The validator receives the `URLSearchParams` after the first question mark of the path and returns the typed object or an error.
+   * @evidence contracts/common.md#clear-and-simple-design It extends the shared base with one function member.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+   * @evidence contracts/common.md#meaningful-documentation The comment states which argument it stands for.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation Handshake paths, parameter positions and callback signatures describe protocol metadata without native filesystem identities.
+   */
   export interface IQuery extends IBase<"query"> {
+    /**
+     * Validates the query of the handshake and returns the typed object, or an
+     * error.
+     *
+     * @evidence contracts/common.md#principled-implementation The function is the query decoder generated for the declared type, and an `Error` result rejects the handshake.
+     * @evidence contracts/common.md#clear-and-simple-design One function member.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+     * @evidence contracts/common.md#meaningful-documentation The comment states the result.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation Handshake paths, parameter positions and callback signatures describe protocol metadata without native filesystem identities.
+     */
     validate: (input: URLSearchParams) => any | Error;
   }
 

package/src/decorators/internal/get_path_and_querify.ts

@@ -4,6 +4,7 @@ import typia, { IValidation, TypeGuardError } from "typia";
 import { IResponseBodyQuerifier } from "../../options/IResponseBodyQuerifier";
 import { NoTransformConfigurationError } from "../NoTransformConfigurationError";
 import type { TypedRoute } from "../TypedRoute";
+import { split_route_arguments } from "./split_route_arguments";
 
 /** @internal */
 export const get_path_and_querify =
@@ -15,15 +16,8 @@ export const get_path_and_querify =
     string | string[] | undefined,
     (input: any, method: string, path: string) => URLSearchParams,
   ] => {
-    const path: string | string[] | null | undefined =
-      args[0] === undefined ||
-      typeof args[0] === "string" ||
-      Array.isArray(args[0])
-        ? args[0]
-        : null;
-    const functor: IResponseBodyQuerifier<any> | undefined =
-      path === null ? args[0] : args[1];
-    return [path ?? undefined, take(logger)(method)(functor)];
+    const [path, functor] = split_route_arguments<any>(args);
+    return [path, take(logger)(method)(functor)];
   };
 
 /** @internal */

package/src/decorators/internal/get_path_and_stringify.ts

@@ -4,6 +4,7 @@ import typia, { IValidation, TypeGuardError } from "typia";
 import { IResponseBodyStringifier } from "../../options/IResponseBodyStringifier";
 import { NoTransformConfigurationError } from "../NoTransformConfigurationError";
 import { TypedRoute } from "../TypedRoute";
+import { split_route_arguments } from "./split_route_arguments";
 
 /** @internal */
 export const get_path_and_stringify =
@@ -15,15 +16,8 @@ export const get_path_and_stringify =
     string | string[] | undefined,
     (input: any, _method: string, _path: string) => string,
   ] => {
-    const path: string | string[] | null | undefined =
-      args[0] === undefined ||
-      typeof args[0] === "string" ||
-      Array.isArray(args[0])
-        ? args[0]
-        : null;
-    const functor: IResponseBodyStringifier<any> | undefined =
-      path === null ? args[0] : args[1];
-    return [path ?? undefined, take(logger)(method)(functor)];
+    const [path, functor] = split_route_arguments<any>(args);
+    return [path, take(logger)(method)(functor)];
   };
 
 /** @internal */

package/src/decorators/internal/load_controller.ts

@@ -3,6 +3,20 @@ import { pathToFileURL } from "url";
 import { Creator } from "../../typings/Creator";
 import { SourceFinder } from "../../utils/SourceFinder";
 
+/**
+ * Finds and imports the controllers under the given paths.
+ *
+ * A path, a list, or include and exclude lists are matched with globs, imported
+ * by file URL, and every export that carries Nest's `path` metadata is a
+ * controller. When no compiled `.js` controller is found and the process runs
+ * from source under `ttsx`, the TypeScript files are used instead.
+ *
+ * @evidence contracts/common.md#principled-implementation Files are selected by a filter chosen from the runtime (JavaScript modules, or TypeScript sources without declaration files), each is imported by `file:` URL through a native dynamic import that survives CommonJS downleveling, and a controller is recognized by Nest's own `path` metadata, so no naming convention is assumed.
+ * @evidence contracts/common.md#clear-and-simple-design One function with the fallback for the source-run case inside it and the filters and the mount loop as private helpers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Discovery follows the metadata Nest itself writes; the `ttsx` fallback is decided by the runtime's own environment variable, not by a project name.
+ * @evidence contracts/common.md#meaningful-documentation The comment states the path forms, the recognition rule, and the source-run fallback.
+ * @evidence contracts/portability.md#os-neutral-implementation SourceFinder returns native absolute file paths and pathToFileURL converts them to escaped file URLs before dynamic import, including drive letters, spaces and URL punctuation. Extension matching selects source formats rather than defining filesystem identity.
+ */
 export const load_controllers = async (
   path: string | string[] | { include: string[]; exclude?: string[] },
   isTsNode?: boolean,

package/src/decorators/internal/split_route_arguments.ts

@@ -0,0 +1,20 @@
+/**
+ * Splits the arguments of a route decorator into its path and its functor.
+ *
+ * A route decorator is called as `Route()`, `Route(path)`, `Route(functor)`, or
+ * `Route(path, functor)`. The first argument is the path when it is absent, a
+ * string, or an array of strings, and the functor otherwise.
+ *
+ * @internal
+ */
+export const split_route_arguments = <Functor>(
+  args: any[],
+): [string | string[] | undefined, Functor | null | undefined] => {
+  const path: string | string[] | undefined | null =
+    args[0] === undefined ||
+    typeof args[0] === "string" ||
+    Array.isArray(args[0])
+      ? args[0]
+      : null;
+  return [path ?? undefined, path === null ? args[0] : args[1]];
+};

package/src/decorators/internal/validate_request_body.ts

@@ -3,62 +3,115 @@ import typia, { IValidation, TypeGuardError } from "typia";
 
 import { IRequestBodyValidator } from "../../options/IRequestBodyValidator";
 import { NoTransformConfigurationError } from "../NoTransformConfigurationError";
+import { IRequestBodyValidation } from "./IRequestBodyValidation";
 
-/** @internal */
+/**
+ * Builds the shared body checker while preserving successful callback values.
+ *
+ * The legacy callable returns an error or null; its resolver returns the same
+ * validation decision and the callback's successful data without validating
+ * twice. Private assert/is/validate adapters preserve each descriptor's error
+ * details. Resolver input is untrusted. The descriptor's existing input:T
+ * signature is retained for compatibility; adapters cast at invocation and rely
+ * on its validation result before exposing successful T data.
+ *
+ * @internal
+ */
 export const validate_request_body =
   (method: string) =>
-  <T>(validator?: IRequestBodyValidator<T>): ((input: T) => Error | null) => {
+  <T>(
+    validator?: IRequestBodyValidator<T>,
+  ): IRequestBodyValidation.IResolved<T> => {
     if (!validator) {
       NoTransformConfigurationError(method);
-      return () => null;
+      return create<T>((input: unknown) => ({
+        success: true,
+        data: input as T,
+      }));
     } else if (validator.type === "assert") return assert(validator.assert);
     else if (validator.type === "is") return is(validator.is);
     else if (validator.type === "validate") return validate(validator.validate);
-    return () =>
-      new Error(`Error on nestia.core.${method}(): invalid typed validator.`);
+    return create<T>(() => ({
+      success: false,
+      error: new Error(
+        `Error on nestia.core.${method}(): invalid typed validator.`,
+      ),
+    }));
   };
 
+/**
+ * Resolves factory checkers or the existing error-only metadata protocol once.
+ *
+ * @internal
+ */
+export const resolve_request_body = <T>(
+  checker: IRequestBodyValidation<T>,
+  input: unknown,
+): IRequestBodyValidation.IResult<T> => {
+  if (checker.resolve) return checker.resolve(input);
+  const error = checker(input as T);
+  return error === null
+    ? { success: true, data: input as T }
+    : { success: false, error };
+};
+
+/** Installs both protocols on one newly created, session-independent checker. */
+const create = <T>(
+  resolve: (input: unknown) => IRequestBodyValidation.IResult<T>,
+): IRequestBodyValidation.IResolved<T> =>
+  Object.assign(
+    (input: T): Error | null => {
+      const result = resolve(input);
+      return result.success ? null : result.error;
+    },
+    { resolve },
+  );
+
 /** @internal */
-const assert =
-  <T>(closure: (data: T) => T) =>
-  (input: T) => {
+const assert = <T>(closure: (data: T) => T) =>
+  create<T>((input: unknown): IRequestBodyValidation.IResult<T> => {
     try {
-      closure(input);
-      return null;
+      return { success: true, data: closure(input as T) };
     } catch (exp) {
       if (typia.is<TypeGuardError>(exp)) {
-        return new BadRequestException({
-          path: exp.path,
-          reason: exp.message,
-          expected: exp.expected,
-          value: exp.value,
-          message: MESSAGE,
-        });
+        return {
+          success: false,
+          error: new BadRequestException({
+            path: exp.path,
+            reason: exp.message,
+            expected: exp.expected,
+            value: exp.value,
+            message: MESSAGE,
+          }),
+        };
       }
       throw exp;
     }
-  };
+  });
 
 /** @internal */
-const is =
-  <T>(closure: (data: T) => boolean) =>
-  (input: T) => {
-    const success: boolean = closure(input);
-    return success ? null : new BadRequestException(MESSAGE);
-  };
+const is = <T>(closure: (data: T) => boolean) =>
+  create<T>((input: unknown): IRequestBodyValidation.IResult<T> => {
+    const success: boolean = closure(input as T);
+    return success
+      ? { success: true, data: input as T }
+      : { success: false, error: new BadRequestException(MESSAGE) };
+  });
 
 /** @internal */
-const validate =
-  <T>(closure: (data: T) => IValidation<T>) =>
-  (input: T) => {
-    const result: IValidation<T> = closure(input);
+const validate = <T>(closure: (data: T) => IValidation<T>) =>
+  create<T>((input: unknown): IRequestBodyValidation.IResult<T> => {
+    const result: IValidation<T> = closure(input as T);
     return result.success
-      ? null
-      : new BadRequestException({
-          errors: result.errors,
-          message: MESSAGE,
-        });
-  };
+      ? { success: true, data: result.data }
+      : {
+          success: false,
+          error: new BadRequestException({
+            errors: result.errors,
+            message: MESSAGE,
+          }),
+        };
+  });
 
 /** @internal */
 const MESSAGE = "Request body data is not following the promised type.";

package/src/options/IRequestBodyValidator.ts

@@ -4,17 +4,88 @@ export type IRequestBodyValidator<T> =
   | IRequestBodyValidator.IAssert<T>
   | IRequestBodyValidator.IIs<T>
   | IRequestBodyValidator.IValidate<T>;
+/**
+ * The request body validator that the transform passes to `TypedBody`,
+ * `EncryptedBody`, `PlainBody`, `WebSocketRoute.Header`, and
+ * `McpRoute.Params`.
+ *
+ * The literal `type` field selects which typia function generated the
+ * validator: `assert`, `is`, or `validate`. `validate_request_body` turns a
+ * failure of any variant into a 400 response. Assert and validate success
+ * supply their returned data to the decorated argument; is success keeps the
+ * input.
+ *
+ * @evidence contracts/common.md#principled-implementation The union is discriminated by the literal `type`, so the runtime selects the assert, is, or validate path with one comparison and the compiler checks that each variant carries the function its tag names.
+ * @evidence contracts/common.md#clear-and-simple-design Three variants, one per typia function family, with no shared base because each function has a different shape.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior; the runtime rejects an unknown `type` with an error instead of accepting it.
+ * @evidence contracts/common.md#meaningful-documentation The comment names the decorators that receive the validator, the meaning of the discriminant, and the response a failure becomes.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation The union and callback members describe validation of parsed body values without native platform resources.
+ */
 export namespace IRequestBodyValidator {
+  /**
+   * Validator generated from `typia.assert`.
+   *
+   * @evidence contracts/common.md#principled-implementation The variant tags a function returning validated data, which may be a clone, or throwing TypeGuardError. The shared runner retains successful data and converts the guard error to BadRequestException carrying the first failure's path, reason, expected type and value.
+   * @evidence contracts/common.md#clear-and-simple-design A two-member record, the tag and the function.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+   * @evidence contracts/common.md#meaningful-documentation The comment names the typia function the variant comes from; the failure response is stated on the union.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation The union and callback members describe validation of parsed body values without native platform resources.
+   */
   export interface IAssert<T> {
     type: "assert";
+    /**
+     * The typia assertion function generated for the requested type.
+     *
+     * @evidence contracts/common.md#principled-implementation The generated assertion returns the validated value, including a separate clone for clone modes, or throws TypeGuardError. Successful data becomes the decorated argument without requiring identity with the parsed input.
+     * @evidence contracts/common.md#clear-and-simple-design One function member with the input the decorator has.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The function is generated from the type, and the runtime never edits its result.
+     * @evidence contracts/common.md#meaningful-documentation The comment states that the function is generated for the requested type; its input is in the signature.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation The union and callback members describe validation of parsed body values without native platform resources.
+     */
     assert: (input: T) => T;
   }
+  /**
+   * Validator generated from `typia.is`.
+   *
+   * @evidence contracts/common.md#principled-implementation The variant tags a function of the parsed value that returns a boolean, because the value is already parsed and is returned as it is; a failing result becomes a `BadRequestException` with only the fixed message, because `typia.is` records no failure detail.
+   * @evidence contracts/common.md#clear-and-simple-design A two-member record, the tag and the function.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+   * @evidence contracts/common.md#meaningful-documentation The comment names the typia function the variant comes from.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation The union and callback members describe validation of parsed body values without native platform resources.
+   */
   export interface IIs<T> {
     type: "is";
+    /**
+     * The typia check function generated for the requested type.
+     *
+     * @evidence contracts/common.md#principled-implementation The transform generates the function for the type argument of the decorator, taking the parsed value and returning a boolean, because the value is already parsed and is returned as it is.
+     * @evidence contracts/common.md#clear-and-simple-design One function member with the input the decorator has.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The function is generated from the type, and the runtime never edits its result.
+     * @evidence contracts/common.md#meaningful-documentation The comment states that the function is generated for the requested type; its result is in the signature.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation The union and callback members describe validation of parsed body values without native platform resources.
+     */
     is: (input: T) => boolean;
   }
+  /**
+   * Validator generated from `typia.validate`.
+   *
+   * @evidence contracts/common.md#principled-implementation The callback returns IValidation; successful result.data becomes the decorated argument, including a clone, while failure becomes BadRequestException carrying every validation error.
+   * @evidence contracts/common.md#clear-and-simple-design A two-member record, the tag and the function.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+   * @evidence contracts/common.md#meaningful-documentation The comment names the typia function the variant comes from.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation The union and callback members describe validation of parsed body values without native platform resources.
+   */
   export interface IValidate<T> {
     type: "validate";
+    /**
+     * The typia validation function generated for the requested type.
+     *
+     * @evidence contracts/common.md#principled-implementation The transform generates the function for the type argument of the decorator, taking the parsed value and returning the validation result with every error.
+     * @evidence contracts/common.md#clear-and-simple-design One function member with the input the decorator has.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The function is generated from the type, and the runtime never edits its result.
+     * @evidence contracts/common.md#meaningful-documentation The comment states that the function is generated for the requested type; its result is in the signature.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation The union and callback members describe validation of parsed body values without native platform resources.
+     */
     validate: (input: T) => IValidation<T>;
   }
 }

package/src/options/IRequestFormDataProps.ts

@@ -7,19 +7,99 @@ export interface IRequestFormDataProps<T> {
     | IRequestFormDataProps.IIs<T>
     | IRequestFormDataProps.IValidate<T>;
 }
+/**
+ * Properties that the transform passes to `TypedFormData.Body`: the file fields
+ * and the validator.
+ *
+ * `files` names the file fields of the type with their limits, and `validator`
+ * validates the `FormData` made from the fields and the uploaded files.
+ *
+ * @evidence contracts/common.md#principled-implementation The record carries what the multipart handling needs: which fields are files, with how many each may hold, and how to validate the assembled form.
+ * @evidence contracts/common.md#clear-and-simple-design A two-member record whose nested types describe the variants and the file entries.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+ * @evidence contracts/common.md#meaningful-documentation The comment names the two members and the decorator that receives them.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation FormData validators and file-field names describe multipart protocol data; no member is a native storage path or handle.
+ */
 export namespace IRequestFormDataProps {
+  /**
+   * Validator generated from `typia.assert`.
+   *
+   * @evidence contracts/common.md#principled-implementation The variant tags a function of `FormData` that returns the decoded object or throws the `TypeGuardError` of typia, which becomes a `BadRequestException` with the path, reason, expected type, and value.
+   * @evidence contracts/common.md#clear-and-simple-design A two-member record, the tag and the function.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+   * @evidence contracts/common.md#meaningful-documentation The comment names the typia function the variant comes from.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation FormData validators and file-field names describe multipart protocol data; no member is a native storage path or handle.
+   */
   export interface IAssert<T> {
     type: "assert";
+    /**
+     * The typia assertion function generated for the requested type.
+     *
+     * @evidence contracts/common.md#principled-implementation The transform generates the function for the type argument, taking the form and returning the decoded object or throwing.
+     * @evidence contracts/common.md#clear-and-simple-design One function member.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The function is generated from the type, and the runtime never edits its result.
+     * @evidence contracts/common.md#meaningful-documentation The comment states that the function is generated for the requested type.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation FormData validators and file-field names describe multipart protocol data; no member is a native storage path or handle.
+     */
     assert: (input: FormData) => T;
   }
+  /**
+   * Validator generated from `typia.is`.
+   *
+   * @evidence contracts/common.md#principled-implementation The variant tags a function of `FormData` that returns the decoded object or `null`; `null` becomes a `BadRequestException` with only the fixed message.
+   * @evidence contracts/common.md#clear-and-simple-design A two-member record, the tag and the function.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+   * @evidence contracts/common.md#meaningful-documentation The comment names the typia function the variant comes from.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation FormData validators and file-field names describe multipart protocol data; no member is a native storage path or handle.
+   */
   export interface IIs<T> {
     type: "is";
+    /**
+     * The typia check function generated for the requested type.
+     *
+     * @evidence contracts/common.md#principled-implementation The transform generates the function for the type argument, taking the form and returning the decoded object or `null`.
+     * @evidence contracts/common.md#clear-and-simple-design One function member.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The function is generated from the type, and the runtime never edits its result.
+     * @evidence contracts/common.md#meaningful-documentation The comment states that the function is generated for the requested type.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation FormData validators and file-field names describe multipart protocol data; no member is a native storage path or handle.
+     */
     is: (input: FormData) => T | null;
   }
+  /**
+   * Validator generated from `typia.validate`.
+   *
+   * @evidence contracts/common.md#principled-implementation The variant tags a function of `FormData` that returns the `IValidation` of typia; a failure becomes a `BadRequestException` carrying every error.
+   * @evidence contracts/common.md#clear-and-simple-design A two-member record, the tag and the function.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+   * @evidence contracts/common.md#meaningful-documentation The comment names the typia function the variant comes from.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation FormData validators and file-field names describe multipart protocol data; no member is a native storage path or handle.
+   */
   export interface IValidate<T> {
     type: "validate";
+    /**
+     * The typia validation function generated for the requested type.
+     *
+     * @evidence contracts/common.md#principled-implementation The transform generates the function for the type argument, taking the form and returning the validation result.
+     * @evidence contracts/common.md#clear-and-simple-design One function member.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The function is generated from the type, and the runtime never edits its result.
+     * @evidence contracts/common.md#meaningful-documentation The comment states that the function is generated for the requested type.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation FormData validators and file-field names describe multipart protocol data; no member is a native storage path or handle.
+     */
     validate: (input: FormData) => IValidation<T>;
   }
+  /**
+   * A file field of a multipart form: its name and the number of files it may
+   * hold, or `null` for no limit.
+   *
+   * A limit of 1 makes the multer field accept one file; any other value leaves
+   * the field unlimited.
+   *
+   * @evidence contracts/common.md#principled-implementation A limit of 1 makes the multer field accept one file and any other value leaves the field unlimited, which is how the runtime configures `multer.fields`.
+   * @evidence contracts/common.md#clear-and-simple-design A two-field record with no behavior.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The values come from the type through the transform, not from a fixture.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the meaning of the name and of the limit.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation FormData validators and file-field names describe multipart protocol data; no member is a native storage path or handle.
+   */
   export interface IFile {
     name: string;
     limit: number | null;

package/src/options/IRequestHeadersValidator.ts

@@ -4,17 +4,84 @@ export type IRequestHeadersValidator<T> =
   | IRequestHeadersValidator.IAssert<T>
   | IRequestHeadersValidator.IIs<T>
   | IRequestHeadersValidator.IValidate<T>;
+/**
+ * The request headers validator that the transform passes to `TypedHeaders`.
+ *
+ * The literal `type` field selects which typia function generated the
+ * validator: `assert`, `is`, or `validate`. `validate_request_headers` turns a
+ * failure of any variant into a 400 response.
+ *
+ * @evidence contracts/common.md#principled-implementation The union is discriminated by the literal `type`, so the runtime selects the assert, is, or validate path with one comparison and the compiler checks that each variant carries the function its tag names.
+ * @evidence contracts/common.md#clear-and-simple-design Three variants, one per typia function family, with no shared base because each function has a different shape.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior; the runtime rejects an unknown `type` with an error instead of accepting it.
+ * @evidence contracts/common.md#meaningful-documentation The comment names the decorators that receive the validator, the meaning of the discriminant, and the response a failure becomes.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation The validator consumes HTTP header records and returns decoded values independently of native filesystem or process spelling.
+ */
 export namespace IRequestHeadersValidator {
+  /**
+   * Validator generated from `typia.assert`.
+   *
+   * @evidence contracts/common.md#principled-implementation The variant tags a function of the header record of the request, whose values are strings, string arrays, or undefined that returns the decoded object or throws the `TypeGuardError` of typia; `validate_request_headers` catches the error and converts it to a `BadRequestException` carrying the path, reason, expected type, and value of the first failure.
+   * @evidence contracts/common.md#clear-and-simple-design A two-member record, the tag and the function.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+   * @evidence contracts/common.md#meaningful-documentation The comment names the typia function the variant comes from; the failure response is stated on the union.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation The validator consumes HTTP header records and returns decoded values independently of native filesystem or process spelling.
+   */
   export interface IAssert<T> {
     type: "assert";
+    /**
+     * The typia assertion function generated for the requested type.
+     *
+     * @evidence contracts/common.md#principled-implementation The transform generates the function for the type argument of the decorator, taking the header record of the request, whose values are strings, string arrays, or undefined and it returns the decoded object or throws the `TypeGuardError` of typia.
+     * @evidence contracts/common.md#clear-and-simple-design One function member with the input the decorator has.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The function is generated from the type, and the runtime never edits its result.
+     * @evidence contracts/common.md#meaningful-documentation The comment states that the function is generated for the requested type; its input is in the signature.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation The validator consumes HTTP header records and returns decoded values independently of native filesystem or process spelling.
+     */
     assert: (input: Record<string, string | string[] | undefined>) => T;
   }
+  /**
+   * Validator generated from `typia.is`.
+   *
+   * @evidence contracts/common.md#principled-implementation The variant tags a function of the header record of the request, whose values are strings, string arrays, or undefined that returns the decoded object or `null`; a failing result becomes a `BadRequestException` with only the fixed message, because `typia.is` records no failure detail.
+   * @evidence contracts/common.md#clear-and-simple-design A two-member record, the tag and the function.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+   * @evidence contracts/common.md#meaningful-documentation The comment names the typia function the variant comes from.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation The validator consumes HTTP header records and returns decoded values independently of native filesystem or process spelling.
+   */
   export interface IIs<T> {
     type: "is";
+    /**
+     * The typia check function generated for the requested type.
+     *
+     * @evidence contracts/common.md#principled-implementation The transform generates the function for the type argument of the decorator, taking the header record of the request, whose values are strings, string arrays, or undefined and returning the decoded object or `null`.
+     * @evidence contracts/common.md#clear-and-simple-design One function member with the input the decorator has.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The function is generated from the type, and the runtime never edits its result.
+     * @evidence contracts/common.md#meaningful-documentation The comment states that the function is generated for the requested type; its result is in the signature.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation The validator consumes HTTP header records and returns decoded values independently of native filesystem or process spelling.
+     */
     is: (input: Record<string, string | string[] | undefined>) => T | null;
   }
+  /**
+   * Validator generated from `typia.validate`.
+   *
+   * @evidence contracts/common.md#principled-implementation The variant tags a function of the header record of the request, whose values are strings, string arrays, or undefined that returns the `IValidation` of typia; a failed result becomes a `BadRequestException` carrying every error of the validation.
+   * @evidence contracts/common.md#clear-and-simple-design A two-member record, the tag and the function.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+   * @evidence contracts/common.md#meaningful-documentation The comment names the typia function the variant comes from.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation The validator consumes HTTP header records and returns decoded values independently of native filesystem or process spelling.
+   */
   export interface IValidate<T> {
     type: "validate";
+    /**
+     * The typia validation function generated for the requested type.
+     *
+     * @evidence contracts/common.md#principled-implementation The transform generates the function for the type argument of the decorator, taking the header record of the request, whose values are strings, string arrays, or undefined and returning the validation result with every error.
+     * @evidence contracts/common.md#clear-and-simple-design One function member with the input the decorator has.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The function is generated from the type, and the runtime never edits its result.
+     * @evidence contracts/common.md#meaningful-documentation The comment states that the function is generated for the requested type; its result is in the signature.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation The validator consumes HTTP header records and returns decoded values independently of native filesystem or process spelling.
+     */
     validate: (
       input: Record<string, string | string[] | undefined>,
     ) => IValidation<T>;