@typia/transform 12.0.0-dev.20260225

package/src/FileTransformer.ts

@@ -0,0 +1,143 @@
+import { ITypiaContext, ImportProgrammer } from "@typia/core";
+import { Singleton } from "@typia/utils";
+import ts from "typescript";
+
+import { NodeTransformer } from "./NodeTransformer";
+import { TransformerError } from "./TransformerError";
+
+/**
+ * TypeScript source file transformer for typia.
+ *
+ * Entry point for typia's compile-time transformation. Traverses AST nodes,
+ * transforms `typia.*` function calls into optimized runtime code, and injects
+ * required imports. Skips declaration files.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+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_",
+        runtime: environments.options.runtime,
+      });
+      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/ITransformProps.ts

@@ -0,0 +1,20 @@
+import { ITypiaContext } from "@typia/core";
+import ts from "typescript";
+
+/**
+ * Properties for individual typia function transformation.
+ *
+ * Passed to each transformer handler when processing a `typia.*()` call.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export interface ITransformProps {
+  /** Typia transformation context with type checker and utilities. */
+  context: ITypiaContext;
+
+  /** Module expression (e.g., `typia` in `typia.is<T>()`). */
+  modulo: ts.LeftHandSideExpression;
+
+  /** The original `typia.*<T>()` call expression being transformed. */
+  expression: ts.CallExpression;
+}

package/src/ImportTransformer.ts

