@typia/interface 12.0.0-dev.20260309 → 12.0.0-dev.20260311

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

@@ -12,7 +12,6 @@ import { IValidation } from "./IValidation";
  *
  * - {@link ILlmApplication.IConfig.validate}: Custom validation per method
  * - {@link ILlmSchema.IConfig.strict}: OpenAI structured output mode
- * - {@link ILlmSchema.IConfig.reference}: Control `$ref` inlining behavior
  *
  * @author Jeongho Nam - https://github.com/samchon
  * @template Class Source class/interface type
@@ -30,7 +29,7 @@ export interface ILlmApplication<Class extends object = any> {
      * Configuration used to generate this application.
      *
      * Contains the settings that were applied during schema generation, including
-     * reference handling, strict mode, and parameter separation.
+     * strict mode and any custom validation hooks.
      */
     config: ILlmApplication.IConfig<Class>;
     /**

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/ILlmSchema.d.ts

@@ -25,19 +25,9 @@ export declare namespace ILlmSchema {
      * Configuration options for LLM schema generation.
      *
      * Controls how TypeScript types are converted to LLM-compatible JSON schemas.
-     * These settings affect reference handling and OpenAI structured output
-     * compatibility.
+     * These settings affect OpenAI structured output compatibility.
      */
     interface IConfig {
-        /**
-         * Whether to allow `$ref` references everywhere.
-         *
-         * When `false`, references are inlined except for recursive types.
-         * References reduce token cost but may cause hallucination.
-         *
-         * @default true
-         */
-        reference: boolean;
         /**
          * Whether to enable strict mode (OpenAI structured output).
          *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typia/interface",
-  "version": "12.0.0-dev.20260309",
+  "version": "12.0.0-dev.20260311",
   "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>;
+}

package/src/http/IHttpLlmApplication.ts

@@ -1,72 +1,72 @@
-import { OpenApi } from "../openapi/OpenApi";
-import { ILlmSchema } from "../schema/ILlmSchema";
-import { IHttpLlmFunction } from "./IHttpLlmFunction";
-import { IHttpMigrateRoute } from "./IHttpMigrateRoute";
-
-/**
- * LLM function calling application from OpenAPI document.
- *
- * `IHttpLlmApplication` is a collection of {@link IHttpLlmFunction} schemas
- * converted from {@link OpenApi.IDocument} by `HttpLlm.application()`. Each
- * OpenAPI operation becomes an LLM-callable function.
- *
- * Successful conversions go to {@link functions}, failed ones to {@link errors}
- * with detailed error messages. Common failure causes:
- *
- * - Unsupported schema features (tuples, `oneOf` with incompatible types)
- * - Missing required fields in OpenAPI document
- * - Operations marked with `x-samchon-human: true`
- *
- * Configure behavior via {@link IHttpLlmApplication.IConfig}:
- *
- * - {@link IHttpLlmApplication.IConfig.maxLength}: Function name length limit
- * - {@link ILlmSchema.IConfig.strict}: OpenAI structured output mode
- *
- * @author Jeongho Nam - https://github.com/samchon
- */
-export interface IHttpLlmApplication {
-  /** Successfully converted LLM function schemas. */
-  functions: IHttpLlmFunction[];
-
-  /** Operations that failed conversion. */
-  errors: IHttpLlmApplication.IError[];
-
-  /** Configuration used for composition. */
-  config: IHttpLlmApplication.IConfig;
-}
-export namespace IHttpLlmApplication {
-  /** Configuration for HTTP LLM application composition. */
-  export interface IConfig extends ILlmSchema.IConfig {
-    /**
-     * Maximum function name length. Truncated or UUID if exceeded.
-     *
-     * @default 64
-     */
-    maxLength: number;
-
-    /**
-     * Whether to disallow superfluous properties.
-     *
-     * @default false
-     */
-    equals: boolean;
-  }
-
-  /** Composition error for an operation. */
-  export interface IError {
-    /** HTTP method of the failed operation. */
-    method: "get" | "post" | "put" | "patch" | "delete" | "head";
-
-    /** Path of the failed operation. */
-    path: string;
-
-    /** Error messages describing the failure. */
-    messages: string[];
-
-    /** Returns source {@link OpenApi.IOperation}. */
-    operation: () => OpenApi.IOperation;
-
-    /** Returns source route. Undefined if error occurred at migration level. */
-    route: () => IHttpMigrateRoute | undefined;
-  }
-}
+import { OpenApi } from "../openapi/OpenApi";
+import { ILlmSchema } from "../schema/ILlmSchema";
+import { IHttpLlmFunction } from "./IHttpLlmFunction";
+import { IHttpMigrateRoute } from "./IHttpMigrateRoute";
+
+/**
+ * LLM function calling application from OpenAPI document.
+ *
+ * `IHttpLlmApplication` is a collection of {@link IHttpLlmFunction} schemas
+ * converted from {@link OpenApi.IDocument} by `HttpLlm.application()`. Each
+ * OpenAPI operation becomes an LLM-callable function.
+ *
+ * Successful conversions go to {@link functions}, failed ones to {@link errors}
+ * with detailed error messages. Common failure causes:
+ *
+ * - Unsupported schema features (tuples, `oneOf` with incompatible types)
+ * - Missing required fields in OpenAPI document
+ * - Operations marked with `x-samchon-human: true`
+ *
+ * Configure behavior via {@link IHttpLlmApplication.IConfig}:
+ *
+ * - {@link IHttpLlmApplication.IConfig.maxLength}: Function name length limit
+ * - {@link ILlmSchema.IConfig.strict}: OpenAI structured output mode
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export interface IHttpLlmApplication {
+  /** Successfully converted LLM function schemas. */
+  functions: IHttpLlmFunction[];
+
+  /** Operations that failed conversion. */
+  errors: IHttpLlmApplication.IError[];
+
+  /** Configuration used for composition. */
+  config: IHttpLlmApplication.IConfig;
+}
+export namespace IHttpLlmApplication {
+  /** Configuration for HTTP LLM application composition. */
+  export interface IConfig extends ILlmSchema.IConfig {
+    /**
+     * Maximum function name length. Truncated or UUID if exceeded.
+     *
+     * @default 64
+     */
+    maxLength: number;
+
+    /**
+     * Whether to disallow superfluous properties.
+     *
+     * @default false
+     */
+    equals: boolean;
+  }
+
+  /** Composition error for an operation. */
+  export interface IError {
+    /** HTTP method of the failed operation. */
+    method: "get" | "post" | "put" | "patch" | "delete" | "head";
+
+    /** Path of the failed operation. */
+    path: string;
+
+    /** Error messages describing the failure. */
+    messages: string[];
+
+    /** Returns source {@link OpenApi.IOperation}. */
+    operation: () => OpenApi.IOperation;
+
+    /** Returns source route. Undefined if error occurred at migration level. */
+    route: () => IHttpMigrateRoute | undefined;
+  }
+}