@nestia/sdk 13.0.4 → 14.0.1

package/src/generates/internal/SdkWebSocketNamespaceProgrammer.ts

@@ -16,6 +16,7 @@ import { ITypedWebSocketRoute } from "../../structures/ITypedWebSocketRoute";
 import { FilePrinter } from "./FilePrinter";
 import { ImportDictionary } from "./ImportDictionary";
 import { SdkAliasCollection } from "./SdkAliasCollection";
+import { SdkPathTemplate } from "./SdkPathTemplate";
 import { SdkWebSocketParameterProgrammer } from "./SdkWebSocketParameterProgrammer";
 
 export namespace SdkWebSocketNamespaceProgrammer {
@@ -29,7 +30,7 @@ export namespace SdkWebSocketNamespaceProgrammer {
         factory.createModuleBlock([
           ...writeTypes(project)(importer)(route),
           FilePrinter.enter(),
-          writePath(project)(route),
+          writePath(project)(importer)(route),
         ]),
         NodeFlags.Namespace,
       );
@@ -50,7 +51,13 @@ export namespace SdkWebSocketNamespaceProgrammer {
         );
 
       if (project.config.keyword === true)
-        declare("Props", SdkAliasCollection.websocketProps(route));
+        declare(
+          "Props",
+          SdkAliasCollection.websocketProps(
+            route,
+            SdkWebSocketParameterProgrammer.getNames({ project, route }),
+          ),
+        );
       declare(
         "Output",
         factory.createTypeLiteralNode([
@@ -128,6 +135,7 @@ export namespace SdkWebSocketNamespaceProgrammer {
 
   const writePath =
     (project: INestiaProject) =>
+    (importer: ImportDictionary) =>
     (route: ITypedWebSocketRoute): Statement => {
       const out = (body: Block | Expression) =>
         constant("path")(
@@ -146,63 +154,30 @@ export namespace SdkWebSocketNamespaceProgrammer {
           ),
         );
       if (route.pathParameters.length === 0 && route.query === null)
-        return out(factory.createStringLiteral(route.path));
-
-      const access = (key: string) =>
-        project.config.keyword === true
-          ? factory.createPropertyAccessExpression(
-              factory.createIdentifier("props"),
-              key,
-            )
-          : factory.createIdentifier(key);
-      const template = () => {
-        const split: string[] = route.path.split(":");
-        if (split.length === 1) return factory.createStringLiteral(route.path);
-        return factory.createTemplateExpression(
-          factory.createTemplateHead(split[0]!),
-          split.slice(1).map((s, i, arr) => {
-            const name: string = s.split("/")[0]!;
-            return factory.createTemplateSpan(
-              factory.createCallExpression(
-                factory.createIdentifier("encodeURIComponent"),
-                undefined,
-                [
-                  factory.createBinaryExpression(
-                    factory.createCallChain(
-                      factory.createPropertyAccessChain(
-                        access(
-                          route.pathParameters.find((p) => p.field === name)!
-                            .name,
-                        ),
-                        factory.createToken(SyntaxKind.QuestionDotToken),
-                        "toString",
-                      ),
-                      undefined,
-                      undefined,
-                      [],
-                    ),
-                    factory.createToken(SyntaxKind.QuestionQuestionToken),
-                    factory.createStringLiteral("null"),
-                  ),
-                ],
-              ),
-              (i !== arr.length - 1
-                ? factory.createTemplateMiddle
-                : factory.createTemplateTail)(s.substring(name.length)),
-            );
+        return out(
+          SdkPathTemplate.compose({
+            importer,
+            path: route.path,
+            argument: () => factory.createIdentifier("undefined"),
           }),
         );
-      };
+      const names: SdkWebSocketParameterProgrammer.INames =
+        SdkWebSocketParameterProgrammer.getNames({ project, route });
+      const template = () =>
+        SdkPathTemplate.compose({
+          importer,
+          path: route.path,
+          argument: (name) =>
+            names.access(
+              names.parameter(
+                route.pathParameters.find((p) => p.field === name)!,
+              ),
+            ),
+        });
       if (route.query === null) return out(template());
 
       const block = (expr: Expression) => {
-        const computeName = (str: string): string =>
-          [...route.pathParameters, ...(route.query ? [route.query] : [])].find(
-            (p) => p.name === str,
-          ) !== undefined
-            ? computeName("_" + str)
-            : str;
-        const variables: string = computeName("variables");
+        const variables: string = names.variables;
         return factory.createBlock(
           [
             local(variables)("URLSearchParams")(
@@ -221,13 +196,13 @@ export namespace SdkWebSocketNamespaceProgrammer {
                       factory.createBindingElement(
                         undefined,
                         undefined,
-                        factory.createIdentifier("key"),
+                        factory.createIdentifier(names.key),
                         undefined,
                       ),
                       factory.createBindingElement(
                         undefined,
                         undefined,
-                        factory.createIdentifier("value"),
+                        factory.createIdentifier(names.value),
                         undefined,
                       ),
                     ]),
@@ -246,19 +221,19 @@ export namespace SdkWebSocketNamespaceProgrammer {
               factory.createIfStatement(
                 factory.createStrictEquality(
                   factory.createIdentifier("undefined"),
-                  factory.createIdentifier("value"),
+                  factory.createIdentifier(names.value),
                 ),
                 factory.createContinueStatement(),
                 factory.createIfStatement(
                   factory.createCallExpression(
                     factory.createIdentifier("Array.isArray"),
                     undefined,
-                    [factory.createIdentifier("value")],
+                    [factory.createIdentifier(names.value)],
                   ),
                   factory.createExpressionStatement(
                     factory.createCallExpression(
                       factory.createPropertyAccessExpression(
-                        factory.createIdentifier("value"),
+                        factory.createIdentifier(names.value),
                         factory.createIdentifier("forEach"),
                       ),
                       undefined,
@@ -266,7 +241,7 @@ export namespace SdkWebSocketNamespaceProgrammer {
                         factory.createArrowFunction(
                           undefined,
                           undefined,
-                          [IdentifierFactory.parameter("elem")],
+                          [IdentifierFactory.parameter(names.elem)],
                           undefined,
                           undefined,
                           factory.createCallExpression(
@@ -276,11 +251,11 @@ export namespace SdkWebSocketNamespaceProgrammer {
                             ),
                             undefined,
                             [
-                              factory.createIdentifier("key"),
+                              factory.createIdentifier(names.key),
                               factory.createCallExpression(
                                 factory.createIdentifier("String"),
                                 undefined,
-                                [factory.createIdentifier("elem")],
+                                [factory.createIdentifier(names.elem)],
                               ),
                             ],
                           ),
@@ -296,11 +271,11 @@ export namespace SdkWebSocketNamespaceProgrammer {
                       ),
                       undefined,
                       [
-                        factory.createIdentifier("key"),
+                        factory.createIdentifier(names.key),
                         factory.createCallExpression(
                           factory.createIdentifier("String"),
                           undefined,
-                          [factory.createIdentifier("value")],
+                          [factory.createIdentifier(names.value)],
                         ),
                       ],
                     ),
@@ -308,7 +283,7 @@ export namespace SdkWebSocketNamespaceProgrammer {
                 ),
               ),
             ),
-            local("location")("string")(template()),
+            local(names.location)("string")(template()),
             factory.createReturnStatement(
               factory.createConditionalExpression(
                 factory.createStrictEquality(
@@ -319,13 +294,13 @@ export namespace SdkWebSocketNamespaceProgrammer {
                   ),
                 ),
                 undefined,
-                factory.createIdentifier("location"),
+                factory.createIdentifier(names.location),
                 undefined,
                 factory.createTemplateExpression(
                   factory.createTemplateHead(""),
                   [
                     factory.createTemplateSpan(
-                      factory.createIdentifier("location"),
+                      factory.createIdentifier(names.location),
                       factory.createTemplateMiddle("?"),
                     ),
                     factory.createTemplateSpan(
@@ -347,7 +322,7 @@ export namespace SdkWebSocketNamespaceProgrammer {
           true,
         );
       };
-      return out(block(access(route.query.name)));
+      return out(block(names.access(names.query)));
     };
 }
 

package/src/generates/internal/SdkWebSocketParameterProgrammer.ts

@@ -1,4 +1,5 @@
 import {
+  type Expression,
   type ParameterDeclaration,
   type TypeNode,
   factory,
@@ -6,6 +7,8 @@ import {
 
 import { INestiaProject } from "../../structures/INestiaProject";
 import { ITypedWebSocketRoute } from "../../structures/ITypedWebSocketRoute";
+import { ITypedWebSocketRouteParameter } from "../../structures/ITypedWebSocketRouteParameter";
+import { StringUtil } from "../../utils/StringUtil";
 import { SdkAliasCollection } from "./SdkAliasCollection";
 
 export namespace SdkWebSocketParameterProgrammer {
@@ -14,22 +17,139 @@ export namespace SdkWebSocketParameterProgrammer {
     type: TypeNode;
   }
 
+  /**
+   * The identifiers one WebSocket route's SDK function and `path()` use,
+   * decided once so the two cannot disagree; the HTTP counterpart,
+   * `SdkHttpParameterProgrammer.INames`, gives the rules.
+   *
+   * Path parameters are the user's names. `query` and `provider` are the SDK's
+   * own: the positional parameters, or the `props` keys in keyword mode, that
+   * carry the query object and the provider, so they yield to a path parameter
+   * of the same name instead of repeating it. A `props` key shadows nothing, so
+   * it yields to nothing else.
+   */
+  export interface INames {
+    connection: string;
+    props: string;
+    query: string;
+    provider: string;
+    url: string;
+    connector: string;
+    driver: string;
+    variables: string;
+    location: string;
+    key: string;
+    value: string;
+    elem: string;
+
+    /** Local identifier of a path parameter in positional mode. */
+    parameter: (p: ITypedWebSocketRouteParameter.IParam) => string;
+
+    /** Reads a parameter, or one of `query` and `provider`, by its key. */
+    access: (key: string) => Expression;
+  }
+
+  export const getNames = (props: {
+    project: INestiaProject;
+    route: ITypedWebSocketRoute;
+  }): INames => {
+    const { project, route } = props;
+    // names each scope references and the SDK cannot change
+    const functional: string[] = [route.name, "WebSocketConnector"];
+    const path: string[] = [
+      ...(route.pathParameters.length !== 0 ? ["PathParameter"] : []),
+      ...(route.query !== null
+        ? ["URLSearchParams", "Object", "Array", "String", "undefined"]
+        : []),
+    ];
+    const locals: Map<ITypedWebSocketRouteParameter.IParam, string> = new Map();
+    if (project.config.keyword !== true)
+      for (const p of route.pathParameters)
+        locals.set(
+          p,
+          StringUtil.escapeDuplicate([
+            ...functional,
+            ...path,
+            ...route.pathParameters.filter((q) => q !== p).map((q) => q.name),
+            ...locals.values(),
+          ])(p.name),
+        );
+    // `query` and `provider` sit beside the path parameters, as parameters or
+    // as `props` keys. Every other own identifier avoids the positional
+    // path parameters its scope reads where it is visible: all of them for
+    // the function's locals, `variables`, and `location`, none for the
+    // loop's `key` and `value`, whose header reads only the query, and for
+    // `elem`.
+    const keys: string[] = route.pathParameters.map(
+      (p) => locals.get(p) ?? p.name,
+    );
+    const positional: string[] = [...locals.values()];
+    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 shared: string[] = [];
+    const $props: string = own([...functional, ...path], [], shared)("props");
+    // Positional `query` and `provider` also yield to the names their scopes
+    // reference; as `props` keys they shadow nothing, so a route named
+    // `query` keeps its `query` key.
+    const beside = (fixed: string[]) =>
+      own(project.config.keyword === true ? [] : fixed, keys, shared);
+    const $query: string = beside([...functional, ...path])("query");
+    const $provider: string = beside(functional)("provider");
+    const inFunction: string[] = [...shared];
+    const inPath: string[] = [...shared];
+    const names: Omit<INames, "parameter" | "access"> = {
+      props: $props,
+      query: $query,
+      provider: $provider,
+      connection: own(functional, positional, inFunction)("connection"),
+      url: own(functional, positional, inFunction)("url"),
+      connector: own(functional, positional, inFunction)("connector"),
+      driver: own(functional, positional, inFunction)("driver"),
+      variables: own(path, positional, inPath)("variables"),
+      location: own(path, positional, inPath)("location"),
+      key: own(path, [], inPath)("key"),
+      value: own(path, [], inPath)("value"),
+      elem: own(path, [], inPath)("elem"),
+    };
+    return {
+      ...names,
+      parameter: (p) => locals.get(p) ?? p.name,
+      access: (key) =>
+        project.config.keyword === true
+          ? factory.createPropertyAccessExpression(
+              factory.createIdentifier(names.props),
+              key,
+            )
+          : factory.createIdentifier(key),
+    };
+  };
+
   export const getEntries = (props: {
     project: INestiaProject;
     route: ITypedWebSocketRoute;
     provider: boolean;
     prefix: boolean;
   }): IEntry[] => {
+    const names: INames = getNames(props);
     const prefix: string = props.prefix ? `${props.route.name}.` : "";
     return [
       ...props.route.pathParameters.map((p) => ({
-        key: p.name,
+        key: names.parameter(p),
         type: SdkAliasCollection.name(p),
       })),
       ...(props.route.query
         ? [
             {
-              key: "query",
+              key: names.query,
               type: factory.createTypeReferenceNode(`${prefix}Query`),
             },
           ]
@@ -37,7 +157,7 @@ export namespace SdkWebSocketParameterProgrammer {
       ...(props.provider
         ? [
             {
-              key: "provider",
+              key: names.provider,
               type: factory.createTypeReferenceNode(`${prefix}Provider`),
             },
           ]
@@ -54,6 +174,7 @@ export namespace SdkWebSocketParameterProgrammer {
     const entries: IEntry[] = getEntries(props);
     if (entries.length === 0) return [];
     else if (props.project.config.keyword === true) {
+      const names: INames = getNames(props);
       const typeName: string = props.prefix
         ? `${props.route.name}.Props`
         : "Props";
@@ -62,14 +183,14 @@ export namespace SdkWebSocketParameterProgrammer {
         : factory.createTypeReferenceNode("Omit", [
             factory.createTypeReferenceNode(typeName),
             factory.createLiteralTypeNode(
-              factory.createStringLiteral("provider"),
+              factory.createStringLiteral(names.provider),
             ),
           ]);
       return [
         factory.createParameterDeclaration(
           undefined,
           undefined,
-          "props",
+          names.props,
           undefined,
           node,
         ),

package/src/generates/internal/SdkWebSocketRouteProgrammer.ts

@@ -6,12 +6,10 @@ import {
   type TypeNode,
   factory,
 } from "@ttsc/factory";
-import { IJsDocTagInfo } from "typia";
 
 import { IdentifierFactory } from "../../factories/IdentifierFactory";
 import { INestiaProject } from "../../structures/INestiaProject";
 import { ITypedWebSocketRoute } from "../../structures/ITypedWebSocketRoute";
-import { StringUtil } from "../../utils/StringUtil";
 import { FilePrinter } from "./FilePrinter";
 import { ImportDictionary } from "./ImportDictionary";
 import { SdkImportWizard } from "./SdkImportWizard";
@@ -25,38 +23,65 @@ export namespace SdkWebSocketRouteProgrammer {
     (route: ITypedWebSocketRoute): Statement[] => [
       FilePrinter.description(
         writeFunction(project)(importer)(route),
-        writeDescription(route),
+        writeDescription(project, route),
       ),
       SdkWebSocketNamespaceProgrammer.write(project)(importer)(route),
     ];
 
-  const writeDescription = (route: ITypedWebSocketRoute): string => {
+  const writeDescription = (
+    project: INestiaProject,
+    route: ITypedWebSocketRoute,
+  ): string => {
     // MAIN DESCRIPTION
     const comments: string[] = route.description
       ? route.description.split("\n")
       : [];
 
-    // COMMENT TAGS
-    const tags: IJsDocTagInfo[] = route.jsDocTags.filter(
-      (tag) =>
-        tag.name !== "param" ||
-        [...route.pathParameters, ...(route.query ? [route.query] : [])]
-          .filter((p) => p.category === "param" || p.category === "query")
-          .some((p) => p.name === tag.text?.[0]?.text),
-    );
-    if (tags.length !== 0) {
-      const content: string[] = tags.map((t) =>
-        t.text?.length
-          ? `@${t.name} ${t.text.map((e) => e.text).join("")}`
-          : `@${t.name}`,
-      );
-      comments.push("", ...new Set(content));
-    }
+    // COMMENT TAGS, each `@param` naming what the SDK function declares,
+    // which yields on a collision
+    const names: SdkWebSocketParameterProgrammer.INames =
+      SdkWebSocketParameterProgrammer.getNames({ project, route });
+    const declared = (name: string | undefined): string | null => {
+      const path = route.pathParameters.find((p) => p.name === name);
+      const key: string | null =
+        path !== undefined
+          ? project.config.keyword === true
+            ? path.name
+            : names.parameter(path)
+          : route.query !== null && route.query.name === name
+            ? names.query
+            : null;
+      return key === null
+        ? null
+        : project.config.keyword === true
+          ? `${names.props}.${key}`
+          : key;
+    };
+    const tags: string[] = route.jsDocTags
+      .map((tag): string | null => {
+        if (tag.name !== "param")
+          return FilePrinter.jsDocTag(
+            tag.name,
+            tag.text?.map((e) => e.text).join("") ?? "",
+          );
+        const name: string | null = declared(tag.text?.[0]?.text);
+        return name === null
+          ? null
+          : FilePrinter.jsDocTag(
+              `param ${name}`,
+              tag.text?.find((e) => e.kind === "text")?.text ?? "",
+            );
+      })
+      .filter((tag): tag is string => tag !== null);
+    // apart from the description, when there is one
+    if (tags.length !== 0)
+      comments.push(...(comments.length !== 0 ? [""] : []), ...new Set(tags));
 
     // POSTFIX
     if (!!comments.length) comments.push("");
     comments.push(
-      `@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.path}`,
       `@nestia Generated by Nestia - https://github.com/samchon/nestia`,
     );
@@ -67,9 +92,8 @@ export namespace SdkWebSocketRouteProgrammer {
     (project: INestiaProject) =>
     (importer: ImportDictionary) =>
     (route: ITypedWebSocketRoute): Statement => {
-      const connection: string = StringUtil.escapeDuplicate([route.name])(
-        "connection",
-      );
+      const names: SdkWebSocketParameterProgrammer.INames =
+        SdkWebSocketParameterProgrammer.getNames({ project, route });
       return factory.createFunctionDeclaration(
         [
           factory.createModifier(SyntaxKind.ExportKeyword),
@@ -80,7 +104,7 @@ export namespace SdkWebSocketRouteProgrammer {
         undefined,
         [
           IdentifierFactory.parameter(
-            connection,
+            names.connection,
             factory.createTypeReferenceNode(
               SdkImportWizard.IConnection(importer),
               [factory.createTypeReferenceNode(`${route.name}.Header`)],
@@ -97,7 +121,7 @@ export namespace SdkWebSocketRouteProgrammer {
           factory.createTypeReferenceNode(`${route.name}.Output`),
         ]),
         factory.createBlock(
-          writeFunctionBody(project)(importer)(route)(connection),
+          writeFunctionBody(project)(importer)(route)(names),
           true,
         ),
       );
@@ -107,18 +131,11 @@ export namespace SdkWebSocketRouteProgrammer {
     (project: INestiaProject) =>
     (importer: ImportDictionary) =>
     (route: ITypedWebSocketRoute) =>
-    (connection: string): Statement[] => {
-      const access = (key: string) =>
-        project.config.keyword === true
-          ? factory.createPropertyAccessExpression(
-              factory.createIdentifier("props"),
-              key,
-            )
-          : factory.createIdentifier(key);
+    (names: SdkWebSocketParameterProgrammer.INames): Statement[] => {
       return [
-        local("url")(factory.createTypeReferenceNode("string"))(
+        local(names.url)(factory.createTypeReferenceNode("string"))(
           joinPath(
-            connection,
+            names.connection,
             factory.createCallExpression(
               factory.createPropertyAccessExpression(
                 factory.createIdentifier(route.name),
@@ -127,7 +144,7 @@ export namespace SdkWebSocketRouteProgrammer {
               [],
               project.config.keyword === true &&
                 SdkWebSocketParameterProgrammer.isPathEmpty(route) === false
-                ? [factory.createIdentifier("props")]
+                ? [factory.createIdentifier(names.props)]
                 : SdkWebSocketParameterProgrammer.getEntries({
                     project,
                     route,
@@ -137,7 +154,7 @@ export namespace SdkWebSocketRouteProgrammer {
             ),
           ),
         ),
-        local("connector")(
+        local(names.connector)(
           factory.createTypeReferenceNode(
             importer.external({
               declaration: false,
@@ -166,7 +183,7 @@ export namespace SdkWebSocketRouteProgrammer {
               factory.createAsExpression(
                 factory.createBinaryExpression(
                   factory.createPropertyAccessExpression(
-                    factory.createIdentifier(connection),
+                    factory.createIdentifier(names.connection),
                     "headers",
                   ),
                   factory.createToken(SyntaxKind.QuestionQuestionToken),
@@ -174,7 +191,7 @@ export namespace SdkWebSocketRouteProgrammer {
                 ),
                 factory.createKeywordTypeNode(SyntaxKind.AnyKeyword),
               ),
-              access("provider"),
+              names.access(names.provider),
             ],
           ),
         ),
@@ -182,15 +199,15 @@ export namespace SdkWebSocketRouteProgrammer {
           factory.createAwaitExpression(
             factory.createCallExpression(
               factory.createPropertyAccessExpression(
-                factory.createIdentifier("connector"),
+                factory.createIdentifier(names.connector),
                 "connect",
               ),
               undefined,
-              [factory.createIdentifier("url")],
+              [factory.createIdentifier(names.url)],
             ),
           ),
         ),
-        local("driver")(
+        local(names.driver)(
           factory.createTypeReferenceNode(
             importer.external({
               declaration: true,
@@ -203,7 +220,7 @@ export namespace SdkWebSocketRouteProgrammer {
         )(
           factory.createCallExpression(
             factory.createPropertyAccessExpression(
-              factory.createIdentifier("connector"),
+              factory.createIdentifier(names.connector),
               "getDriver",
             ),
             undefined,
@@ -213,8 +230,8 @@ export namespace SdkWebSocketRouteProgrammer {
         factory.createReturnStatement(
           factory.createObjectLiteralExpression(
             [
-              factory.createShorthandPropertyAssignment("connector"),
-              factory.createShorthandPropertyAssignment("driver"),
+              writeOutputMember("connector", names.connector),
+              writeOutputMember("driver", names.driver),
               factory.createPropertyAssignment(
                 factory.createIdentifier("reconnect"),
                 factory.createArrowFunction(
@@ -226,11 +243,11 @@ export namespace SdkWebSocketRouteProgrammer {
                   factory.createAwaitExpression(
                     factory.createCallExpression(
                       factory.createPropertyAccessExpression(
-                        factory.createIdentifier("connector"),
+                        factory.createIdentifier(names.connector),
                         factory.createIdentifier("connect"),
                       ),
                       undefined,
-                      [factory.createIdentifier("url")],
+                      [factory.createIdentifier(names.url)],
                     ),
                   ),
                 ),
@@ -243,6 +260,12 @@ export namespace SdkWebSocketRouteProgrammer {
     };
 }
 
+/** A member of the returned `Output`, shorthand when its local has its name. */
+const writeOutputMember = (key: string, local: string) =>
+  key === local
+    ? factory.createShorthandPropertyAssignment(key)
+    : factory.createPropertyAssignment(key, factory.createIdentifier(local));
+
 const local = (name: string) => (type: TypeNode) => (expression: Expression) =>
   factory.createVariableStatement(
     [],