@nestia/migrate 12.0.0-dev.20260612.1 → 12.0.0-dev.20260619.1

package/src/factories/IdentifierFactory.ts

@@ -0,0 +1,84 @@
+import {
+  type Expression,
+  type Identifier,
+  type ParameterDeclaration,
+  type StringLiteral,
+  SyntaxKind,
+  type Token,
+  type TypeNode,
+  factory,
+} from "@ttsc/factory";
+
+import { TypeFactory } from "./TypeFactory";
+
+// Conservative "is this string a syntactically valid JavaScript variable
+// name?" test, inlined to avoid pulling in @typia/utils' full namespace.
+const VARIABLE_REGEX = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+const isVariableName = (str: string): boolean => VARIABLE_REGEX.test(str);
+
+/**
+ * Identifier and member-access helpers. The surface kept here is the subset
+ * nestia generators actually call (`identifier`, `access`, `parameter`).
+ */
+export namespace IdentifierFactory {
+  /**
+   * Build an identifier or string literal depending on whether `name` is a
+   * valid JavaScript identifier.
+   */
+  export const identifier = (name: string): Identifier | StringLiteral =>
+    isVariableName(name)
+      ? factory.createIdentifier(name)
+      : factory.createStringLiteral(name);
+
+  /**
+   * Member access on `input` by `key`. Falls back to element access when the
+   * key is not a valid identifier.
+   */
+  export const access = (
+    input: Expression,
+    key: string,
+    chain?: boolean,
+  ): Expression => {
+    const postfix = identifier(key);
+    if (postfix.kind === "StringLiteral")
+      return chain === true
+        ? factory.createElementAccessChain(
+            input,
+            factory.createToken(SyntaxKind.QuestionDotToken),
+            postfix,
+          )
+        : factory.createElementAccessExpression(input, postfix);
+    return chain === true
+      ? factory.createPropertyAccessChain(
+          input,
+          factory.createToken(SyntaxKind.QuestionDotToken),
+          postfix,
+        )
+      : factory.createPropertyAccessExpression(input, postfix);
+  };
+
+  /**
+   * Parameter declaration with default `any` type when the caller omits one.
+   * Passing a `QuestionToken` as `init` marks the parameter optional.
+   */
+  export const parameter = (
+    name: string | Identifier,
+    type?: TypeNode,
+    init?: Expression | Token,
+  ): ParameterDeclaration => {
+    const isQuestionToken =
+      !!init &&
+      init.kind === "Token" &&
+      (init as Token).token === SyntaxKind.QuestionToken;
+    return factory.createParameterDeclaration(
+      undefined,
+      undefined,
+      name,
+      isQuestionToken
+        ? factory.createToken(SyntaxKind.QuestionToken)
+        : undefined,
+      type ?? TypeFactory.keyword("any"),
+      isQuestionToken ? undefined : (init as Expression | undefined),
+    );
+  };
+}

package/src/factories/LiteralFactory.ts

@@ -0,0 +1,54 @@
+import { type Expression, factory } from "@ttsc/factory";
+
+import { ExpressionFactory } from "./ExpressionFactory";
+import { IdentifierFactory } from "./IdentifierFactory";
+
+const PASSTHROUGH_KINDS = new Set<string>([
+  "ArrowFunction",
+  "CallExpression",
+  "Identifier",
+]);
+
+const isNode = (value: unknown): value is Expression =>
+  typeof value === "object" &&
+  value !== null &&
+  typeof (value as { kind?: unknown }).kind === "string";
+
+/**
+ * Recursive value-to-AST-literal builder. Hands back already-AST inputs
+ * unchanged (so callers can mix factory output with raw JS values inside the
+ * same object/array), and emits the appropriate literal node otherwise.
+ */
+export namespace LiteralFactory {
+  export const write = (input: any): Expression => {
+    if (input === null) return factory.createNull();
+    if (isNode(input) && PASSTHROUGH_KINDS.has(input.kind)) return input;
+    if (Array.isArray(input)) return writeArray(input);
+    if (typeof input === "object") return writeObject(input as object);
+    if (typeof input === "boolean")
+      return input ? factory.createTrue() : factory.createFalse();
+    if (typeof input === "number") return ExpressionFactory.number(input);
+    if (typeof input === "string") return factory.createStringLiteral(input);
+    if (typeof input === "bigint")
+      return factory.createStringLiteral(input.toString());
+    if (typeof input === "function")
+      return factory.createIdentifier("undefined");
+    throw new TypeError("LiteralFactory.write: unsupported input type.");
+  };
+
+  const writeObject = (obj: object): Expression =>
+    factory.createObjectLiteralExpression(
+      Object.entries(obj)
+        .filter(([, value]) => value !== undefined)
+        .map(([key, value]) =>
+          factory.createPropertyAssignment(
+            IdentifierFactory.identifier(key),
+            write(value),
+          ),
+        ),
+      true,
+    );
+
+  const writeArray = (array: readonly any[]): Expression =>
+    factory.createArrayLiteralExpression(array.map(write), true);
+}

