@nestia/sdk 13.0.4 → 14.0.1

package/src/generates/internal/SdkHttpParameterProgrammer.ts

@@ -1,8 +1,15 @@
-import { type Node, SyntaxKind, type TypeNode, factory } from "@ttsc/factory";
+import {
+  type Expression,
+  type Node,
+  SyntaxKind,
+  type TypeNode,
+  factory,
+} from "@ttsc/factory";
 
 import { INestiaProject } from "../../structures/INestiaProject";
 import { ITypedHttpRoute } from "../../structures/ITypedHttpRoute";
 import { ITypedHttpRouteParameter } from "../../structures/ITypedHttpRouteParameter";
+import { StringUtil } from "../../utils/StringUtil";
 import { ImportDictionary } from "./ImportDictionary";
 import { SdkAliasCollection } from "./SdkAliasCollection";
 
@@ -14,6 +21,157 @@ export namespace SdkHttpParameterProgrammer {
     parameter: ITypedHttpRouteParameter;
   }
 
+  /**
+   * The identifiers one route's SDK function, `path()`, and `simulate()` use,
+   * decided once so the three cannot disagree.
+   *
+   * A user parameter shares those scopes with identifiers the SDK writes: its
+   * own `connection` and `props` parameters and locals, and names it cannot
+   * change — the route's function and namespace, which are public, and the
+   * imports, namespace members, and globals the bodies reference. Nothing kept
+   * them apart, so a parameter named like its method or `connection` produced
+   * an SDK that does not compile (#1647).
+   *
+   * The SDK's own identifiers are escaped with `_` prefixes, as it already
+   * escaped `output` and `variables`. A user parameter keeps its name, which an
+   * IDE shows and which is a `props` key in keyword mode, unless the name is
+   * one the SDK cannot change; then the positional parameter alone is renamed,
+   * which positional callers never see. The fixed names are only those the
+   * generated code actually references for this route and configuration, and an
+   * own identifier yields only to the names its scope can see, so nothing is
+   * renamed where no name is shadowed.
+   */
+  export interface INames {
+    connection: string;
+    props: string;
+    output: string;
+    assert: string;
+    variables: string;
+    location: string;
+    key: string;
+    value: string;
+    elem: string;
+
+    /** Local identifier of a significant parameter in positional mode. */
+    parameter: (p: ITypedHttpRouteParameter) => string;
+
+    /** Reads a significant parameter: `props.<name>` or its local. */
+    access: (p: ITypedHttpRouteParameter) => Expression;
+  }
+
+  export const getNames = (props: {
+    project: INestiaProject;
+    route: ITypedHttpRoute;
+  }): INames => {
+    const { project, route } = props;
+    const parameters: ITypedHttpRouteParameter[] = getSignificant(route, true);
+    const simulate: boolean =
+      project.config.simulate === true && parameters.length !== 0;
+
+    // names each scope references and the SDK cannot change
+    const functional: string[] = [
+      route.name,
+      !!route.body?.encrypted || route.success.encrypted
+        ? "EncryptedFetcher"
+        : "PlainFetcher",
+      ...(project.config.assert === true ? ["typia"] : []),
+      ...(route.success.setHeaders.some((h) => h.type === "assigner")
+        ? ["Object"]
+        : []),
+    ];
+    const path: string[] = [
+      ...(route.pathParameters.length !== 0 ? ["PathParameter"] : []),
+      ...(route.queryObject !== null || route.queryParameters.length !== 0
+        ? ["URLSearchParams", "Object", "Array", "String", "undefined"]
+        : []),
+    ];
+    const simulation: string[] = simulate
+      ? ["NestiaSimulator", "METADATA", "path", "random", "typia"]
+      : [];
+
+    const locals: Map<ITypedHttpRouteParameter, string> = new Map();
+    if (project.config.keyword !== true)
+      for (const p of parameters)
+        locals.set(
+          p,
+          StringUtil.escapeDuplicate([
+            ...functional,
+            ...simulation,
+            ...(p.category !== "body" ? path : []),
+            ...parameters.filter((q) => q !== p).map((q) => q.name),
+            ...locals.values(),
+          ])(p.name),
+        );
+    // An SDK-own identifier avoids the fixed names and the other own ones of
+    // its scope, and the positional parameters whose values its scope reads
+    // where it is visible: the SDK function's and simulate()'s parameters and
+    // locals see every one; in path(), `variables` and `location` see its
+    // parameters, the loop's `key` and `value` the query values its header
+    // reads, and `elem` none.
+    const declared = (list: ITypedHttpRouteParameter[]): string[] =>
+      list
+        .map((p) => locals.get(p))
+        .filter((name): name is string => name !== undefined);
+    const queries: ITypedHttpRouteParameter[] = [
+      ...route.queryParameters,
+      ...(route.queryObject ? [route.queryObject] : []),
+    ];
+    const own =
+      (fixed: string[], reads: string[], taken: string[]) =>
+      (name: string): string => {
+        const escaped: string = StringUtil.escapeDuplicate([
+          ...fixed,
+          ...reads,
+          ...taken,
+        ])(name);
+        taken.push(escaped);
+        return escaped;
+      };
+    const every: string[] = declared(parameters);
+    const shared: string[] = [];
+    const $props: string = own(
+      [...functional, ...path, ...simulation],
+      every,
+      shared,
+    )("props");
+    const $connection: string = own(
+      [...functional, ...simulation],
+      every,
+      shared,
+    )("connection");
+    const inPath: string[] = [...shared];
+    const names: Omit<INames, "parameter" | "access"> = {
+      props: $props,
+      connection: $connection,
+      output: own(functional, every, [...shared])("output"),
+      assert: own(simulation, every, [...shared])("assert"),
+      variables: own(
+        path,
+        declared([...route.pathParameters, ...queries]),
+        inPath,
+      )("variables"),
+      location: own(
+        path,
+        declared([...route.pathParameters, ...queries]),
+        inPath,
+      )("location"),
+      key: own(path, declared(queries), inPath)("key"),
+      value: own(path, declared(queries), inPath)("value"),
+      elem: own(path, [], inPath)("elem"),
+    };
+    return {
+      ...names,
+      parameter: (p) => locals.get(p) ?? p.name,
+      access: (p) =>
+        project.config.keyword === true
+          ? factory.createPropertyAccessExpression(
+              factory.createIdentifier(names.props),
+              p.name,
+            )
+          : factory.createIdentifier(locals.get(p) ?? p.name),
+    };
+  };
+
   export const getAll = (
     route: ITypedHttpRoute,
   ): ITypedHttpRouteParameter[] => [
@@ -113,7 +271,8 @@ export namespace SdkHttpParameterProgrammer {
   }): Node[] => {
     const entries: IEntry[] = getEntries(props);
     if (entries.length === 0) return [];
-    else if (props.project.config.keyword === true) {
+    const names: INames = getNames(props);
+    if (props.project.config.keyword === true) {
       const typeName: string = props.prefix
         ? `${props.route.name}.Props`
         : "Props";
@@ -130,25 +289,45 @@ export namespace SdkHttpParameterProgrammer {
         factory.createParameterDeclaration(
           undefined,
           undefined,
-          "props",
+          names.props,
           undefined,
           node,
           undefined,
         ),
       ];
     }
-    return entries.map((e) =>
-      factory.createParameterDeclaration(
+    // a required parameter cannot follow an optional one (TS1016), so an
+    // optional parameter before a required one trades its `?` for `undefined`
+    // in its type
+    return entries.map((e, i) => {
+      const trailing: boolean =
+        e.required === false &&
+        entries.slice(i + 1).every((next) => next.required === false);
+      return factory.createParameterDeclaration(
         undefined,
         undefined,
-        e.key,
-        e.required ? undefined : factory.createToken(SyntaxKind.QuestionToken),
-        e.type,
+        names.parameter(e.parameter),
+        trailing ? factory.createToken(SyntaxKind.QuestionToken) : undefined,
+        e.required || trailing ? e.type : undefinable(props.project, e),
         undefined,
-      ),
-    );
+      );
+    });
   };
 
+  // a cloned field's type admits `undefined` when optional, and a reflected
+  // field's does when its name says so (`mode: string | undefined`, not
+  // `mode?: string`); the `Query` and `Body` aliases are not inspected
+  const undefinable = (project: INestiaProject, e: IEntry): TypeNode =>
+    e.parameter.category !== "body" &&
+    e.parameter.field !== null &&
+    (project.config.clone === true ||
+      e.parameter.type.name.split("|").some((t) => t.trim() === "undefined"))
+      ? e.type
+      : factory.createUnionTypeNode([
+          e.type,
+          factory.createKeywordTypeNode(SyntaxKind.UndefinedKeyword),
+        ]);
+
   export const getArguments = (props: {
     project: INestiaProject;
     route: ITypedHttpRoute;
@@ -156,8 +335,9 @@ export namespace SdkHttpParameterProgrammer {
   }): Node[] => {
     const parameters = getSignificant(props.route, props.body);
     if (parameters.length === 0) return [];
-    else if (props.project.config.keyword === true)
-      return [factory.createIdentifier("props")];
-    return parameters.map((p) => factory.createIdentifier(p.name));
+    const names: INames = getNames(props);
+    if (props.project.config.keyword === true)
+      return [factory.createIdentifier(names.props)];
+    return parameters.map((p) => factory.createIdentifier(names.parameter(p)));
   };
 }

package/src/generates/internal/SdkHttpRouteProgrammer.ts

@@ -1,7 +1,6 @@
 import { type Node } from "@ttsc/factory";
 import { IJsDocTagInfo } from "typia";
 
-import { INestiaConfig } from "../../INestiaConfig";
 import { INestiaProject } from "../../structures/INestiaProject";
 import { ITypedHttpRoute } from "../../structures/ITypedHttpRoute";
 import { FilePrinter } from "./FilePrinter";
@@ -17,12 +16,17 @@ export namespace SdkHttpRouteProgrammer {
     (route: ITypedHttpRoute): Node[] => [
       FilePrinter.description(
         SdkHttpFunctionProgrammer.write(project)(importer)(route),
-        describe(project.config, route),
+        describe(project, route),
       ),
       SdkHttpNamespaceProgrammer.write(project)(importer)(route),
     ];
 
-  const describe = (config: INestiaConfig, route: ITypedHttpRoute): string => {
+  const describe = (
+    project: INestiaProject,
+    route: ITypedHttpRoute,
+  ): string => {
+    const names: SdkHttpParameterProgrammer.INames =
+      SdkHttpParameterProgrammer.getNames({ project, route });
     // MAIN DESCRIPTION
     const descriptionComments: string[] = route.description
       ? route.description.split("\n")
@@ -37,23 +41,15 @@ export namespace SdkHttpRouteProgrammer {
           ?.text ??
         route.jsDocTags
           .find((tag) => tag.name === "param" && tag.text?.[0]?.text === p.name)
-          ?.text?.map((e) => e.text)
-          .join("")
-          .substring(p.name.length);
+          ?.text?.find((e) => e.kind === "text")?.text;
       if (!description?.length) continue;
 
-      const name: string = config.keyword === true ? `props.${p.name}` : p.name;
-      tagComments.push(
-        `@param ${name} ${description
-          .split("\n")
-          .map((str) => str.trim())
-          .map((str, i) => {
-            if (i === 0) return str;
-            const rpad: number = p.name.length + 8;
-            return `${" ".repeat(rpad)}${str}`;
-          })
-          .join("\n")}`,
-      );
+      // the name the SDK function declares, which yields on a collision
+      const name: string =
+        project.config.keyword === true
+          ? `${names.props}.${p.name}`
+          : names.parameter(p);
+      tagComments.push(FilePrinter.jsDocTag(`param ${name}`, description));
     }
 
     // COMMENT TAGS
@@ -62,18 +58,7 @@ export namespace SdkHttpRouteProgrammer {
     );
     if (tags.length !== 0) {
       const content: string[] = tags.map((t) =>
-        t.text?.length
-          ? `@${t.name} ${t.text
-              .map((e) => e.text)
-              .join("")
-              .split("\n")
-              .map((str) => str.trim())
-              .map((str, i) => {
-                if (i === 0) return str;
-                return `${" ".repeat(t.name.length + 1)} ${str}`;
-              })
-              .join("\n")}`
-          : `@${t.name}`,
+        FilePrinter.jsDocTag(t.name, t.text?.map((e) => e.text).join("") ?? ""),
       );
       tagComments.push(...new Set(content));
     }
@@ -100,7 +85,8 @@ export namespace SdkHttpRouteProgrammer {
       ...(descriptionComments.length && tagComments.length ? [""] : []),
       ...tagComments,
       ...(descriptionComments.length && tagComments.length ? [""] : []),
-      `@controller ${route.controller.class.name}.${route.name}`,
+      // the public name, kept by a route declared under a local one
+      `@controller ${route.controller.class.name}.${route.key}`,
       `@path ${route.method} ${route.path}`,
       `@accessor api.functional.${route.accessor.join(".")}`,
       `@nestia Generated by Nestia - https://github.com/samchon/nestia`,

package/src/generates/internal/SdkHttpSimulationProgrammer.ts

@@ -65,6 +65,8 @@ export namespace SdkHttpSimulationProgrammer {
     (project: INestiaProject) =>
     (importer: ImportDictionary) =>
     (route: ITypedHttpRoute): Node => {
+      const names: SdkHttpParameterProgrammer.INames =
+        SdkHttpParameterProgrammer.getNames({ project, route });
       const output: boolean =
         project.config.propagate === true ||
         route.success.binary === true ||
@@ -82,9 +84,9 @@ export namespace SdkHttpSimulationProgrammer {
           [
             IdentifierFactory.parameter(
               SdkHttpParameterProgrammer.getSignificant(route, true).length !==
-                0
-                ? "connection"
-                : "_connection",
+                0 || route.headerObject !== null
+                ? names.connection
+                : `_${names.connection}`,
               factory.createTypeReferenceNode(
                 SdkImportWizard.IConnection(importer),
                 route.headerObject
@@ -104,7 +106,7 @@ export namespace SdkHttpSimulationProgrammer {
           undefined,
           factory.createBlock(
             [
-              ...assert(project)(importer)(route),
+              ...assert(project)(importer)(route)(names),
               factory.createReturnStatement(
                 project.config.propagate
                   ? factory.createAsExpression(
@@ -145,13 +147,14 @@ export namespace SdkHttpSimulationProgrammer {
   const assert =
     (project: INestiaProject) =>
     (importer: ImportDictionary) =>
-    (route: ITypedHttpRoute): Statement[] => {
+    (route: ITypedHttpRoute) =>
+    (names: SdkHttpParameterProgrammer.INames): Statement[] => {
       const parameters = SdkHttpParameterProgrammer.getSignificant(route, true);
-      if (parameters.length === 0) return [];
+      if (parameters.length === 0 && route.headerObject === null) return [];
 
       const typia = SdkImportWizard.typia(importer);
       const validator = StatementFactory.constant({
-        name: "assert",
+        name: names.assert,
         value: factory.createCallExpression(
           IdentifierFactory.access(
             factory.createIdentifier(
@@ -174,7 +177,10 @@ export namespace SdkHttpSimulationProgrammer {
                 ),
                 factory.createPropertyAssignment(
                   "host",
-                  factory.createIdentifier("connection.host"),
+                  IdentifierFactory.access(
+                    factory.createIdentifier(names.connection),
+                    "host",
+                  ),
                 ),
                 factory.createPropertyAssignment(
                   "path",
@@ -205,7 +211,7 @@ export namespace SdkHttpSimulationProgrammer {
           factory.createCallExpression(
             (() => {
               const base = IdentifierFactory.access(
-                factory.createIdentifier("assert"),
+                factory.createIdentifier(names.assert),
                 p.category,
               );
               if (p.category !== "param") return base;
@@ -227,17 +233,48 @@ export namespace SdkHttpSimulationProgrammer {
                     "assert",
                   ),
                   undefined,
-                  [
-                    project.config.keyword === true
-                      ? factory.createIdentifier(`props.${p.name}`)
-                      : factory.createIdentifier(p.name),
-                  ],
+                  [names.access(p)],
                 ),
               ),
             ],
           ),
         )
         .map(factory.createExpressionStatement);
+      // the headers travel in the connection, validated as the server does
+      if (route.headerObject !== null)
+        individual.push(
+          factory.createExpressionStatement(
+            factory.createCallExpression(
+              IdentifierFactory.access(
+                factory.createIdentifier(names.assert),
+                "headers",
+              ),
+              undefined,
+              [
+                factory.createArrowFunction(
+                  undefined,
+                  undefined,
+                  [],
+                  undefined,
+                  undefined,
+                  factory.createCallExpression(
+                    IdentifierFactory.access(
+                      factory.createIdentifier(typia),
+                      "assert",
+                    ),
+                    [factory.createTypeReferenceNode(`${route.name}.Headers`)],
+                    [
+                      IdentifierFactory.access(
+                        factory.createIdentifier(names.connection),
+                        "headers",
+                      ),
+                    ],
+                  ),
+                ),
+              ],
+            ),
+          ),
+        );
       return [
         validator,
         ...(project.config.propagate !== true