@typia/interface 12.0.0-dev.20260225

package/src/schema/ILlmSchema.ts

@@ -0,0 +1,484 @@
+import { tags } from "../index";
+import { IJsonSchemaAttribute } from "./IJsonSchemaAttribute";
+
+/**
+ * Type schema for LLM function calling.
+ *
+ * `ILlmSchema` is a JSON Schema subset designed for LLM function calling
+ * compatibility. Most LLMs (OpenAI GPT, Anthropic Claude, Google Gemini, etc.)
+ * do not fully support JSON Schema, so this simplified schema omits unsupported
+ * features like tuples, `const`, and mixed union types.
+ *
+ * Generated by `typia.llm.schema<T>()` for single types or included in
+ * {@link ILlmApplication} via `typia.llm.application<Class>()`. Shared type
+ * definitions use `$defs` with `$ref` references to reduce duplication and
+ * handle recursive structures.
+ *
+ * Set {@link ILlmSchema.IConfig.strict} to `true` for OpenAI's structured output
+ * mode, which requires all properties to be `required` and
+ * `additionalProperties: false`.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export type ILlmSchema =
+  | ILlmSchema.IBoolean
+  | ILlmSchema.IInteger
+  | ILlmSchema.INumber
+  | ILlmSchema.IString
+  | ILlmSchema.IArray
+  | ILlmSchema.IObject
+  | ILlmSchema.IReference
+  | ILlmSchema.IAnyOf
+  | ILlmSchema.INull
+  | ILlmSchema.IUnknown;
+export 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.
+   */
+  export 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).
+     *
+     * When `true`, all properties become required and `additionalProperties` is
+     * forced to `false`.
+     *
+     * @default false
+     */
+    strict: boolean;
+  }
+
+  /**
+   * Function parameters schema with shared type definitions.
+   *
+   * Extends the object schema to include a `$defs` map for named type
+   * definitions that can be referenced via `$ref`. This structure allows
+   * recursive types and reduces schema duplication.
+   *
+   * The `additionalProperties` is always `false` for parameters to ensure
+   * strict argument validation and prevent unexpected properties.
+   */
+  export interface IParameters extends Omit<IObject, "additionalProperties"> {
+    /**
+     * Named schema definitions for reference.
+     *
+     * Contains type definitions that can be referenced throughout the schema
+     * using `$ref: "#/$defs/TypeName"`. Essential for recursive types and
+     * shared structures.
+     */
+    $defs: Record<string, ILlmSchema>;
+
+    /**
+     * Whether additional properties are allowed.
+     *
+     * Always `false` for function parameters to ensure strict type checking.
+     * This prevents LLMs from hallucinating extra properties.
+     */
+    additionalProperties: false;
+  }
+
+  /**
+   * Boolean type schema.
+   *
+   * Represents a JSON Schema boolean type with optional enum constraints and
+   * default value. Used for true/false parameters and flags.
+   */
+  export interface IBoolean extends IJsonSchemaAttribute.IBoolean {
+    /**
+     * Allowed boolean values.
+     *
+     * Restricts the value to specific boolean literals. Typically unused since
+     * booleans only have two possible values, but supported for consistency
+     * with other types.
+     */
+    enum?: Array<boolean>;
+
+    /**
+     * Default value when not provided.
+     *
+     * The boolean value to use when the LLM omits this parameter.
+     */
+    default?: boolean;
+  }
+
+  /**
+   * Integer type schema.
+   *
+   * Represents a JSON Schema integer type with numeric constraints. Maps to
+   * TypeScript `number` with integer validation. Supports range constraints,
+   * enum restrictions, and divisibility checks.
+   */
+  export interface IInteger extends IJsonSchemaAttribute.IInteger {
+    /**
+     * Allowed integer values.
+     *
+     * Restricts the value to specific integer literals. Useful for representing
+     * enum-like integer codes or limited value sets.
+     */
+    enum?: Array<number & tags.Type<"int64">>;
+
+    /**
+     * Default value when not provided.
+     *
+     * The integer value to use when the LLM omits this parameter.
+     */
+    default?: number & tags.Type<"int64">;
+
+    /**
+     * Minimum value (inclusive).
+     *
+     * The value must be greater than or equal to this number.
+     */
+    minimum?: number & tags.Type<"int64">;
+
+    /**
+     * Maximum value (inclusive).
+     *
+     * The value must be less than or equal to this number.
+     */
+    maximum?: number & tags.Type<"int64">;
+
+    /**
+     * Exclusive minimum value.
+     *
+     * The value must be strictly greater than this number.
+     */
+    exclusiveMinimum?: number & tags.Type<"int64">;
+
+    /**
+     * Exclusive maximum value.
+     *
+     * The value must be strictly less than this number.
+     */
+    exclusiveMaximum?: number & tags.Type<"int64">;
+
+    /**
+     * Value must be divisible by this number.
+     *
+     * Used for constraints like "must be even" (multipleOf: 2) or "must be a
+     * multiple of 100" (multipleOf: 100).
+     */
+    multipleOf?: number & tags.Type<"uint64"> & tags.ExclusiveMinimum<0>;
+  }
+
+  /**
+   * Number (floating-point) type schema.
+   *
+   * Represents a JSON Schema number type for floating-point values. Maps to
+   * TypeScript `number` type. Supports range constraints, enum restrictions,
+   * and precision checks via multipleOf.
+   */
+  export interface INumber extends IJsonSchemaAttribute.INumber {
+    /**
+     * Allowed numeric values.
+     *
+     * Restricts the value to specific number literals. Useful for representing
+     * specific valid values like percentages or rates.
+     */
+    enum?: Array<number>;
+
+    /**
+     * Default value when not provided.
+     *
+     * The number to use when the LLM omits this parameter.
+     */
+    default?: number;
+
+    /**
+     * Minimum value (inclusive).
+     *
+     * The value must be greater than or equal to this number.
+     */
+    minimum?: number;
+
+    /**
+     * Maximum value (inclusive).
+     *
+     * The value must be less than or equal to this number.
+     */
+    maximum?: number;
+
+    /**
+     * Exclusive minimum value.
+     *
+     * The value must be strictly greater than this number.
+     */
+    exclusiveMinimum?: number;
+
+    /**
+     * Exclusive maximum value.
+     *
+     * The value must be strictly less than this number.
+     */
+    exclusiveMaximum?: number;
+
+    /**
+     * Value must be divisible by this number.
+     *
+     * Useful for decimal precision constraints like "two decimal places"
+     * (multipleOf: 0.01) or currency amounts (multipleOf: 0.01).
+     */
+    multipleOf?: number & tags.ExclusiveMinimum<0>;
+  }
+
+  /**
+   * String type schema.
+   *
+   * Represents a JSON Schema string type with format validation, pattern
+   * matching, and length constraints. Maps to TypeScript `string` type with
+   * optional semantic format annotations.
+   */
+  export interface IString extends IJsonSchemaAttribute.IString {
+    /**
+     * Allowed string values.
+     *
+     * Restricts the value to specific string literals. Maps directly to
+     * TypeScript string literal union types.
+     */
+    enum?: Array<string>;
+
+    /**
+     * Default value when not provided.
+     *
+     * The string to use when the LLM omits this parameter.
+     */
+    default?: string;
+
+    /**
+     * Semantic format specifier.
+     *
+     * Indicates the string represents a specific format like email, UUID, or
+     * date-time. LLMs may use this to generate appropriate values. Common
+     * formats include "email", "uri", "uuid", "date-time".
+     */
+    format?:
+      | "binary"
+      | "byte"
+      | "password"
+      | "regex"
+      | "uuid"
+      | "email"
+      | "hostname"
+      | "idn-email"
+      | "idn-hostname"
+      | "iri"
+      | "iri-reference"
+      | "ipv4"
+      | "ipv6"
+      | "uri"
+      | "uri-reference"
+      | "uri-template"
+      | "url"
+      | "date-time"
+      | "date"
+      | "time"
+      | "duration"
+      | "json-pointer"
+      | "relative-json-pointer"
+      | (string & {});
+
+    /**
+     * Regular expression pattern for validation.
+     *
+     * The string must match this regex pattern. Note that LLMs may struggle
+     * with complex regex patterns; simple patterns work best.
+     */
+    pattern?: string;
+
+    /**
+     * MIME type of the string content.
+     *
+     * Indicates the content type when the string contains encoded binary data,
+     * such as "application/json" or "image/png".
+     */
+    contentMediaType?: string;
+
+    /**
+     * Minimum string length.
+     *
+     * The string must have at least this many characters.
+     */
+    minLength?: number & tags.Type<"uint64">;
+
+    /**
+     * Maximum string length.
+     *
+     * The string must have at most this many characters.
+     */
+    maxLength?: number & tags.Type<"uint64">;
+  }
+
+  /**
+   * Array type schema.
+   *
+   * Represents a JSON Schema array type with item type validation and size
+   * constraints. Maps to TypeScript `T[]` or `Array<T>` types. Note: Tuple
+   * types are not supported by LLM schemas.
+   */
+  export interface IArray extends IJsonSchemaAttribute.IArray {
+    /**
+     * Schema for array elements.
+     *
+     * All elements in the array must conform to this schema. For heterogeneous
+     * arrays, use an `anyOf` schema.
+     */
+    items: ILlmSchema;
+
+    /**
+     * Whether elements must be unique.
+     *
+     * When `true`, no two elements may be equal. Maps to TypeScript `Set<T>`
+     * semantics but represented as an array.
+     */
+    uniqueItems?: boolean;
+
+    /**
+     * Minimum number of elements.
+     *
+     * The array must contain at least this many items.
+     */
+    minItems?: number & tags.Type<"uint64">;
+
+    /**
+     * Maximum number of elements.
+     *
+     * The array must contain at most this many items.
+     */
+    maxItems?: number & tags.Type<"uint64">;
+  }
+
+  /**
+   * Object type schema.
+   *
+   * Represents a JSON Schema object type with named properties. Maps to
+   * TypeScript interface or object type. Supports required property
+   * declarations and dynamic additional properties.
+   */
+  export interface IObject extends IJsonSchemaAttribute.IObject {
+    /**
+     * Property name to schema mapping.
+     *
+     * Defines the type of each named property on the object. All properties are
+     * defined here regardless of whether they are required or optional.
+     */
+    properties: Record<string, ILlmSchema>;
+
+    /**
+     * Schema for dynamic/additional properties.
+     *
+     * - `false` (default): No additional properties allowed
+     * - `true`: Any additional properties allowed
+     * - Schema: Additional properties must match this schema
+     *
+     * Note: ChatGPT and Gemini do not support `additionalProperties`. Use
+     * {@link ILlmSchema.IConfig.strict} mode for OpenAI compatibility.
+     */
+    additionalProperties?: ILlmSchema | boolean;
+
+    /**
+     * List of required property names.
+     *
+     * Properties in this array must be present in the object. In strict mode,
+     * all properties become required automatically.
+     */
+    required: string[];
+  }
+
+  /**
+   * Reference to a named schema definition.
+   *
+   * Points to a schema defined in the `$defs` map using a JSON pointer. Used to
+   * avoid schema duplication and enable recursive type definitions. The
+   * reference path format is `#/$defs/TypeName`.
+   */
+  export interface IReference extends IJsonSchemaAttribute {
+    /**
+     * JSON pointer to the referenced schema.
+     *
+     * Must be in the format `#/$defs/TypeName` where TypeName is a key in the
+     * parent schema's `$defs` map.
+     */
+    $ref: string;
+  }
+
+  /**
+   * Union type schema (A | B | C).
+   *
+   * Represents a TypeScript union type where the value can match any one of the
+   * member schemas. Note: Gemini does not support `anyOf`/`oneOf` schemas. Use
+   * discriminated unions with `x-discriminator` when possible for better LLM
+   * comprehension.
+   */
+  export interface IAnyOf extends IJsonSchemaAttribute {
+    /**
+     * Array of possible schemas.
+     *
+     * The value must match at least one of these schemas. Nested `anyOf`
+     * schemas are flattened to avoid deep nesting.
+     */
+    anyOf: Exclude<ILlmSchema, ILlmSchema.IAnyOf>[];
+
+    /**
+     * Discriminator for tagged/discriminated unions.
+     *
+     * Helps LLMs understand which variant to select based on a discriminating
+     * property value. Improves type inference accuracy.
+     */
+    "x-discriminator"?: IAnyOf.IDiscriminator;
+  }
+  export namespace IAnyOf {
+    /**
+     * Discriminator configuration for tagged unions.
+     *
+     * Specifies which property distinguishes between union variants and maps
+     * discriminator values to their corresponding schemas.
+     */
+    export interface IDiscriminator {
+      /**
+       * Name of the discriminating property.
+       *
+       * This property must exist on all union member object schemas and contain
+       * unique literal values that identify each variant.
+       */
+      propertyName: string;
+
+      /**
+       * Mapping from discriminator values to schema references.
+       *
+       * Keys are the literal values of the discriminator property, values are
+       * `$ref` paths to the corresponding schemas.
+       */
+      mapping?: Record<string, string>;
+    }
+  }
+
+  /**
+   * Null type schema.
+   *
+   * Represents the JSON null value. In TypeScript union types like `T | null`,
+   * this schema appears in an `anyOf` alongside the T schema.
+   */
+  export interface INull extends IJsonSchemaAttribute.INull {}
+
+  /**
+   * Unknown/any type schema.
+   *
+   * Represents TypeScript `any` or `unknown` types where no specific type
+   * constraint is defined. Use sparingly as LLMs may generate unexpected values
+   * for unconstrained types.
+   */
+  export interface IUnknown extends IJsonSchemaAttribute.IUnknown {}
+}

