@nestia/core 12.0.0-rc.2 → 12.0.0-rc.3

package/src/decorators/McpRoute.ts

@@ -1,154 +1,154 @@
-import { IRequestBodyValidator } from "../options/IRequestBodyValidator";
-import { IMcpRouteReflect } from "./internal/IMcpRouteReflect";
-import { validate_request_body } from "./internal/validate_request_body";
-
-/**
- * MCP (Model Context Protocol) route decorator.
- *
- * `@McpRoute()` marks a controller method as a callable MCP tool. When the
- * application bootstraps, every method annotated with this decorator is
- * registered on the MCP server built by {@link McpAdaptor.upgrade}, making it
- * reachable by LLM clients through the standard Streamable HTTP transport.
- *
- * The public form takes only the tool's `name` (string). Human-readable
- * `description` and `title` are read from the method's JSDoc:
- *
- * - `description`: the JSDoc comment body.
- * - `title`: the value of an optional `@title` JSDoc tag.
- *
- * For type-safe tool inputs, decorate exactly one parameter of the method with
- * {@link McpRoute.Params}. The parameter type `T` is analyzed at compile time by
- * the nestia transformer, which generates both a runtime validator and the JSON
- * Schema attached to `inputSchema` in `tools/list` responses.
- *
- * For the MCP endpoint to actually be served, call {@link McpAdaptor.upgrade} on
- * the {@link INestApplication} instance at bootstrap. The decorator alone only
- * stores reflection metadata.
- *
- * @author wildduck - https://github.com/wildduck2
- * @example
- *   ```typescript
- *   import core from "@nestia/core";
- *
- *   @Controller()
- *   export class WeatherController {
- *     /**
- *      * Return current weather for a city.
- *      *
- *      * @title Get weather
- *      *\/
- *     @core.McpRoute("get_weather")
- *     public async get(
- *       @core.McpRoute.Params() params: { city: string },
- *     ): Promise<{ temp: number }> {
- *       return { temp: 22 };
- *     }
- *   }
- *   ```;
- *
- * @param name Unique tool identifier exposed to MCP clients via `tools/list`.
- * @returns Method decorator.
- */
-export function McpRoute(name: string): MethodDecorator;
-
-/** @internal */
-export function McpRoute(config: McpRoute.IConfig): MethodDecorator;
-
-export function McpRoute(input: string | McpRoute.IConfig): MethodDecorator {
-  const config: McpRoute.IConfig =
-    typeof input === "string" ? { name: input } : input;
-  return function McpRoute(
-    _target: Object,
-    _propertyKey: string | symbol,
-    descriptor: TypedPropertyDescriptor<any>,
-  ): TypedPropertyDescriptor<any> {
-    Reflect.defineMetadata(
-      "nestia/McpRoute",
-      {
-        name: config.name,
-        title: config.title,
-        description: config.description,
-        inputSchema: config.inputSchema ?? { type: "object", properties: {} },
-        outputSchema: config.outputSchema,
-        annotations: config.annotations,
-      } satisfies IMcpRouteReflect,
-      descriptor.value,
-    );
-    return descriptor;
-  };
-}
-
-export namespace McpRoute {
-  /**
-   * Configuration object emitted by the nestia transformer at compile time.
-   *
-   * Users call `@McpRoute("name")`; the transformer rewrites the call to
-   * `@McpRoute({ name, description, title, inputSchema, ... })` after parsing
-   * method JSDoc and analyzing the `@McpRoute.Params<T>()` parameter type.
-   *
-   * @internal
-   */
-  export interface IConfig {
-    name: string;
-    title?: string;
-    description?: string;
-    inputSchema?: object;
-    outputSchema?: object;
-    annotations?: IMcpRouteReflect["annotations"];
-  }
-
-  /**
-   * Parameter decorator for an MCP tool's input arguments.
-   *
-   * `@McpRoute.Params<T>()` validates the `arguments` object from a
-   * `tools/call` request against the TypeScript type `T` using typia. A failed
-   * validation surfaces to the client as a JSON-RPC `-32602` (`InvalidParams`)
-   * error with structured diagnostics, giving the LLM precise feedback to
-   * self-correct.
-   *
-   * MCP tools accept exactly one arguments object; applying this decorator more
-   * than once on a single method is a compile-time error. The decorated type
-   * `T` must be an object type without dynamic properties.
-   *
-   * @author wildduck - https://github.com/wildduck2
-   * @param validator Optional custom validator. Default is `typia.assert()`.
-   * @returns Parameter decorator.
-   */
-  export function Params<T>(
-    validator?: IRequestBodyValidator<T>,
-  ): ParameterDecorator {
-    const validate = validate_request_body("McpRoute.Params")(validator);
-    return function McpRouteParams(
-      target: Object,
-      propertyKey: string | symbol | undefined,
-      parameterIndex: number,
-    ) {
-      emplace(target, propertyKey ?? "", {
-        category: "params",
-        index: parameterIndex,
-        validate,
-      });
-    };
-  }
-
-  /** @internal */
-  const emplace = (
-    target: Object,
-    propertyKey: string | symbol,
-    value: IMcpRouteReflect.IArgument,
-  ) => {
-    const array: IMcpRouteReflect.IArgument[] | undefined = Reflect.getMetadata(
-      "nestia/McpRoute/Parameters",
-      target,
-      propertyKey,
-    );
-    if (array !== undefined) array.push(value);
-    else
-      Reflect.defineMetadata(
-        "nestia/McpRoute/Parameters",
-        [value],
-        target,
-        propertyKey,
-      );
-  };
-}
+import { IRequestBodyValidator } from "../options/IRequestBodyValidator";
+import { IMcpRouteReflect } from "./internal/IMcpRouteReflect";
+import { validate_request_body } from "./internal/validate_request_body";
+
+/**
+ * MCP (Model Context Protocol) route decorator.
+ *
+ * `@McpRoute()` marks a controller method as a callable MCP tool. When the
+ * application bootstraps, every method annotated with this decorator is
+ * registered on the MCP server built by {@link McpAdaptor.upgrade}, making it
+ * reachable by LLM clients through the standard Streamable HTTP transport.
+ *
+ * The public form takes only the tool's `name` (string). Human-readable
+ * `description` and `title` are read from the method's JSDoc:
+ *
+ * - `description`: the JSDoc comment body.
+ * - `title`: the value of an optional `@title` JSDoc tag.
+ *
+ * For type-safe tool inputs, decorate exactly one parameter of the method with
+ * {@link McpRoute.Params}. The parameter type `T` is analyzed at compile time by
+ * the nestia transformer, which generates both a runtime validator and the JSON
+ * Schema attached to `inputSchema` in `tools/list` responses.
+ *
+ * For the MCP endpoint to actually be served, call {@link McpAdaptor.upgrade} on
+ * the {@link INestApplication} instance at bootstrap. The decorator alone only
+ * stores reflection metadata.
+ *
+ * @author wildduck - https://github.com/wildduck2
+ * @example
+ *   ```typescript
+ *   import core from "@nestia/core";
+ *
+ *   @Controller()
+ *   export class WeatherController {
+ *     /**
+ *      * Return current weather for a city.
+ *      *
+ *      * @title Get weather
+ *      *\/
+ *     @core.McpRoute("get_weather")
+ *     public async get(
+ *       @core.McpRoute.Params() params: { city: string },
+ *     ): Promise<{ temp: number }> {
+ *       return { temp: 22 };
+ *     }
+ *   }
+ *   ```;
+ *
+ * @param name Unique tool identifier exposed to MCP clients via `tools/list`.
+ * @returns Method decorator.
+ */
+export function McpRoute(name: string): MethodDecorator;
+
+/** @internal */
+export function McpRoute(config: McpRoute.IConfig): MethodDecorator;
+
+export function McpRoute(input: string | McpRoute.IConfig): MethodDecorator {
+  const config: McpRoute.IConfig =
+    typeof input === "string" ? { name: input } : input;
+  return function McpRoute(
+    _target: Object,
+    _propertyKey: string | symbol,
+    descriptor: TypedPropertyDescriptor<any>,
+  ): TypedPropertyDescriptor<any> {
+    Reflect.defineMetadata(
+      "nestia/McpRoute",
+      {
+        name: config.name,
+        title: config.title,
+        description: config.description,
+        inputSchema: config.inputSchema ?? { type: "object", properties: {} },
+        outputSchema: config.outputSchema,
+        annotations: config.annotations,
+      } satisfies IMcpRouteReflect,
+      descriptor.value,
+    );
+    return descriptor;
+  };
+}
+
+export namespace McpRoute {
+  /**
+   * Configuration object emitted by the nestia transformer at compile time.
+   *
+   * Users call `@McpRoute("name")`; the transformer rewrites the call to
+   * `@McpRoute({ name, description, title, inputSchema, ... })` after parsing
+   * method JSDoc and analyzing the `@McpRoute.Params<T>()` parameter type.
+   *
+   * @internal
+   */
+  export interface IConfig {
+    name: string;
+    title?: string;
+    description?: string;
+    inputSchema?: object;
+    outputSchema?: object;
+    annotations?: IMcpRouteReflect["annotations"];
+  }
+
+  /**
+   * Parameter decorator for an MCP tool's input arguments.
+   *
+   * `@McpRoute.Params<T>()` validates the `arguments` object from a
+   * `tools/call` request against the TypeScript type `T` using typia. A failed
+   * validation surfaces to the client as a JSON-RPC `-32602` (`InvalidParams`)
+   * error with structured diagnostics, giving the LLM precise feedback to
+   * self-correct.
+   *
+   * MCP tools accept exactly one arguments object; applying this decorator more
+   * than once on a single method is a compile-time error. The decorated type
+   * `T` must be an object type without dynamic properties.
+   *
+   * @author wildduck - https://github.com/wildduck2
+   * @param validator Optional custom validator. Default is `typia.assert()`.
+   * @returns Parameter decorator.
+   */
+  export function Params<T>(
+    validator?: IRequestBodyValidator<T>,
+  ): ParameterDecorator {
+    const validate = validate_request_body("McpRoute.Params")(validator);
+    return function McpRouteParams(
+      target: Object,
+      propertyKey: string | symbol | undefined,
+      parameterIndex: number,
+    ) {
+      emplace(target, propertyKey ?? "", {
+        category: "params",
+        index: parameterIndex,
+        validate,
+      });
+    };
+  }
+
+  /** @internal */
+  const emplace = (
+    target: Object,
+    propertyKey: string | symbol,
+    value: IMcpRouteReflect.IArgument,
+  ) => {
+    const array: IMcpRouteReflect.IArgument[] | undefined = Reflect.getMetadata(
+      "nestia/McpRoute/Parameters",
+      target,
+      propertyKey,
+    );
+    if (array !== undefined) array.push(value);
+    else
+      Reflect.defineMetadata(
+        "nestia/McpRoute/Parameters",
+        [value],
+        target,
+        propertyKey,
+      );
+  };
+}

