typia 9.7.0 → 9.7.2

package/src/IRandomGenerator.ts

@@ -3,28 +3,28 @@ import { OpenApi } from "@samchon/openapi";
 /**
  * Interface for generating random values for various data types.
  *
- * `IRandomGenerator` defines the contract for generating random values
- * that can be used by typia for creating mock data, testing scenarios,
- * and random value generation based on JSON schema constraints.
+ * `IRandomGenerator` defines the contract for generating random values that can
+ * be used by typia for creating mock data, testing scenarios, and random value
+ * generation based on JSON schema constraints.
  *
  * This interface supports generating random values for:
+ *
  * - Basic types (boolean, number, integer, bigint, string, array)
  * - String format patterns (email, URL, UUID, etc.)
  * - Date and time formats
  * - Various address and identifier formats
  *
- * @example
- * ```typescript
- * const generator: IRandomGenerator = {
- *   boolean: () => Math.random() > 0.5,
- *   number: (schema) => Math.random() * (schema.maximum ?? 100),
- *   string: (schema) => "example-string",
- *   email: () => "test@example.com",
- *   // ... implement other methods
- * };
- * ```
- *
  * @author Jeongho Nam - https://github.com/samchon
+ * @example
+ *   ```typescript
+ *   const generator: IRandomGenerator = {
+ *     boolean: () => Math.random() > 0.5,
+ *     number: (schema) => Math.random() * (schema.maximum ?? 100),
+ *     string: (schema) => "example-string",
+ *     email: () => "test@example.com",
+ *     // ... implement other methods
+ *   };
+ *   ```;
  */
 export interface IRandomGenerator {
   // REGULAR DATA TYPES
@@ -63,13 +63,15 @@ export interface IRandomGenerator {
   /**
    * Generates a random string based on JSON schema constraints.
    *
-   * @param schema JSON schema with string constraints (minLength, maxLength, pattern, etc.)
+   * @param schema JSON schema with string constraints (minLength, maxLength,
+   *   pattern, etc.)
    * @returns Random string matching the specified constraints
    */
   string(schema: OpenApi.IJsonSchema.IString): string;
 
   /**
-   * Generates a random array with elements created by the provided generator function.
+   * Generates a random array with elements created by the provided generator
+   * function.
    *
    * @param schema Array schema with element generator function
    * @returns Random array with generated elements
@@ -261,52 +263,60 @@ export namespace IRandomGenerator {
   /**
    * Map of custom generators for different data types.
    *
-   * This interface allows customization of random generation for specific
-   * types when they have certain schema properties or constraints.
+   * This interface allows customization of random generation for specific types
+   * when they have certain schema properties or constraints.
    *
    * @example
-   * ```typescript
-   * const generator: Partial<IRandomGenerator> = {
-   *   string: (schema) => {
-   *     if ((schema as any)["x-typia-monetary"] === "dollar") {
-   *       return "$" + Math.floor(Math.random() * 1000);
-   *     }
-   *     return "default-string";
-   *   },
-   *   number: (schema) => {
-   *     if ((schema as any)["x-typia-powerOf"] !== undefined) {
-   *       const powerOf = (schema as any)["x-typia-powerOf"];
-   *       return Math.pow(powerOf, Math.random() * 10 + 1);
+   *   ```typescript
+   *   const generator: Partial<IRandomGenerator> = {
+   *     string: (schema) => {
+   *       if ((schema as any)["x-typia-monetary"] === "dollar") {
+   *         return "$" + Math.floor(Math.random() * 1000);
+   *       }
+   *       return "default-string";
+   *     },
+   *     number: (schema) => {
+   *       if ((schema as any)["x-typia-powerOf"] !== undefined) {
+   *         const powerOf = (schema as any)["x-typia-powerOf"];
+   *         return Math.pow(powerOf, Math.random() * 10 + 1);
+   *       }
+   *       return Math.random() * 100;
    *     }
-   *     return Math.random() * 100;
-   *   }
-   * };
-   * ```
+   *   };
+   *   ```;
    */
   export interface CustomMap {
     /**
-     * Custom string generator that can handle special string formats
-     * based on schema properties.
+     * Custom string generator that can handle special string formats based on
+     * schema properties.
      */
-    string?: (schema: OpenApi.IJsonSchema.IString & Record<string, any>) => string;
+    string?: (
+      schema: OpenApi.IJsonSchema.IString & Record<string, any>,
+    ) => string;
 
     /**
-     * Custom number generator that can handle special number constraints
-     * based on schema properties.
+     * Custom number generator that can handle special number constraints based
+     * on schema properties.
      */
-    number?: (schema: OpenApi.IJsonSchema.INumber & Record<string, any>) => number;
+    number?: (
+      schema: OpenApi.IJsonSchema.INumber & Record<string, any>,
+    ) => number;
 
     /**
      * Custom integer generator that can handle special integer constraints
      * based on schema properties.
      */
-    integer?: (schema: OpenApi.IJsonSchema.IInteger & Record<string, any>) => number;
+    integer?: (
+      schema: OpenApi.IJsonSchema.IInteger & Record<string, any>,
+    ) => number;
 
     /**
-     * Custom bigint generator that can handle special bigint constraints
-     * based on schema properties.
+     * Custom bigint generator that can handle special bigint constraints based
+     * on schema properties.
      */
-    bigint?: (schema: OpenApi.IJsonSchema.IInteger & Record<string, any>) => bigint;
+    bigint?: (
+      schema: OpenApi.IJsonSchema.IInteger & Record<string, any>,
+    ) => bigint;
 
     /**
      * Custom boolean generator that can handle special boolean constraints
@@ -315,13 +325,13 @@ export namespace IRandomGenerator {
     boolean?: (schema: Record<string, any>) => boolean | undefined;
 
     /**
-     * Custom array generator that can handle special array constraints
-     * based on schema properties.
+     * Custom array generator that can handle special array constraints based on
+     * schema properties.
      */
     array?: <T>(
       schema: Omit<OpenApi.IJsonSchema.IArray, "items"> & {
         element: (index: number, count: number) => T;
-      } & Record<string, any>
+      } & Record<string, any>,
     ) => T[];
   }
 }