package/src/factories/StatementFactory.ts

@@ -0,0 +1,56 @@
+import {
+  type Expression,
+  NodeFlags,
+  type TypeNode,
+  type VariableStatement,
+  factory,
+} from "@ttsc/factory";
+
+import { TypeFactory } from "./TypeFactory";
+
+/** Variable-statement helpers. `constant` emits `const`, `mut` emits `let`. */
+export namespace StatementFactory {
+  export const mut = (props: {
+    name: string;
+    type?: TypeNode | undefined;
+    initializer?: Expression | undefined;
+  }): VariableStatement =>
+    factory.createVariableStatement(
+      undefined,
+      factory.createVariableDeclarationList(
+        [
+          factory.createVariableDeclaration(
+            props.name,
+            undefined,
+            props.type !== undefined
+              ? props.type
+              : props.initializer === undefined
+                ? TypeFactory.keyword("any")
+                : undefined,
+            props.initializer,
+          ),
+        ],
+        NodeFlags.Let,
+      ),
+    );
+
+  export const constant = (props: {
+    name: string;
+    type?: TypeNode | undefined;
+    value?: Expression | undefined;
+  }): VariableStatement =>
+    factory.createVariableStatement(
+      undefined,
+      factory.createVariableDeclarationList(
+        [
+          factory.createVariableDeclaration(
+            props.name,
+            undefined,
+            props.type,
+            props.value,
+          ),
+        ],
+        NodeFlags.Const,
+      ),
+    );
+}

package/src/factories/TypeFactory.ts

@@ -0,0 +1,27 @@
+import { type KeywordTypeNode, SyntaxKind, factory } from "@ttsc/factory";
+
+/**
+ * Higher-level type-keyword factory.
+ *
+ * Wraps {@link factory.createKeywordTypeNode} with a name-based interface so
+ * generator code reads as `TypeFactory.keyword("any")` instead of selecting the
+ * `SyntaxKind.AnyKeyword` token by hand.
+ */
+export namespace TypeFactory {
+  const KEYWORDS = {
+    void: SyntaxKind.VoidKeyword,
+    any: SyntaxKind.AnyKeyword,
+    unknown: SyntaxKind.UnknownKeyword,
+    boolean: SyntaxKind.BooleanKeyword,
+    number: SyntaxKind.NumberKeyword,
+    bigint: SyntaxKind.BigIntKeyword,
+    string: SyntaxKind.StringKeyword,
+    never: SyntaxKind.NeverKeyword,
+    undefined: SyntaxKind.UndefinedKeyword,
+  } as const;
+
+  export type Keyword = keyof typeof KEYWORDS;
+
+  export const keyword = (type: Keyword): KeywordTypeNode =>
+    factory.createKeywordTypeNode(KEYWORDS[type]);
+}

package/src/factories/TypeLiteralFactory.ts

@@ -1,5 +1,6 @@
-import { TypeScriptFactory } from "@nestia/factory";
+import { SyntaxKind, factory } from "@ttsc/factory";
 import * as typiaUtils from "@typia/utils";
+
 import ts from "../internal/ts";
 
 const { NamingConvention } =
