@typia/interface 12.0.0 → 12.1.0-dev.20260325

package/src/openapi/index.ts

@@ -1,5 +1,5 @@
-export * from "./OpenApi";
-export * from "./OpenApiV3";
-export * from "./OpenApiV3_1";
-export * from "./OpenApiV3_2";
-export * from "./SwaggerV2";
+export * from "./OpenApi";
+export * from "./OpenApiV3";
+export * from "./OpenApiV3_1";
+export * from "./OpenApiV3_2";
+export * from "./SwaggerV2";

package/src/schema/IJsonParseResult.ts

@@ -1,134 +1,134 @@
-import { DeepPartial } from "../typings/DeepPartial";
-
-/**
- * Result of lenient JSON parsing.
- *
- * `IJsonParseResult<T>` represents the result of parsing JSON that may be
- * incomplete, malformed, or contain non-standard syntax (e.g., unquoted keys,
- * trailing commas, missing quotes).
- *
- * Unlike standard JSON parsing which fails on any syntax error, lenient parsing
- * attempts to recover as much data as possible while reporting issues.
- *
- * Check the {@link IJsonParseResult.success} discriminator:
- *
- * - `true` → {@link IJsonParseResult.ISuccess} with parsed
- *   {@link IJsonParseResult.ISuccess.data}
- * - `false` → {@link IJsonParseResult.IFailure} with partial
- *   {@link IJsonParseResult.IFailure.data} and
- *   {@link IJsonParseResult.IFailure.errors}
- *
- * @author Jeongho Nam - https://github.com/samchon
- * @template T The expected type after successful parsing
- */
-export type IJsonParseResult<T = unknown> =
-  | IJsonParseResult.ISuccess<T>
-  | IJsonParseResult.IFailure<T>;
-
-export namespace IJsonParseResult {
-  /**
-   * Successful parsing result.
-   *
-   * Indicates the JSON was parsed without any errors. The data may still have
-   * been recovered from non-standard syntax (e.g., unquoted keys, trailing
-   * commas), but no information was lost.
-   *
-   * @template T The parsed type
-   */
-  export interface ISuccess<T = unknown> {
-    /**
-     * Success discriminator.
-     *
-     * Always `true` for successful parsing.
-     */
-    success: true;
-
-    /** The parsed data with correct type. */
-    data: T;
-  }
-
-  /**
-   * Failed parsing result with partial data and errors.
-   *
-   * Indicates the JSON had syntax errors that could not be fully recovered. The
-   * {@link data} contains whatever could be parsed, and {@link errors} describes
-   * what went wrong.
-   *
-   * @template T The expected type (data may be partial)
-   */
-  export interface IFailure<T = unknown> {
-    /**
-     * Success discriminator.
-     *
-     * Always `false` for failed parsing.
-     */
-    success: false;
-
-    /**
-     * Partially parsed data.
-     *
-     * Contains whatever could be recovered from the malformed JSON. May be
-     * incomplete or have missing properties.
-     */
-    data: DeepPartial<T> | undefined;
-
-    /**
-     * The original input string that was parsed.
-     *
-     * Preserved for debugging or error correction purposes.
-     */
-    input: string;
-
-    /**
-     * Array of parsing errors encountered.
-     *
-     * Each error describes a specific issue found during parsing, with location
-     * and suggested fix.
-     */
-    errors: IError[];
-  }
-
-  /** Detailed information about a parsing error. */
-  export interface IError {
-    /**
-     * Property path to the error location.
-     *
-     * A dot-notation path from the root to the error location. Uses `$input` as
-     * the root.
-     *
-     * @example
-     *   $input.user.email;
-     *
-     * @example
-     *   $input.items[0].price;
-     */
-    path: string;
-
-    /**
-     * What was expected at this location.
-     *
-     * @example
-     *   JSON value (string, number, boolean, null, object, or array)
-     *
-     * @example
-     *   quoted string
-     *
-     * @example
-     *   ":";
-     */
-    expected: string;
-
-    /**
-     * Description of what was actually found.
-     *
-     * Human/AI-readable message explaining the issue.
-     *
-     * @example
-     *   unquoted string 'abc' - did you forget quotes?
-     *
-     * @example
-     *   missing opening quote for 'hello'
-     */
-    description: unknown;
-  }
-}
+import { DeepPartial } from "../typings/DeepPartial";
+
+/**
+ * Result of lenient JSON parsing.
+ *
+ * `IJsonParseResult<T>` represents the result of parsing JSON that may be
+ * incomplete, malformed, or contain non-standard syntax (e.g., unquoted keys,
+ * trailing commas, missing quotes).
+ *
+ * Unlike standard JSON parsing which fails on any syntax error, lenient parsing
+ * attempts to recover as much data as possible while reporting issues.
+ *
+ * Check the {@link IJsonParseResult.success} discriminator:
+ *
+ * - `true` → {@link IJsonParseResult.ISuccess} with parsed
+ *   {@link IJsonParseResult.ISuccess.data}
+ * - `false` → {@link IJsonParseResult.IFailure} with partial
+ *   {@link IJsonParseResult.IFailure.data} and
+ *   {@link IJsonParseResult.IFailure.errors}
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @template T The expected type after successful parsing
+ */
+export type IJsonParseResult<T = unknown> =
+  | IJsonParseResult.ISuccess<T>
+  | IJsonParseResult.IFailure<T>;
+
+export namespace IJsonParseResult {
+  /**
+   * Successful parsing result.
+   *
+   * Indicates the JSON was parsed without any errors. The data may still have
+   * been recovered from non-standard syntax (e.g., unquoted keys, trailing
+   * commas), but no information was lost.
+   *
+   * @template T The parsed type
+   */
+  export interface ISuccess<T = unknown> {
+    /**
+     * Success discriminator.
+     *
+     * Always `true` for successful parsing.
+     */
+    success: true;
+
+    /** The parsed data with correct type. */
+    data: T;
+  }
+
+  /**
+   * Failed parsing result with partial data and errors.
+   *
+   * Indicates the JSON had syntax errors that could not be fully recovered. The
+   * {@link data} contains whatever could be parsed, and {@link errors} describes
+   * what went wrong.
+   *
+   * @template T The expected type (data may be partial)
+   */
+  export interface IFailure<T = unknown> {
+    /**
+     * Success discriminator.
+     *
+     * Always `false` for failed parsing.
+     */
+    success: false;
+
+    /**
+     * Partially parsed data.
+     *
+     * Contains whatever could be recovered from the malformed JSON. May be
+     * incomplete or have missing properties.
+     */
+    data: DeepPartial<T> | undefined;
+
+    /**
+     * The original input string that was parsed.
+     *
+     * Preserved for debugging or error correction purposes.
+     */
+    input: string;
+
+    /**
+     * Array of parsing errors encountered.
+     *
+     * Each error describes a specific issue found during parsing, with location
+     * and suggested fix.
+     */
+    errors: IError[];
+  }
+
+  /** Detailed information about a parsing error. */
+  export interface IError {
+    /**
+     * Property path to the error location.
+     *
+     * A dot-notation path from the root to the error location. Uses `$input` as
+     * the root.
+     *
+     * @example
+     *   $input.user.email;
+     *
+     * @example
+     *   $input.items[0].price;
+     */
+    path: string;
+
+    /**
+     * What was expected at this location.
+     *
+     * @example
+     *   JSON value (string, number, boolean, null, object, or array)
+     *
+     * @example
+     *   quoted string
+     *
+     * @example
+     *   ":";
+     */
+    expected: string;
+
+    /**
+     * Description of what was actually found.
+     *
+     * Human/AI-readable message explaining the issue.
+     *
+     * @example
+     *   unquoted string 'abc' - did you forget quotes?
+     *
+     * @example
+     *   missing opening quote for 'hello'
+     */
+    description: unknown;
+  }
+}

