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

package/src/schema/IResult.ts

@@ -1,84 +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;
-  }
-}
+/**
+ * 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

@@ -1,134 +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;
-  }
-}
+/**
+ * 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

@@ -1,14 +1,14 @@
-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 "./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 "./IJsonParseResult";

package/src/tags/Constant.ts

@@ -1,49 +1,49 @@
-import { TagBase } from "./TagBase";
-
-/**
- * Documentation metadata for literal/constant values.
- *
- * `Constant<Value, Content>` enhances literal type values with human-readable
- * documentation that appears in generated JSON Schema output. This is useful
- * for enum-like values where each literal needs individual documentation.
- *
- * Unlike TypeScript enums which lose their documentation in schema generation,
- * `Constant` preserves title and description for each value. This helps API
- * consumers understand the meaning of each allowed value.
- *
- * The tag itself doesn't perform validation - it only adds metadata. The
- * literal type constraint is enforced by TypeScript's type system.
- *
- * @author Jeongho Nam - https://github.com/samchon
- * @example
- *   type OrderStatus =
- *     | Constant<
- *         "pending",
- *         { title: "Pending"; description: "Order placed" }
- *       >
- *     | Constant<"shipped", { title: "Shipped"; description: "In transit" }>
- *     | Constant<
- *         "delivered",
- *         { title: "Delivered"; description: "Complete" }
- *       >;
- *
- *   interface Order {
- *     status: OrderStatus;
- *   }
- *
- * @template Value The literal value (boolean, number, string, or bigint)
- * @template Content Object with optional `title` and `description` properties
- */
-export type Constant<
-  Value extends boolean | number | string | bigint,
-  Content extends {
-    title?: string | undefined;
-    description?: string | undefined;
-  },
-> = Value &
-  TagBase<{
-    target: "string" | "boolean" | "number" | "bigint";
-    kind: "constant";
-    value: undefined;
-    schema: Content;
-  }>;
+import { TagBase } from "./TagBase";
+
+/**
+ * Documentation metadata for literal/constant values.
+ *
+ * `Constant<Value, Content>` enhances literal type values with human-readable
+ * documentation that appears in generated JSON Schema output. This is useful
+ * for enum-like values where each literal needs individual documentation.
+ *
+ * Unlike TypeScript enums which lose their documentation in schema generation,
+ * `Constant` preserves title and description for each value. This helps API
+ * consumers understand the meaning of each allowed value.
+ *
+ * The tag itself doesn't perform validation - it only adds metadata. The
+ * literal type constraint is enforced by TypeScript's type system.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @example
+ *   type OrderStatus =
+ *     | Constant<
+ *         "pending",
+ *         { title: "Pending"; description: "Order placed" }
+ *       >
+ *     | Constant<"shipped", { title: "Shipped"; description: "In transit" }>
+ *     | Constant<
+ *         "delivered",
+ *         { title: "Delivered"; description: "Complete" }
+ *       >;
+ *
+ *   interface Order {
+ *     status: OrderStatus;
+ *   }
+ *
+ * @template Value The literal value (boolean, number, string, or bigint)
+ * @template Content Object with optional `title` and `description` properties
+ */
+export type Constant<
+  Value extends boolean | number | string | bigint,
+  Content extends {
+    title?: string | undefined;
+    description?: string | undefined;
+  },
+> = Value &
+  TagBase<{
+    target: "string" | "boolean" | "number" | "bigint";
+    kind: "constant";
+    value: undefined;
+    schema: Content;
+  }>;

package/src/tags/ContentMediaType.ts

@@ -1,40 +1,40 @@
-import { TagBase } from "./TagBase";
-
-/**
- * MIME type metadata for string content.
- *
- * `ContentMediaType<Type>` is a type tag that documents the media type of
- * string content. This is metadata-only - no runtime validation is performed.
- * The information appears in generated JSON Schema output.
- *
- * This is useful when a string property contains encoded binary data or
- * structured content that should be interpreted according to a specific media
- * type, such as base64-encoded images or embedded JSON.
- *
- * Common MIME types:
- *
- * - `"application/json"`: JSON data as string
- * - `"application/xml"`: XML data as string
- * - `"image/png"`: Base64-encoded PNG image
- * - `"image/jpeg"`: Base64-encoded JPEG image
- * - `"application/octet-stream"`: Generic binary data
- *
- * @author Jeongho Nam - https://github.com/samchon
- * @example
- *   interface Document {
- *     // Base64-encoded PNG image
- *     thumbnail: string & ContentMediaType<"image/png">;
- *     // JSON stored as string
- *     metadata: string & ContentMediaType<"application/json">;
- *   }
- *
- * @template Value MIME type string literal
- */
-export type ContentMediaType<Value extends string> = TagBase<{
-  target: "string";
-  kind: "contentMediaType";
-  value: undefined;
-  schema: {
-    contentMediaType: Value;
-  };
-}>;
+import { TagBase } from "./TagBase";
+
+/**
+ * MIME type metadata for string content.
+ *
+ * `ContentMediaType<Type>` is a type tag that documents the media type of
+ * string content. This is metadata-only - no runtime validation is performed.
+ * The information appears in generated JSON Schema output.
+ *
+ * This is useful when a string property contains encoded binary data or
+ * structured content that should be interpreted according to a specific media
+ * type, such as base64-encoded images or embedded JSON.
+ *
+ * Common MIME types:
+ *
+ * - `"application/json"`: JSON data as string
+ * - `"application/xml"`: XML data as string
+ * - `"image/png"`: Base64-encoded PNG image
+ * - `"image/jpeg"`: Base64-encoded JPEG image
+ * - `"application/octet-stream"`: Generic binary data
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @example
+ *   interface Document {
+ *     // Base64-encoded PNG image
+ *     thumbnail: string & ContentMediaType<"image/png">;
+ *     // JSON stored as string
+ *     metadata: string & ContentMediaType<"application/json">;
+ *   }
+ *
+ * @template Value MIME type string literal
+ */
+export type ContentMediaType<Value extends string> = TagBase<{
+  target: "string";
+  kind: "contentMediaType";
+  value: undefined;
+  schema: {
+    contentMediaType: Value;
+  };
+}>;