@@ -19,42 +20,40 @@ export namespace TypeLiteralFactory {
               : Array.isArray(value)
                 ? generateTuple(value)
                 : generateObject(value)
-            : TypeScriptFactory.createKeywordTypeNode(ts.SyntaxKind.AnyKeyword);
+            : factory.createKeywordTypeNode(SyntaxKind.AnyKeyword);
 
   const generatestring = (str: string) =>
-    TypeScriptFactory.createLiteralTypeNode(
-      TypeScriptFactory.createStringLiteral(str),
-    );
+    factory.createLiteralTypeNode(factory.createStringLiteral(str));
 
   const generateNumber = (num: number) =>
-    TypeScriptFactory.createLiteralTypeNode(
+    factory.createLiteralTypeNode(
       num < 0
-        ? TypeScriptFactory.createPrefixUnaryExpression(
-            ts.SyntaxKind.MinusToken,
-            TypeScriptFactory.createNumericLiteral(-num),
+        ? factory.createPrefixUnaryExpression(
+            SyntaxKind.MinusToken,
+            factory.createNumericLiteral(-num),
           )
-        : TypeScriptFactory.createNumericLiteral(num),
+        : factory.createNumericLiteral(num),
     );
 
   const generateBoolean = (bool: boolean) =>
-    TypeScriptFactory.createLiteralTypeNode(
-      bool ? TypeScriptFactory.createTrue() : TypeScriptFactory.createFalse(),
+    factory.createLiteralTypeNode(
+      bool ? factory.createTrue() : factory.createFalse(),
     );
 
   const generateNull = () =>
-    TypeScriptFactory.createLiteralTypeNode(TypeScriptFactory.createNull());
+    factory.createLiteralTypeNode(factory.createNull());
 
   const generateTuple = (items: any[]) =>
-    TypeScriptFactory.createTupleTypeNode(items.map(generate));
+    factory.createTupleTypeNode(items.map(generate));
 
   const generateObject = (obj: object) =>
-    TypeScriptFactory.createTypeLiteralNode(
+    factory.createTypeLiteralNode(
       Object.entries(obj).map(([key, value]) =>
-        TypeScriptFactory.createPropertySignature(
+        factory.createPropertySignature(
           undefined,
           NamingConvention.variable(key)
-            ? TypeScriptFactory.createIdentifier(key)
-            : TypeScriptFactory.createStringLiteral(key),
+            ? factory.createIdentifier(key)
+            : factory.createStringLiteral(key),
           undefined,
           generate(value),
         ),

package/src/internal/ts.ts

@@ -1,94 +1,75 @@
-// Compatibility shim that replaces `import ts from "./ts"`. The values
-// (`ts.factory`, `ts.SyntaxKind`, `ts.NodeFlags`) are routed to @nestia/factory
-// so the migration generators run without a `typescript` dependency, while the
-// type aliases (`ts.Expression`, `ts.ParameterDeclaration`, …) collapse to the
-// shared @nestia/factory `Node` so existing annotations type-check unchanged.
-//
-// Every alias is intentionally `Node`; the migrate package treats AST nodes as
-// opaque tokens it composes and prints — it never inspects them with
-// TypeScript-Compiler-API guards that would need the original brands.
-
+// Compatibility shim that replaces `import ts from "typescript"`. AST
+// construction now goes through `@ttsc/factory`'s `factory`, `SyntaxKind`, and
+// `NodeFlags`, imported directly where needed; the value side here exposes only
+// the `isUnionTypeNode` guard the migrate generators still call. The type
+// aliases (`ts.Expression`, `ts.ParameterDeclaration`, …) map to the matching
+// `@ttsc/factory` node types so existing annotations keep their precise shapes.
 import {
-  NodeFlags,
-  SyntaxKind,
-  TypeScriptFactory,
+  type Block,
+  type CallExpression,
+  type Decorator,
+  type Expression,
+  type FunctionDeclaration,
+  type Identifier,
+  type KeywordTypeNode,
+  type MethodDeclaration,
+  type ModuleDeclaration,
   type Node,
-} from "@nestia/factory";
-
-interface MutableEmitNode {
-  leadingComments?: Array<{
-    kind: number;
-    text: string;
-    hasTrailingNewLine?: boolean;
-  }>;
-}
+  type ParameterDeclaration,
+  type Statement,
+  type TypeAliasDeclaration,
+  type TypeNode,
+  type TypeReferenceNode,
+  type UnionTypeNode,
+  type VariableStatement,
+} from "@ttsc/factory";
 
 interface TsValue {
-  factory: typeof TypeScriptFactory;
-  NodeFlags: typeof NodeFlags;
-  SyntaxKind: typeof SyntaxKind;
-  addSyntheticLeadingComment(
-    node: Node,
-    kind: number,
-    text: string,
-    hasTrailingNewLine?: boolean,
-  ): Node;
-  isUnionTypeNode(node: Node | undefined): node is Node;
-  isTypeReferenceNode(node: Node | undefined): node is Node;
-  isIdentifier(node: Node | undefined): node is Node;
+  isUnionTypeNode(node: Node | undefined): node is UnionTypeNode;
 }
 
 const ts: TsValue = {
-  factory: TypeScriptFactory,
-  NodeFlags,
-  SyntaxKind,
-  // Pushes a synthetic leading comment onto the node's emit metadata, matching
-  // the surface of the TypeScript-Compiler-API helper of the same name. The
-  // @nestia/factory printer reads `emitNode.leadingComments` and emits them
-  // before the node body.
-  addSyntheticLeadingComment: (
-    node: Node,
-    kind: number,
-    text: string,
-    hasTrailingNewLine?: boolean,
-  ): Node => {
-    const mutable = node as Node & { emitNode?: MutableEmitNode };
-    const emitNode = (mutable.emitNode ??= {});
-    (emitNode.leadingComments ??= []).push({
-      kind,
-      text,
-      hasTrailingNewLine,
-    });
-    return node;
-  },
-  isUnionTypeNode: (node: Node | undefined): node is Node =>
-    !!node && node.kind === SyntaxKind.UnionType,
-  isTypeReferenceNode: (node: Node | undefined): node is Node =>
-    !!node && node.kind === SyntaxKind.TypeReference,
-  isIdentifier: (node: Node | undefined): node is Node =>
-    !!node && node.kind === SyntaxKind.Identifier,
+  isUnionTypeNode: (node: Node | undefined): node is UnionTypeNode =>
+    !!node && node.kind === "UnionTypeNode",
 };
 
+type _Block = Block;
+type _CallExpression = CallExpression;
+type _Decorator = Decorator;
+type _Expression = Expression;
+type _FunctionDeclaration = FunctionDeclaration;
+type _Identifier = Identifier;
+type _KeywordTypeNode = KeywordTypeNode;
+type _MethodDeclaration = MethodDeclaration;
+type _ModuleDeclaration = ModuleDeclaration;
 type _Node = Node;
+type _ParameterDeclaration = ParameterDeclaration;
+type _Statement = Statement;
+type _TypeAliasDeclaration = TypeAliasDeclaration;
+type _TypeNode = TypeNode;
+type _TypeReferenceNode = TypeReferenceNode;
+type _UnionTypeNode = UnionTypeNode;
+type _VariableStatement = VariableStatement;
 
 declare namespace ts {
   export type Node = _Node;
-  export type CallExpression = Node;
-  export type ConciseBody = Node;
-  export type Decorator = Node;
-  export type Expression = Node;
-  export type FunctionDeclaration = Node;
-  export type Identifier = Node;
-  export type KeywordTypeNode = Node;
-  export type MethodDeclaration = Node;
-  export type ModuleDeclaration = Node;
-  export type ParameterDeclaration = Node;
-  export type Statement = Node;
-  export type TypeAliasDeclaration = Node;
-  export type TypeNode = Node;
-  export type TypeReferenceNode = Node;
-  export type UnionTypeNode = Node;
-  export type VariableStatement = Node;
+  export type Block = _Block;
+  export type CallExpression = _CallExpression;
+  export type ConciseBody = _Block | _Expression;
+  export type Decorator = _Decorator;
+  export type Expression = _Expression;
+  export type FunctionDeclaration = _FunctionDeclaration;
+  export type Identifier = _Identifier;
+  export type KeywordTypeNode = _KeywordTypeNode;
+  export type MethodDeclaration = _MethodDeclaration;
+  export type ModuleDeclaration = _ModuleDeclaration;
+  export type ParameterDeclaration = _ParameterDeclaration;
+  export type Statement = _Statement;
+  export type TypeAliasDeclaration = _TypeAliasDeclaration;
+  export type TypeNode = _TypeNode;
+  export type TypeReferenceNode = _TypeReferenceNode;
+  export type UnionTypeNode = _UnionTypeNode;
+  export type VariableStatement = _VariableStatement;
 }
 
 export default ts;

package/src/programmers/NestiaMigrateApiFileProgrammer.ts

@@ -1,7 +1,7 @@
-import { TypeScriptFactory } from "@nestia/factory";
+import { factory } from "@ttsc/factory";
 import { IHttpMigrateRoute, OpenApi } from "@typia/interface";
-import ts from "../internal/ts";
 
+import ts from "../internal/ts";
 import { INestiaMigrateConfig } from "../structures/INestiaMigrateConfig";
 import { FilePrinter } from "../utils/FilePrinter";
 import { NestiaMigrateApiFunctionProgrammer } from "./NestiaMigrateApiFunctionProgrammer";
@@ -42,14 +42,11 @@ export namespace NestiaMigrateApiFileProgrammer {
         (ref) => `../${"../".repeat(props.namespace.length)}structures/${ref}`,
       ),
       ...[...props.children].map((child) =>
-        TypeScriptFactory.createExportDeclaration(
+        factory.createExportDeclaration(
           undefined,
           false,
-          TypeScriptFactory.createNamespaceExport(
-            TypeScriptFactory.createIdentifier(child),
-          ),
-          TypeScriptFactory.createStringLiteral(`./${child}/index`),
-          undefined,
+          factory.createNamespaceExport(factory.createIdentifier(child)),
+          factory.createStringLiteral(`./${child}/index`),
         ),
       ),
       ...statements,