@nestia/core 14.0.1 → 14.0.3

package/src/decorators/TypedRoute.ts

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

package/src/decorators/WebSocketRoute.ts

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

package/src/decorators/doNotThrowTransformError.ts

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

package/src/decorators/internal/IMcpRouteReflect.ts

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

package/src/decorators/internal/IRequestBodyValidation.ts

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

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.";