typia 9.4.0 → 9.5.0-dev.20250710

package/src/transformers/FileTransformer.ts

@@ -1,136 +1,136 @@
-import ts from "typescript";
-
-import { ImportProgrammer } from "../programmers/ImportProgrammer";
-
-import { Singleton } from "../utils/Singleton";
-
-import { ITypiaContext } from "./ITypiaContext";
-import { NodeTransformer } from "./NodeTransformer";
-import { TransformerError } from "./TransformerError";
-
-export namespace FileTransformer {
-  export const transform =
-    (environments: Omit<ITypiaContext, "transformer" | "importer">) =>
-    (transformer: ts.TransformationContext) =>
-    (file: ts.SourceFile): ts.SourceFile => {
-      if (file.isDeclarationFile) return file;
-
-      const importer: ImportProgrammer = new ImportProgrammer({
-        internalPrefix: "typia_transform_",
-      });
-      const context: ITypiaContext = {
-        ...environments,
-        transformer,
-        importer,
-      };
-      checkJsDocParsingMode.get(context, file);
-
-      file = ts.visitEachChild(
-        file,
-        (node) =>
-          iterate_node({
-            context,
-            node,
-          }),
-        transformer,
-      );
-      const index: number = find_import_injection_index(file);
-      return ts.factory.updateSourceFile(
-        file,
-        [
-          ...file.statements.slice(0, index),
-          ...importer.toStatements(),
-          ...file.statements.slice(index),
-        ],
-        false,
-        file.referencedFiles,
-        file.typeReferenceDirectives,
-        file.hasNoDefaultLib,
-        file.libReferenceDirectives,
-      );
-    };
-
-  const iterate_node = (props: {
-    context: ITypiaContext;
-    node: ts.Node;
-  }): ts.Node =>
-    ts.visitEachChild(
-      try_transform_node(props) ?? props.node,
-      (node) =>
-        iterate_node({
-          context: props.context,
-          node,
-        }),
-      props.context.transformer,
-    );
-
-  const try_transform_node = (props: {
-    context: ITypiaContext;
-    node: ts.Node;
-  }): ts.Node | null => {
-    try {
-      return NodeTransformer.transform(props);
-    } catch (exp) {
-      // ONLY ACCEPT TRANSFORMER-ERROR
-      if (!isTransformerError(exp)) throw exp;
-
-      // REPORT DIAGNOSTIC
-      const diagnostic = ts.createDiagnosticForNode(props.node, {
-        key: exp.code,
-        category: ts.DiagnosticCategory.Error,
-        message: exp.message,
-        code: `(${exp.code})` as any,
-      });
-      props.context.extras.addDiagnostic(diagnostic);
-      return null;
-    }
-  };
-
-  const find_import_injection_index = (file: ts.SourceFile): number => {
-    let i: number = 0;
-    for (; i < file.statements.length; ++i) {
-      const stmt: ts.Statement = file.statements[i]!;
-      if (
-        ts.isExpressionStatement(stmt) &&
-        ts.isStringLiteralLike(stmt.expression) &&
-        stmt.expression.text.startsWith("use ")
-      )
-        continue;
-      break;
-    }
-    return i;
-  };
-}
-
-const isTransformerError = (error: any): error is TransformerError =>
-  typeof error === "object" &&
-  error !== null &&
-  error.constructor.name === "TransformerError" &&
-  typeof error.code === "string" &&
-  typeof error.message === "string";
-
-const checkJsDocParsingMode = new Singleton(
-  (context: ITypiaContext, file: ts.SourceFile) => {
-    if (
-      typeof file.jsDocParsingMode === "number" &&
-      file.jsDocParsingMode !== 0
-    ) {
-      context.extras.addDiagnostic(
-        ts.createDiagnosticForNode(file, {
-          code: `(typia setup)` as any,
-          key: "jsDocParsingMode",
-          category: ts.DiagnosticCategory.Warning,
-          message: [
-            `Run "npx typia setup" or "npx typia patch" command again.`,
-            ``,
-            `Since TypeScript v5.3 update, "tsc" no more parses JSDoc comments. Therefore, "typia" also cannot utilize those JSDoc comments too, and it damages on some features of "typia" like "comment tags" or "JSON schema" generator.`,
-            ``,
-            `To solve this problem, run "npx typia setup" or "npx typia patch" command to hack the TypeScript compiler to revive the JSDoc parsing feature.`,
-            ``,
-            `  - reference: https://github.com/microsoft/TypeScript/pull/55739`,
-          ].join("\n"),
-        }),
-      );
-    }
-  },
-);
+import ts from "typescript";
+
+import { ImportProgrammer } from "../programmers/ImportProgrammer";
+
+import { Singleton } from "../utils/Singleton";
+
+import { ITypiaContext } from "./ITypiaContext";
+import { NodeTransformer } from "./NodeTransformer";
+import { TransformerError } from "./TransformerError";
+
+export namespace FileTransformer {
+  export const transform =
+    (environments: Omit<ITypiaContext, "transformer" | "importer">) =>
+    (transformer: ts.TransformationContext) =>
+    (file: ts.SourceFile): ts.SourceFile => {
+      if (file.isDeclarationFile) return file;
+
+      const importer: ImportProgrammer = new ImportProgrammer({
+        internalPrefix: "typia_transform_",
+      });
+      const context: ITypiaContext = {
+        ...environments,
+        transformer,
+        importer,
+      };
+      checkJsDocParsingMode.get(context, file);
+
+      file = ts.visitEachChild(
+        file,
+        (node) =>
+          iterate_node({
+            context,
+            node,
+          }),
+        transformer,
+      );
+      const index: number = find_import_injection_index(file);
+      return ts.factory.updateSourceFile(
+        file,
+        [
+          ...file.statements.slice(0, index),
+          ...importer.toStatements(),
+          ...file.statements.slice(index),
+        ],
+        false,
+        file.referencedFiles,
+        file.typeReferenceDirectives,
+        file.hasNoDefaultLib,
+        file.libReferenceDirectives,
+      );
+    };
+
+  const iterate_node = (props: {
+    context: ITypiaContext;
+    node: ts.Node;
+  }): ts.Node =>
+    ts.visitEachChild(
+      try_transform_node(props) ?? props.node,
+      (node) =>
+        iterate_node({
+          context: props.context,
+          node,
+        }),
+      props.context.transformer,
+    );
+
+  const try_transform_node = (props: {
+    context: ITypiaContext;
+    node: ts.Node;
+  }): ts.Node | null => {
+    try {
+      return NodeTransformer.transform(props);
+    } catch (exp) {
+      // ONLY ACCEPT TRANSFORMER-ERROR
+      if (!isTransformerError(exp)) throw exp;
+
+      // REPORT DIAGNOSTIC
+      const diagnostic = ts.createDiagnosticForNode(props.node, {
+        key: exp.code,
+        category: ts.DiagnosticCategory.Error,
+        message: exp.message,
+        code: `(${exp.code})` as any,
+      });
+      props.context.extras.addDiagnostic(diagnostic);
+      return null;
+    }
+  };
+
+  const find_import_injection_index = (file: ts.SourceFile): number => {
+    let i: number = 0;
+    for (; i < file.statements.length; ++i) {
+      const stmt: ts.Statement = file.statements[i]!;
+      if (
+        ts.isExpressionStatement(stmt) &&
+        ts.isStringLiteralLike(stmt.expression) &&
+        stmt.expression.text.startsWith("use ")
+      )
+        continue;
+      break;
+    }
+    return i;
+  };
+}
+
+const isTransformerError = (error: any): error is TransformerError =>
+  typeof error === "object" &&
+  error !== null &&
+  error.constructor.name === "TransformerError" &&
+  typeof error.code === "string" &&
+  typeof error.message === "string";
+
+const checkJsDocParsingMode = new Singleton(
+  (context: ITypiaContext, file: ts.SourceFile) => {
+    if (
+      typeof file.jsDocParsingMode === "number" &&
+      file.jsDocParsingMode !== 0
+    ) {
+      context.extras.addDiagnostic(
+        ts.createDiagnosticForNode(file, {
+          code: `(typia setup)` as any,
+          key: "jsDocParsingMode",
+          category: ts.DiagnosticCategory.Warning,
+          message: [
+            `Run "npx typia setup" or "npx typia patch" command again.`,
+            ``,
+            `Since TypeScript v5.3 update, "tsc" no more parses JSDoc comments. Therefore, "typia" also cannot utilize those JSDoc comments too, and it damages on some features of "typia" like "comment tags" or "JSON schema" generator.`,
+            ``,
+            `To solve this problem, run "npx typia setup" or "npx typia patch" command to hack the TypeScript compiler to revive the JSDoc parsing feature.`,
+            ``,
+            `  - reference: https://github.com/microsoft/TypeScript/pull/55739`,
+          ].join("\n"),
+        }),
+      );
+    }
+  },
+);