@@ -0,0 +1,262 @@
+import path from "path";
+import ts from "typescript";
+
+/**
+ * Transforms import paths for typia build output.
+ *
+ * Rewrites relative import paths when building typia packages. Also removes
+ * unused typia imports that only contained transformable function calls (since
+ * those are replaced at compile time).
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+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);
+
+    // First pass: transform relative imports
+    let transformedFile = ts.visitEachChild(
+      props.file,
+      (node) =>
+        transform_node({
+          top: props.top,
+          from,
+          to,
+          node,
+        }),
+      props.context,
+    );
+
+    // Second pass: remove unused typia imports
+    transformedFile = removeUnusedTypiaImports(transformedFile);
+
+    return transformedFile;
+  };
+
+  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));
+};
+
+/** Remove unused typia imports that are only used in transformable calls */
+const removeUnusedTypiaImports = (file: ts.SourceFile): ts.SourceFile => {
+  // Find typia imports and collect all identifiers
+  interface ImportMetadata {
+    declaration: ts.ImportDeclaration;
+    default: boolean;
+  }
+  const imports: Map<string, ImportMetadata> = new Map();
+  for (const stmt of file.statements) {
+    if (
+      ts.isImportDeclaration(stmt) === false ||
+      ts.isStringLiteral(stmt.moduleSpecifier) === false ||
+      stmt.moduleSpecifier.text !== "typia" ||
+      stmt.importClause === undefined
+    )
+      continue;
+
+    // Track default import (import typia from 'typia')
+    if (stmt.importClause.name)
+      imports.set(stmt.importClause.name.text, {
+        declaration: stmt,
+        default: true,
+      });
+
+    // Track named imports (import { tags } from 'typia') - keep these
+    if (
+      stmt.importClause.namedBindings &&
+      ts.isNamedImports(stmt.importClause.namedBindings)
+    )
+      for (const element of stmt.importClause.namedBindings.elements)
+        imports.set(element.name.text, {
+          declaration: stmt,
+          default: false,
+        });
+  }
+  if (imports.size === 0) return file; // No typia imports to check
+
+  // Find usage of typia identifiers that are NOT transformable calls
+  const nonTransformableUsage = new Set<string>();
+  const checkUsage = (node: ts.Node) => {
+    if (ts.isIdentifier(node) && imports.has(node.text)) {
+      const identifier: string = node.text;
+      // Check if this identifier is being used as part of a property access
+      if (
+        node.parent &&
+        ts.isPropertyAccessExpression(node.parent) &&
+        node.parent.expression === node
+      ) {
+        // This is typia.something - check if it's a transformable call pattern
+        if (!isLikelyTransformableCall(node.parent))
+          nonTransformableUsage.add(identifier);
+      } else
+        // Direct usage of the typia identifier (not as property access)
+        // This is definitely non-transformable usage
+        nonTransformableUsage.add(identifier);
+    }
+    ts.forEachChild(node, checkUsage);
+  };
+
+  // Check all statements except import declarations
+  for (const stmt of file.statements)
+    if (
+      !ts.isImportDeclaration(stmt) ||
+      !ts.isStringLiteral(stmt.moduleSpecifier) ||
+      stmt.moduleSpecifier.text !== "typia"
+    )
+      checkUsage(stmt);
+
+  // Update import statements
+  const newStatements: ts.Statement[] = file.statements
+    .map((stmt) => {
+      if (
+        ts.isImportDeclaration(stmt) &&
+        ts.isStringLiteral(stmt.moduleSpecifier) &&
+        stmt.moduleSpecifier.text === "typia" &&
+        stmt.importClause
+      ) {
+        const newImportClause = filterTypiaImportClause(
+          stmt.importClause,
+          nonTransformableUsage,
+        );
+        if (newImportClause)
+          return ts.factory.createImportDeclaration(
+            stmt.modifiers,
+            newImportClause,
+            stmt.moduleSpecifier,
+            stmt.attributes,
+          );
+        return null; // Skip adding the import if all imports are unused
+      }
+      return stmt;
+    })
+    .filter((stmt) => stmt !== null);
+  return ts.factory.updateSourceFile(
+    file,
+    newStatements,
+    file.isDeclarationFile,
+    file.referencedFiles,
+    file.typeReferenceDirectives,
+    file.hasNoDefaultLib,
+    file.libReferenceDirectives,
+  );
+};
+
+/**
+ * Check if a property access expression looks like a transformable typia call
+ * This uses heuristics to detect patterns like typia.xxx(),
+ * typia.namespace.xxx()
+ */
+const isLikelyTransformableCall = (
+  node: ts.PropertyAccessExpression,
+): boolean => {
+  // Check if this is eventually part of a call expression
+  let current: ts.Node = node;
+
+  // Walk up the chain to find if this leads to a call expression
+  // Handle patterns like: typia.xxx(), typia.namespace.xxx()
+  while (ts.isPropertyAccessExpression(current)) {
+    current = current.parent;
+  }
+
+  // If the final result is a call expression, this is likely transformable
+  if (
+    ts.isCallExpression(current) &&
+    (current.expression === node ||
+      (ts.isPropertyAccessExpression(current.expression) &&
+        isTypiaPropertyChain(current.expression)))
+  ) {
+    return true;
+  }
+
+  return false;
+};
+
+/** Check if a property access expression is part of a typia.xxx.yyy chain */
+const isTypiaPropertyChain = (node: ts.PropertyAccessExpression): boolean => {
+  let current: ts.Expression = node;
+
+  while (ts.isPropertyAccessExpression(current)) {
+    current = current.expression;
+  }
+
+  return ts.isIdentifier(current) && current.text === "typia";
+};
+
+/** Filter import clause to remove unused default imports */
+const filterTypiaImportClause = (
+  importClause: ts.ImportClause,
+  usedImports: Set<string>,
+): ts.ImportClause | undefined => {
+  const hasDefaultImport =
+    importClause.name && usedImports.has(importClause.name.text);
+  const namedBindings = importClause.namedBindings; // Always keep named bindings like { tags }
+
+  // Return undefined if no imports are used
+  if (!hasDefaultImport && !namedBindings) {
+    return undefined;
+  }
+
+  return ts.factory.createImportClause(
+    importClause.isTypeOnly,
+    hasDefaultImport ? importClause.name : undefined,
+    namedBindings,
+  );
+};

package/src/NodeTransformer.ts