package/src/IReadableURLSearchParams.ts

@@ -1,8 +1,8 @@
 /**
  * Interface for a readable URLSearchParams object.
  *
- * This interface is a subset of the {@link URLSearchParams} interface,
- * designed especially for the [Hono.JS](https://hono.dev/) library.
+ * This interface is a subset of the {@link URLSearchParams} interface, designed
+ * especially for the [Hono.JS](https://hono.dev/) library.
  *
  * @author https://github.com/miyaji255
  */

package/src/PascalCase.ts

@@ -10,8 +10,8 @@ import { ValueOf } from "./typings/ValueOf";
  *
  * It also erases every method property like {@link Resolved} type.
  *
- * @template T Target type to be pascalized
  * @author Jeongho Nam - https://github.com/samchon
+ * @template T Target type to be pascalized
  */
 export type PascalCase<T> =
   Equal<T, PascalizeMain<T>> extends true ? T : PascalizeMain<T>;

package/src/Primitive.ts

@@ -8,36 +8,34 @@ import { Format } from "./tags";
 /**
  * Primitive type of JSON.
  *
- * `Primitive<T>` is a TMP (Type Meta Programming) type which converts
- * its argument as a primitive type within the framework JSON.
+ * `Primitive<T>` is a TMP (Type Meta Programming) type which converts its
+ * argument as a primitive type within the framework JSON.
  *
- * If the target argument is a built-in class which returns its origin primitive type
- * through the `valueOf()` method like the `String` or `Number`, its return type will
- * be the `string` or `number`. Otherwise, if the built-in class does not have the
- * `valueOf()` method, the return type will be an empty object (`{}`).
+ * If the target argument is a built-in class which returns its origin primitive
+ * type through the `valueOf()` method like the `String` or `Number`, its return
+ * type will be the `string` or `number`. Otherwise, if the built-in class does
+ * not have the `valueOf()` method, the return type will be an empty object
+ * (`{}`).
  *
- * Otherwise, if the target argument is a type of custom class, all of its custom methods
- * will be erased and its prototype will be changed to the primitive `object`.
- * Therefore, the return type of the TMP type will finally be the primitive object.
+ * Otherwise, if the target argument is a type of custom class, all of its
+ * custom methods will be erased and its prototype will be changed to the
+ * primitive `object`. Therefore, the return type of the TMP type will finally
+ * be the primitive object.
  *
- * In addition, if the target argument is a type of custom class and it has a special
- * method `toJSON()`, the return type of this `Primitive` will be not `Primitive<Instance>`
- * but `Primitive<ReturnType<Instance.toJSON>>`.
+ * In addition, if the target argument is a type of custom class and it has a
+ * special method `toJSON()`, the return type of this `Primitive` will be not
+ * `Primitive<Instance>` but `Primitive<ReturnType<Instance.toJSON>>`.
  *
- * Before                  | After
- * ------------------------|----------------------------------------
- * `Boolean`               | `boolean`
- * `Number`                | `number`
- * `String`                | `string`
- * `Class`                 | `object`
- * `Class` with `toJSON()` | `Primitive<ReturnType<Class.toJSON>>`
- * Native Class            | never
- * Others                  | No change
+ * Before | After
+ * ------------------------|---------------------------------------- `Boolean` |
+ * `boolean` `Number` | `number` `String` | `string` `Class` | `object` `Class`
+ * with `toJSON()` | `Primitive<ReturnType<Class.toJSON>>` Native Class | never
+ * Others | No change
  *
- * @template T Target argument type.
  * @author Jeongho Nam - https://github.com/samchon
  * @author Kyungsu Kang - https://github.com/kakasoo
  * @author Michael - https://github.com/8471919
+ * @template T Target argument type.
  */
 export type Primitive<T> =
   Equal<T, PrimitiveMain<T>> extends true ? T : PrimitiveMain<T>;