package/src/transformers/IProgrammerProps.ts

@@ -1,11 +1,11 @@
-import ts from "typescript";
-
-import { ITypiaContext } from "./ITypiaContext";
-
-export interface IProgrammerProps {
-  context: ITypiaContext;
-  modulo: ts.LeftHandSideExpression;
-  type: ts.Type;
-  name: string | undefined;
-  init?: ts.Expression | undefined;
-}
+import ts from "typescript";
+
+import { ITypiaContext } from "./ITypiaContext";
+
+export interface IProgrammerProps {
+  context: ITypiaContext;
+  modulo: ts.LeftHandSideExpression;
+  type: ts.Type;
+  name: string | undefined;
+  init?: ts.Expression | undefined;
+}

package/src/transformers/ITransformOptions.ts

@@ -1,62 +1,62 @@
-export interface ITransformOptions {
-  /**
-   * Whether to validate finite number or not.
-   *
-   * If configured true, number typed values would be validated by Number.isNaN().
-   *
-   * However, whatever you configure, it would be ignored when marshaling or parsing.
-   *
-   *   - when marshaling, always be true
-   *     - assertStringify()
-   *     - validateEncode()
-   *   - when parsing, always be false
-   *     - assertParse()
-   *     - isDecode()
-   *
-   * @default false
-   */
-  finite?: undefined | boolean;
-
-  /**
-   * Whether to validate finite number or not.
-   *
-   * If configured true, number typed values would be validated by Number.isFinite().
-   *
-   * However, whatever you configure, it can be ignored in below case.
-   *
-   *   - when `finite` option is true, this option would be ignored
-   *   - when marshaling, always be true
-   *     - assertStringify()
-   *     - validateEncode()
-   *   - when parsing, always be false
-   *     - assertParse()
-   *     - isDecode()
-   *
-   * @default false
-   */
-  numeric?: undefined | boolean;
-
-  /**
-   * Whether to validate functional type or not.
-   *
-   * However, whatever you configure, it becomes false when marshaling or parsing.
-   *
-   * @default false
-   */
-  functional?: undefined | boolean;
-
-  /**
-   * Whether to check undefined value or not.
-   *
-   * JavaScript can assign `undefined` value to a specific property and it is an
-   * issue when validating without allowing superfluous properties. Should undefined
-   * value assigned superfluous property be allowed or not?
-   *
-   * Note that, this option only works on {@link equals} function. Other function
-   * like {@link assertEquals} or {@link validateEquals} would ignore this option
-   * value and always allow the `undefined` value.
-   *
-   * @default true
-   */
-  undefined?: undefined | boolean;
-}
+export interface ITransformOptions {
+  /**
+   * Whether to validate finite number or not.
+   *
+   * If configured true, number typed values would be validated by Number.isNaN().
+   *
+   * However, whatever you configure, it would be ignored when marshaling or parsing.
+   *
+   *   - when marshaling, always be true
+   *     - assertStringify()
+   *     - validateEncode()
+   *   - when parsing, always be false
+   *     - assertParse()
+   *     - isDecode()
+   *
+   * @default false
+   */
+  finite?: undefined | boolean;
+
+  /**
+   * Whether to validate finite number or not.
+   *
+   * If configured true, number typed values would be validated by Number.isFinite().
+   *
+   * However, whatever you configure, it can be ignored in below case.
+   *
+   *   - when `finite` option is true, this option would be ignored
+   *   - when marshaling, always be true
+   *     - assertStringify()
+   *     - validateEncode()
+   *   - when parsing, always be false
+   *     - assertParse()
+   *     - isDecode()
+   *
+   * @default false
+   */
+  numeric?: undefined | boolean;
+
+  /**
+   * Whether to validate functional type or not.
+   *
+   * However, whatever you configure, it becomes false when marshaling or parsing.
+   *
+   * @default false
+   */
+  functional?: undefined | boolean;
+
+  /**
+   * Whether to check undefined value or not.
+   *
+   * JavaScript can assign `undefined` value to a specific property and it is an
+   * issue when validating without allowing superfluous properties. Should undefined
+   * value assigned superfluous property be allowed or not?
+   *
+   * Note that, this option only works on {@link equals} function. Other function
+   * like {@link assertEquals} or {@link validateEquals} would ignore this option
+   * value and always allow the `undefined` value.
+   *
+   * @default true
+   */
+  undefined?: undefined | boolean;
+}