@@ -0,0 +1,25 @@
+import { ITypiaContext } from "@typia/core";
+import ts from "typescript";
+
+import { CallExpressionTransformer } from "./CallExpressionTransformer";
+
+/**
+ * TypeScript AST node transformer.
+ *
+ * Delegates call expression nodes to {@link CallExpressionTransformer} for
+ * potential `typia.*` function transformation. Non-call nodes pass through.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export namespace NodeTransformer {
+  export const transform = (props: {
+    context: ITypiaContext;
+    node: ts.Node;
+  }): ts.Node | null =>
+    ts.isCallExpression(props.node) && props.node.parent
+      ? CallExpressionTransformer.transform({
+          context: props.context,
+          expression: props.node,
+        })
+      : props.node;
+}

package/src/TransformerError.ts

@@ -0,0 +1,85 @@
+import { MetadataFactory, MetadataObjectType } from "@typia/core";
+import { NamingConvention } from "@typia/utils";
+
+/**
+ * Error thrown during typia transformation.
+ *
+ * `TransformerError` is thrown when `typia.*<T>()` receives unsupported types
+ * or invalid configurations at compile time. The error message details which
+ * types failed and why.
+ *
+ * Common causes:
+ *
+ * - Tuples in LLM schema (not supported by most LLMs)
+ * - Recursive types without `$ref` support
+ * - `any` types without explicit handling
+ * - Native classes not serializable to JSON
+ *
+ * Use {@link from} to create from {@link MetadataFactory.IError} instances.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export class TransformerError extends Error {
+  /** Error code identifying the error type. */
+  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 {
+  /** Constructor properties for TransformerError. */
+  export interface IProps {
+    /** Error code identifying the error type. */
+    code: string;
+
+    /** Human-readable error message. */
+    message: string;
+  }
+
+  /**
+   * Create error from metadata factory errors.
+   *
+   * Formats multiple type errors into a single TransformerError.
+   */
+  export const from = (props: {
+    code: string;
+    errors: MetadataFactory.IError[];
+  }): TransformerError => {
+    const body: string = props.errors
+      .map((e) => {
+        const subject: string =
+          e.explore.object === null
+            ? ""
+            : join(e.explore.object)(e.explore.property);
+        const middle: string = e.explore.parameter
+          ? `(parameter: ${JSON.stringify(e.explore.parameter)})`
+          : e.explore.output
+            ? "(return type)"
+            : "";
+        const type: string = `${subject.length ? `${subject}: ` : ""}${e.name}`;
+        return `- ${type}${middle}\n${e.messages
+          .map((msg) => `  - ${msg}`)
+          .join("\n")}`;
+      })
+      .join("\n\n");
+    return new TransformerError({
+      code: props.code,
+      message: `unsupported type detected\n\n${body}`,
+    });
+  };
+
+  const join =
+    (object: MetadataObjectType) => (key: string | object | null) => {
+      if (key === null) return object.name;
+      else if (typeof key === "object") return `${object.name}[key]`;
+      else if (NamingConvention.variable(key)) return `${object.name}.${key}`;
+      return `${object.name}[${JSON.stringify(key)}]`;
+    };
+}

package/src/TypiaGenerator.ts

