typia/lib/TypeGuardError.d.ts

Superfast runtime validators with only one line

/**
 * Error thrown when type assertion fails.
 *
 * Thrown by {@link assert}, {@link assertGuard}, and other assert-family
 * functions when input doesn't match expected type `T`. Contains detailed
 * information about the first assertion failure:
 *
 * - `method`: Which typia function threw (e.g., `"typia.assert"`)
 * - `path`: Property path where error occurred (e.g., `"input.user.age"`)
 * - `expected`: Expected type string (e.g., `"number & ExclusiveMinimum<19>"`)
 * - `value`: Actual value that failed validation
 *
 * @template T Expected type (for type safety)
 */
export declare class TypeGuardError<T = any> extends Error {
    /**
     * Name of the typia method that threw this error.
     *
     * E.g., `"typia.assert"`, `"typia.assertEquals"`, `"typia.assertGuard"`.
     */
    readonly method: string;
    /**
     * Property path where assertion failed.
     *
     * Uses dot notation for nested properties. `undefined` if error occurred at
     * root level.
     *
     * E.g., `"input.age"`, `"input.profile.email"`, `"input[0].name"`.
     */
    readonly path: string | undefined;
    /**
     * String representation of expected type.
     *
     * E.g., `"string"`, `"number & ExclusiveMinimum<19>"`, `"{ name: string; age:
     * number }"`.
     */
    readonly expected: string;
    /**
     * Actual value that failed assertion.
     *
     * The raw value at the error path, useful for debugging.
     */
    readonly value: unknown;
    /**
     * Optional human-readable error description.
     *
     * Primarily for AI agent libraries or custom validation scenarios needing
     * additional context. Standard assertions rely on `path`, `expected`, and
     * `value` for error reporting.
     */
    readonly description?: string | undefined;
    /**
     * Creates a new TypeGuardError instance.
     *
     * @param props Error properties
     */
    constructor(props: TypeGuardError.IProps);
}
export declare namespace TypeGuardError {
    /** Properties for constructing a TypeGuardError. */
    interface IProps {
        /**
         * Name of the typia method that threw the error.
         *
         * E.g., `"typia.assert"`, `"typia.assertEquals"`.
         */
        method: string;
        /**
         * Property path where assertion failed (optional).
         *
         * E.g., `"input.age"`, `"input.profile.email"`.
         */
        path?: undefined | string;
        /**
         * String representation of expected type.
         *
         * E.g., `"string"`, `"number & ExclusiveMinimum<19>"`.
         */
        expected: string;
        /** Actual value that failed assertion. */
        value: unknown;
        /**
         * Optional human-readable error description.
         *
         * For AI agent libraries or custom validation needing additional context.
         */
        description?: string;
        /**
         * Custom error message (optional).
         *
         * If not provided, a default message is generated from other properties.
         */
        message?: undefined | string;
    }
}