@typia/interface 12.0.0-dev.20260225

package/lib/schema/ILlmSchema.d.ts

@@ -0,0 +1,412 @@
+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 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.
+     */
+    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.
+     */
+    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.
+     */
+    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.
+     */
+    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.
+     */
+    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.
+     */
+    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.
+     */
+    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.
+     */
+    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`.
+     */
+    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.
+     */
+    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;
+    }
+    namespace IAnyOf {
+        /**
+         * Discriminator configuration for tagged unions.
+         *
+         * Specifies which property distinguishes between union variants and maps
+         * discriminator values to their corresponding schemas.
+         */
+        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.
+     */
+    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.
+     */
+    interface IUnknown extends IJsonSchemaAttribute.IUnknown {
+    }
+}

package/lib/schema/ILlmSchema.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=ILlmSchema.js.map

package/lib/schema/ILlmSchema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ILlmSchema.js","sourceRoot":"","sources":["../../src/schema/ILlmSchema.ts"],"names":[],"mappings":""}

package/lib/schema/IResult.d.ts

@@ -0,0 +1,81 @@
+/**
+ * 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 declare 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
+     */
+    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
+     */
+    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/lib/schema/IResult.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=IResult.js.map

package/lib/schema/IResult.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IResult.js","sourceRoot":"","sources":["../../src/schema/IResult.ts"],"names":[],"mappings":""}

package/lib/schema/IValidation.d.ts

@@ -0,0 +1,123 @@
+/**
+ * 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 declare 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
+     */
+    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.
+     */
+    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.
+     */
+    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/lib/schema/IValidation.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=IValidation.js.map

package/lib/schema/IValidation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IValidation.js","sourceRoot":"","sources":["../../src/schema/IValidation.ts"],"names":[],"mappings":""}

package/lib/schema/index.d.ts

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

package/lib/schema/index.js

@@ -0,0 +1,28 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./IResult"), exports);
+__exportStar(require("./IValidation"), exports);
+__exportStar(require("./IJsonSchemaTransformError"), exports);
+__exportStar(require("./IJsonSchemaApplication"), exports);
+__exportStar(require("./IJsonSchemaCollection"), exports);
+__exportStar(require("./IJsonSchemaUnit"), exports);
+__exportStar(require("./IJsonSchemaAttribute"), exports);
+__exportStar(require("./ILlmController"), exports);
+__exportStar(require("./ILlmApplication"), exports);
+__exportStar(require("./ILlmFunction"), exports);
+__exportStar(require("./ILlmSchema"), exports);
+//# sourceMappingURL=index.js.map

package/lib/schema/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/schema/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,4CAA0B;AAC1B,gDAA8B;AAE9B,8DAA4C;AAC5C,2DAAyC;AACzC,0DAAwC;AACxC,oDAAkC;AAClC,yDAAuC;AAEvC,mDAAiC;AACjC,oDAAkC;AAClC,iDAA+B;AAC/B,+CAA6B"}