package/src/Resolved.ts

@@ -6,30 +6,28 @@ import { ValueOf } from "./typings/ValueOf";
 /**
  * Resolved type that erases every method.
  *
- * `Resolved` is a TMP (Type Meta Programming) type which converts
- * its argument as a resolved type that erases every method property.
+ * `Resolved` is a TMP (Type Meta Programming) type which converts its argument
+ * as a resolved type that erases every method property.
  *
- * If the target argument is a built-in class which returns its origin primitive type
- * through the `valueOf()` method like the `String` or `Number`, its return type will
- * be the `string` or `number`. Otherwise, if the built-in class does not have the
- * `valueOf()` method, the return type will be the same as the target argument.
+ * If the target argument is a built-in class which returns its origin primitive
+ * type through the `valueOf()` method like the `String` or `Number`, its return
+ * type will be the `string` or `number`. Otherwise, if the built-in class does
+ * not have the `valueOf()` method, the return type will be the same as the
+ * target argument.
  *
- * Otherwise, if the target argument is a type of custom class, all of its custom methods
- * will be erased and its prototype will be changed to the primitive `object`.
- * Therefore, the return type of the TMP type will finally be the resolved object.
+ * Otherwise, if the target argument is a type of custom class, all of its
+ * custom methods will be erased and its prototype will be changed to the
+ * primitive `object`. Therefore, the return type of the TMP type will finally
+ * be the resolved object.
  *
- * Before                  | After
- * ------------------------|----------------------------------------
- * `Boolean`               | `boolean`
- * `Number`                | `number`
- * `BigInt`                | `bigint`
- * `String`                | `string`
- * `Class`                 | `interface`
- * Native Class or Others  | No change
+ * Before | After
+ * ------------------------|---------------------------------------- `Boolean` |
+ * `boolean` `Number` | `number` `BigInt` | `bigint` `String` | `string` `Class`
+ * | `interface` Native Class or Others | No change
  *
- * @template T Target argument type.
  * @author Jeongho Nam - https://github.com/samchon
  * @author Kyungsu Kang - https://github.com/kakasoo
+ * @template T Target argument type.
  */
 export type Resolved<T> =
   Equal<T, ResolvedMain<T>> extends true ? T : ResolvedMain<T>;

package/src/SnakeCase.ts

@@ -5,12 +5,13 @@ import { ValueOf } from "./typings/ValueOf";
 /**
  * Snake case type.
  *
- * `SnakeCase` type is a type that all keys of an object are converted to snake case.
+ * `SnakeCase` type is a type that all keys of an object are converted to snake
+ * case.
  *
  * It also erases every method property like {@link Resolved} type.
  *
- * @template T Target type to be snake cased
  * @author Jeongho Nam - https://github.com/samchon
+ * @template T Target type to be snake cased
  */
 export type SnakeCase<T> =
   Equal<T, SnakageMain<T>> extends true ? T : SnakageMain<T>;

package/src/TypeGuardError.ts