package/src/decorators/NoTransformConfigurationError.ts

@@ -1,40 +1,40 @@
-/** @internal */
-export function NoTransformConfigurationError(method: string) {
-  if (NoTransformConfigurationError.throws === true)
-    throw new Error(
-      [
-        `Error on nestia.core.${method}(): no transform has been configured.`,
-        `Build the project with "ttsc" (not stock "tsc"); the Go-backed @nestia/core transform attaches automatically through ttsc plugin auto-discovery.`,
-        `If "ttsc" is missing, run "npx nestia setup" to install the toolchain and runtime packages.`,
-        `If you're using a non-standard TypeScript compiler like Babel or SWC, the @nestia/core transformer is not available.`,
-        `If you're running "npx nestia sdk/swagger" or similar, run "npx ttsc --noEmit" to surface the underlying compilation error.`,
-        `See https://nestia.io/docs/setup for the full setup (tsgo and legacy paths); migration notes are at node_modules/@nestia/core/MIGRATION.md.`,
-      ].join(" "),
-    );
-  return undefined as never;
-}
-
-/** @internal */
-export namespace NoTransformConfigurationError {
-  /**
-   * Whether to throw an error or not.
-   *
-   * If you set this value to `false`, {@link NoTransformConfigurationError} will
-   * not throw an error.
-   *
-   * Even if you've not configured the plugin transformer of `tsconfig.json`
-   * file, the error will not be thrown and the program will be continued.
-   * Instead, every validations and assertions will be skipped and the value
-   * will be returned as it is. Furthermore, unexpected behaviors may occur.
-   *
-   * Therefore, it is not recommended to set this value to `false` in production
-   * environment. Configure this value to be `false` only when you're debugging
-   * or testing.
-   *
-   * By the way, if you hope the `false` value to be set, you have to do it
-   * before the first. If you configure the `false` value after the
-   * `@nestia/core` decorator functions are composed, the value will not be
-   * applied and the error will be thrown.
-   */
-  export let throws = true;
-}
+/** @internal */
+export function NoTransformConfigurationError(method: string) {
+  if (NoTransformConfigurationError.throws === true)
+    throw new Error(
+      [
+        `Error on nestia.core.${method}(): no transform has been configured.`,
+        `Build the project with "ttsc" (not stock "tsc"); the Go-backed @nestia/core transform attaches automatically through ttsc plugin auto-discovery.`,
+        `If "ttsc" is missing, install the toolchain manually: npm i -D ttsc typescript.`,
+        `If you're using a non-standard TypeScript compiler like Babel or SWC, the @nestia/core transformer is not available.`,
+        `If you're running "npx nestia sdk/swagger" or similar, run "npx ttsc --noEmit" to surface the underlying compilation error.`,
+        `See https://nestia.io/docs/setup for the full setup; migration notes are at node_modules/@nestia/core/MIGRATION.md.`,
+      ].join(" "),
+    );
+  return undefined as never;
+}
+
+/** @internal */
+export namespace NoTransformConfigurationError {
+  /**
+   * Whether to throw an error or not.
+   *
+   * If you set this value to `false`, {@link NoTransformConfigurationError} will
+   * not throw an error.
+   *
+   * Even if the transform did not run, the error will not be thrown and the
+   * program will be continued. Instead, every validation and assertion will be
+   * skipped and the value
+   * will be returned as it is. Furthermore, unexpected behaviors may occur.
+   *
+   * Therefore, it is not recommended to set this value to `false` in production
+   * environment. Configure this value to be `false` only when you're debugging
+   * or testing.
+   *
+   * By the way, if you hope the `false` value to be set, you have to do it
+   * before the first. If you configure the `false` value after the
+   * `@nestia/core` decorator functions are composed, the value will not be
+   * applied and the error will be thrown.
+   */
+  export let throws = true;
+}

