@nestia/sdk 13.0.4 → 14.0.1

package/src/generates/internal/SdkMcpRouteProgrammer.ts

@@ -12,6 +12,7 @@ import {
 import { IdentifierFactory } from "../../factories/IdentifierFactory";
 import { INestiaProject } from "../../structures/INestiaProject";
 import { ITypedMcpRoute } from "../../structures/ITypedMcpRoute";
+import { StringUtil } from "../../utils/StringUtil";
 import { FilePrinter } from "./FilePrinter";
 import { ImportDictionary } from "./ImportDictionary";
 
@@ -39,6 +40,16 @@ export namespace SdkMcpRouteProgrammer {
     (_project: INestiaProject) =>
     (importer: ImportDictionary) =>
     (route: ITypedMcpRoute): Node => {
+      // The body reads `<route>.METADATA` next to these, so they yield to a
+      // tool of the same name, as the HTTP and WebSocket SDKs' own do.
+      const own = StringUtil.escapeDuplicate([route.name]);
+      const names = {
+        client: own("client"),
+        args: own("args"),
+        raw: own("raw"),
+        result: own("result"),
+        first: own("first"),
+      };
       const clientType = factory.createTypeReferenceNode(
         importer.external({
           declaration: true,
@@ -75,7 +86,7 @@ export namespace SdkMcpRouteProgrammer {
         factory.createParameterDeclaration(
           undefined,
           undefined,
-          "client",
+          names.client,
           undefined,
           clientType,
           undefined,
@@ -86,7 +97,7 @@ export namespace SdkMcpRouteProgrammer {
           factory.createParameterDeclaration(
             undefined,
             undefined,
-            "args",
+            names.args,
             undefined,
             inputRef,
             undefined,
@@ -110,7 +121,7 @@ export namespace SdkMcpRouteProgrammer {
             "arguments",
             factory.createAsExpression(
               factory.createAsExpression(
-                factory.createIdentifier("args"),
+                factory.createIdentifier(names.args),
                 factory.createKeywordTypeNode(SyntaxKind.AnyKeyword),
               ),
               factory.createTypeReferenceNode("Record", [
@@ -128,13 +139,13 @@ export namespace SdkMcpRouteProgrammer {
             factory.createVariableDeclarationList(
               [
                 factory.createVariableDeclaration(
-                  "raw",
+                  names.raw,
                   undefined,
                   undefined,
                   factory.createAwaitExpression(
                     factory.createCallExpression(
                       factory.createPropertyAccessExpression(
-                        factory.createIdentifier("client"),
+                        factory.createIdentifier(names.client),
                         "callTool",
                       ),
                       undefined,
@@ -165,7 +176,7 @@ export namespace SdkMcpRouteProgrammer {
               ),
               undefined,
               [
-                factory.createIdentifier("raw"),
+                factory.createIdentifier(names.raw),
                 factory.createStringLiteral("toolResult"),
               ],
             ),
@@ -179,11 +190,11 @@ export namespace SdkMcpRouteProgrammer {
             factory.createVariableDeclarationList(
               [
                 factory.createVariableDeclaration(
-                  "result",
+                  names.result,
                   undefined,
                   factory.createTypeReferenceNode(callToolResultTypeName),
                   factory.createAsExpression(
-                    factory.createIdentifier("raw"),
+                    factory.createIdentifier(names.raw),
                     factory.createTypeReferenceNode(callToolResultTypeName),
                   ),
                 ),
@@ -194,13 +205,13 @@ export namespace SdkMcpRouteProgrammer {
           factory.createIfStatement(
             factory.createBinaryExpression(
               factory.createPropertyAccessExpression(
-                factory.createIdentifier("result"),
+                factory.createIdentifier(names.result),
                 "isError",
               ),
               factory.createToken(SyntaxKind.EqualsEqualsEqualsToken),
               factory.createTrue(),
             ),
-            throwToolError(toolNameExpr, '" returned isError'),
+            throwToolErrorWithText(toolNameExpr, names.result),
           ),
           ...(isVoid
             ? [factory.createReturnStatement()]
@@ -210,13 +221,13 @@ export namespace SdkMcpRouteProgrammer {
                   factory.createVariableDeclarationList(
                     [
                       factory.createVariableDeclaration(
-                        "first",
+                        names.first,
                         undefined,
                         undefined,
                         factory.createCallExpression(
                           factory.createPropertyAccessExpression(
                             factory.createPropertyAccessExpression(
-                              factory.createIdentifier("result"),
+                              factory.createIdentifier(names.result),
                               "content",
                             ),
                             "find",
@@ -249,7 +260,7 @@ export namespace SdkMcpRouteProgrammer {
                 ),
                 factory.createIfStatement(
                   factory.createBinaryExpression(
-                    factory.createIdentifier("first"),
+                    factory.createIdentifier(names.first),
                     factory.createToken(SyntaxKind.EqualsEqualsEqualsToken),
                     factory.createIdentifier("undefined"),
                   ),
@@ -258,7 +269,7 @@ export namespace SdkMcpRouteProgrammer {
                 factory.createIfStatement(
                   factory.createBinaryExpression(
                     factory.createPropertyAccessExpression(
-                      factory.createIdentifier("first"),
+                      factory.createIdentifier(names.first),
                       "type",
                     ),
                     factory.createToken(SyntaxKind.EqualsEqualsEqualsToken),
@@ -274,7 +285,7 @@ export namespace SdkMcpRouteProgrammer {
                         undefined,
                         [
                           factory.createPropertyAccessExpression(
-                            factory.createIdentifier("first"),
+                            factory.createIdentifier(names.first),
                             "text",
                           ),
                         ],
@@ -423,6 +434,92 @@ export namespace SdkMcpRouteProgrammer {
   const isVoidName = (name: string): boolean =>
     name === "void" || name === "undefined";
 
+  /**
+   * The error of a tool that answered `isError`, carrying the text content the
+   * tool put its reason in, as `McpAdaptor` does an `HttpException`'s message.
+   */
+  const throwToolErrorWithText = (
+    toolNameExpr: Expression,
+    result: string,
+  ): Statement => {
+    const entry = (): Expression => factory.createIdentifier("entry");
+    return factory.createThrowStatement(
+      factory.createNewExpression(
+        factory.createIdentifier("Error"),
+        undefined,
+        [
+          factory.createTemplateExpression(
+            factory.createTemplateHead('MCP tool "'),
+            [
+              factory.createTemplateSpan(
+                toolNameExpr,
+                factory.createTemplateMiddle('" returned isError: '),
+              ),
+              factory.createTemplateSpan(
+                factory.createCallExpression(
+                  factory.createPropertyAccessExpression(
+                    factory.createCallExpression(
+                      factory.createPropertyAccessExpression(
+                        factory.createCallExpression(
+                          factory.createPropertyAccessExpression(
+                            factory.createPropertyAccessExpression(
+                              factory.createIdentifier(result),
+                              "content",
+                            ),
+                            "filter",
+                          ),
+                          undefined,
+                          [
+                            factory.createArrowFunction(
+                              undefined,
+                              undefined,
+                              [IdentifierFactory.parameter("entry")],
+                              undefined,
+                              undefined,
+                              factory.createBinaryExpression(
+                                factory.createPropertyAccessExpression(
+                                  entry(),
+                                  "type",
+                                ),
+                                factory.createToken(
+                                  SyntaxKind.EqualsEqualsEqualsToken,
+                                ),
+                                factory.createStringLiteral("text"),
+                              ),
+                            ),
+                          ],
+                        ),
+                        "map",
+                      ),
+                      undefined,
+                      [
+                        factory.createArrowFunction(
+                          undefined,
+                          undefined,
+                          [IdentifierFactory.parameter("entry")],
+                          undefined,
+                          undefined,
+                          factory.createPropertyAccessExpression(
+                            entry(),
+                            "text",
+                          ),
+                        ),
+                      ],
+                    ),
+                    "join",
+                  ),
+                  undefined,
+                  [factory.createStringLiteral("\n")],
+                ),
+                factory.createTemplateTail(""),
+              ),
+            ],
+          ),
+        ],
+      ),
+    );
+  };
+
   const throwToolError = (
     toolNameExpr: Expression,
     suffix: string,

package/src/generates/internal/SdkPathTemplate.ts

@@ -0,0 +1,73 @@
+import { type Expression, factory } from "@ttsc/factory";
+
+import { PathAnalyzer } from "../../analyses/PathAnalyzer";
+import { IdentifierFactory } from "../../factories/IdentifierFactory";
+import { ImportDictionary } from "./ImportDictionary";
+
+export namespace SdkPathTemplate {
+  /**
+   * The expression an SDK function builds its route's path with: the literal
+   * text of the path, each parameter filled in by `PathParameter.encode()` of
+   * `@nestia/fetcher` with the value `argument` names for it: URI-encoded, or
+   * `"null"` when nullish, and refused when it is a dot segment (`.`, `..`) the
+   * URL would resolve away.
+   *
+   * The positions come from {@link PathAnalyzer.segments}, as the server's
+   * router reads the path, so a parameter with literal text beside it in its
+   * segment, such as `/files/:id.json` or `/range/:from-:to`, is filled in
+   * where it stands.
+   */
+  export const compose = (props: {
+    importer: ImportDictionary;
+    path: string;
+    argument: (name: string) => Expression;
+  }): Expression => {
+    const segments: PathAnalyzer.ISegment[] | null = PathAnalyzer.segments(
+      props.path,
+    );
+    if (segments === null) return factory.createStringLiteral(props.path);
+    // the literal text as the router reads it, an escaped `\:` unescaped
+    else if (segments.every((segment) => segment.type === "literal"))
+      return factory.createStringLiteral(
+        segments
+          .map((segment) => (segment.type === "literal" ? segment.value : ""))
+          .join(""),
+      );
+
+    // a template holds a literal between every two expressions
+    const literals: string[] = [""];
+    const parameters: string[] = [];
+    for (const segment of segments)
+      if (segment.type === "literal")
+        literals[literals.length - 1] += segment.value;
+      else {
+        parameters.push(segment.name);
+        literals.push("");
+      }
+    return factory.createTemplateExpression(
+      factory.createTemplateHead(literals[0]!),
+      parameters.map((name, i) =>
+        factory.createTemplateSpan(
+          factory.createCallExpression(
+            IdentifierFactory.access(
+              factory.createIdentifier(
+                props.importer.external({
+                  declaration: false,
+                  file: "@nestia/fetcher",
+                  type: "element",
+                  name: "PathParameter",
+                }),
+              ),
+              "encode",
+            ),
+            undefined,
+            [factory.createStringLiteral(name), props.argument(name)],
+          ),
+          (i !== parameters.length - 1
+            ? factory.createTemplateMiddle
+            : factory.createTemplateTail)(literals[i + 1]!),
+        ),
+      ),
+    );
+  };
+}

package/src/generates/internal/SdkTypeProgrammer.ts

@@ -3,6 +3,7 @@ import { NamingConvention } from "@typia/utils";
 import { IJsDocTagInfo, IMetadataTypeTag } from "typia";
 
 import { ExpressionFactory } from "../../factories/ExpressionFactory";
+import { LiteralFactory } from "../../factories/LiteralFactory";
 import { TypeFactory } from "../../factories/TypeFactory";
 import {
   MetadataAliasType,
@@ -14,6 +15,7 @@ import {
   MetadataProperty,
   MetadataSchema,
   MetadataTuple,
+  decodeMetadataValue,
   isRequiredOf,
   isSoleLiteralOf,
   sizeOf,
@@ -43,7 +45,7 @@ export namespace SdkTypeProgrammer {
 
       // ATOMIC TYPES
       for (const c of meta.constants)
-        for (const value of c.values) union.push(write_constant(value));
+        for (const value of c.values) union.push(write_constant(c.type, value));
       for (const tpl of meta.templates)
         union.push(write_template(project)(importer)(tpl.row ?? tpl));
       for (const atom of meta.atomics) union.push(write_atomic(importer)(atom));
@@ -106,10 +108,7 @@ export namespace SdkTypeProgrammer {
       )
         return factory.createIntersectionTypeNode([
           TypeFactory.keyword("string"),
-          SdkTypeTagProgrammer.write(importer, "string", {
-            name: "Format",
-            value: "date-time",
-          } as IMetadataTypeTag),
+          SdkTypeTagProgrammer.writePredefined(importer, "Format", "date-time"),
         ]);
       return write(project)(importer)(meta.returns, true);
     };
@@ -117,26 +116,24 @@ export namespace SdkTypeProgrammer {
   /* -----------------------------------------------------------
     ATOMICS
   ----------------------------------------------------------- */
-  const write_constant = (value: MetadataConstantValue) => {
-    if (typeof value.value === "boolean")
+  const write_constant = (
+    type: string,
+    constant: MetadataConstantValue,
+  ): TypeNode => {
+    const value: unknown = decodeMetadataValue(type, constant.value);
+    if (typeof value === "boolean")
       return factory.createLiteralTypeNode(
-        value.value ? factory.createTrue() : factory.createFalse(),
-      );
-    else if (typeof value.value === "bigint")
-      return factory.createLiteralTypeNode(
-        value.value < BigInt(0)
-          ? factory.createPrefixUnaryExpression(
-              SyntaxKind.MinusToken,
-              factory.createBigIntLiteral((-value.value).toString()),
-            )
-          : factory.createBigIntLiteral(value.value.toString()),
-      );
-    else if (typeof value.value === "number")
-      return factory.createLiteralTypeNode(
-        ExpressionFactory.number(value.value),
+        value ? factory.createTrue() : factory.createFalse(),
       );
+    else if (typeof value === "bigint")
+      return factory.createLiteralTypeNode(LiteralFactory.write(value) as any);
+    else if (typeof value === "number")
+      // NaN is the one number with no literal type
+      return Number.isNaN(value)
+        ? TypeFactory.keyword("number")
+        : factory.createLiteralTypeNode(ExpressionFactory.number(value));
     return factory.createLiteralTypeNode(
-      factory.createStringLiteral(value.value as string),
+      factory.createStringLiteral(value as string),
     );
   };