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

package/src/schema/IJsonSchemaTransformError.ts

@@ -1,86 +1,86 @@
-import { OpenApi } from "../openapi";
-
-/**
- * Error information from JSON schema transformation.
- *
- * `IJsonSchemaTransformError` represents an error that occurred during
- * transformation or iteration of {@link OpenApi.IJsonSchema} types. This error
- * type is primarily generated when converting OpenAPI schemas to LLM-compatible
- * formats via {@link ILlmSchema}.
- *
- * Common transformation failures include:
- *
- * - **Missing references**: `$ref` pointing to non-existent schema definitions
- * - **Unsupported tuple types**: All LLM providers reject tuple schemas
- * - **Unsupported union types**: Gemini does not support `oneOf` schemas
- * - **Unsupported dynamic objects**: ChatGPT and Gemini reject
- *   `additionalProperties`
- *
- * The {@link reasons} array provides detailed information about each failure,
- * including the problematic schema, its location path, and a human-readable
- * error message. Use this information to diagnose and fix schema compatibility
- * issues.
- *
- * @author Jeongho Nam - https://github.com/samchon
- */
-export interface IJsonSchemaTransformError {
-  /**
-   * Name of the method that caused the error.
-   *
-   * Identifies which transformation function failed, such as
-   * `"HttpLlm.application"` or `"LlmSchemaConverter.schema"`.
-   */
-  method: string;
-
-  /**
-   * Summary error message.
-   *
-   * A human-readable description of the overall error. For detailed information
-   * about specific failures, examine the {@link reasons} array.
-   */
-  message: string;
-
-  /**
-   * Detailed list of transformation failures.
-   *
-   * Each entry describes a specific schema that failed transformation,
-   * including its location and the reason for failure. Multiple failures can
-   * occur in a single transformation when processing complex schemas.
-   */
-  reasons: IJsonSchemaTransformError.IReason[];
-}
-export namespace IJsonSchemaTransformError {
-  /**
-   * Detailed information about a single transformation failure.
-   *
-   * Provides the specific schema that failed, its accessor path for locating it
-   * within the document, and a message explaining why the transformation
-   * failed.
-   */
-  export interface IReason {
-    /**
-     * The schema that caused the transformation failure.
-     *
-     * The actual JSON schema object that could not be transformed. Inspect this
-     * to understand the problematic schema structure.
-     */
-    schema: OpenApi.IJsonSchema;
-
-    /**
-     * Path to the failing schema within the document.
-     *
-     * A dot-notation path (e.g., `"components.schemas.User.properties.tags"`)
-     * that identifies where the problematic schema is located. Use this to
-     * locate and fix the issue in the source OpenAPI document.
-     */
-    accessor: string;
-
-    /**
-     * Human-readable explanation of the failure.
-     *
-     * Describes why the schema could not be transformed, such as "Tuple type is
-     * not supported" or "Cannot resolve $ref reference".
-     */
-    message: string;
-  }
-}
+import { OpenApi } from "../openapi";
+
+/**
+ * Error information from JSON schema transformation.
+ *
+ * `IJsonSchemaTransformError` represents an error that occurred during
+ * transformation or iteration of {@link OpenApi.IJsonSchema} types. This error
+ * type is primarily generated when converting OpenAPI schemas to LLM-compatible
+ * formats via {@link ILlmSchema}.
+ *
+ * Common transformation failures include:
+ *
+ * - **Missing references**: `$ref` pointing to non-existent schema definitions
+ * - **Unsupported tuple types**: All LLM providers reject tuple schemas
+ * - **Unsupported union types**: Gemini does not support `oneOf` schemas
+ * - **Unsupported dynamic objects**: ChatGPT and Gemini reject
+ *   `additionalProperties`
+ *
+ * The {@link reasons} array provides detailed information about each failure,
+ * including the problematic schema, its location path, and a human-readable
+ * error message. Use this information to diagnose and fix schema compatibility
+ * issues.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export interface IJsonSchemaTransformError {
+  /**
+   * Name of the method that caused the error.
+   *
+   * Identifies which transformation function failed, such as
+   * `"HttpLlm.application"` or `"LlmSchemaConverter.schema"`.
+   */
+  method: string;
+
+  /**
+   * Summary error message.
+   *
+   * A human-readable description of the overall error. For detailed information
+   * about specific failures, examine the {@link reasons} array.
+   */
+  message: string;
+
+  /**
+   * Detailed list of transformation failures.
+   *
+   * Each entry describes a specific schema that failed transformation,
+   * including its location and the reason for failure. Multiple failures can
+   * occur in a single transformation when processing complex schemas.
+   */
+  reasons: IJsonSchemaTransformError.IReason[];
+}
+export namespace IJsonSchemaTransformError {
+  /**
+   * Detailed information about a single transformation failure.
+   *
+   * Provides the specific schema that failed, its accessor path for locating it
+   * within the document, and a message explaining why the transformation
+   * failed.
+   */
+  export interface IReason {
+    /**
+     * The schema that caused the transformation failure.
+     *
+     * The actual JSON schema object that could not be transformed. Inspect this
+     * to understand the problematic schema structure.
+     */
+    schema: OpenApi.IJsonSchema;
+
+    /**
+     * Path to the failing schema within the document.
+     *
+     * A dot-notation path (e.g., `"components.schemas.User.properties.tags"`)
+     * that identifies where the problematic schema is located. Use this to
+     * locate and fix the issue in the source OpenAPI document.
+     */
+    accessor: string;
+
+    /**
+     * Human-readable explanation of the failure.
+     *
+     * Describes why the schema could not be transformed, such as "Tuple type is
+     * not supported" or "Cannot resolve $ref reference".
+     */
+    message: string;
+  }
+}

