typia/lib/TypeGuardError.mjs

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)
 */
class TypeGuardError extends Error {
    /**
     * The name of the typia method that threw this error.
     *
     * @example
     *   typia.assert;
     */
    method;
    /**
     * 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
     */
    path;
    /**
     * 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
     */
    expected;
    /**
     * 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
     */
    value;
    /**
     * 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;
    /**
     * 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.
     *
     * @internal
     */
    fake_expected_typed_value_;
    /**
     * 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) {
        // MESSAGE CONSTRUCTION
        // Use custom message if provided, otherwise generate default format
        super(props.message ||
            `Error on ${props.method}(): invalid type${props.path ? ` on ${props.path}` : ""}, expect to be ${props.expected}`);
        // INHERITANCE POLYFILL
        // Set up prototype for compatibility across different JavaScript environments
        const proto = new.target.prototype;
        if (Object.setPrototypeOf)
            Object.setPrototypeOf(this, proto);
        else
            this.__proto__ = proto;
        // ASSIGN MEMBERS
        this.method = props.method;
        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");
    }
}

export { TypeGuardError };
//# sourceMappingURL=TypeGuardError.mjs.map