typia 9.4.0 → 9.5.0-dev.20250710

package/src/TypeGuardError.ts

@@ -1,179 +1,179 @@
-/**
- * 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.
- *
- * @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>;
- * }
- *
- * 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
- *   }
- * }
- * ```
- */
-export class TypeGuardError<T = any> extends Error {
-  /**
-   * The name of the typia method that threw this error.
-   *
-   * @example "typia.assert"
-   */
-  public 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
-   */
-  public 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
-   */
-  public 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
-   */
-  public readonly value: unknown;
-
-  /**
-   * 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
-   */
-  protected readonly fake_expected_typed_value_?: T | undefined;
-
-  /**
-   * 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
-   * });
-   * ```
-   */
-  public constructor(props: TypeGuardError.IProps) {
-    // 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 as any).__proto__ = proto;
-
-    // ASSIGN MEMBERS
-    this.method = props.method;
-    this.path = props.path;
-    this.expected = props.expected;
-    this.value = props.value;
-  }
-}
-
-export 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
-   * };
-   * ```
-   */
-  export 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;
-
-    /**
-     * Custom error message (optional).
-     *
-     * If not provided, a default format message will be automatically generated.
-     */
-    message?: undefined | string;
-  }
-}
+/**
+ * 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.
+ *
+ * @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>;
+ * }
+ *
+ * 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
+ *   }
+ * }
+ * ```
+ */
+export class TypeGuardError<T = any> extends Error {
+  /**
+   * The name of the typia method that threw this error.
+   *
+   * @example "typia.assert"
+   */
+  public 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
+   */
+  public 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
+   */
+  public 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
+   */
+  public readonly value: unknown;
+
+  /**
+   * 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
+   */
+  protected readonly fake_expected_typed_value_?: T | undefined;
+
+  /**
+   * 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
+   * });
+   * ```
+   */
+  public constructor(props: TypeGuardError.IProps) {
+    // 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 as any).__proto__ = proto;
+
+    // ASSIGN MEMBERS
+    this.method = props.method;
+    this.path = props.path;
+    this.expected = props.expected;
+    this.value = props.value;
+  }
+}
+
+export 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
+   * };
+   * ```
+   */
+  export 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;
+
+    /**
+     * Custom error message (optional).
+     *
+     * If not provided, a default format message will be automatically generated.
+     */
+    message?: undefined | string;
+  }
+}

package/src/executable/TypiaGenerateWizard.ts

@@ -1,83 +1,83 @@
-import fs from "fs";
-
-import { TypiaProgrammer } from "../programmers/TypiaProgrammer";
-
-import { ArgumentParser } from "./setup/ArgumentParser";
-import { PackageManager } from "./setup/PackageManager";
-
-export namespace TypiaGenerateWizard {
-  export async function generate(): Promise<void> {
-    console.log("----------------------------------------");
-    console.log(" Typia Generate Wizard");
-    console.log("----------------------------------------");
-
-    // LOAD PACKAGE.JSON INFO
-    const pack: PackageManager = await PackageManager.mount();
-    const options: IArguments = await ArgumentParser.parse(pack, inquiry);
-    await TypiaProgrammer.build(options);
-  }
-
-  const inquiry: ArgumentParser.Inquiry<IArguments> = async (
-    _pack,
-    command,
-    prompt,
-    action,
-  ) => {
-    // PREPARE ASSETS
-    command.option("--input [path]", "input directory");
-    command.option("--output [directory]", "output directory");
-    command.option("--project [project]", "tsconfig.json file location");
-
-    const questioned = { value: false };
-
-    const input = (name: string) => async (message: string) => {
-      const result = await prompt()({
-        type: "input",
-        name,
-        message,
-        default: "",
-      });
-      return result[name] as string;
-    };
-    const select =
-      (name: string) =>
-      (message: string) =>
-      async <Choice extends string>(choices: Choice[]): Promise<Choice> => {
-        questioned.value = true;
-        return (
-          await prompt()({
-            type: "list",
-            name: name,
-            message: message,
-            choices: choices,
-          })
-        )[name];
-      };
-    const configure = async (): Promise<string> => {
-      const files: string[] = await (
-        await fs.promises.readdir(process.cwd())
-      ).filter(
-        (str) =>
-          str.substring(0, 8) === "tsconfig" &&
-          str.substring(str.length - 5) === ".json",
-      );
-      if (files.length === 0)
-        throw new URIError(`Unable to find "tsconfig.json" file.`);
-      else if (files.length === 1) return files[0]!;
-      return select("tsconfig")("TS Config File")(files);
-    };
-
-    return action(async (options) => {
-      options.input ??= await input("input")("input directory");
-      options.output ??= await input("output")("output directory");
-      options.project ??= await configure();
-      return options as IArguments;
-    });
-  };
-
-  export interface IArguments {
-    input: string;
-    output: string;
-    project: string;
-  }
-}
+import fs from "fs";
+
+import { TypiaProgrammer } from "../programmers/TypiaProgrammer";
+
+import { ArgumentParser } from "./setup/ArgumentParser";
+import { PackageManager } from "./setup/PackageManager";
+
+export namespace TypiaGenerateWizard {
+  export async function generate(): Promise<void> {
+    console.log("----------------------------------------");
+    console.log(" Typia Generate Wizard");
+    console.log("----------------------------------------");
+
+    // LOAD PACKAGE.JSON INFO
+    const pack: PackageManager = await PackageManager.mount();
+    const options: IArguments = await ArgumentParser.parse(pack, inquiry);
+    await TypiaProgrammer.build(options);
+  }
+
+  const inquiry: ArgumentParser.Inquiry<IArguments> = async (
+    _pack,
+    command,
+    prompt,
+    action,
+  ) => {
+    // PREPARE ASSETS
+    command.option("--input [path]", "input directory");
+    command.option("--output [directory]", "output directory");
+    command.option("--project [project]", "tsconfig.json file location");
+
+    const questioned = { value: false };
+
+    const input = (name: string) => async (message: string) => {
+      const result = await prompt()({
+        type: "input",
+        name,
+        message,
+        default: "",
+      });
+      return result[name] as string;
+    };
+    const select =
+      (name: string) =>
+      (message: string) =>
+      async <Choice extends string>(choices: Choice[]): Promise<Choice> => {
+        questioned.value = true;
+        return (
+          await prompt()({
+            type: "list",
+            name: name,
+            message: message,
+            choices: choices,
+          })
+        )[name];
+      };
+    const configure = async (): Promise<string> => {
+      const files: string[] = await (
+        await fs.promises.readdir(process.cwd())
+      ).filter(
+        (str) =>
+          str.substring(0, 8) === "tsconfig" &&
+          str.substring(str.length - 5) === ".json",
+      );
+      if (files.length === 0)
+        throw new URIError(`Unable to find "tsconfig.json" file.`);
+      else if (files.length === 1) return files[0]!;
+      return select("tsconfig")("TS Config File")(files);
+    };
+
+    return action(async (options) => {
+      options.input ??= await input("input")("input directory");
+      options.output ??= await input("output")("output directory");
+      options.project ??= await configure();
+      return options as IArguments;
+    });
+  };
+
+  export interface IArguments {
+    input: string;
+    output: string;
+    project: string;
+  }
+}

package/src/executable/TypiaPatchWizard.ts

@@ -1,45 +1,45 @@
-import fs from "fs";
-
-export namespace TypiaPatchWizard {
-  export const main = async (): Promise<void> => {
-    console.log("----------------------------------------");
-    console.log(" Typia Setup Wizard");
-    console.log("----------------------------------------");
-    console.log(
-      [
-        `Since TypeScript v5.3 update, "tsc" no more parses JSDoc comments.`,
-        ``,
-        `Therefore, "typia" revives the JSDoc parsing feature by patching "tsc".`,
-        ``,
-        `This is a temporary feature of "typia", and it would be removed when "ts-patch" being updated.`,
-      ].join("\n"),
-    );
-
-    await patch();
-  };
-
-  export const patch = async (): Promise<void> => {
-    for (const file of ["tsc.js", "_tsc.js"])
-      try {
-        const location: string = require.resolve(`typescript/lib/${file}`);
-        const content: string = await fs.promises.readFile(location, "utf8");
-        if (content.indexOf(FROM_WITH_COMMENT) !== -1)
-          await fs.promises.writeFile(
-            location,
-            content.replace(FROM_WITH_COMMENT, TO_WITH_COMMENT),
-            "utf8",
-          );
-        else if (content.indexOf(FROM_ONLY) !== -1)
-          await fs.promises.writeFile(
-            location,
-            content.replace(FROM_ONLY, TO_ONLY),
-            "utf8",
-          );
-      } catch {}
-  };
-}
-
-const FROM_WITH_COMMENT = `var defaultJSDocParsingMode = 2 /* ParseForTypeErrors */`;
-const TO_WITH_COMMENT = `var defaultJSDocParsingMode = 0 /* ParseAll */`;
-const FROM_ONLY = `var defaultJSDocParsingMode = 2`;
-const TO_ONLY = `var defaultJSDocParsingMode = 0`;
+import fs from "fs";
+
+export namespace TypiaPatchWizard {
+  export const main = async (): Promise<void> => {
+    console.log("----------------------------------------");
+    console.log(" Typia Setup Wizard");
+    console.log("----------------------------------------");
+    console.log(
+      [
+        `Since TypeScript v5.3 update, "tsc" no more parses JSDoc comments.`,
+        ``,
+        `Therefore, "typia" revives the JSDoc parsing feature by patching "tsc".`,
+        ``,
+        `This is a temporary feature of "typia", and it would be removed when "ts-patch" being updated.`,
+      ].join("\n"),
+    );
+
+    await patch();
+  };
+
+  export const patch = async (): Promise<void> => {
+    for (const file of ["tsc.js", "_tsc.js"])
+      try {
+        const location: string = require.resolve(`typescript/lib/${file}`);
+        const content: string = await fs.promises.readFile(location, "utf8");
+        if (content.indexOf(FROM_WITH_COMMENT) !== -1)
+          await fs.promises.writeFile(
+            location,
+            content.replace(FROM_WITH_COMMENT, TO_WITH_COMMENT),
+            "utf8",
+          );
+        else if (content.indexOf(FROM_ONLY) !== -1)
+          await fs.promises.writeFile(
+            location,
+            content.replace(FROM_ONLY, TO_ONLY),
+            "utf8",
+          );
+      } catch {}
+  };
+}
+
+const FROM_WITH_COMMENT = `var defaultJSDocParsingMode = 2 /* ParseForTypeErrors */`;
+const TO_WITH_COMMENT = `var defaultJSDocParsingMode = 0 /* ParseAll */`;
+const FROM_ONLY = `var defaultJSDocParsingMode = 2`;
+const TO_ONLY = `var defaultJSDocParsingMode = 0`;