@typia/interface 12.0.0-dev.20260307-2 → 12.0.0-dev.20260310

package/lib/http/IHttpLlmController.d.ts

@@ -7,16 +7,16 @@ import { IHttpResponse } from "./IHttpResponse";
  *
  * `IHttpLlmController` is a controller for registering OpenAPI operations as
  * LLM function calling tools. It contains {@link IHttpLlmApplication} with
- * {@link IHttpLlmFunction function calling schemas}, {@link name identifier},
- * and {@link connection} to the API server.
+ * {@link IHttpLlmFunction function calling schemas}, {@link name identifier}, and
+ * {@link connection} to the API server.
  *
- * You can create this controller with {@link HttpLlm.controller} function,
- * and register it to MCP server with {@link registerMcpControllers}:
+ * You can create this controller with {@link HttpLlm.controller} function, and
+ * register it to MCP server with {@link registerMcpControllers}:
  *
  * ```typescript
  * import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
- * import { HttpLlm } from "@typia/utils";
  * import { registerMcpControllers } from "@typia/mcp";
+ * import { HttpLlm } from "@typia/utils";
  *
  * const server = new McpServer({ name: "my-server", version: "1.0.0" });
  * registerMcpControllers({

package/lib/schema/IJsonParseResult.d.ts

@@ -78,9 +78,7 @@ export declare namespace IJsonParseResult {
          */
         errors: IError[];
     }
-    /**
-     * Detailed information about a parsing error.
-     */
+    /** Detailed information about a parsing error. */
     interface IError {
         /**
          * Property path to the error location.

package/lib/schema/ILlmApplication.d.ts

@@ -83,6 +83,6 @@ export declare namespace ILlmApplication {
      * @ignore
      */
     interface __IPrimitive<Class extends object = any> extends Omit<ILlmApplication<Class>, "config" | "functions"> {
-        functions: Omit<ILlmFunction, "parse">[];
+        functions: Omit<ILlmFunction, "parse" | "coerce">[];
     }
 }

package/lib/schema/ILlmController.d.ts

@@ -12,8 +12,8 @@ import { ILlmApplication } from "./ILlmApplication";
  *
  * ```typescript
  * import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
- * import typia from "typia";
  * import { registerMcpControllers } from "@typia/mcp";