package/src/schema/IResult.ts

@@ -0,0 +1,84 @@
+/**
+ * Result type for operations that can either succeed or fail.
+ *
+ * `IResult` is a discriminated union representing the outcome of an operation
+ * that may fail. This pattern (often called "Result" or "Either" monad) enables
+ * explicit error handling without exceptions.
+ *
+ * Check the {@link IResult.success | success} discriminator to determine the
+ * outcome:
+ *
+ * - `true` → {@link IResult.ISuccess} with the result in
+ *   {@link IResult.ISuccess.value | value}
+ * - `false` → {@link IResult.IFailure} with the error in
+ *   {@link IResult.IFailure.error | error}
+ *
+ * This pattern is used throughout typia for safe operations like parsing and
+ * transformation where errors are expected possibilities.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @example
+ *   const result: IResult<User, ParseError> = parseUser(json);
+ *   if (result.success) {
+ *     console.log(result.value.name);
+ *   } else {
+ *     console.error(result.error.message);
+ *   }
+ *
+ * @template T Type of the success value
+ * @template E Type of the error value
+ */
+export type IResult<T, E> = IResult.ISuccess<T> | IResult.IFailure<E>;
+export namespace IResult {
+  /**
+   * Successful result variant.
+   *
+   * Indicates the operation completed successfully and contains the result
+   * value. Access via {@link value} after checking {@link success} is `true`.
+   *
+   * @template T Type of the success value
+   */
+  export interface ISuccess<T> {
+    /**
+     * Success discriminator.
+     *
+     * Always `true` for successful results. Use this to narrow the type before
+     * accessing {@link value}.
+     */
+    success: true;
+
+    /**
+     * The successful result value.
+     *
+     * Contains the operation's output. Only accessible when {@link success} is
+     * `true`.
+     */
+    value: T;
+  }
+
+  /**
+   * Failed result variant.
+   *
+   * Indicates the operation failed and contains error information. Access via
+   * {@link error} after checking {@link success} is `false`.
+   *
+   * @template E Type of the error value
+   */
+  export interface IFailure<E> {
+    /**
+     * Success discriminator.
+     *
+     * Always `false` for failed results. Use this to narrow the type before
+     * accessing {@link error}.
+     */
+    success: false;
+
+    /**
+     * The error information.
+     *
+     * Contains details about why the operation failed. Only accessible when
+     * {@link success} is `false`.
+     */
+    error: E;
+  }
+}