package/src/transformers/ITransformProps.ts

@@ -1,9 +1,9 @@
-import ts from "typescript";
-
-import { ITypiaContext } from "./ITypiaContext";
-
-export interface ITransformProps {
-  context: ITypiaContext;
-  modulo: ts.LeftHandSideExpression;
-  expression: ts.CallExpression;
-}
+import ts from "typescript";
+
+import { ITypiaContext } from "./ITypiaContext";
+
+export interface ITransformProps {
+  context: ITypiaContext;
+  modulo: ts.LeftHandSideExpression;
+  expression: ts.CallExpression;
+}

package/src/transformers/ITypiaContext.ts

@@ -1,18 +1,18 @@
-import ts from "typescript";
-
-import { ImportProgrammer } from "../programmers/ImportProgrammer";
-
-import { ITransformOptions } from "./ITransformOptions";
-
-export interface ITypiaContext {
-  program: ts.Program;
-  compilerOptions: ts.CompilerOptions;
-  checker: ts.TypeChecker;
-  printer: ts.Printer;
-  options: ITransformOptions;
-  transformer: ts.TransformationContext;
-  importer: ImportProgrammer;
-  extras: {
-    addDiagnostic: (diag: ts.Diagnostic) => number;
-  };
-}
+import ts from "typescript";
+
+import { ImportProgrammer } from "../programmers/ImportProgrammer";
+
+import { ITransformOptions } from "./ITransformOptions";
+
+export interface ITypiaContext {
+  program: ts.Program;
+  compilerOptions: ts.CompilerOptions;
+  checker: ts.TypeChecker;
+  printer: ts.Printer;
+  options: ITransformOptions;
+  transformer: ts.TransformationContext;
+  importer: ImportProgrammer;
+  extras: {
+    addDiagnostic: (diag: ts.Diagnostic) => number;
+  };
+}

