typia/lib/TypeGuardError.d.mts

Superfast runtime validators with only one line

/**
 * 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.
 *
 * @author Jeongho Nam - https://github.com/samchon
 * @example
 *   ```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
 *     }
 *   }
 *   ```;
 *
 * @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;
     */
    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.
     *
     * @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
     */
    readonly path: string | undefined;
    /**
     * String representation of the expected type at the error location.
     *
     * Represents TypeScript types as strings, including detailed type information
     * 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
     */
    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.
     *
     * @example
     *   - `18` - Numeric value
     *   - `"invalid"` - String value
     *   - `{ name: "John", age: 18, sex: 1 }` - Object value
     */
    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.
     */
    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
     *   });
     *   ```;
     *
     * @param props - Object containing the properties needed to create the error
     */
    constructor(props: TypeGuardError.IProps);
}
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
     *   };
     *   ```;
     */
    interface IProps {
        /**
         * The name of the typia method that threw the error.
         *
         * @example
         *   typia.assert, "typia.assertEquals";
         */
        method: string;
        /**
         * The access path to the property where the assertion error occurred
         * (optional).
         *
         * @example
         *   input.age, "input.profile.email";
         */
        path?: undefined | string;
        /**
         * String representation of the expected type at the error location.
         *
         * @example
         *   string, "number & ExclusiveMinimum<19>";
         */
        expected: string;
        /** The actual value that failed assertion. */
        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.
         */
        description?: string;
        /**
         * Custom error message (optional).
         *
         * If not provided, a default format message will be automatically
         * generated.
         */
        message?: undefined | string;
    }
}