typia 9.7.1 → 10.0.0-dev.20251107

package/lib/TypeGuardError.d.mts

@@ -1,51 +1,55 @@
 /**
- * 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 declare class TypeGuardError<T = any> extends Error {
     /**
      * The name of the typia method that threw this error.
      *
-     * @example "typia.assert"
+     * @example
+     *   typia.assert;
      */
     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
      */
     readonly path: string | undefined;
     /**
@@ -55,38 +59,48 @@ export declare 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
      */
     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
      */
     readonly value: unknown;
     /**
-     * Creates a new TypeGuardError instance.
+     * Optional human-readable description of the type guard error
      *
-     * @param props - Object containing the properties needed to create the 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.
+     */
+    readonly description?: string | undefined;
+    /**
+     * Creates a new TypeGuardError instance.
      *
      * @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
      */
     constructor(props: TypeGuardError.IProps);
 }
@@ -95,43 +109,56 @@ export declare 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
+     *   };
+     *   ```;
      */
     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/lib/TypeGuardError.d.ts

@@ -1,51 +1,55 @@
 /**
- * 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 declare class TypeGuardError<T = any> extends Error {
     /**
      * The name of the typia method that threw this error.
      *
-     * @example "typia.assert"
+     * @example
+     *   typia.assert;
      */
     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
      */
     readonly path: string | undefined;
     /**
@@ -55,38 +59,48 @@ export declare 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
      */
     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
      */
     readonly value: unknown;
     /**
-     * Creates a new TypeGuardError instance.
+     * Optional human-readable description of the type guard error
      *
-     * @param props - Object containing the properties needed to create the 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.
+     */
+    readonly description?: string | undefined;
+    /**
+     * Creates a new TypeGuardError instance.
      *
      * @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
      */
     constructor(props: TypeGuardError.IProps);
 }
@@ -95,43 +109,56 @@ export declare 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
+     *   };
+     *   ```;
      */
     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/lib/TypeGuardError.js

@@ -2,52 +2,56 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TypeGuardError = void 0;
 /**
- * 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)
  */
 class TypeGuardError 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
      */
     constructor(props) {
+        var _a;
         // MESSAGE CONSTRUCTION
         // Use custom message if provided, otherwise generate default format
         super(props.message ||
@@ -64,6 +68,13 @@ class TypeGuardError extends Error {
         this.path = props.path;
         this.expected = props.expected;
         this.value = props.value;
+        if (props.description || props.value === undefined)
+            this.description =
+                (_a = props.description) !== null && _a !== void 0 ? _a : [
+                    "The value at this path is `undefined`.",
+                    "",
+                    `Please fill the \`${props.expected}\` typed value next time.`,
+                ].join("\n");
     }
 }
 exports.TypeGuardError = TypeGuardError;

package/lib/TypeGuardError.js.map

@@ -1 +1 @@
-{"version":3,"file":"TypeGuardError.js","sourceRoot":"","sources":["../src/TypeGuardError.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAa,cAAwB,SAAQ,KAAK;IA4DhD;;;;;;;;;;;;;;OAcG;IACH,YAAmB,KAA4B;QAC7C,uBAAuB;QACvB,oEAAoE;QACpE,KAAK,CACH,KAAK,CAAC,OAAO;YACX,YAAY,KAAK,CAAC,MAAM,mBACtB,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EACrC,kBAAkB,KAAK,CAAC,QAAQ,EAAE,CACrC,CAAC;QAEF,uBAAuB;QACvB,8EAA8E;QAC9E,MAAM,KAAK,GAAG,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC;QACnC,IAAI,MAAM,CAAC,cAAc;YAAE,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;;YACxD,IAAY,CAAC,SAAS,GAAG,KAAK,CAAC;QAErC,iBAAiB;QACjB,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;QAC3B,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC;QACvB,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC;QAC/B,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC;IAC3B,CAAC;CACF;AAjGD,wCAiGC"}
+{"version":3,"file":"TypeGuardError.js","sourceRoot":"","sources":["../src/TypeGuardError.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAa,cAAwB,SAAQ,KAAK;IAwEhD;;;;;;;;;;;;;;OAcG;IACH,YAAmB,KAA4B;;QAC7C,uBAAuB;QACvB,oEAAoE;QACpE,KAAK,CACH,KAAK,CAAC,OAAO;YACX,YAAY,KAAK,CAAC,MAAM,mBACtB,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EACrC,kBAAkB,KAAK,CAAC,QAAQ,EAAE,CACrC,CAAC;QAEF,uBAAuB;QACvB,8EAA8E;QAC9E,MAAM,KAAK,GAAG,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC;QACnC,IAAI,MAAM,CAAC,cAAc;YAAE,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;;YACxD,IAAY,CAAC,SAAS,GAAG,KAAK,CAAC;QAErC,iBAAiB;QACjB,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;QAC3B,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC;QACvB,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC;QAC/B,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC;QACzB,IAAI,KAAK,CAAC,WAAW,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS;YAChD,IAAI,CAAC,WAAW;gBACd,MAAA,KAAK,CAAC,WAAW,mCACjB;oBACE,wCAAwC;oBACxC,EAAE;oBACF,qBAAqB,KAAK,CAAC,QAAQ,2BAA2B;iBAC/D,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACnB,CAAC;CACF;AArHD,wCAqHC"}