package/src/schema/IJsonSchemaUnit.ts

@@ -1,120 +1,120 @@
-import { OpenApi } from "../openapi/OpenApi";
-import { OpenApiV3 } from "../openapi/OpenApiV3";
-
-/**
- * Single JSON schema unit for one TypeScript type.
- *
- * `IJsonSchemaUnit` represents a complete JSON schema for a single TypeScript
- * type, including the main schema definition and any referenced component
- * schemas. Generated by `typia.json.schema<T>()` at compile time.
- *
- * The result contains:
- *
- * - {@link IV3_0.schema | schema}: The main JSON schema for the type
- * - {@link IV3_0.components | components}: Shared schemas referenced via `$ref`
- * - {@link IV3_0.__type | __type}: Phantom property for TypeScript type inference
- *
- * Use this for single-type schema generation. For multiple types, see
- * {@link IJsonSchemaCollection}. For function schemas, see
- * {@link IJsonSchemaApplication}.
- *
- * @author Jeongho Nam - https://github.com/samchon
- * @template Version OpenAPI version ("3.0" or "3.1")
- * @template Type Original TypeScript type
- */
-export type IJsonSchemaUnit<
-  Version extends "3.0" | "3.1" = "3.1",
-  Type = unknown,
-> = Version extends "3.0"
-  ? IJsonSchemaUnit.IV3_0<Type>
-  : IJsonSchemaUnit.IV3_1<Type>;
-
-export namespace IJsonSchemaUnit {
-  /**
-   * JSON Schema unit for OpenAPI v3.0 specification.
-   *
-   * Uses OpenAPI v3.0 compatible JSON Schema format. In v3.0, nullable types
-   * are expressed with `nullable: true` rather than v3.1's `type: ["string",
-   * "null"]`.
-   *
-   * @template Type Original TypeScript type for phantom type preservation
-   */
-  export interface IV3_0<Type> {
-    /**
-     * OpenAPI specification version.
-     *
-     * Always `"3.0"` for this variant. Use this discriminator to determine
-     * which schema format is in use.
-     */
-    version: "3.0";
-
-    /**
-     * The main JSON schema definition for the type.
-     *
-     * Contains the complete schema for the target TypeScript type. May include
-     * `$ref` references to schemas in {@link components}.
-     */
-    schema: OpenApiV3.IJsonSchema;
-
-    /**
-     * Reusable schema definitions for `$ref` references.
-     *
-     * Contains named schemas that can be referenced throughout the main schema.
-     * Essential for recursive types and reducing duplication.
-     */
-    components: OpenApiV3.IComponents;
-
-    /**
-     * Phantom property for TypeScript generic type preservation.
-     *
-     * This property exists only in the type system to preserve the `Type`
-     * generic parameter. It is always `undefined` at runtime and should not be
-     * accessed or used in application code.
-     */
-    __type?: Type | undefined;
-  }
-
-  /**
-   * JSON Schema unit for OpenAPI v3.1 specification.
-   *
-   * Uses OpenAPI v3.1 compatible JSON Schema format. v3.1 aligns more closely
-   * with JSON Schema draft 2020-12, supporting features like `type` arrays for
-   * nullable types and `const` values.
-   *
-   * @template Type Original TypeScript type for phantom type preservation
-   */
-  export interface IV3_1<Type> {
-    /**
-     * OpenAPI specification version.
-     *
-     * Always `"3.1"` for this variant. Use this discriminator to determine
-     * which schema format is in use.
-     */
-    version: "3.1";
-
-    /**
-     * The main JSON schema definition for the type.
-     *
-     * Contains the complete schema for the target TypeScript type. May include
-     * `$ref` references to schemas in {@link components}.
-     */
-    schema: OpenApi.IJsonSchema;
-
-    /**
-     * Reusable schema definitions for `$ref` references.
-     *
-     * Contains named schemas that can be referenced throughout the main schema.
-     * Essential for recursive types and reducing duplication.
-     */
-    components: OpenApi.IComponents;
-
-    /**
-     * Phantom property for TypeScript generic type preservation.
-     *
-     * This property exists only in the type system to preserve the `Type`
-     * generic parameter. It is always `undefined` at runtime and should not be
-     * accessed or used in application code.
-     */
-    __type?: Type | undefined;
-  }
-}
+import { OpenApi } from "../openapi/OpenApi";
+import { OpenApiV3 } from "../openapi/OpenApiV3";
+
+/**
+ * Single JSON schema unit for one TypeScript type.
+ *
+ * `IJsonSchemaUnit` represents a complete JSON schema for a single TypeScript
+ * type, including the main schema definition and any referenced component
+ * schemas. Generated by `typia.json.schema<T>()` at compile time.
+ *
+ * The result contains:
+ *
+ * - {@link IV3_0.schema | schema}: The main JSON schema for the type
+ * - {@link IV3_0.components | components}: Shared schemas referenced via `$ref`
+ * - {@link IV3_0.__type | __type}: Phantom property for TypeScript type inference
+ *
+ * Use this for single-type schema generation. For multiple types, see
+ * {@link IJsonSchemaCollection}. For function schemas, see
+ * {@link IJsonSchemaApplication}.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @template Version OpenAPI version ("3.0" or "3.1")
+ * @template Type Original TypeScript type
+ */
+export type IJsonSchemaUnit<
+  Version extends "3.0" | "3.1" = "3.1",
+  Type = unknown,
+> = Version extends "3.0"
+  ? IJsonSchemaUnit.IV3_0<Type>
+  : IJsonSchemaUnit.IV3_1<Type>;
+
+export namespace IJsonSchemaUnit {
+  /**
+   * JSON Schema unit for OpenAPI v3.0 specification.
+   *
+   * Uses OpenAPI v3.0 compatible JSON Schema format. In v3.0, nullable types
+   * are expressed with `nullable: true` rather than v3.1's `type: ["string",
+   * "null"]`.
+   *
+   * @template Type Original TypeScript type for phantom type preservation
+   */
+  export interface IV3_0<Type> {
+    /**
+     * OpenAPI specification version.
+     *
+     * Always `"3.0"` for this variant. Use this discriminator to determine
+     * which schema format is in use.
+     */
+    version: "3.0";
+
+    /**
+     * The main JSON schema definition for the type.
+     *
+     * Contains the complete schema for the target TypeScript type. May include
+     * `$ref` references to schemas in {@link components}.
+     */
+    schema: OpenApiV3.IJsonSchema;
+
+    /**
+     * Reusable schema definitions for `$ref` references.
+     *
+     * Contains named schemas that can be referenced throughout the main schema.
+     * Essential for recursive types and reducing duplication.
+     */
+    components: OpenApiV3.IComponents;
+
+    /**
+     * Phantom property for TypeScript generic type preservation.
+     *
+     * This property exists only in the type system to preserve the `Type`
+     * generic parameter. It is always `undefined` at runtime and should not be
+     * accessed or used in application code.
+     */
+    __type?: Type | undefined;
+  }
+
+  /**
+   * JSON Schema unit for OpenAPI v3.1 specification.
+   *
+   * Uses OpenAPI v3.1 compatible JSON Schema format. v3.1 aligns more closely
+   * with JSON Schema draft 2020-12, supporting features like `type` arrays for
+   * nullable types and `const` values.
+   *
+   * @template Type Original TypeScript type for phantom type preservation
+   */
+  export interface IV3_1<Type> {
+    /**
+     * OpenAPI specification version.
+     *
+     * Always `"3.1"` for this variant. Use this discriminator to determine
+     * which schema format is in use.
+     */
+    version: "3.1";
+
+    /**
+     * The main JSON schema definition for the type.
+     *
+     * Contains the complete schema for the target TypeScript type. May include
+     * `$ref` references to schemas in {@link components}.
+     */
+    schema: OpenApi.IJsonSchema;
+
+    /**
+     * Reusable schema definitions for `$ref` references.
+     *
+     * Contains named schemas that can be referenced throughout the main schema.
+     * Essential for recursive types and reducing duplication.
+     */
+    components: OpenApi.IComponents;
+
+    /**
+     * Phantom property for TypeScript generic type preservation.
+     *
+     * This property exists only in the type system to preserve the `Type`
+     * generic parameter. It is always `undefined` at runtime and should not be
+     * accessed or used in application code.
+     */
+    __type?: Type | undefined;
+  }
+}