@@ -1,52 +1,56 @@
 /**
- * Custom error class thrown when runtime assertion fails in `typia.assert<T>()` function.
+ * Custom error class thrown when runtime assertion fails in `typia.assert<T>()`
+ * function.
  *
  * This error is thrown by the `typia.assert<T>()` function when the input value
  * doesn't match the expected type.
  *
- * The error provides detailed information about the first assertion failure encountered,
- * including the access path where the error occurred, the expected type, and the actual value.
+ * The error provides detailed information about the first assertion failure
+ * encountered, including the access path where the error occurred, the expected
+ * type, and the actual value.
  *
- * @template T - The expected type (generic for type safety)
  * @author Jeongho Nam - https://github.com/samchon
  * @example
- * ```typescript
- * interface IMember {
- *   name: string;
- *   age: number & ExclusiveMinimum<19>;
- * }
+ *   ```typescript
+ *   interface IMember {
+ *     name: string;
+ *     age: number & ExclusiveMinimum<19>;
+ *   }
  *
- * try {
- *   typia.assert<IMember>({ name: "John", age: 18 });
- * } catch (error) {
- *   if (error instanceof TypeGuardError) {
- *     console.log(error.method);   // "typia.assert"
- *     console.log(error.path);     // "input.age"
- *     console.log(error.expected); // "number & ExclusiveMinimum<19>"
- *     console.log(error.value);    // 18
+ *   try {
+ *     typia.assert<IMember>({ name: "John", age: 18 });
+ *   } catch (error) {
+ *     if (error instanceof TypeGuardError) {
+ *       console.log(error.method);   // "typia.assert"
+ *       console.log(error.path);     // "input.age"
+ *       console.log(error.expected); // "number & ExclusiveMinimum<19>"
+ *       console.log(error.value);    // 18
+ *     }
  *   }
- * }
- * ```
+ *   ```;
+ *
+ * @template T - The expected type (generic for type safety)
  */
 export class TypeGuardError<T = any> extends Error {
   /**
    * The name of the typia method that threw this error.
    *
-   * @example "typia.assert"
+   * @example
+   *   typia.assert;
    */
   public readonly method: string;
 
   /**
    * The access path to the property where the assertion error occurred.
    *
-   * Uses dot notation to indicate the path for nested object properties.
-   * May be `undefined` if the error occurred at the root level.
+   * Uses dot notation to indicate the path for nested object properties. May be
+   * `undefined` if the error occurred at the root level.
    *
    * @example
-   * - `"input.age"` - Error in the age property of the object
-   * - `"input.profile.email"` - Error in the email property of a nested object
-   * - `"input[0].name"` - Error in the name property of the first array element
-   * - `undefined` - Error occurred at the root level
+   *   - `"input.age"` - Error in the age property of the object
+   *   - `"input.profile.email"` - Error in the email property of a nested object
+   *   - `"input[0].name"` - Error in the name property of the first array element
+   *   - `undefined` - Error occurred at the root level
    */
   public readonly path: string | undefined;
 
@@ -57,32 +61,43 @@ export class TypeGuardError<T = any> extends Error {
    * for complex types.
    *
    * @example
-   * - `"string"` - Expected string type
-   * - `"number & ExclusiveMinimum<19>"` - Expected number greater than 19
-   * - `"undefined"` - Expected undefined (when superfluous property found in assertion)
-   * - `"{ name: string; age: number }"` - Expected object type
+   *   - `"string"` - Expected string type
+   *   - `"number & ExclusiveMinimum<19>"` - Expected number greater than 19
+   *   - `"undefined"` - Expected undefined (when superfluous property found in assertion)
+   *   - `"{ name: string; age: number }"` - Expected object type
    */
   public readonly expected: string;
 
   /**
    * The actual value that failed assertion.
    *
-   * Stores the actual value at the error path as-is.
-   * Useful for debugging by comparing the expected type with the actual value.
+   * Stores the actual value at the error path as-is. Useful for debugging by
+   * comparing the expected type with the actual value.
    *
    * @example
-   * - `18` - Numeric value
-   * - `"invalid"` - String value
-   * - `{ name: "John", age: 18, sex: 1 }` - Object value
+   *   - `18` - Numeric value
+   *   - `"invalid"` - String value
+   *   - `{ name: "John", age: 18, sex: 1 }` - Object value
    */
   public readonly value: unknown;
 
+  /**
+   * Optional human-readable description of the type guard error
+   *
+   * This field is rarely populated in standard typia type assertion and is
+   * primarily intended for specialized AI agent libraries or custom validation
+   * scenarios that require additional context beyond the technical type
+   * information. Most assertion errors rely solely on the path, expected, and
+   * value fields for comprehensive error reporting.
+   */
+  public readonly description?: string | undefined;
+
   /**
    * Phantom property for type safety purposes.
    *
-   * This property is not actually used and exists only to maintain
-   * the generic type T in TypeScript's type system.
-   * Always has an `undefined` value at runtime.
+   * This property is not actually used and exists only to maintain the generic
+   * type T in TypeScript's type system. Always has an `undefined` value at
+   * runtime.
    *
    * @internal
    */
@@ -91,17 +106,17 @@ export class TypeGuardError<T = any> extends Error {
   /**
    * Creates a new TypeGuardError instance.
    *
-   * @param props - Object containing the properties needed to create the error
-   *
    * @example
-   * ```typescript
-   * const error = new TypeGuardError({
-   *   method: "typia.assert",
-   *   path: "input.age",
-   *   expected: "number & ExclusiveMinimum<19>",
-   *   value: 18
-   * });
-   * ```
+   *   ```typescript
+   *   const error = new TypeGuardError({
+   *     method: "typia.assert",
+   *     path: "input.age",
+   *     expected: "number & ExclusiveMinimum<19>",
+   *     value: 18
+   *   });
+   *   ```;
+   *
+   * @param props - Object containing the properties needed to create the error
    */
   public constructor(props: TypeGuardError.IProps) {
     // MESSAGE CONSTRUCTION
@@ -124,6 +139,14 @@ export class TypeGuardError<T = any> extends Error {
     this.path = props.path;
     this.expected = props.expected;
     this.value = props.value;
+    if (props.description || props.value === undefined)
+      this.description =
+        props.description ??
+        [
+          "The value at this path is `undefined`.",
+          "",
+          `Please fill the \`${props.expected}\` typed value next time.`,
+        ].join("\n");
   }
 }
 
@@ -132,47 +155,61 @@ export namespace TypeGuardError {
    * Interface for properties passed to the TypeGuardError constructor.
    *
    * @example
-   * ```typescript
-   * const props: TypeGuardError.IProps = {
-   *   method: "typia.assertEquals",
-   *   path: "input.sex",
-   *   expected: "undefined",
-   *   value: 1,
-   *   message: "Custom error message" // optional
-   * };
-   * ```
+   *   ```typescript
+   *   const props: TypeGuardError.IProps = {
+   *     method: "typia.assertEquals",
+   *     path: "input.sex",
+   *     expected: "undefined",
+   *     value: 1,
+   *     message: "Custom error message" // optional
+   *   };
+   *   ```;
    */
   export interface IProps {
     /**
      * The name of the typia method that threw the error.
      *
-     * @example "typia.assert", "typia.assertEquals"
+     * @example
+     *   typia.assert, "typia.assertEquals";
      */
     method: string;
 
     /**
-     * The access path to the property where the assertion error occurred (optional).
+     * The access path to the property where the assertion error occurred
+     * (optional).
      *
-     * @example "input.age", "input.profile.email"
+     * @example
+     *   input.age, "input.profile.email";
      */
     path?: undefined | string;
 
     /**
      * String representation of the expected type at the error location.
      *
-     * @example "string", "number & ExclusiveMinimum<19>"
+     * @example
+     *   string, "number & ExclusiveMinimum<19>";
      */
     expected: string;
 
+    /** The actual value that failed assertion. */
+    value: unknown;
+
     /**
-     * The actual value that failed assertion.
+     * Optional human-readable description of the type guard error
+     *
+     * This field is rarely populated in standard typia type assertion and is
+     * primarily intended for specialized AI agent libraries or custom
+     * validation scenarios that require additional context beyond the technical
+     * type information. Most assertion errors rely solely on the path,
+     * expected, and value fields for comprehensive error reporting.
      */
-    value: unknown;
+    description?: string;
 
     /**
      * Custom error message (optional).
      *
-     * If not provided, a default format message will be automatically generated.
+     * If not provided, a default format message will be automatically
+     * generated.
      */
     message?: undefined | string;
   }

package/src/factories/MetadataCollection.ts

@@ -100,9 +100,7 @@ export class MetadataCollection {
     return addicted;
   }
 
-  /**
-   * @internal
-   */
+  /** @internal */
   public getUnionIndex(meta: Metadata): number {
     const key: string = meta.objects.map((obj) => obj.type.name).join(" | ");
     MapUtil.take(this.object_unions_, key, () =>
@@ -199,23 +197,17 @@ export class MetadataCollection {
     return [tuple, true, (elements) => (Writable(tuple).elements = elements)];
   }
 
-  /**
-   * @internal
-   */
+  /** @internal */
   public setObjectRecursive(obj: MetadataObjectType, recursive: boolean): void {
     Writable(obj).recursive = recursive;
   }
 
-  /**
-   * @internal
-   */
+  /** @internal */
   public setAliasRecursive(alias: MetadataAliasType, recursive: boolean): void {
     Writable(alias).recursive = recursive;
   }
 
-  /**
-   * @internal
-   */
+  /** @internal */
   public setArrayRecursive(array: MetadataArrayType, recursive: boolean): void {
     Writable(array).recursive = recursive;
     if (recursive) Writable(array).index = this.recursive_array_index_++;