typia 15.0.1 → 15.1.0

package/lib/TypeGuardError.d.ts

@@ -22,8 +22,8 @@ export declare class TypeGuardError<T = any> extends Error {
     /**
      * Property path where assertion failed.
      *
-     * Uses dot notation for nested properties. `undefined` if error occurred at
-     * root level.
+     * Uses dot notation for nested properties. Generated assertions start at
+     * `$input`; callers constructing the error may omit the path.
      *
      * E.g., `"input.age"`, `"input.profile.email"`, `"input[0].name"`.
      */
@@ -56,8 +56,23 @@ export declare class TypeGuardError<T = any> extends Error {
      */
     constructor(props: TypeGuardError.IProps);
 }
+/**
+ * Properties of {@link TypeGuardError}.
+ *
+ * @evidence contracts/common.md#principled-implementation The error extends Error and carries the failing method, optional path, expected type text and actual value as readonly fields. A nonempty message overrides the generated text. A nonempty description is retained; when the value is undefined, a supplied description (including an empty one) is retained or a missing-value instruction is generated. The prototype assignment preserves the subclass prototype when a toolchain downlevels `extends Error`.
+ * @evidence contracts/common.md#clear-and-simple-design One class with a namespace holding its constructor properties; the generic `T` is carried by a protected phantom member that is marked internal and never assigned.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The phantom member is a type-level device. The constructor changes only its own error instance's prototype to new.target.prototype for downlevel Error subclass compatibility; it does not replace a foreign method, global or prototype.
+ * @evidence contracts/common.md#meaningful-documentation The class comment lists the carried fields with examples, each field has its own comment and the phantom and constructor are explained.
+ */
 export declare namespace TypeGuardError {
-    /** Properties for constructing a TypeGuardError. */
+    /**
+     * Properties for constructing a TypeGuardError.
+     *
+     * @evidence contracts/common.md#principled-implementation The record lists exactly what the constructor reads: method, expected and value are required, while path, description and message are optional. A nonempty message overrides the generated text; absence or an empty message uses the default.
+     * @evidence contracts/common.md#clear-and-simple-design A flat record in the class namespace used only by the constructor and the factories.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts A data record.
+     * @evidence contracts/common.md#meaningful-documentation Each property has a comment with examples and the meaning of absence.
+     */
     interface IProps {
         /**
          * Name of the typia method that threw the error.
@@ -88,7 +103,8 @@ export declare namespace TypeGuardError {
         /**
          * Custom error message (optional).
          *
-         * If not provided, a default message is generated from other properties.
+         * If omitted or empty, a default message is generated from other
+         * properties.
          */
         message?: undefined | string;
     }

package/lib/TypeGuardError.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"TypeGuardError.mjs","names":[],"sources":["../src/TypeGuardError.ts"],"sourcesContent":["/**\n * Error thrown when type assertion fails.\n *\n * Thrown by {@link assert}, {@link assertGuard}, and other assert-family\n * functions when input doesn't match expected type `T`. Contains detailed\n * information about the first assertion failure:\n *\n * - `method`: Which typia function threw (e.g., `\"typia.assert\"`)\n * - `path`: Property path where error occurred (e.g., `\"input.user.age\"`)\n * - `expected`: Expected type string (e.g., `\"number & ExclusiveMinimum<19>\"`)\n * - `value`: Actual value that failed validation\n *\n * @template T Expected type (for type safety)\n */\nexport class TypeGuardError<T = any> extends Error {\n  /**\n   * Name of the typia method that threw this error.\n   *\n   * E.g., `\"typia.assert\"`, `\"typia.assertEquals\"`, `\"typia.assertGuard\"`.\n   */\n  public readonly method: string;\n\n  /**\n   * Property path where assertion failed.\n   *\n   * Uses dot notation for nested properties. `undefined` if error occurred at\n   * root level.\n   *\n   * E.g., `\"input.age\"`, `\"input.profile.email\"`, `\"input[0].name\"`.\n   */\n  public readonly path: string | undefined;\n\n  /**\n   * String representation of expected type.\n   *\n   * E.g., `\"string\"`, `\"number & ExclusiveMinimum<19>\"`, `\"{ name: string; age:\n   * number }\"`.\n   */\n  public readonly expected: string;\n\n  /**\n   * Actual value that failed assertion.\n   *\n   * The raw value at the error path, useful for debugging.\n   */\n  public readonly value: unknown;\n\n  /**\n   * Optional human-readable error description.\n   *\n   * Primarily for AI agent libraries or custom validation scenarios needing\n   * additional context. Standard assertions rely on `path`, `expected`, and\n   * `value` for error reporting.\n   */\n  public readonly description?: string | undefined;\n\n  /**\n   * Phantom property for TypeScript type safety.\n   *\n   * Not used at runtime—exists only to preserve generic type `T` in the type\n   * system. Always `undefined`.\n   *\n   * @internal\n   */\n  protected readonly fake_expected_typed_value_?: T | undefined;\n\n  /**\n   * Creates a new TypeGuardError instance.\n   *\n   * @param props Error properties\n   */\n  public constructor(props: TypeGuardError.IProps) {\n    // MESSAGE CONSTRUCTION\n    // Use custom message if provided, otherwise generate default format\n    super(\n      props.message ||\n        `Error on ${props.method}(): invalid type${\n          props.path ? ` on ${props.path}` : \"\"\n        }, expect to be ${props.expected}`,\n    );\n\n    // INHERITANCE POLYFILL\n    // Set up prototype for compatibility across different JavaScript environments\n    const proto = new.target.prototype;\n    if (Object.setPrototypeOf) Object.setPrototypeOf(this, proto);\n    else (this as any).__proto__ = proto;\n\n    // ASSIGN MEMBERS\n    this.name = \"TypeGuardError\";\n    this.method = props.method;\n    this.path = props.path;\n    this.expected = props.expected;\n    this.value = props.value;\n    if (props.description || props.value === undefined)\n      this.description =\n        props.description ??\n        [\n          \"The value at this path is `undefined`.\",\n          \"\",\n          `Please fill the \\`${props.expected}\\` typed value next time.`,\n        ].join(\"\\n\");\n  }\n}\n\nexport namespace TypeGuardError {\n  /** Properties for constructing a TypeGuardError. */\n  export interface IProps {\n    /**\n     * Name of the typia method that threw the error.\n     *\n     * E.g., `\"typia.assert\"`, `\"typia.assertEquals\"`.\n     */\n    method: string;\n\n    /**\n     * Property path where assertion failed (optional).\n     *\n     * E.g., `\"input.age\"`, `\"input.profile.email\"`.\n     */\n    path?: undefined | string;\n\n    /**\n     * String representation of expected type.\n     *\n     * E.g., `\"string\"`, `\"number & ExclusiveMinimum<19>\"`.\n     */\n    expected: string;\n\n    /** Actual value that failed assertion. */\n    value: unknown;\n\n    /**\n     * Optional human-readable error description.\n     *\n     * For AI agent libraries or custom validation needing additional context.\n     */\n    description?: string;\n\n    /**\n     * Custom error message (optional).\n     *\n     * If not provided, a default message is generated from other properties.\n     */\n    message?: undefined | string;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;AAcA,IAAa,iBAAb,cAA6C,MAAM;;;;;;CAyDjD,YAAmB,OAA8B;EAG/C,MACE,MAAM,WACJ,YAAY,MAAM,OAAO,kBACvB,MAAM,OAAO,OAAO,MAAM,SAAS,GACpC,iBAAiB,MAAM,UAC5B;EAIA,MAAM,QAAQ,IAAI,OAAO;EACzB,IAAI,OAAO,gBAAgB,OAAO,eAAe,MAAM,KAAK;OACvD,KAAc,YAAY;EAG/B,KAAK,OAAO;EACZ,KAAK,SAAS,MAAM;EACpB,KAAK,OAAO,MAAM;EAClB,KAAK,WAAW,MAAM;EACtB,KAAK,QAAQ,MAAM;EACnB,IAAI,MAAM,eAAe,MAAM,UAAU,KAAA,GACvC,KAAK,cACH,MAAM,eACN;GACE;GACA;GACA,qBAAqB,MAAM,SAAS;EACtC,CAAC,CAAC,KAAK,IAAI;CACjB;AACF"}
+{"version":3,"file":"TypeGuardError.mjs","names":[],"sources":["../src/TypeGuardError.ts"],"sourcesContent":["/**\n * Error thrown when type assertion fails.\n *\n * Thrown by {@link assert}, {@link assertGuard}, and other assert-family\n * functions when input doesn't match expected type `T`. Contains detailed\n * information about the first assertion failure:\n *\n * - `method`: Which typia function threw (e.g., `\"typia.assert\"`)\n * - `path`: Property path where error occurred (e.g., `\"input.user.age\"`)\n * - `expected`: Expected type string (e.g., `\"number & ExclusiveMinimum<19>\"`)\n * - `value`: Actual value that failed validation\n *\n * @template T Expected type (for type safety)\n */\nexport class TypeGuardError<T = any> extends Error {\n  /**\n   * Name of the typia method that threw this error.\n   *\n   * E.g., `\"typia.assert\"`, `\"typia.assertEquals\"`, `\"typia.assertGuard\"`.\n   */\n  public readonly method: string;\n\n  /**\n   * Property path where assertion failed.\n   *\n   * Uses dot notation for nested properties. Generated assertions start at\n   * `$input`; callers constructing the error may omit the path.\n   *\n   * E.g., `\"input.age\"`, `\"input.profile.email\"`, `\"input[0].name\"`.\n   */\n  public readonly path: string | undefined;\n\n  /**\n   * String representation of expected type.\n   *\n   * E.g., `\"string\"`, `\"number & ExclusiveMinimum<19>\"`, `\"{ name: string; age:\n   * number }\"`.\n   */\n  public readonly expected: string;\n\n  /**\n   * Actual value that failed assertion.\n   *\n   * The raw value at the error path, useful for debugging.\n   */\n  public readonly value: unknown;\n\n  /**\n   * Optional human-readable error description.\n   *\n   * Primarily for AI agent libraries or custom validation scenarios needing\n   * additional context. Standard assertions rely on `path`, `expected`, and\n   * `value` for error reporting.\n   */\n  public readonly description?: string | undefined;\n\n  /**\n   * Phantom property for TypeScript type safety.\n   *\n   * Not used at runtime—exists only to preserve generic type `T` in the type\n   * system. Always `undefined`.\n   *\n   * @internal\n   */\n  protected readonly fake_expected_typed_value_?: T | undefined;\n\n  /**\n   * Creates a new TypeGuardError instance.\n   *\n   * @param props Error properties\n   */\n  public constructor(props: TypeGuardError.IProps) {\n    // MESSAGE CONSTRUCTION\n    // Use custom message if provided, otherwise generate default format\n    super(\n      props.message ||\n        `Error on ${props.method}(): invalid type${\n          props.path ? ` on ${props.path}` : \"\"\n        }, expect to be ${props.expected}`,\n    );\n\n    // INHERITANCE POLYFILL\n    // Set up prototype for compatibility across different JavaScript environments\n    const proto = new.target.prototype;\n    if (Object.setPrototypeOf) Object.setPrototypeOf(this, proto);\n    else (this as any).__proto__ = proto;\n\n    // ASSIGN MEMBERS\n    this.name = \"TypeGuardError\";\n    this.method = props.method;\n    this.path = props.path;\n    this.expected = props.expected;\n    this.value = props.value;\n    if (props.description || props.value === undefined)\n      this.description =\n        props.description ??\n        [\n          \"The value at this path is `undefined`.\",\n          \"\",\n          `Please fill the \\`${props.expected}\\` typed value next time.`,\n        ].join(\"\\n\");\n  }\n}\n\n/**\n * Properties of {@link TypeGuardError}.\n *\n * @evidence contracts/common.md#principled-implementation The error extends Error and carries the failing method, optional path, expected type text and actual value as readonly fields. A nonempty message overrides the generated text. A nonempty description is retained; when the value is undefined, a supplied description (including an empty one) is retained or a missing-value instruction is generated. The prototype assignment preserves the subclass prototype when a toolchain downlevels `extends Error`.\n * @evidence contracts/common.md#clear-and-simple-design One class with a namespace holding its constructor properties; the generic `T` is carried by a protected phantom member that is marked internal and never assigned.\n * @evidence contracts/common.md#prohibited-implementation-shortcuts The phantom member is a type-level device. The constructor changes only its own error instance's prototype to new.target.prototype for downlevel Error subclass compatibility; it does not replace a foreign method, global or prototype.\n * @evidence contracts/common.md#meaningful-documentation The class comment lists the carried fields with examples, each field has its own comment and the phantom and constructor are explained.\n */\nexport namespace TypeGuardError {\n  /**\n   * Properties for constructing a TypeGuardError.\n   *\n   * @evidence contracts/common.md#principled-implementation The record lists exactly what the constructor reads: method, expected and value are required, while path, description and message are optional. A nonempty message overrides the generated text; absence or an empty message uses the default.\n   * @evidence contracts/common.md#clear-and-simple-design A flat record in the class namespace used only by the constructor and the factories.\n   * @evidence contracts/common.md#prohibited-implementation-shortcuts A data record.\n   * @evidence contracts/common.md#meaningful-documentation Each property has a comment with examples and the meaning of absence.\n   */\n  export interface IProps {\n    /**\n     * Name of the typia method that threw the error.\n     *\n     * E.g., `\"typia.assert\"`, `\"typia.assertEquals\"`.\n     */\n    method: string;\n\n    /**\n     * Property path where assertion failed (optional).\n     *\n     * E.g., `\"input.age\"`, `\"input.profile.email\"`.\n     */\n    path?: undefined | string;\n\n    /**\n     * String representation of expected type.\n     *\n     * E.g., `\"string\"`, `\"number & ExclusiveMinimum<19>\"`.\n     */\n    expected: string;\n\n    /** Actual value that failed assertion. */\n    value: unknown;\n\n    /**\n     * Optional human-readable error description.\n     *\n     * For AI agent libraries or custom validation needing additional context.\n     */\n    description?: string;\n\n    /**\n     * Custom error message (optional).\n     *\n     * If omitted or empty, a default message is generated from other\n     * properties.\n     */\n    message?: undefined | string;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;AAcA,IAAa,iBAAb,cAA6C,MAAM;;;;;;CAyDjD,YAAmB,OAA8B;EAG/C,MACE,MAAM,WACJ,YAAY,MAAM,OAAO,kBACvB,MAAM,OAAO,OAAO,MAAM,SAAS,GACpC,iBAAiB,MAAM,UAC5B;EAIA,MAAM,QAAQ,IAAI,OAAO;EACzB,IAAI,OAAO,gBAAgB,OAAO,eAAe,MAAM,KAAK;OACvD,KAAc,YAAY;EAG/B,KAAK,OAAO;EACZ,KAAK,SAAS,MAAM;EACpB,KAAK,OAAO,MAAM;EAClB,KAAK,WAAW,MAAM;EACtB,KAAK,QAAQ,MAAM;EACnB,IAAI,MAAM,eAAe,MAAM,UAAU,KAAA,GACvC,KAAK,cACH,MAAM,eACN;GACE;GACA;GACA,qBAAqB,MAAM,SAAS;EACtC,CAAC,CAAC,KAAK,IAAI;CACjB;AACF"}