package/src/schema/ILlmApplication.ts

@@ -1,99 +1,99 @@
-import { ILlmFunction } from "./ILlmFunction";
-import { ILlmSchema } from "./ILlmSchema";
-import { IValidation } from "./IValidation";
-
-/**
- * LLM function calling application.
- *
- * `ILlmApplication` is a collection of {@link ILlmFunction} schemas generated
- * from a TypeScript class or interface by `typia.llm.application<App>()`. Each
- * public method becomes an {@link ILlmFunction} that LLM agents can invoke.
- *
- * Configure behavior via {@link ILlmApplication.IConfig}:
- *
- * - {@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
- */
-export interface ILlmApplication<Class extends object = any> {
-  /**
-   * Array of callable function schemas.
-   *
-   * Each function represents a method from the source class that the LLM can
-   * invoke. Functions include parameter schemas, descriptions, and validation
-   * logic for type-safe function calling.
-   */
-  functions: ILlmFunction[];
-
-  /**
-   * Configuration used to generate this application.
-   *
-   * Contains the settings that were applied during schema generation, including
-   * reference handling, strict mode, and parameter separation.
-   */
-  config: ILlmApplication.IConfig<Class>;
-
-  /**
-   * Phantom property for TypeScript generic type preservation.
-   *
-   * This property exists only in the type system to preserve the `Class`
-   * generic parameter at compile time. It is always `undefined` at runtime and
-   * should not be accessed or used in application code.
-   *
-   * This pattern enables type inference to recover the original class type from
-   * an `ILlmApplication` instance, useful for type-safe function routing.
-   */
-  __class?: Class | undefined;
-}
-export namespace ILlmApplication {
-  /**
-   * Configuration for LLM application generation.
-   *
-   * Extends {@link ILlmSchema.IConfig} with application-specific options for
-   * custom validation. These settings control how the application schema is
-   * generated from the source class.
-   */
-  export interface IConfig<Class extends object = any>
-    extends ILlmSchema.IConfig {
-    /**
-     * Custom validation functions per method name.
-     *
-     * Allows overriding the default type-based validation with custom business
-     * logic. Useful for complex validation rules that cannot be expressed in
-     * JSON Schema.
-     *
-     * @default null (use default type validation)
-     */
-    validate: null | Partial<ILlmApplication.IValidationHook<Class>>;
-  }
-
-  /**
-   * Type-safe mapping of method names to custom validators.
-   *
-   * Maps each method name to a validation function that receives the raw input
-   * and returns a validation result. The type inference ensures validators
-   * match the expected argument types.
-   *
-   * @template Class - The source class type for type inference
-   */
-  export type IValidationHook<Class extends object> = {
-    [K in keyof Class]?: Class[K] extends (args: infer Argument) => unknown
-      ? (input: unknown) => IValidation<Argument>
-      : never;
-  };
-
-  /**
-   * Internal type for typia transformer.
-   *
-   * @ignore
-   */
-  export interface __IPrimitive<Class extends object = any> extends Omit<
-    ILlmApplication<Class>,
-    "config" | "functions"
-  > {
-    functions: Omit<ILlmFunction, "parse" | "coerce">[];
-  }
-}
+import { ILlmFunction } from "./ILlmFunction";
+import { ILlmSchema } from "./ILlmSchema";
+import { IValidation } from "./IValidation";
+
+/**
+ * LLM function calling application.
+ *
+ * `ILlmApplication` is a collection of {@link ILlmFunction} schemas generated
+ * from a TypeScript class or interface by `typia.llm.application<App>()`. Each
+ * public method becomes an {@link ILlmFunction} that LLM agents can invoke.
+ *
+ * Configure behavior via {@link ILlmApplication.IConfig}:
+ *
+ * - {@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
+ */
+export interface ILlmApplication<Class extends object = any> {
+  /**
+   * Array of callable function schemas.
+   *
+   * Each function represents a method from the source class that the LLM can
+   * invoke. Functions include parameter schemas, descriptions, and validation
+   * logic for type-safe function calling.
+   */
+  functions: ILlmFunction[];
+
+  /**
+   * Configuration used to generate this application.
+   *
+   * Contains the settings that were applied during schema generation, including
+   * reference handling, strict mode, and parameter separation.
+   */
+  config: ILlmApplication.IConfig<Class>;
+
+  /**
+   * Phantom property for TypeScript generic type preservation.
+   *
+   * This property exists only in the type system to preserve the `Class`
+   * generic parameter at compile time. It is always `undefined` at runtime and
+   * should not be accessed or used in application code.
+   *
+   * This pattern enables type inference to recover the original class type from
+   * an `ILlmApplication` instance, useful for type-safe function routing.
+   */
+  __class?: Class | undefined;
+}
+export namespace ILlmApplication {
+  /**
+   * Configuration for LLM application generation.
+   *
+   * Extends {@link ILlmSchema.IConfig} with application-specific options for
+   * custom validation. These settings control how the application schema is
+   * generated from the source class.
+   */
+  export interface IConfig<Class extends object = any>
+    extends ILlmSchema.IConfig {
+    /**
+     * Custom validation functions per method name.
+     *
+     * Allows overriding the default type-based validation with custom business
+     * logic. Useful for complex validation rules that cannot be expressed in
+     * JSON Schema.
+     *
+     * @default null (use default type validation)
+     */
+    validate: null | Partial<ILlmApplication.IValidationHook<Class>>;
+  }
+
+  /**
+   * Type-safe mapping of method names to custom validators.
+   *
+   * Maps each method name to a validation function that receives the raw input
+   * and returns a validation result. The type inference ensures validators
+   * match the expected argument types.
+   *
+   * @template Class - The source class type for type inference
+   */
+  export type IValidationHook<Class extends object> = {
+    [K in keyof Class]?: Class[K] extends (args: infer Argument) => unknown
+      ? (input: unknown) => IValidation<Argument>
+      : never;
+  };
+
+  /**
+   * Internal type for typia transformer.
+   *
+   * @ignore
+   */
+  export interface __IPrimitive<Class extends object = any> extends Omit<
+    ILlmApplication<Class>,
+    "config" | "functions"
+  > {
+    functions: Omit<ILlmFunction, "parse" | "coerce">[];
+  }
+}