package/src/schema/ILlmStructuredOutput.ts

@@ -1,112 +1,112 @@
-import { IJsonParseResult } from "./IJsonParseResult";
-import { ILlmSchema } from "./ILlmSchema";
-import { IValidation } from "./IValidation";
-
-/**
- * LLM structured output schema with parsing and validation utilities.
- *
- * `ILlmStructuredOutput<T>` is generated by `typia.llm.structuredOutput<T>()`
- * to provide everything needed for handling LLM structured outputs: the JSON
- * schema for prompting, and functions for parsing, coercing, and validating
- * responses.
- *
- * Structured outputs allow LLMs to generate data conforming to a predefined
- * schema instead of free-form text. This is useful for:
- *
- * - Extracting structured data from conversations
- * - Generating typed responses for downstream processing
- * - Ensuring consistent output formats across LLM calls
- *
- * Workflow:
- *
- * 1. Pass {@link parameters} schema to LLM provider
- * 2. Receive LLM response (JSON string or pre-parsed object)
- * 3. Use {@link parse} for raw strings or {@link coerce} for pre-parsed objects
- * 4. Use {@link validate} to check the result and get detailed errors
- *
- * @author Jeongho Nam - https://github.com/samchon
- * @template T The expected output type
- */
-export interface ILlmStructuredOutput<T = unknown> {
-  /**
-   * JSON schema for the structured output.
-   *
-   * Pass this schema to LLM providers (OpenAI, Anthropic, Google, etc.) to
-   * constrain the output format. The schema includes `$defs` for shared type
-   * definitions and `properties` for the output structure.
-   *
-   * Most LLM providers accept this directly in their structured output or
-   * response format configuration.
-   */
-  parameters: ILlmSchema.IParameters;
-
-  /**
-   * Lenient JSON parser with schema-based type coercion.
-   *
-   * Handles incomplete or malformed JSON commonly produced by LLMs:
-   *
-   * - Unclosed brackets, strings, trailing commas
-   * - JavaScript-style comments (`//` and multi-line)
-   * - Unquoted object keys, incomplete keywords (`tru`, `fal`, `nul`)
-   * - Markdown code block extraction, junk prefix skipping
-   *
-   * Also coerces double-stringified values based on the schema:
-   *
-   * - `"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)
-   *
-   * 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 {@link coerce} instead.
-   *
-   * @param input Raw JSON string from LLM output
-   * @returns Parse result with data on success, or partial data with errors
-   */
-  parse: (input: string) => IJsonParseResult<T>;
-
-  /**
-   * Coerce pre-parsed output to match expected schema types.
-   *
-   * **Use this only when the SDK 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 input Pre-parsed output object from SDK
-   * @returns Coerced output with corrected types
-   */
-  coerce: (input: unknown) => T;
-
-  /**
-   * Validates LLM-generated output against the schema.
-   *
-   * LLMs frequently make type errors such as returning strings instead of
-   * numbers or missing required properties. Use this validator to check output
-   * before further processing.
-   *
-   * 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 input The output generated by the LLM
-   * @returns Validation result with success status and any errors
-   */
-  validate: (input: unknown) => IValidation<T>;
-}
+import { IJsonParseResult } from "./IJsonParseResult";
+import { ILlmSchema } from "./ILlmSchema";
+import { IValidation } from "./IValidation";
+
+/**
+ * LLM structured output schema with parsing and validation utilities.
+ *
+ * `ILlmStructuredOutput<T>` is generated by `typia.llm.structuredOutput<T>()`
+ * to provide everything needed for handling LLM structured outputs: the JSON
+ * schema for prompting, and functions for parsing, coercing, and validating
+ * responses.
+ *
+ * Structured outputs allow LLMs to generate data conforming to a predefined
+ * schema instead of free-form text. This is useful for:
+ *
+ * - Extracting structured data from conversations
+ * - Generating typed responses for downstream processing
+ * - Ensuring consistent output formats across LLM calls
+ *
+ * Workflow:
+ *
+ * 1. Pass {@link parameters} schema to LLM provider
+ * 2. Receive LLM response (JSON string or pre-parsed object)
+ * 3. Use {@link parse} for raw strings or {@link coerce} for pre-parsed objects
+ * 4. Use {@link validate} to check the result and get detailed errors
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @template T The expected output type
+ */
+export interface ILlmStructuredOutput<T = unknown> {
+  /**
+   * JSON schema for the structured output.
+   *
+   * Pass this schema to LLM providers (OpenAI, Anthropic, Google, etc.) to
+   * constrain the output format. The schema includes `$defs` for shared type
+   * definitions and `properties` for the output structure.
+   *
+   * Most LLM providers accept this directly in their structured output or
+   * response format configuration.
+   */
+  parameters: ILlmSchema.IParameters;
+
+  /**
+   * Lenient JSON parser with schema-based type coercion.
+   *
+   * Handles incomplete or malformed JSON commonly produced by LLMs:
+   *
+   * - Unclosed brackets, strings, trailing commas
+   * - JavaScript-style comments (`//` and multi-line)
+   * - Unquoted object keys, incomplete keywords (`tru`, `fal`, `nul`)
+   * - Markdown code block extraction, junk prefix skipping
+   *
+   * Also coerces double-stringified values based on the schema:
+   *
+   * - `"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)
+   *
+   * 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 {@link coerce} instead.
+   *
+   * @param input Raw JSON string from LLM output
+   * @returns Parse result with data on success, or partial data with errors
+   */
+  parse: (input: string) => IJsonParseResult<T>;
+
+  /**
+   * Coerce pre-parsed output to match expected schema types.
+   *
+   * **Use this only when the SDK 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 input Pre-parsed output object from SDK
+   * @returns Coerced output with corrected types
+   */
+  coerce: (input: unknown) => T;
+
+  /**
+   * Validates LLM-generated output against the schema.
+   *
+   * LLMs frequently make type errors such as returning strings instead of
+   * numbers or missing required properties. Use this validator to check output
+   * before further processing.
+   *
+   * 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 input The output generated by the LLM
+   * @returns Validation result with success status and any errors
+   */
+  validate: (input: unknown) => IValidation<T>;
+}

package/src/schema/index.ts

@@ -1,15 +1,15 @@
-export * from "./IResult";
-export * from "./IValidation";
-
-export * from "./IJsonSchemaTransformError";
-export * from "./IJsonSchemaApplication";
-export * from "./IJsonSchemaCollection";
-export * from "./IJsonSchemaUnit";
-export * from "./IJsonSchemaAttribute";
-
-export * from "./ILlmController";
-export * from "./ILlmApplication";
-export * from "./ILlmFunction";
-export * from "./ILlmSchema";
-export * from "./ILlmStructuredOutput";
-export * from "./IJsonParseResult";
+export * from "./IResult";
+export * from "./IValidation";
+
+export * from "./IJsonSchemaTransformError";
+export * from "./IJsonSchemaApplication";
+export * from "./IJsonSchemaCollection";
+export * from "./IJsonSchemaUnit";
+export * from "./IJsonSchemaAttribute";
+
+export * from "./ILlmController";
+export * from "./ILlmApplication";
+export * from "./ILlmFunction";
+export * from "./ILlmSchema";
+export * from "./ILlmStructuredOutput";
+export * from "./IJsonParseResult";