package/src/schema/IValidation.ts

@@ -0,0 +1,134 @@
+/**
+ * Validation result type with detailed error information.
+ *
+ * `IValidation<T>` is the return type of `typia.validate<T>()` and related
+ * validation functions. Unlike `typia.is<T>()` which returns a boolean, or
+ * `typia.assert<T>()` which throws exceptions, `typia.validate<T>()` returns
+ * this structured result with full error details.
+ *
+ * Check the {@link IValidation.success | success} discriminator:
+ *
+ * - `true` → {@link IValidation.ISuccess} with validated
+ *   {@link IValidation.ISuccess.data | data}
+ * - `false` → {@link IValidation.IFailure} with
+ *   {@link IValidation.IFailure.errors | errors} array
+ *
+ * This is the recommended validation function when you need to report
+ * validation errors to users or log them for debugging.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @example
+ *   const result = typia.validate<User>(input);
+ *   if (result.success) {
+ *     return result.data; // User type
+ *   } else {
+ *     result.errors.forEach((e) => console.log(e.path, e.expected));
+ *   }
+ *
+ * @template T The expected type after successful validation
+ */
+export type IValidation<T = unknown> =
+  | IValidation.ISuccess<T>
+  | IValidation.IFailure;
+
+export namespace IValidation {
+  /**
+   * Successful validation result.
+   *
+   * Indicates the input matches the expected type. The validated data is
+   * available in {@link data} with full type information.
+   *
+   * @template T The validated type
+   */
+  export interface ISuccess<T = unknown> {
+    /**
+     * Success discriminator.
+     *
+     * Always `true` for successful validations. Use this to narrow the type
+     * before accessing {@link data}.
+     */
+    success: true;
+
+    /**
+     * The validated data with correct type.
+     *
+     * The original input after successful validation. TypeScript will narrow
+     * this to type `T` when {@link success} is `true`.
+     */
+    data: T;
+  }
+
+  /**
+   * Failed validation result with error details.
+   *
+   * Indicates the input did not match the expected type. Contains the original
+   * data and an array of all validation errors found.
+   */
+  export interface IFailure {
+    /**
+     * Success discriminator.
+     *
+     * Always `false` for failed validations. Use this to narrow the type before
+     * accessing {@link errors}.
+     */
+    success: false;
+
+    /**
+     * The original input that failed validation.
+     *
+     * Preserved as `unknown` type since it didn't match the expected type.
+     * Useful for debugging or logging the actual value.
+     */
+    data: unknown;
+
+    /**
+     * Array of validation errors.
+     *
+     * Contains one entry for each validation failure found. Multiple errors may
+     * exist if the input has multiple type mismatches.
+     */
+    errors: IError[];
+  }
+
+  /**
+   * Detailed information about a single validation error.
+   *
+   * Describes exactly what went wrong during validation, including the
+   * location, expected type, and actual value.
+   */
+  export interface IError {
+    /**
+     * Property path to the error location.
+     *
+     * A dot-notation path from the root input to the failing property. Uses
+     * `$input` as the root. Example: `"$input.user.email"` or
+     * `"$input.items[0].price"`.
+     */
+    path: string;
+
+    /**
+     * Expected type expression.
+     *
+     * A human-readable description of what type was expected at this location.
+     * Examples: `"string"`, `"number & ExclusiveMinimum<0>"`, `"(\"active\" |
+     * \"inactive\")"`.
+     */
+    expected: string;
+
+    /**
+     * The actual value that failed validation.
+     *
+     * The value found at the error path. May be `undefined` if the property was
+     * missing. Useful for debugging type mismatches.
+     */
+    value: unknown;
+
+    /**
+     * Human-readable error description.
+     *
+     * Optional additional context about the validation failure, such as
+     * constraint violations or custom error messages.
+     */
+    description?: string;
+  }
+}

package/src/schema/index.ts

@@ -0,0 +1,13 @@
+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";