@nestia/sdk 13.0.4 → 14.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nestia/sdk",
-  "version": "13.0.4",
+  "version": "14.0.1",
   "description": "Nestia SDK and Swagger generator",
   "main": "lib/index.js",
   "bin": {
@@ -46,8 +46,8 @@
   "homepage": "https://nestia.io",
   "dependencies": {
     "@ttsc/factory": "^0.28.1",
-    "@typia/interface": "^14.0.2",
-    "@typia/utils": "^14.0.2",
+    "@typia/interface": "^15.0.0",
+    "@typia/utils": "^15.0.0",
     "get-function-location": "^2.0.0",
     "glob": "^11.0.3",
     "path-to-regexp": "^6.2.1",
@@ -55,12 +55,12 @@
     "tgrid": "^1.2.1",
     "ttsc": "^0.28.1",
     "tstl": "^3.0.0",
-    "typia": "^14.0.2",
-    "@nestia/core": "^13.0.4",
-    "@nestia/fetcher": "^13.0.4"
+    "typia": "15.0.0",
+    "@nestia/core": "^14.0.1",
+    "@nestia/fetcher": "^14.0.1"
   },
   "peerDependencies": {
-    "@nestia/core": "^13.0.4"
+    "@nestia/core": "^14.0.1"
   },
   "devDependencies": {
     "@modelcontextprotocol/sdk": "^1.18.0",
@@ -88,7 +88,7 @@
   "scripts": {
     "build": "rimraf lib && ttsc",
     "dev": "ttsc --watch",
-    "test:go": "cd test && go test ./..."
+    "test:go": "cd test && go test -count=1 ./..."
   },
   "types": "lib/index.d.ts"
 }

package/src/INestiaConfig.ts

@@ -174,12 +174,11 @@ export namespace INestiaConfig {
     /**
      * OpenAPI version.
      *
-     * If you configure this property to be `2.0` or `3.0`, the newly generated
-     * `swagger.json` file would follow the specified OpenAPI version. The newly
-     * generated `swagger.json` file would be downgraded from the OpenAPI v3.1
-     * specification by {@link OpenApi.downgrade} method.
+     * If you configure this property to be `2.0`, `3.0`, or `3.1`, the newly
+     * generated `swagger.json` file would follow the specified OpenAPI version,
+     * downgraded from the OpenAPI v3.2 specification.
      *
-     * @default 3.1
+     * @default 3.2
      */
     openapi?: "2.0" | "3.0" | "3.1" | "3.2";
 
@@ -199,10 +198,12 @@ export namespace INestiaConfig {
      * Whether to include additional information or not.
      *
      * If configured to be `true`, those properties would be added into each API
-     * endpoinnt.
+     * endpoint.
      *
-     * - `x-nestia-method`
-     * - `x-nestia-namespace` ` `x-nestia-jsDocTags`
+     * - `x-nestia-method`: the HTTP method, such as `"GET"`
+     * - `x-nestia-namespace`: the SDK function's accessor, such as
+     *   `"bbs.articles.index"`
+     * - `x-nestia-jsDocTags`: the JSDoc tags of the controller method
      *
      * @default false
      */
@@ -223,7 +224,10 @@ export namespace INestiaConfig {
      *
      * When generating `swagger.json` file through `nestia`, if your controllers
      * or theirs methods have a security key which is not enrolled in here
-     * property, it would be an error.
+     * property, it would be an error. So would an OAuth2 scope none of the
+     * scheme's flows declares, and, for an OpenAPI `3.0` or `2.0` document,
+     * scopes on a scheme other than OAuth2 or OpenID Connect, which those
+     * versions require to be empty; from `3.1` on they list role names.
      */
     security?: Record<string, OpenApi.ISecurityScheme>;
 
@@ -245,7 +249,12 @@ export namespace INestiaConfig {
      * If you configure this property to be `true`, the query DTO would be
      * decomposed into individual query parameters per each property. Otherwise
      * you set it to be `false`, the query DTO would be one object type which
-     * contains all of query parameters.
+     * contains all of query parameters, spread into its keys by `style: form`
+     * and `explode: true`.
+     *
+     * Swagger 2.0 has no object query parameter, and no OpenAPI version can
+     * spread an object into headers, so a query DTO of a Swagger 2.0 document
+     * and a headers DTO are decomposed regardless of this property.
      *
      * @default true
      */

package/src/NestiaSdkApplication.ts

@@ -62,18 +62,18 @@ export class NestiaSdkApplication {
         "Error on NestiaApplication.e2e(): configure INestiaConfig.e2e property.",
       );
 
-    const validate =
-      (title: string) =>
-      async (location: string): Promise<void> => {
-        const parent: string = path.resolve(location + "/..");
-        const stats: fs.Stats = await fs.promises.lstat(parent);
-        if (stats.isDirectory() === false)
-          throw new Error(
-            `Error on NestiaApplication.e2e(): output directory of ${title} does not exists.`,
-          );
-      };
-    await validate("sdk")(this.config.output);
-    await validate("e2e")(this.config.e2e);
+    await assertDirectory({
+      method: "e2e",
+      property: "output",
+      location: this.config.output,
+      directory: path.resolve(this.config.output + "/.."),
+    });
+    await assertDirectory({
+      method: "e2e",
+      property: "e2e",
+      location: this.config.e2e,
+      directory: path.resolve(this.config.e2e + "/.."),
+    });
 
     print_title("Nestia E2E Generator");
     await this.generate({
@@ -90,12 +90,12 @@ export class NestiaSdkApplication {
         "Error on NestiaApplication.sdk(): configure INestiaConfig.output property.",
       );
 
-    const parent: string = path.resolve(this.config.output + "/..");
-    const stats: fs.Stats = await fs.promises.lstat(parent);
-    if (stats.isDirectory() === false)
-      throw new Error(
-        "Error on NestiaApplication.sdk(): output directory does not exists.",
-      );
+    await assertDirectory({
+      method: "sdk",
+      property: "output",
+      location: this.config.output,
+      directory: path.resolve(this.config.output + "/.."),
+    });
 
     print_title("Nestia SDK Generator");
     await this.generate({
@@ -111,14 +111,14 @@ export class NestiaSdkApplication {
       );
 
     const parsed: path.ParsedPath = path.parse(this.config.swagger.output);
-    const directory: string = !!parsed.ext
-      ? path.resolve(parsed.dir)
-      : this.config.swagger.output;
-    const stats: fs.Stats = await fs.promises.lstat(directory);
-    if (stats.isDirectory() === false)
-      throw new Error(
-        "Error on NestiaApplication.swagger(): output directory does not exists.",
-      );
+    await assertDirectory({
+      method: "swagger",
+      property: "swagger.output",
+      location: this.config.swagger.output,
+      directory: !!parsed.ext
+        ? path.resolve(parsed.dir)
+        : path.resolve(this.config.swagger.output),
+    });
 
     print_title("Nestia Swagger Generator");
     await this.generate({
@@ -218,10 +218,10 @@ export class NestiaSdkApplication {
           continue;
         }
         const pathList: Set<string> = new Set();
-        const versions: string[] = VersioningStrategy.merge(project)([
-          ...(c.versions ?? []),
-          ...(o.versions ?? []),
-        ]);
+        const versions: string[] = VersioningStrategy.merge(project)({
+          controller: c.versions,
+          method: o.versions,
+        });
         for (const v of versions)
           for (const prefix of wrapPaths(c.prefixes))
             for (const cPath of wrapPaths(c.paths))
@@ -288,6 +288,30 @@ export class NestiaSdkApplication {
   }
 }
 
+/**
+ * Asserts the directory an output is written into exists, naming the configured
+ * location. `fs.promises.stat()` itself rejects a missing path, so it is caught
+ * rather than left to surface as a bare `ENOENT`; a symbolic link to a
+ * directory is followed.
+ */
+const assertDirectory = async (props: {
+  method: string;
+  property: string;
+  location: string;
+  directory: string;
+}): Promise<void> => {
+  const stats: fs.Stats | null = await fs.promises
+    .stat(props.directory)
+    .catch((error: NodeJS.ErrnoException): null => {
+      if (error.code === "ENOENT" || error.code === "ENOTDIR") return null;
+      throw error;
+    });
+  if (stats === null || stats.isDirectory() === false)
+    throw new Error(
+      `Error on NestiaApplication.${props.method}(): directory ${JSON.stringify(props.directory)} of INestiaConfig.${props.property} ${JSON.stringify(props.location)} ${stats === null ? "does not exist" : "is not a directory"}.`,
+    );
+};
+
 const print_title = (str: string): void => {
   console.log("-----------------------------------------------------------");
   console.log(` ${str}`);
@@ -308,6 +332,8 @@ const report = (props: {
   console.log("");
   print_title(`Nestia ${StringUtil.capitalize(props.type)} Report`);
 
+  // every contradiction at once, not only the first function's
+  const messages: string[] = [];
   for (const {
     first: { error },
     second: contents,
@@ -318,24 +344,27 @@ const report = (props: {
       `${location} - `,
       error.class,
       ...(error.function !== null ? [`.${error.function}()`] : [""]),
-      ...(error.from !== null ? [` from ${error.from}`] : [""]),
+      // an empty origin names no part of the function
+      ...(error.from ? [` from ${error.from}`] : [""]),
       ":\n",
       contents
         .map((c) => {
           if (typeof c === "string") return `  - ${c}`;
           else
             return [
+              // the property the type was found at, when there is one
               c.accessor
-                ? `  - ${c.name}: `
-                : `  - ${c.name} (${c.accessor}): `,
+                ? `  - ${c.name} (${c.accessor}): `
+                : `  - ${c.name}: `,
               ...c.messages.map((msg) => `    - ${msg}`),
             ].join("\n");
         })
         .join("\n"),
     ].join("");
-    if (props.type === "error") throw new Error(message);
+    if (props.type === "error") messages.push(message);
     else console.log(message);
   }
+  if (messages.length !== 0) throw new Error(messages.join("\n\n"));
 };
 
 const wrapPaths = (paths: string[]): string[] =>

package/src/NestiaSwaggerComposer.ts

@@ -68,10 +68,10 @@ export namespace NestiaSwaggerComposer {
       for (const o of c.operations) {
         if (o.protocol !== "http") continue;
         const pathList: Set<string> = new Set();
-        const versions: string[] = VersioningStrategy.merge(project)([
-          ...(c.versions ?? []),
-          ...(o.versions ?? []),
-        ]);
+        const versions: string[] = VersioningStrategy.merge(project)({
+          controller: c.versions,
+          method: o.versions,
+        });
         for (const v of versions)
           for (const prefix of wrapPaths(c.prefixes))
             for (const cPath of wrapPaths(c.paths))
@@ -131,7 +131,8 @@ const report = (props: {
         `${location} - `,
         error.class,
         ...(error.function !== null ? [`.${error.function}()`] : [""]),
-        ...(error.from !== null ? [` from ${error.from}`] : [""]),
+        // an empty origin names no part of the function
+        ...(error.from ? [` from ${error.from}`] : [""]),
         ":\n",
         contents
           .map((c) => {
@@ -139,8 +140,8 @@ const report = (props: {
             else
               return [
                 c.accessor
-                  ? `  - ${c.name}: `
-                  : `  - ${c.name} (${c.accessor}): `,
+                  ? `  - ${c.name} (${c.accessor}): `
+                  : `  - ${c.name}: `,
                 ...c.messages.map((msg) => `    - ${msg}`),
               ].join("\n");
           })
@@ -148,7 +149,9 @@ const report = (props: {
       ].join(""),
     );
   }
-  throw new Error(`Error on NestiaSwaggerComposer.compose():\n${messages}`);
+  throw new Error(
+    `Error on NestiaSwaggerComposer.compose():\n${messages.join("\n\n")}`,
+  );
 };
 
 const wrapPaths = (paths: string[]): string[] =>

package/src/analyses/ConfigAnalyzer.ts

@@ -111,10 +111,10 @@ export namespace ConfigAnalyzer {
         versioning === undefined || versioning.type !== VersioningType.URI
           ? undefined
           : {
+              // as NestJS's RoutePathFactory.getVersionPrefix(): `false` is no
+              // prefix at all, and only an absent one is the default "v"
               prefix:
-                versioning.prefix === undefined || versioning.prefix === false
-                  ? "v"
-                  : versioning.prefix,
+                versioning.prefix === false ? "" : (versioning.prefix ?? "v"),
               defaultVersion: versioning.defaultVersion,
             },
     };

package/src/analyses/ParameterNameAnalyzer.ts

@@ -0,0 +1,51 @@
+import { NamingConvention } from "@typia/utils";
+
+import { StringUtil } from "../utils/StringUtil";
+
+export namespace ParameterNameAnalyzer {
+  export interface IParameter {
+    name: string;
+    category: string;
+    field?: string | null;
+  }
+
+  /**
+   * Names every parameter that declares no name of its own.
+   *
+   * A destructured parameter, `@TypedBody() { title }: IBody`, binds names but
+   * is not one, so the SDK's metadata carries it with an empty name. Its source
+   * text is no identifier the SDK could declare, and passing it as one would
+   * send `{ title }` alone. It is named after what it carries instead: its
+   * field when that is an identifier, or reads as one with its separators
+   * dropped in camel case, otherwise its category, such as `body` or `query`.
+   * The name yields to every other parameter's, which are the user's and are
+   * kept.
+   */
+  export const name = <T extends IParameter>(parameters: T[]): T[] => {
+    const taken: string[] = parameters
+      .map((p) => p.name)
+      .filter((name) => name.length !== 0);
+    return parameters.map((p) => {
+      if (p.name.length !== 0) return p;
+      const name: string = StringUtil.escapeDuplicate(taken)(candidate(p));
+      taken.push(name);
+      return { ...p, name };
+    });
+  };
+
+  const candidate = (p: IParameter): string => {
+    if (p.field !== undefined && p.field !== null && p.field.length !== 0) {
+      if (NamingConvention.variable(p.field)) return p.field;
+      // `x-tenant` as `xTenant`
+      const camel: string = p.field
+        .split(/[^A-Za-z0-9_$]+/)
+        .filter((word) => word.length !== 0)
+        .map((word, i) =>
+          i === 0 ? word : word.charAt(0).toUpperCase() + word.slice(1),
+        )
+        .join("");
+      if (NamingConvention.variable(camel)) return camel;
+    }
+    return p.category;
+  };
+}

package/src/analyses/PathAnalyzer.ts

@@ -1,16 +1,19 @@
 import { RequestMethod } from "@nestjs/common";
-import path from "path";
 import { Token, parse } from "path-to-regexp";
 
 export namespace PathAnalyzer {
+  /**
+   * The route paths joined as the router joins them: one `/` between them, and
+   * none doubled. A route path is router syntax, never a file path, so a
+   * backslash stays the escape of the character after it (`items\\:batchGet`).
+   */
   export const join = (...args: string[]) =>
     "/" +
-    _Trim(
-      path
-        .join(...args.filter((s) => !!s.length))
-        .split("\\")
-        .join("/"),
-    );
+    args
+      .join("/")
+      .split("/")
+      .filter((str) => str.length !== 0)
+      .join("/");
 
   export const joinWithGlobalPrefix = (props: {
     globalPrefix: string;
@@ -41,20 +44,78 @@ export namespace PathAnalyzer {
     );
   };
 
+  /**
+   * Whether a route path holds a wildcard: a `*` not escaped as the literal
+   * character (`\\*`), which a route path may hold since #1713.
+   */
+  export const wildcard = (str: string): boolean => /(^|[^\\])\*/.test(str);
+
+  /**
+   * The literal text and parameters of a path, in order, as path-to-regexp
+   * reads it: `/files/:id.json` is `/files/`, the parameter `id`, then `.json`,
+   * and `/range/:from-:to` holds two parameters parted by `-`. Every generator
+   * that writes a path with its parameters filled in reads it from here, never
+   * by splitting the text at `:` or `/`. `null` for a path it cannot parse.
+   */
+  export const segments = (str: string): ISegment[] | null => {
+    const tokens: Token[] | null = _Tokenize(str);
+    if (tokens === null) return null;
+    const output: ISegment[] = [];
+    const literal = (value: string): void => {
+      if (value.length === 0) return;
+      const last: ISegment | undefined = output[output.length - 1];
+      if (last?.type === "literal") last.value += value;
+      else output.push({ type: "literal", value });
+    };
+    for (const token of tokens)
+      if (typeof token === "string") literal(token);
+      else if (typeof token.name === "number") return null;
+      else {
+        literal(token.prefix);
+        output.push({ type: "param", name: token.name });
+        literal(token.suffix);
+      }
+    return output;
+  };
+
+  /**
+   * The path in OpenAPI's template syntax, each parameter written `{name}`:
+   * `/files/:id.json` is `/files/{id}.json`.
+   */
+  export const toOpenApi = (str: string): string => {
+    const list: ISegment[] | null = segments(str);
+    return list === null
+      ? str
+      : list
+          .map((s) => (s.type === "literal" ? s.value : `{${s.name}}`))
+          .join("");
+  };
+
+  export type ISegment =
+    | { type: "literal"; value: string }
+    | { type: "param"; name: string };
+
   export const parameters = (str: string): string[] | null => {
     const args = _Parse(str);
     if (args === null) return null;
     return args.filter((arg) => arg.type === "param").map((arg) => arg.value);
   };
 
+  /**
+   * The route's tokens, its literal text unescaped. Both routers' spellings of
+   * a literal colon are read: path-to-regexp's (Express) `\\:`, and
+   * find-my-way's (Fastify) `::`, which path-to-regexp would reject.
+   */
+  function _Tokenize(str: string): Token[] | null {
+    try {
+      return parse(fromFastifyColons(join(str)));
+    } catch {
+      return null;
+    }
+  }
+
   function _Parse(str: string): IArgument[] | null {
-    const tokens: Token[] | null = (() => {
-      try {
-        return parse(path.join(str).split("\\").join("/"));
-      } catch {
-        return null;
-      }
-    })();
+    const tokens: Token[] | null = _Tokenize(str);
     if (tokens === null) return null;
 
     const output: IArgument[] = [];
@@ -128,3 +189,34 @@ const REQUEST_METHODS: Record<string, RequestMethod> = {
   POST: RequestMethod.POST,
   PUT: RequestMethod.PUT,
 };
+
+/**
+ * A route with find-my-way's (Fastify) literal colon `::` spelled as
+ * path-to-regexp's `\:`. find-my-way reads `::` as a colon in static text
+ * alone: after a parameter it is part of the parameter's name, so it is left as
+ * is there, and path-to-regexp then rejects the route, as no parameter of that
+ * name is what the handler reads.
+ *
+ * @internal
+ */
+const fromFastifyColons = (route: string): string => {
+  let output: string = "";
+  for (let i: number = 0; i < route.length; ) {
+    if (route[i] === "\\") {
+      output += route.slice(i, i + 2);
+      i += 2;
+    } else if (route.startsWith("::", i)) {
+      output += "\\:";
+      i += 2;
+    } else if (route[i] === ":") {
+      const name: string = /^:[A-Za-z0-9_$]*/.exec(route.slice(i))![0];
+      output += name;
+      i += name.length;
+      if (route.startsWith("::", i)) {
+        output += "::";
+        i += 2;
+      }
+    } else output += route[i++];
+  }
+  return output;
+};

package/src/analyses/ReflectControllerAnalyzer.ts

@@ -12,6 +12,7 @@ import { IReflectHttpOperation } from "../structures/IReflectHttpOperation";
 import { IReflectMcpOperation } from "../structures/IReflectMcpOperation";
 import { IReflectWebSocketOperation } from "../structures/IReflectWebSocketOperation";
 import { ArrayUtil } from "../utils/ArrayUtil";
+import { PathAnalyzer } from "./PathAnalyzer";
 import { ReflectHttpOperationAnalyzer } from "./ReflectHttpOperationAnalyzer";
 import { ReflectMcpOperationAnalyzer } from "./ReflectMcpOperationAnalyzer";
 import { ReflectMetadataAnalyzer } from "./ReflectMetadataAnalyzer";
@@ -46,7 +47,7 @@ export namespace ReflectControllerAnalyzer {
       prefixes: props.controller.prefixes,
       paths: ReflectMetadataAnalyzer.paths(props.controller.class).filter(
         (str) => {
-          if (str.includes("*") === true) {
+          if (PathAnalyzer.wildcard(str)) {
             props.project.warnings.push({
               file: props.controller.location,
               class: props.controller.class.name,

package/src/analyses/ReflectHttpOperationAnalyzer.ts

@@ -77,7 +77,7 @@ export namespace ReflectHttpOperationAnalyzer {
       name: props.name,
       method: method === "ALL" ? "POST" : method,
       paths: ReflectMetadataAnalyzer.paths(props.function).filter((str) => {
-        if (str.includes("*") === true) {
+        if (PathAnalyzer.wildcard(str)) {
           props.project.warnings.push({
             file: props.controller.file,
             class: props.controller.class.name,
@@ -117,8 +117,8 @@ export namespace ReflectHttpOperationAnalyzer {
       jsDocTags: props.metadata.jsDocTags,
       operationId: props.metadata.jsDocTags
         .find(({ name }) => name === "operationId")
-        ?.text?.[0]?.text.split(" ")[0]
-        ?.trim(),
+        ?.text?.[0]?.text.trim()
+        .split(/\s+/)[0],
       extensions: ReflectMetadataAnalyzer.extensions(props.function),
     };
 
@@ -130,7 +130,7 @@ export namespace ReflectHttpOperationAnalyzer {
           controllerLocation,
           metaLocation,
         );
-        if (location.includes("*")) continue;
+        if (PathAnalyzer.wildcard(location)) continue;
 
         // LIST UP PARAMETERS
         const binded: string[] | null = PathAnalyzer.parameters(location);