@nestia/sdk 12.0.0-dev.20260612.2 → 12.0.0-rc.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/generates/CloneGenerator.ts

@@ -1,9 +1,10 @@
 import {
-  Node,
+  type Node,
   NodeFlags,
+  type Statement,
   SyntaxKind,
-  TypeScriptFactory,
-} from "@nestia/factory";
+  factory,
+} from "@ttsc/factory";
 import fs from "fs";
 
 import { INestiaProject } from "../structures/INestiaProject";
@@ -60,10 +61,10 @@ export namespace CloneGenerator {
         for (const child of modulo.children.values())
           internal.push(...iterate(importer)(child));
         output.push(
-          TypeScriptFactory.createModuleDeclaration(
-            [TypeScriptFactory.createModifier(SyntaxKind.ExportKeyword)],
-            TypeScriptFactory.createIdentifier(modulo.name),
-            TypeScriptFactory.createModuleBlock(internal),
+          factory.createModuleDeclaration(
+            [factory.createModifier(SyntaxKind.ExportKeyword)],
+            factory.createIdentifier(modulo.name),
+            factory.createModuleBlock(internal as Statement[]),
             NodeFlags.Namespace,
           ),
         );

package/src/generates/internal/E2eFileProgrammer.ts

@@ -1,11 +1,14 @@
 import {
-  Node,
+  type Node,
   NodeFlags,
+  type NumericLiteral,
   SyntaxKind,
-  TypeScriptFactory,
-} from "@nestia/factory";
-import { IdentifierFactory, LiteralFactory } from "@nestia/factory";
+  type TypeNode,
+  factory,
+} from "@ttsc/factory";
 
+import { IdentifierFactory } from "../../factories/IdentifierFactory";
+import { LiteralFactory } from "../../factories/LiteralFactory";
 import { INestiaProject } from "../../structures/INestiaProject";
 import { ITypedHttpRoute } from "../../structures/ITypedHttpRoute";
 import { FilePrinter } from "./FilePrinter";
@@ -44,12 +47,12 @@ export namespace E2eFileProgrammer {
     (project: INestiaProject) =>
     (importer: ImportDictionary) =>
     (route: ITypedHttpRoute): Node =>
-      TypeScriptFactory.createVariableStatement(
-        [TypeScriptFactory.createModifier(SyntaxKind.ExportKeyword)],
-        TypeScriptFactory.createVariableDeclarationList(
+      factory.createVariableStatement(
+        [factory.createModifier(SyntaxKind.ExportKeyword)],
+        factory.createVariableDeclarationList(
           [
-            TypeScriptFactory.createVariableDeclaration(
-              TypeScriptFactory.createIdentifier(getFunctionName(route)),
+            factory.createVariableDeclaration(
+              factory.createIdentifier(getFunctionName(route)),
               undefined,
               undefined,
               generateArrow(project)(importer)(route),
@@ -64,34 +67,36 @@ export namespace E2eFileProgrammer {
     (importer: ImportDictionary) =>
     (route: ITypedHttpRoute) => {
       const random = IdentifierFactory.access(
-        TypeScriptFactory.createIdentifier(SdkImportWizard.typia(importer)),
+        factory.createIdentifier(SdkImportWizard.typia(importer)),
         "random",
       );
       const connection = route.headerObject
-        ? TypeScriptFactory.createObjectLiteralExpression(
+        ? factory.createObjectLiteralExpression(
             [
-              TypeScriptFactory.createSpreadAssignment(
-                TypeScriptFactory.createIdentifier("connection"),
+              factory.createSpreadAssignment(
+                factory.createIdentifier("connection"),
               ),
-              TypeScriptFactory.createPropertyAssignment(
+              factory.createPropertyAssignment(
                 "headers",
-                TypeScriptFactory.createObjectLiteralExpression(
+                factory.createObjectLiteralExpression(
                   [
-                    TypeScriptFactory.createSpreadAssignment(
+                    factory.createSpreadAssignment(
                       IdentifierFactory.access(
-                        TypeScriptFactory.createIdentifier("connection"),
+                        factory.createIdentifier("connection"),
                         "headers",
                       ),
                     ),
-                    TypeScriptFactory.createSpreadAssignment(
-                      TypeScriptFactory.createCallExpression(
+                    factory.createSpreadAssignment(
+                      factory.createCallExpression(
                         random,
                         [
-                          project.config.clone === true
+                          (project.config.clone === true
                             ? SdkAliasCollection.from(project)(importer)(
                                 route.headerObject.metadata,
                               )
-                            : SdkAliasCollection.name(route.headerObject),
+                            : SdkAliasCollection.name(
+                                route.headerObject,
+                              )) as TypeNode,
                         ],
                         undefined,
                       ),
@@ -103,7 +108,7 @@ export namespace E2eFileProgrammer {
             ],
             true,
           )
-        : TypeScriptFactory.createIdentifier("connection");
+        : factory.createIdentifier("connection");
       const entries = SdkHttpParameterProgrammer.getEntries({
         project,
         importer,
@@ -112,8 +117,8 @@ export namespace E2eFileProgrammer {
         e2e: true,
         prefix: ["api", "functional", ...route.accessor].join(".") + ".",
       });
-      const fetch = TypeScriptFactory.createCallExpression(
-        TypeScriptFactory.createIdentifier(
+      const fetch = factory.createCallExpression(
+        factory.createIdentifier(
           ["api", "functional", ...route.accessor].join("."),
         ),
         undefined,
@@ -125,9 +130,9 @@ export namespace E2eFileProgrammer {
                   Object.fromEntries(
                     entries.map((e) => [
                       e.key,
-                      TypeScriptFactory.createCallExpression(
+                      factory.createCallExpression(
                         IdentifierFactory.access(
-                          TypeScriptFactory.createIdentifier(
+                          factory.createIdentifier(
                             SdkImportWizard.typia(importer),
                           ),
                           "random",
@@ -140,11 +145,9 @@ export namespace E2eFileProgrammer {
                 ),
               ]
             : entries.map((e) =>
-                TypeScriptFactory.createCallExpression(
+                factory.createCallExpression(
                   IdentifierFactory.access(
-                    TypeScriptFactory.createIdentifier(
-                      SdkImportWizard.typia(importer),
-                    ),
+                    factory.createIdentifier(SdkImportWizard.typia(importer)),
                     "random",
                   ),
                   [getRandomType(importer)(e)],
@@ -153,39 +156,41 @@ export namespace E2eFileProgrammer {
               )),
         ],
       );
-      const assert = TypeScriptFactory.createCallExpression(
+      const assert = factory.createCallExpression(
         IdentifierFactory.access(
-          TypeScriptFactory.createIdentifier(SdkImportWizard.typia(importer)),
+          factory.createIdentifier(SdkImportWizard.typia(importer)),
           "assert",
         ),
         undefined,
-        [TypeScriptFactory.createIdentifier("output")],
+        [factory.createIdentifier("output")],
       );
 
-      return TypeScriptFactory.createArrowFunction(
-        [TypeScriptFactory.createModifier(SyntaxKind.AsyncKeyword)],
+      return factory.createArrowFunction(
+        [factory.createModifier(SyntaxKind.AsyncKeyword)],
         undefined,
         [
           IdentifierFactory.parameter(
             "connection",
-            TypeScriptFactory.createTypeReferenceNode("api.IConnection"),
+            factory.createTypeReferenceNode("api.IConnection"),
           ),
         ],
         undefined,
         undefined,
-        TypeScriptFactory.createBlock([
-          TypeScriptFactory.createVariableStatement(
+        factory.createBlock([
+          factory.createVariableStatement(
             [],
-            TypeScriptFactory.createVariableDeclarationList(
+            factory.createVariableDeclarationList(
               [
-                TypeScriptFactory.createVariableDeclaration(
+                factory.createVariableDeclaration(
                   "output",
                   undefined,
                   project.config.propagate !== true &&
                     route.success.type!.name === "void"
                     ? undefined
-                    : SdkAliasCollection.response(project)(importer)(route),
-                  TypeScriptFactory.createAwaitExpression(fetch),
+                    : (SdkAliasCollection.response(project)(importer)(
+                        route,
+                      ) as TypeNode),
+                  factory.createAwaitExpression(fetch),
                 ),
               ],
               NodeFlags.Const,
@@ -193,7 +198,7 @@ export namespace E2eFileProgrammer {
           ),
           ...(route.success.binary === true
             ? []
-            : [TypeScriptFactory.createExpressionStatement(assert)]),
+            : [factory.createExpressionStatement(assert)]),
         ]),
       );
     };
@@ -201,13 +206,14 @@ export namespace E2eFileProgrammer {
 
 const getRandomType =
   (importer: ImportDictionary) =>
-  (entry: SdkHttpParameterProgrammer.IEntry): Node => {
-    if (isPlainStringPathParameter(entry) === false) return entry.type;
-    return TypeScriptFactory.createIntersectionTypeNode([
-      entry.type,
-      TypeScriptFactory.createTypeReferenceNode(
-        TypeScriptFactory.createQualifiedName(
-          TypeScriptFactory.createIdentifier(
+  (entry: SdkHttpParameterProgrammer.IEntry): TypeNode => {
+    if (isPlainStringPathParameter(entry) === false)
+      return entry.type as TypeNode;
+    return factory.createIntersectionTypeNode([
+      entry.type as TypeNode,
+      factory.createTypeReferenceNode(
+        factory.createQualifiedName(
+          factory.createIdentifier(
             importer.external({
               declaration: true,
               file: "typia",
@@ -215,11 +221,11 @@ const getRandomType =
               name: "tags",
             }),
           ),
-          TypeScriptFactory.createIdentifier("MinLength"),
+          factory.createIdentifier("MinLength"),
         ),
         [
-          TypeScriptFactory.createLiteralTypeNode(
-            LiteralFactory.write(1) as Node,
+          factory.createLiteralTypeNode(
+            LiteralFactory.write(1) as NumericLiteral,
           ),
         ],
       ),

package/src/generates/internal/FilePrinter.ts

@@ -1,55 +1,47 @@
 import {
-  Node,
+  type Node,
+  type Statement,
   SyntaxKind,
-  TypeScriptFactory,
-  TypeScriptPrinter,
-} from "@nestia/factory";
+  TsPrinter,
+  addSyntheticLeadingComment,
+  factory,
+} from "@ttsc/factory";
 import fs from "fs";
 import { format } from "prettier";
 
 export namespace FilePrinter {
-  export const description = <T extends Node>(
-    node: T,
-    comment: string,
-  ): T => {
+  export const description = <T extends Node>(node: T, comment: string): T => {
     if (comment.length === 0) return node;
-    node.emitNode ??= {};
-    node.emitNode.leadingComments = [
-      ...(node.emitNode.leadingComments ?? []),
-      {
-        kind: SyntaxKind.MultiLineCommentTrivia,
-        text: [
-          "*",
-          ...comment
-            .split("\r\n")
-            .join("\n")
-            .split("\n")
-            .map(
-              (str) =>
-                ` * ${str.split("*/").join("*\\\\/").split("*\\/").join("*\\\\/")}`,
-            ),
-          "",
-        ].join("\n"),
-        hasTrailingNewLine: true,
-      },
-    ];
-    return node;
+    return addSyntheticLeadingComment(
+      node,
+      SyntaxKind.MultiLineCommentTrivia,
+      [
+        "*",
+        ...comment
+          .split("\r\n")
+          .join("\n")
+          .split("\n")
+          .map(
+            (str) =>
+              ` * ${str.split("*/").join("*\\\\/").split("*\\/").join("*\\\\/")}`,
+          ),
+        "",
+      ].join("\n"),
+      true,
+    );
   };
 
   export const enter = () =>
-    TypeScriptFactory.createExpressionStatement(
-      TypeScriptFactory.createIdentifier("\n"),
-    );
+    factory.createExpressionStatement(factory.createIdentifier("\n"));
 
   export const write = async (props: {
     location: string;
     statements: Node[];
     top?: string;
   }): Promise<void> => {
-    const script: string = TypeScriptPrinter.write({
-      statements: props.statements,
-      top: props.top,
-    });
+    const script: string =
+      (props.top ?? "") +
+      new TsPrinter().printFile(undefined, props.statements as Statement[]);
     await fs.promises.writeFile(props.location, await beautify(script), "utf8");
   };
 

package/src/generates/internal/ImportDictionary.ts

@@ -1,4 +1,4 @@
-import { Node, TypeScriptFactory } from "@nestia/factory";
+import { type ImportClause, type Node, factory } from "@ttsc/factory";
 import path from "path";
 import { HashMap, TreeMap, hash } from "tstl";
 
@@ -109,11 +109,10 @@ export class ImportDictionary {
           .sort((a, b) => a.file.localeCompare(b.file));
         for (const c of compositions)
           container.push(
-            TypeScriptFactory.createImportDeclaration(
+            factory.createImportDeclaration(
               undefined,
               this.toImportClaude(c),
-              TypeScriptFactory.createStringLiteral(c.file),
-              undefined,
+              factory.createStringLiteral(c.file),
             ),
           );
       };
@@ -127,29 +126,28 @@ export class ImportDictionary {
     ];
   }
 
-  private toImportClaude(c: ICompositeValue): Node {
+  private toImportClaude(c: ICompositeValue): ImportClause {
+    // A namespace import cannot carry a per-binding `type` modifier, so the
+    // type-only flag stays off here (a value namespace import resolves type
+    // members fine), matching the legacy printer output `import * as X`.
     if (c.asterisk !== null)
-      return TypeScriptFactory.createImportClause(
-        c.declaration,
+      return factory.createImportClause(
+        false,
         undefined,
-        TypeScriptFactory.createNamespaceImport(
-          TypeScriptFactory.createIdentifier(c.asterisk),
-        ),
+        factory.createNamespaceImport(factory.createIdentifier(c.asterisk)),
       );
-    return TypeScriptFactory.createImportClause(
+    // `c.declaration` (type-only) belongs on the import clause, not on each
+    // specifier — emitting both produces the invalid `import type { type X }`.
+    return factory.createImportClause(
       c.declaration,
-      c.default !== null
-        ? TypeScriptFactory.createIdentifier(c.default)
-        : undefined,
+      c.default !== null ? factory.createIdentifier(c.default) : undefined,
       c.elements.size() !== 0
-        ? TypeScriptFactory.createNamedImports(
+        ? factory.createNamedImports(
             Array.from(c.elements).map(({ first: name, second: alias }) =>
-              TypeScriptFactory.createImportSpecifier(
-                c.declaration,
-                alias !== null
-                  ? TypeScriptFactory.createIdentifier(name)
-                  : undefined,
-                TypeScriptFactory.createIdentifier(alias ?? name),
+              factory.createImportSpecifier(
+                false,
+                alias !== null ? factory.createIdentifier(name) : undefined,
+                factory.createIdentifier(alias ?? name),
               ),
             ),
           )