typia 5.3.0-dev.20231120 → 5.3.0-dev.20231126

package/src/transformers/FileTransformer.ts

@@ -1,57 +1,91 @@
-import ts from "typescript";
-
-import { IProject } from "./IProject";
-import { NodeTransformer } from "./NodeTransformer";
-import { TransformerError } from "./TransformerError";
-
-export namespace FileTransformer {
-  export const transform =
-    (project: Omit<IProject, "context">) =>
-    (context: ts.TransformationContext) =>
-    (file: ts.SourceFile): ts.SourceFile => {
-      if (file.isDeclarationFile) return file;
-      return ts.visitEachChild(
-        file,
-        (node) => iterate_node({ ...project, context })(context)(node),
-        context,
-      );
-    };
-
-  const iterate_node =
-    (project: IProject) =>
-    (context: ts.TransformationContext) =>
-    (node: ts.Node): ts.Node =>
-      ts.visitEachChild(
-        try_transform_node(project)(node) ?? node,
-        (child) => iterate_node(project)(context)(child),
-        context,
-      );
-
-  const try_transform_node =
-    (project: IProject) =>
-    (node: ts.Node): ts.Node | null => {
-      try {
-        return NodeTransformer.transform(project)(node);
-      } catch (exp) {
-        // ONLY ACCEPT TRANSFORMER-ERROR
-        if (!isTransformerError(exp)) throw exp;
-
-        // REPORT DIAGNOSTIC
-        const diagnostic = ts.createDiagnosticForNode(node, {
-          key: exp.code,
-          category: ts.DiagnosticCategory.Error,
-          message: exp.message,
-          code: `(${exp.code})` as any,
-        });
-        project.extras.addDiagnostic(diagnostic);
-        return null;
-      }
-    };
-}
-
-const isTransformerError = (error: any): error is TransformerError =>
-  typeof error === "object" &&
-  error !== null &&
-  error.constructor.name === "TransformerError" &&
-  typeof error.code === "string" &&
-  typeof error.message === "string";
+import ts from "typescript";
+
+import { Singleton } from "../utils/Singleton";
+
+import { IProject } from "./IProject";
+import { NodeTransformer } from "./NodeTransformer";
+import { TransformerError } from "./TransformerError";
+
+export namespace FileTransformer {
+  export const transform =
+    (environments: Omit<IProject, "context">) =>
+    (context: ts.TransformationContext) =>
+    (file: ts.SourceFile): ts.SourceFile => {
+      if (file.isDeclarationFile) return file;
+
+      const project: IProject = {
+        ...environments,
+        context,
+      };
+      checkJsDocParsingMode.get(project, file);
+
+      return ts.visitEachChild(
+        file,
+        (node) => iterate_node(project)(node),
+        context,
+      );
+    };
+
+  const iterate_node =
+    (project: IProject) =>
+    (node: ts.Node): ts.Node =>
+      ts.visitEachChild(
+        try_transform_node(project)(node) ?? node,
+        (child) => iterate_node(project)(child),
+        project.context,
+      );
+
+  const try_transform_node =
+    (project: IProject) =>
+    (node: ts.Node): ts.Node | null => {
+      try {
+        return NodeTransformer.transform(project)(node);
+      } catch (exp) {
+        // ONLY ACCEPT TRANSFORMER-ERROR
+        if (!isTransformerError(exp)) throw exp;
+
+        // REPORT DIAGNOSTIC
+        const diagnostic = ts.createDiagnosticForNode(node, {
+          key: exp.code,
+          category: ts.DiagnosticCategory.Error,
+          message: exp.message,
+          code: `(${exp.code})` as any,
+        });
+        project.extras.addDiagnostic(diagnostic);
+        return null;
+      }
+    };
+}
+
+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(
+  (project: IProject, file: ts.SourceFile) => {
+    if (
+      typeof file.jsDocParsingMode === "number" &&
+      file.jsDocParsingMode !== 0
+    ) {
+      project.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, and it would damage 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/IProject.ts

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

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/ImportTransformer.ts

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

package/src/transformers/NodeTransformer.ts

@@ -1,13 +1,13 @@
-import ts from "typescript";
-
-import { CallExpressionTransformer } from "./CallExpressionTransformer";
-import { IProject } from "./IProject";
-
-export namespace NodeTransformer {
-  export const transform =
-    (project: IProject) =>
-    (expression: ts.Node): ts.Node | null =>
-      ts.isCallExpression(expression) && expression.parent
-        ? CallExpressionTransformer.transform(project)(expression)
-        : expression;
-}
+import ts from "typescript";
+
+import { CallExpressionTransformer } from "./CallExpressionTransformer";
+import { IProject } from "./IProject";
+
+export namespace NodeTransformer {
+  export const transform =
+    (project: IProject) =>
+    (expression: ts.Node): ts.Node | null =>
+      ts.isCallExpression(expression) && expression.parent
+        ? CallExpressionTransformer.transform(project)(expression)
+        : expression;
+}

package/src/transformers/TransformerError.ts

@@ -1,55 +1,55 @@
-import { MetadataFactory } from "../factories/MetadataFactory";
-
-import { MetadataObject } from "../schemas/metadata/MetadataObject";
-
-import { Escaper } from "../utils/Escaper";
-
-export class TransformerError extends Error {
-  public readonly code: string;
-
-  public constructor(props: TransformerError.IProps) {
-    super(props.message);
-    this.code = props.code;
-
-    // INHERITANCE POLYFILL
-    const proto = new.target.prototype;
-    if (Object.setPrototypeOf) Object.setPrototypeOf(this, proto);
-    else (this as any).__proto__ = proto;
-  }
-}
-export namespace TransformerError {
-  export interface IProps {
-    code: string;
-    message: string;
-  }
-
-  export const from =
-    (method: string) =>
-    (errors: MetadataFactory.IError[]): TransformerError => {
-      const body: string = errors
-        .map((e) => {
-          const subject: string =
-            e.explore.object === null
-              ? ""
-              : join(e.explore.object)(e.explore.property);
-          const type: string = `${subject.length ? `${subject}: ` : ""}${
-            e.name
-          }`;
-          return `- ${type}\n${e.messages
-            .map((msg) => `  - ${msg}`)
-            .join("\n")}`;
-        })
-        .join("\n\n");
-      return new TransformerError({
-        code: method,
-        message: `unsupported type detected\n\n${body}`,
-      });
-    };
-
-  const join = (object: MetadataObject) => (key: string | object | null) => {
-    if (key === null) return object.name;
-    else if (typeof key === "object") return `${object.name}[key]`;
-    else if (Escaper.variable(key)) return `${object.name}.${key}`;
-    return `${object.name}[${JSON.stringify(key)}]`;
-  };
-}
+import { MetadataFactory } from "../factories/MetadataFactory";
+
+import { MetadataObject } from "../schemas/metadata/MetadataObject";
+
+import { Escaper } from "../utils/Escaper";
+
+export class TransformerError extends Error {
+  public readonly code: string;
+
+  public constructor(props: TransformerError.IProps) {
+    super(props.message);
+    this.code = props.code;
+
+    // INHERITANCE POLYFILL
+    const proto = new.target.prototype;
+    if (Object.setPrototypeOf) Object.setPrototypeOf(this, proto);
+    else (this as any).__proto__ = proto;
+  }
+}
+export namespace TransformerError {
+  export interface IProps {
+    code: string;
+    message: string;
+  }
+
+  export const from =
+    (method: string) =>
+    (errors: MetadataFactory.IError[]): TransformerError => {
+      const body: string = errors
+        .map((e) => {
+          const subject: string =
+            e.explore.object === null
+              ? ""
+              : join(e.explore.object)(e.explore.property);
+          const type: string = `${subject.length ? `${subject}: ` : ""}${
+            e.name
+          }`;
+          return `- ${type}\n${e.messages
+            .map((msg) => `  - ${msg}`)
+            .join("\n")}`;
+        })
+        .join("\n\n");
+      return new TransformerError({
+        code: method,
+        message: `unsupported type detected\n\n${body}`,
+      });
+    };
+
+  const join = (object: MetadataObject) => (key: string | object | null) => {
+    if (key === null) return object.name;
+    else if (typeof key === "object") return `${object.name}[key]`;
+    else if (Escaper.variable(key)) return `${object.name}.${key}`;
+    return `${object.name}[${JSON.stringify(key)}]`;
+  };
+}

package/src/transformers/features/AssertTransformer.ts

@@ -1,16 +1,16 @@
-import { AssertProgrammer } from "../../programmers/AssertProgrammer";
-
-import { GenericTransformer } from "../internal/GenericTransformer";
-
-export namespace AssertTransformer {
-  export const transform = (props: { equals: boolean; guard: boolean }) =>
-    GenericTransformer.scalar(
-      props.equals
-        ? props.guard
-          ? "assertGuardEquals"
-          : "assertEquals"
-        : props.guard
-        ? "assertGuard"
-        : "assert",
-    )((project) => (modulo) => AssertProgrammer.write(project)(modulo)(props));
-}
+import { AssertProgrammer } from "../../programmers/AssertProgrammer";
+
+import { GenericTransformer } from "../internal/GenericTransformer";
+
+export namespace AssertTransformer {
+  export const transform = (props: { equals: boolean; guard: boolean }) =>
+    GenericTransformer.scalar(
+      props.equals
+        ? props.guard
+          ? "assertGuardEquals"
+          : "assertEquals"
+        : props.guard
+        ? "assertGuard"
+        : "assert",
+    )((project) => (modulo) => AssertProgrammer.write(project)(modulo)(props));
+}

package/src/transformers/features/CreateAssertTransformer.ts

@@ -1,16 +1,16 @@
-import { AssertProgrammer } from "../../programmers/AssertProgrammer";
-
-import { GenericTransformer } from "../internal/GenericTransformer";
-
-export namespace CreateAssertTransformer {
-  export const transform = (props: { equals: boolean; guard: boolean }) =>
-    GenericTransformer.factory(
-      props.equals
-        ? props.guard
-          ? "createAssertGuardEquals"
-          : "createAssertEquals"
-        : props.guard
-        ? "createAssertGuard"
-        : "createAssert",
-    )((project) => (modulo) => AssertProgrammer.write(project)(modulo)(props));
-}
+import { AssertProgrammer } from "../../programmers/AssertProgrammer";
+
+import { GenericTransformer } from "../internal/GenericTransformer";
+
+export namespace CreateAssertTransformer {
+  export const transform = (props: { equals: boolean; guard: boolean }) =>
+    GenericTransformer.factory(
+      props.equals
+        ? props.guard
+          ? "createAssertGuardEquals"
+          : "createAssertEquals"
+        : props.guard
+        ? "createAssertGuard"
+        : "createAssert",
+    )((project) => (modulo) => AssertProgrammer.write(project)(modulo)(props));
+}

package/src/transformers/features/CreateIsTransformer.ts

@@ -1,10 +1,10 @@
-import { IsProgrammer } from "../../programmers/IsProgrammer";
-
-import { GenericTransformer } from "../internal/GenericTransformer";
-
-export namespace CreateIsTransformer {
-  export const transform = (equals: boolean) =>
-    GenericTransformer.factory(equals ? "createEquals" : "createIs")(
-      (project) => (modulo) => IsProgrammer.write(project)(modulo)(equals),
-    );
-}
+import { IsProgrammer } from "../../programmers/IsProgrammer";
+
+import { GenericTransformer } from "../internal/GenericTransformer";
+
+export namespace CreateIsTransformer {
+  export const transform = (equals: boolean) =>
+    GenericTransformer.factory(equals ? "createEquals" : "createIs")(
+      (project) => (modulo) => IsProgrammer.write(project)(modulo)(equals),
+    );
+}