package/src/decorators/PlainBody.ts

@@ -1,76 +1,76 @@
-import {
-  BadRequestException,
-  ExecutionContext,
-  createParamDecorator,
-} from "@nestjs/common";
-import type express from "express";
-import type { FastifyRequest } from "fastify";
-
-import { get_text_body } from "./internal/get_text_body";
-import { is_request_body_undefined } from "./internal/is_request_body_undefined";
-import { validate_request_body } from "./internal/validate_request_body";
-
-/**
- * Plain body decorator.
- *
- * `PlainBody` is a decorator function getting full body text from the HTTP
- * request.
- *
- * If you adjust the regular {@link Body} decorator function to the body
- * parameter, you can't get the full body text because the {@link Body} tries to
- * convert the body text to JSON object. Therefore, `@nestia/core` provides this
- * `PlainBody` decorator function to get the full body text.
- *
- * ```typescript
- * \@TypedRoute.Post("memo")
- * public store
- *     (
- *         \@PlainBody() body: string
- *     ): void;
- * ```
- *
- * @author Jeongho Nam - https://github.com/samchon
- * @returns Parameter decorator
- */
-export function PlainBody(): ParameterDecorator;
-
-/** @internal */
-export function PlainBody(
-  assert?: (input: unknown) => string,
-): ParameterDecorator {
-  const checker = assert
-    ? validate_request_body("PlainBody")({
-        type: "assert",
-        assert,
-      })
-    : null;
-  return createParamDecorator(async function PlainBody(
-    _data: any,
-    context: ExecutionContext,
-  ) {
-    const request: express.Request | FastifyRequest = context
-      .switchToHttp()
-      .getRequest();
-    if (
-      is_request_body_undefined(request) &&
-      (checker ?? (() => null))(undefined as any) === null
-    )
-      return undefined;
-    else if (!isTextPlain(request.headers["content-type"]))
-      throw new BadRequestException(`Request body type is not "text/plain".`);
-    const value: string = await get_text_body(request);
-    if (checker) {
-      const error: Error | null = checker(value);
-      if (error !== null) throw error;
-    }
-    return value;
-  })();
-}
-
-/** @internal */
-const isTextPlain = (text?: string): boolean =>
-  text !== undefined &&
-  text
-    .split(";")
-    .map((str) => str.trim())
-    .some((str) => str === "text/plain");
+import {
+  BadRequestException,
+  ExecutionContext,
+  createParamDecorator,
+} from "@nestjs/common";
+import type express from "express";
+import type { FastifyRequest } from "fastify";
+
+import { get_text_body } from "./internal/get_text_body";
+import { is_request_body_undefined } from "./internal/is_request_body_undefined";
+import { validate_request_body } from "./internal/validate_request_body";
+
+/**
+ * Plain body decorator.
+ *
+ * `PlainBody` is a decorator function getting full body text from the HTTP
+ * request.
+ *
+ * If you adjust the regular {@link Body} decorator function to the body
+ * parameter, you can't get the full body text because the {@link Body} tries to
+ * convert the body text to JSON object. Therefore, `@nestia/core` provides this
+ * `PlainBody` decorator function to get the full body text.
+ *
+ * ```typescript
+ * \@TypedRoute.Post("memo")
+ * public store
+ *     (
+ *         \@PlainBody() body: string
+ *     ): void;
+ * ```
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @returns Parameter decorator
+ */
+export function PlainBody(): ParameterDecorator;
+
+/** @internal */
+export function PlainBody(
+  assert?: (input: unknown) => string,
+): ParameterDecorator {
+  const checker = assert
+    ? validate_request_body("PlainBody")({
+        type: "assert",
+        assert,
+      })
+    : null;
+  return createParamDecorator(async function PlainBody(
+    _data: any,
+    context: ExecutionContext,
+  ) {
+    const request: express.Request | FastifyRequest = context
+      .switchToHttp()
+      .getRequest();
+    if (
+      is_request_body_undefined(request) &&
+      (checker ?? (() => null))(undefined as any) === null
+    )
+      return undefined;
+    else if (!isTextPlain(request.headers["content-type"]))
+      throw new BadRequestException(`Request body type is not "text/plain".`);
+    const value: string = await get_text_body(request);
+    if (checker) {
+      const error: Error | null = checker(value);
+      if (error !== null) throw error;
+    }
+    return value;
+  })();
+}
+
+/** @internal */
+const isTextPlain = (text?: string): boolean =>
+  text !== undefined &&
+  text
+    .split(";")
+    .map((str) => str.trim())
+    .some((str) => str === "text/plain");