@@ -0,0 +1,174 @@
+import fs from "fs";
+import path from "path";
+import ts from "typescript";
+
+import { ImportTransformer } from "./ImportTransformer";
+import { transform } from "./transform";
+
+export namespace TypiaGenerator {
+  export interface ILocation {
+    input: string;
+    output: string;
+    project: string;
+  }
+
+  export const build = async (
+    location: TypiaGenerator.ILocation,
+  ): Promise<void> => {
+    location.input = path.resolve(location.input);
+    location.output = path.resolve(location.output);
+
+    if ((await is_directory(location.input)) === false)
+      throw new URIError(
+        "Error on TypiaGenerator.generate(): input path is not a directory.",
+      );
+    else if (fs.existsSync(location.output) === false)
+      await fs.promises.mkdir(location.output, { recursive: true });
+    else if ((await is_directory(location.output)) === false) {
+      const parent: string = path.join(location.output, "..");
+      if ((await is_directory(parent)) === false)
+        throw new URIError(
+          "Error on TypiaGenerator.generate(): output path is not a directory.",
+        );
+      await fs.promises.mkdir(location.output);
+    }
+
+    // CREATE PROGRAM
+    const { options: compilerOptions } = ts.parseJsonConfigFileContent(
+      ts.readConfigFile(location.project, ts.sys.readFile).config,
+      {
+        fileExists: ts.sys.fileExists,
+        readFile: ts.sys.readFile,
+        readDirectory: ts.sys.readDirectory,
+        useCaseSensitiveFileNames: ts.sys.useCaseSensitiveFileNames,
+      },
+      path.dirname(location.project),
+    );
+
+    const program: ts.Program = ts.createProgram(
+      await (async () => {
+        const container: string[] = [];
+        await gather({
+          location,
+          container,
+          from: location.input,
+          to: location.output,
+        });
+        return container;
+      })(),
+      compilerOptions,
+    );
+
+    // DO TRANSFORM
+    const diagnostics: ts.Diagnostic[] = [];
+    const result: ts.TransformationResult<ts.SourceFile> = ts.transform(
+      program
+        .getSourceFiles()
+        .filter(
+          (file) =>
+            !file.isDeclarationFile &&
+            path.resolve(file.fileName).indexOf(location.input) !== -1,
+        ),
+      [
+        ImportTransformer.transform({
+          from: location.input,
+          to: location.output,
+        }),
+        transform(
+          program,
+          ((compilerOptions.plugins as any[]) ?? []).find(
+            (p: any) =>
+              p.transform === "typia/src/transform" ||
+              p.transform === "../src/transform.ts",
+          ) ?? {},
+          {
+            addDiagnostic: (diag) => diagnostics.push(diag),
+          },
+        ),
+      ],
+      program.getCompilerOptions(),
+    );
+
+    // TRACE ERRORS
+    for (const diag of diagnostics) {
+      const file: string = diag.file
+        ? path.relative(diag.file.fileName, process.cwd())
+        : "(unknown file)";
+      const category: string =
+        diag.category === ts.DiagnosticCategory.Warning
+          ? "warning"
+          : diag.category === ts.DiagnosticCategory.Error
+            ? "error"
+            : diag.category === ts.DiagnosticCategory.Suggestion
+              ? "suggestion"
+              : diag.category === ts.DiagnosticCategory.Message
+                ? "message"
+                : "unknown";
+      const [line, pos] = diag.file
+        ? (() => {
+            const lines: string[] = diag
+              .file!.text.substring(0, diag.start)
+              .split("\n");
+            if (lines.length === 0) return [0, 0];
+            return [lines.length, lines.at(-1)!.length + 1];
+          })()
+        : [0, 0];
+      console.error(
+        `${file}:${line}:${pos} - ${category} TS${diag.code}: ${diag.messageText}`,
+      );
+    }
+    if (diagnostics.length) process.exit(-1);
+
+    // ARCHIVE TRANSFORMED FILES
+    const printer: ts.Printer = ts.createPrinter({
+      newLine: ts.NewLineKind.LineFeed,
+    });
+    for (const file of result.transformed) {
+      const to: string = path
+        .resolve(file.fileName)
+        .replace(location.input, location.output);
+
+      const content: string = printer.printFile(file);
+      await fs.promises.writeFile(to, content, "utf8");
+    }
+  };
+
+  const is_directory = async (current: string): Promise<boolean> => {
+    const stat: fs.Stats = await fs.promises.stat(current);
+    return stat.isDirectory();
+  };
+
+  const gather = async (props: {
+    location: ILocation;
+    container: string[];
+    from: string;
+    to: string;
+  }) => {
+    if (props.from === props.location.output) return;
+    else if (fs.existsSync(props.to) === false)
+      await fs.promises.mkdir(props.to);
+
+    for (const file of await fs.promises.readdir(props.from)) {
+      const next: string = path.join(props.from, file);
+      const stat: fs.Stats = await fs.promises.stat(next);
+
+      if (stat.isDirectory()) {
+        await gather({
+          location: props.location,
+          container: props.container,
+          from: next,
+          to: path.join(props.to, file),
+        });
+        continue;
+      } else if (is_supported_extension(file)) props.container.push(next);
+    }
+  };
+
+  const is_supported_extension = (filename: string): boolean => {
+    // avoid using look-behind assertion as it is not marked as Baseline Widely Available
+    return TS_PATTERN.test(filename) && !DTS_PATTERN.test(filename);
+  };
+}
+
+const TS_PATTERN = /\.[cm]?tsx?$/;
+const DTS_PATTERN = /\.d\.[cm]?tsx?$/;