package/src/transformers/ImportTransformer.ts

@@ -1,81 +1,81 @@
-import path from "path";
-import ts from "typescript";
-
-export namespace ImportTransformer {
-  export const transform =
-    (props: { from: string; to: string }) =>
-    (context: ts.TransformationContext) =>
-    (file: ts.SourceFile) =>
-      transform_file({
-        top: props.from,
-        to: props.to,
-        context,
-        file,
-      });
-
-  const transform_file = (props: {
-    top: string;
-    to: string;
-    context: ts.TransformationContext;
-    file: ts.SourceFile;
-  }): ts.SourceFile => {
-    if (props.file.isDeclarationFile) return props.file;
-
-    const from: string = get_directory_path(
-      path.resolve(props.file.getSourceFile().fileName),
-    );
-    const to: string = from.replace(props.top, props.to);
-
-    return ts.visitEachChild(
-      props.file,
-      (node) =>
-        transform_node({
-          top: props.top,
-          from,
-          to,
-          node,
-        }),
-      props.context,
-    );
-  };
-
-  const transform_node = (props: {
-    top: string;
-    from: string;
-    to: string;
-    node: ts.Node;
-  }) => {
-    if (
-      !ts.isImportDeclaration(props.node) ||
-      !ts.isStringLiteral(props.node.moduleSpecifier)
-    )
-      return props.node;
-
-    const text: string = props.node.moduleSpecifier.text;
-    if (text[0] !== ".") return props.node;
-
-    const location: string = path.resolve(props.from, text);
-    if (location.indexOf(props.top) === 0) return props.node;
-
-    const replaced: string = (() => {
-      const simple: string = path
-        .relative(props.to, location)
-        .split(path.sep)
-        .join("/");
-      return simple[0] === "." ? simple : `./${simple}`;
-    })();
-
-    return ts.factory.createImportDeclaration(
-      undefined,
-      props.node.importClause,
-      ts.factory.createStringLiteral(replaced),
-      props.node.assertClause,
-    );
-  };
-}
-
-const get_directory_path = (file: string): string => {
-  const split: string[] = path.resolve(file).split(path.sep);
-  split.pop();
-  return path.resolve(split.join(path.sep));
-};
+import path from "path";
+import ts from "typescript";
+
+export namespace ImportTransformer {
+  export const transform =
+    (props: { from: string; to: string }) =>
+    (context: ts.TransformationContext) =>
+    (file: ts.SourceFile) =>
+      transform_file({
+        top: props.from,
+        to: props.to,
+        context,
+        file,
+      });
+
+  const transform_file = (props: {
+    top: string;
+    to: string;
+    context: ts.TransformationContext;
+    file: ts.SourceFile;
+  }): ts.SourceFile => {
+    if (props.file.isDeclarationFile) return props.file;
+
+    const from: string = get_directory_path(
+      path.resolve(props.file.getSourceFile().fileName),
+    );
+    const to: string = from.replace(props.top, props.to);
+
+    return ts.visitEachChild(
+      props.file,
+      (node) =>
+        transform_node({
+          top: props.top,
+          from,
+          to,
+          node,
+        }),
+      props.context,
+    );
+  };
+
+  const transform_node = (props: {
+    top: string;
+    from: string;
+    to: string;
+    node: ts.Node;
+  }) => {
+    if (
+      !ts.isImportDeclaration(props.node) ||
+      !ts.isStringLiteral(props.node.moduleSpecifier)
+    )
+      return props.node;
+
+    const text: string = props.node.moduleSpecifier.text;
+    if (text[0] !== ".") return props.node;
+
+    const location: string = path.resolve(props.from, text);
+    if (location.indexOf(props.top) === 0) return props.node;
+
+    const replaced: string = (() => {
+      const simple: string = path
+        .relative(props.to, location)
+        .split(path.sep)
+        .join("/");
+      return simple[0] === "." ? simple : `./${simple}`;
+    })();
+
+    return ts.factory.createImportDeclaration(
+      undefined,
+      props.node.importClause,
+      ts.factory.createStringLiteral(replaced),
+      props.node.assertClause,
+    );
+  };
+}
+
+const get_directory_path = (file: string): string => {
+  const split: string[] = path.resolve(file).split(path.sep);
+  split.pop();
+  return path.resolve(split.join(path.sep));
+};

package/src/transformers/NoTransformConfigurationError.ts

@@ -1,18 +1,18 @@
-/**
- * @internal
- */
-export function NoTransformConfigurationError(name: string): never {
-  throw new Error(
-    [
-      `Error on typia.${name}(): no transform has been configured.`,
-      "",
-      "Read and follow https://typia.io/docs/setup please.",
-      "",
-      [
-        "If you've already completed the setup, it means there's",
-        "a bug in your code. Run `tsc` command so that check what",
-        "is wrong with your code.",
-      ].join(" "),
-    ].join("\n"),
-  );
-}
+/**
+ * @internal
+ */
+export function NoTransformConfigurationError(name: string): never {
+  throw new Error(
+    [
+      `Error on typia.${name}(): no transform has been configured.`,
+      "",
+      "Read and follow https://typia.io/docs/setup please.",
+      "",
+      [
+        "If you've already completed the setup, it means there's",
+        "a bug in your code. Run `tsc` command so that check what",
+        "is wrong with your code.",
+      ].join(" "),
+    ].join("\n"),
+  );
+}