+ * import typia from "typia";
  *
  * class Calculator {
  *   add(input: { a: number; b: number }): number {
@@ -28,10 +28,7 @@ import { ILlmApplication } from "./ILlmApplication";
  * registerMcpControllers({
  *   server,
  *   controllers: [
- *     typia.llm.controller<Calculator>(
- *       "calculator",
- *       new Calculator(),
- *     ),
+ *     typia.llm.controller<Calculator>("calculator", new Calculator()),
  *   ],
  * });
  * ```

package/lib/schema/ILlmFunction.d.ts

@@ -1,3 +1,4 @@
+import { tags } from "..";
 import { IJsonParseResult } from "./IJsonParseResult";
 import { ILlmSchema } from "./ILlmSchema";
 import { IValidation } from "./IValidation";
@@ -20,11 +21,11 @@ export interface ILlmFunction {
      * Function name for LLM invocation.
      *
      * The identifier used by the LLM to call this function. Must be unique within
-     * the application. OpenAI limits function names to 64 characters.
+     * the application.
      *
-     * @maxLength 64
+     * OpenAI limits function names to 64 characters.
      */
-    name: string;
+    name: string & tags.MaxLength<64>;
     /**
      * Schema for function parameters.
      *
@@ -83,13 +84,38 @@ export interface ILlmFunction {
      * Type validation is NOT performed — use {@link validate} after parsing.
      *
      * If the SDK (e.g., LangChain, Vercel AI, MCP) already parses JSON internally
-     * and provides a pre-parsed object, use `LlmJson.coerce()` from `@typia/utils`
-     * instead to apply schema-based type coercion without re-parsing.
+     * and provides a pre-parsed object, use {@link coerce} instead to apply
+     * schema-based type coercion without re-parsing.
      *
      * @param str Raw JSON string from LLM output
      * @returns Parse result with data on success, or partial data with errors
      */
     parse: (str: string) => IJsonParseResult<unknown>;
+    /**
+     * Coerce pre-parsed arguments to match expected schema types.
+     *
+     * **Use this only when the SDK (e.g., LangChain, Vercel AI, MCP) already
+     * parses JSON internally.** For raw JSON strings from LLM output, use
+     * {@link parse} instead — it handles both lenient parsing and type coercion in
+     * one step.
+     *
+     * LLMs often return values with incorrect types even after parsing:
+     *
+     * - `"42"` → `42` (when schema expects number)
+     * - `"true"` → `true` (when schema expects boolean)
+     * - `"null"` → `null` (when schema expects null)
+     * - `"{...}"` → `{...}` (when schema expects object)
+     * - `"[...]"` → `[...]` (when schema expects array)
+     *
+     * This function recursively coerces these double-stringified values based on
+     * the {@link parameters} schema.
+     *
+     * Type validation is NOT performed — use {@link validate} after coercion.
+     *
+     * @param data Pre-parsed arguments object from SDK
+     * @returns Coerced arguments with corrected types
+     */
+    coerce: (data: unknown) => unknown;
     /**
      * Validates LLM-generated arguments against the schema.
      *
@@ -97,10 +123,10 @@ export interface ILlmFunction {
      * numbers or missing required properties. Use this validator to check
      * arguments before execution.
      *
-     * When validation fails, use `stringifyValidationFailure()` from
-     * `@typia/utils` to format the error for LLM feedback. The formatted output
-     * shows the invalid JSON with inline error comments, helping the LLM
-     * understand and correct its mistakes in the next turn.
+     * When validation fails, use {@link LlmJson.stringify} from `@typia/utils` to
+     * format the error for LLM feedback. The formatted output shows the invalid
+     * JSON with inline error comments, helping the LLM understand and correct its
+     * mistakes in the next turn.
      *
      * @param args The arguments generated by the LLM
      * @returns Validation result with success status and any errors

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typia/interface",
-  "version": "12.0.0-dev.20260307-2",
+  "version": "12.0.0-dev.20260310",
   "description": "Superfast runtime validators with only one line",
   "main": "lib/index.js",
   "exports": {

package/src/http/IHttpConnection.ts

@@ -1,200 +1,200 @@
-/// <reference lib="dom" />
-
-/**
- * HTTP connection configuration for remote server communication.
- *
- * `IHttpConnection` defines connection settings required to communicate with
- * remote HTTP servers. This interface is primarily used by `@nestia/fetcher`
- * and generated SDK functions to establish HTTP connections.
- *
- * The {@link host} property specifies the base URL of the target server, while
- * {@link headers} allows passing custom HTTP headers with each request. For
- * fine-grained control over fetch behavior, use {@link options} to configure
- * caching, CORS, credentials, and other fetch API settings.
- *
- * In Node.js versions prior to 20 (which lack native fetch), provide a polyfill
- * like `node-fetch` via the {@link fetch} property.
- *
- * @author Jeongho Nam - https://github.com/samchon
- * @author Seungjun We - https://github.com/SeungjunWe
- */
-export interface IHttpConnection {
-  /**
-   * Base URL of the remote HTTP server.
-   *
-   * Must include protocol (http:// or https://) and may include port. Example:
-   * `"https://api.example.com"` or `"http://localhost:3000"`.
-   */
-  host: string;
-
-  /**
-   * Custom HTTP headers to send with every request.
-   *
-   * Common use cases include authentication tokens, API keys, and content
-   * negotiation headers. Values can be primitives or arrays.
-   */
-  headers?: Record<string, IHttpConnection.HeaderValue>;
-
-  /**
-   * Additional fetch API options.
-   *
-   * Configure caching, CORS mode, credentials handling, and other
-   * fetch-specific behaviors. These options are passed directly to the
-   * underlying fetch call.
-   */
-  options?: IHttpConnection.IOptions;
-
-  /**
-   * Custom fetch function implementation.
-   *
-   * For Node.js versions before 20 that lack native fetch support, provide a
-   * polyfill such as `node-fetch`. This allows the same connection
-   * configuration to work across all Node.js versions.
-   *
-   * @example
-   *   import fetch from "node-fetch";
-   *
-   *   const connection: IHttpConnection = {
-   *     host: "https://api.example.com",
-   *     fetch: fetch as any,
-   *   };
-   */
-  fetch?: typeof fetch;
-}
-export namespace IHttpConnection {
-  /**
-   * Fetch API request options.
-   *
-   * Subset of the standard `RequestInit` interface, excluding properties that
-   * are managed internally (body, headers, method). These options control
-   * caching, CORS, credentials, and request lifecycle behavior.
-   */
-  export interface IOptions {
-    /**
-     * Request cache mode.
-     *
-     * Controls how the request interacts with the browser's HTTP cache.
-     *
-     * - `"default"`: Standard browser caching behavior
-     * - `"no-store"`: Bypass cache completely, don't store response
-     * - `"reload"`: Bypass cache, but store response
-     * - `"no-cache"`: Validate with server before using cache
-     * - `"force-cache"`: Use cache even if stale
-     * - `"only-if-cached"`: Only use cache, fail if not cached
-     */
-    cache?:
-      | "default"
-      | "force-cache"
-      | "no-cache"
-      | "no-store"
-      | "only-if-cached"
-      | "reload";
-
-    /**
-     * Credentials inclusion mode.
-     *
-     * Controls whether cookies and HTTP authentication are sent.
-     *
-     * - `"omit"`: Never send credentials
-     * - `"same-origin"`: Send credentials only for same-origin requests
-     * - `"include"`: Always send credentials, even cross-origin
-     */
-    credentials?: "omit" | "same-origin" | "include";
-
-    /**
-     * Subresource integrity hash for verification.
-     *
-     * A cryptographic hash (e.g., `"sha256-abc123..."`) to verify the fetched
-     * resource hasn't been tampered with. The browser will reject responses
-     * that don't match the expected hash.
-     */
-    integrity?: string;
-
-    /**
-     * Whether to keep the connection alive after page unload.
-     *
-     * When `true`, the request can outlive the page that initiated it. Useful
-     * for analytics or logging requests that should complete even if the user
-     * navigates away.
-     */
-    keepalive?: boolean;
-
-    /**
-     * CORS (Cross-Origin Resource Sharing) mode.
-     *
-     * Controls cross-origin request behavior.
-     *
-     * - `"cors"`: Standard CORS request (requires server support)
-     * - `"no-cors"`: Limited cross-origin request (opaque response)
-     * - `"same-origin"`: Only allow same-origin requests
-     * - `"navigate"`: For navigation requests (used by browsers)
-     */
-    mode?: "cors" | "navigate" | "no-cors" | "same-origin";
-
-    /**
-     * HTTP redirect handling behavior.
-     *
-     * - `"follow"`: Automatically follow redirects (default)
-     * - `"error"`: Throw an error on redirect
-     * - `"manual"`: Return redirect response for manual handling
-     */
-    redirect?: "error" | "follow" | "manual";
-
-    /**
-     * Referrer URL to send with the request.
-     *
-     * Overrides the default referrer. Use empty string to suppress the referrer
-     * header entirely.
-     */
-    referrer?: string;
-
-    /**
-     * Policy for how much referrer information to include.
-     *
-     * Controls what referrer information is sent with requests. More
-     * restrictive policies improve privacy but may break some server-side
-     * analytics or security checks.
-     */
-    referrerPolicy?:
-      | ""
-      | "no-referrer"
-      | "no-referrer-when-downgrade"
-      | "origin"
-      | "origin-when-cross-origin"
-      | "same-origin"
-      | "strict-origin"
-      | "strict-origin-when-cross-origin"
-      | "unsafe-url";
-
-    /**
-     * AbortSignal for request cancellation.
-     *
-     * Connect to an AbortController to enable cancellation of in-flight
-     * requests. When the signal is aborted, the fetch promise rejects with an
-     * AbortError.
-     *
-     * @example
-     *   const controller = new AbortController();
-     *   const options = { signal: controller.signal };
-     *   // Later: controller.abort();
-     */
-    signal?: AbortSignal | null;
-  }
-
-  /**
-   * Allowed types for HTTP header values.
-   *
-   * Supports primitive types (string, boolean, number, bigint) and arrays of
-   * primitives. Arrays are typically joined with commas when sent as HTTP
-   * headers.
-   */
-  export type HeaderValue =
-    | string
-    | boolean
-    | number
-    | bigint
-    | Array<boolean>
-    | Array<number>
-    | Array<bigint>
-    | Array<string>;
-}
+/// <reference lib="dom" />
+
+/**
+ * HTTP connection configuration for remote server communication.
+ *
+ * `IHttpConnection` defines connection settings required to communicate with
+ * remote HTTP servers. This interface is primarily used by `@nestia/fetcher`
+ * and generated SDK functions to establish HTTP connections.
+ *
+ * The {@link host} property specifies the base URL of the target server, while
+ * {@link headers} allows passing custom HTTP headers with each request. For
+ * fine-grained control over fetch behavior, use {@link options} to configure
+ * caching, CORS, credentials, and other fetch API settings.
+ *
+ * In Node.js versions prior to 20 (which lack native fetch), provide a polyfill
+ * like `node-fetch` via the {@link fetch} property.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @author Seungjun We - https://github.com/SeungjunWe
+ */
+export interface IHttpConnection {
+  /**
+   * Base URL of the remote HTTP server.
+   *
+   * Must include protocol (http:// or https://) and may include port. Example:
+   * `"https://api.example.com"` or `"http://localhost:3000"`.
+   */
+  host: string;
+
+  /**
+   * Custom HTTP headers to send with every request.
+   *
+   * Common use cases include authentication tokens, API keys, and content
+   * negotiation headers. Values can be primitives or arrays.
+   */
+  headers?: Record<string, IHttpConnection.HeaderValue>;
+
+  /**
+   * Additional fetch API options.
+   *
+   * Configure caching, CORS mode, credentials handling, and other
+   * fetch-specific behaviors. These options are passed directly to the
+   * underlying fetch call.
+   */
+  options?: IHttpConnection.IOptions;
+
+  /**
+   * Custom fetch function implementation.
+   *
+   * For Node.js versions before 20 that lack native fetch support, provide a
+   * polyfill such as `node-fetch`. This allows the same connection
+   * configuration to work across all Node.js versions.
+   *
+   * @example
+   *   import fetch from "node-fetch";
+   *
+   *   const connection: IHttpConnection = {
+   *     host: "https://api.example.com",
+   *     fetch: fetch as any,
+   *   };
+   */
+  fetch?: typeof fetch;
+}
+export namespace IHttpConnection {
+  /**
+   * Fetch API request options.
+   *
+   * Subset of the standard `RequestInit` interface, excluding properties that
+   * are managed internally (body, headers, method). These options control
+   * caching, CORS, credentials, and request lifecycle behavior.
+   */
+  export interface IOptions {
+    /**
+     * Request cache mode.
+     *
+     * Controls how the request interacts with the browser's HTTP cache.
+     *
+     * - `"default"`: Standard browser caching behavior
+     * - `"no-store"`: Bypass cache completely, don't store response
+     * - `"reload"`: Bypass cache, but store response
+     * - `"no-cache"`: Validate with server before using cache
+     * - `"force-cache"`: Use cache even if stale
+     * - `"only-if-cached"`: Only use cache, fail if not cached
+     */
+    cache?:
+      | "default"
+      | "force-cache"
+      | "no-cache"
+      | "no-store"
+      | "only-if-cached"
+      | "reload";
+
+    /**
+     * Credentials inclusion mode.
+     *
+     * Controls whether cookies and HTTP authentication are sent.
+     *
+     * - `"omit"`: Never send credentials
+     * - `"same-origin"`: Send credentials only for same-origin requests
+     * - `"include"`: Always send credentials, even cross-origin
+     */
+    credentials?: "omit" | "same-origin" | "include";
+
+    /**
+     * Subresource integrity hash for verification.
+     *
+     * A cryptographic hash (e.g., `"sha256-abc123..."`) to verify the fetched
+     * resource hasn't been tampered with. The browser will reject responses
+     * that don't match the expected hash.
+     */
+    integrity?: string;
+
+    /**
+     * Whether to keep the connection alive after page unload.
+     *
+     * When `true`, the request can outlive the page that initiated it. Useful
+     * for analytics or logging requests that should complete even if the user
+     * navigates away.
+     */
+    keepalive?: boolean;
+
+    /**
+     * CORS (Cross-Origin Resource Sharing) mode.
+     *
+     * Controls cross-origin request behavior.
+     *
+     * - `"cors"`: Standard CORS request (requires server support)
+     * - `"no-cors"`: Limited cross-origin request (opaque response)
+     * - `"same-origin"`: Only allow same-origin requests
+     * - `"navigate"`: For navigation requests (used by browsers)
+     */
+    mode?: "cors" | "navigate" | "no-cors" | "same-origin";
+
+    /**
+     * HTTP redirect handling behavior.
+     *
+     * - `"follow"`: Automatically follow redirects (default)
+     * - `"error"`: Throw an error on redirect
+     * - `"manual"`: Return redirect response for manual handling
+     */
+    redirect?: "error" | "follow" | "manual";
+
+    /**
+     * Referrer URL to send with the request.
+     *
+     * Overrides the default referrer. Use empty string to suppress the referrer
+     * header entirely.
+     */
+    referrer?: string;
+
+    /**
+     * Policy for how much referrer information to include.
+     *
+     * Controls what referrer information is sent with requests. More
+     * restrictive policies improve privacy but may break some server-side
+     * analytics or security checks.
+     */
+    referrerPolicy?:
+      | ""
+      | "no-referrer"
+      | "no-referrer-when-downgrade"
+      | "origin"
+      | "origin-when-cross-origin"
+      | "same-origin"
+      | "strict-origin"
+      | "strict-origin-when-cross-origin"
+      | "unsafe-url";
+
+    /**
+     * AbortSignal for request cancellation.
+     *
+     * Connect to an AbortController to enable cancellation of in-flight
+     * requests. When the signal is aborted, the fetch promise rejects with an
+     * AbortError.
+     *
+     * @example
+     *   const controller = new AbortController();
+     *   const options = { signal: controller.signal };
+     *   // Later: controller.abort();
+     */
+    signal?: AbortSignal | null;
+  }
+
+  /**
+   * Allowed types for HTTP header values.
+   *
+   * Supports primitive types (string, boolean, number, bigint) and arrays of
+   * primitives. Arrays are typically joined with commas when sent as HTTP
+   * headers.
+   */
+  export type HeaderValue =
+    | string
+    | boolean
+    | number
+    | bigint
+    | Array<boolean>
+    | Array<number>
+    | Array<bigint>
+    | Array<string>;
+}