@typia/transform 12.0.0-dev.20260309 → 12.0.0-dev.20260311

package/src/TransformerError.ts

@@ -1,85 +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)}]`;
-    };
-}
+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

@@ -1,172 +1,172 @@
-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/lib/transform",
-          ) ?? {},
-          {
-            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?$/;
+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/lib/transform",
+          ) ?? {},
+          {
+            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?$/;

package/src/features/AssertTransformer.ts

@@ -1,24 +1,24 @@
-import { AssertProgrammer } from "@typia/core";
-
-import { ITransformProps } from "../ITransformProps";
-import { GenericTransformer } from "../internal/GenericTransformer";
-
-export namespace AssertTransformer {
-  export const transform =
-    (config: AssertProgrammer.IConfig) => (props: ITransformProps) =>
-      GenericTransformer.scalar({
-        ...props,
-        method: config.equals
-          ? config.guard
-            ? "assertGuardEquals"
-            : "assertEquals"
-          : config.guard
-            ? "assertGuard"
-            : "assert",
-        write: (x) =>
-          AssertProgrammer.write({
-            ...x,
-            config,
-          }),
-      });
-}
+import { AssertProgrammer } from "@typia/core";
+
+import { ITransformProps } from "../ITransformProps";
+import { GenericTransformer } from "../internal/GenericTransformer";
+
+export namespace AssertTransformer {
+  export const transform =
+    (config: AssertProgrammer.IConfig) => (props: ITransformProps) =>
+      GenericTransformer.scalar({
+        ...props,
+        method: config.equals
+          ? config.guard
+            ? "assertGuardEquals"
+            : "assertEquals"
+          : config.guard
+            ? "assertGuard"
+            : "assert",
+        write: (x) =>
+          AssertProgrammer.write({
+            ...x,
+            config,
+          }),
+      });
+}

package/src/features/CreateAssertTransformer.ts

@@ -1,24 +1,24 @@
-import { AssertProgrammer } from "@typia/core";
-
-import { ITransformProps } from "../ITransformProps";
-import { GenericTransformer } from "../internal/GenericTransformer";
-
-export namespace CreateAssertTransformer {
-  export const transform =
-    (config: AssertProgrammer.IConfig) => (props: ITransformProps) =>
-      GenericTransformer.factory({
-        ...props,
-        method: config.equals
-          ? config.guard
-            ? "assertGuardEquals"
-            : "assertEquals"
-          : config.guard
-            ? "assertGuard"
-            : "assert",
-        write: (x) =>
-          AssertProgrammer.write({
-            ...x,
-            config,
-          }),
-      });
-}
+import { AssertProgrammer } from "@typia/core";
+
+import { ITransformProps } from "../ITransformProps";
+import { GenericTransformer } from "../internal/GenericTransformer";
+
+export namespace CreateAssertTransformer {
+  export const transform =
+    (config: AssertProgrammer.IConfig) => (props: ITransformProps) =>
+      GenericTransformer.factory({
+        ...props,
+        method: config.equals
+          ? config.guard
+            ? "assertGuardEquals"
+            : "assertEquals"
+          : config.guard
+            ? "assertGuard"
+            : "assert",
+        write: (x) =>
+          AssertProgrammer.write({
+            ...x,
+            config,
+          }),
+      });
+}

package/src/features/CreateIsTransformer.ts

@@ -1,18 +1,18 @@
-import { IsProgrammer } from "@typia/core";
-
-import { ITransformProps } from "../ITransformProps";
-import { GenericTransformer } from "../internal/GenericTransformer";
-
-export namespace CreateIsTransformer {
-  export const transform =
-    (config: IsProgrammer.IConfig) => (props: ITransformProps) =>
-      GenericTransformer.factory({
-        ...props,
-        method: config.equals ? "equals" : "is",
-        write: (x) =>
-          IsProgrammer.write({
-            ...x,
-            config,
-          }),
-      });
-}
+import { IsProgrammer } from "@typia/core";
+
+import { ITransformProps } from "../ITransformProps";
+import { GenericTransformer } from "../internal/GenericTransformer";
+
+export namespace CreateIsTransformer {
+  export const transform =
+    (config: IsProgrammer.IConfig) => (props: ITransformProps) =>
+      GenericTransformer.factory({
+        ...props,
+        method: config.equals ? "equals" : "is",
+        write: (x) =>
+          IsProgrammer.write({
+            ...x,
+            config,
+          }),
+      });
+}