@nestia/sdk 3.0.0-dev.20231209 → 3.0.0-dev.20240412

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nestia/sdk",
-  "version": "3.0.0-dev.20231209",
+  "version": "3.0.0-dev.20240412",
   "description": "Nestia SDK and Swagger generator",
   "main": "lib/index.js",
   "typings": "lib/index.d.ts",
@@ -11,8 +11,6 @@
     "build": "rimraf lib && tsc",
     "dev": "rimraf lib && tsc --watch",
     "eslint": "eslint ./**/*.ts",
-    "package:latest": "npm run build && npm publish --access public",
-    "package:next": "npm run package:latest -- --tag next",
     "prepare": "ts-patch install && typia patch"
   },
   "repository": {
@@ -34,44 +32,42 @@
   },
   "homepage": "https://nestia.io",
   "dependencies": {
-    "@nestia/fetcher": "^3.0.0-dev.20231209",
+    "@nestia/fetcher": "^3.0.0-dev.20240412",
+    "@samchon/openapi": "^0.1.2",
     "cli": "^1.0.1",
     "get-function-location": "^2.0.0",
     "glob": "^7.2.0",
     "path-to-regexp": "^6.2.1",
-    "reflect-metadata": ">=0.1.12",
+    "prettier": "^3.2.5",
     "tsconfck": "^2.0.1",
     "tsconfig-paths": "^4.1.1",
-    "tstl": "^2.5.13",
-    "typia": "^5.3.4"
+    "ts-node": ">=10.6.0",
+    "tstl": "^3.0.0",
+    "typia": "^6.0.0"
   },
   "peerDependencies": {
-    "@nestia/fetcher": ">=3.0.0-dev.20231209",
+    "@nestia/fetcher": ">=3.0.0-dev.20240412",
     "@nestjs/common": ">=7.0.1",
     "@nestjs/core": ">=7.0.1",
     "reflect-metadata": ">=0.1.12",
     "ts-node": ">=10.6.0",
-    "typescript": ">=4.8.0 <5.4.0",
-    "typia": ">=5.3.4 <6.0.0"
+    "typia": ">=6.0.0 <7.0.0"
   },
   "devDependencies": {
-    "@nestia/e2e": "^0.3.7",
-    "@nestjs/common": ">= 7.0.1",
-    "@nestjs/core": ">= 7.0.1",
+    "@nestia/e2e": "^0.4.1",
+    "@trivago/prettier-plugin-sort-imports": "^4.3.0",
     "@types/cli": "^0.11.21",
     "@types/express": "^4.17.15",
     "@types/glob": "^7.2.0",
     "@types/node": "^18.11.15",
-    "@types/reflect-metadata": "^0.1.0",
     "@types/uuid": "^9.0.0",
     "@typescript-eslint/eslint-plugin": "^5.46.1",
     "@typescript-eslint/parser": "^5.46.1",
     "eslint": "^8.29.0",
     "eslint-plugin-deprecation": "^1.4.1",
     "rimraf": "^3.0.2",
-    "ts-node": "^10.9.1",
     "ts-patch": "v3.0.2",
-    "typescript": "^5.3.2",
+    "typescript": "^5.4.2",
     "typescript-transform-paths": "^3.4.4",
     "uuid": "^9.0.0"
   },

package/src/INestiaConfig.ts

@@ -1,9 +1,7 @@
 import type { INestApplication } from "@nestjs/common";
 
 import type { INormalizedInput } from "./structures/INormalizedInput";
-import type { ISwagger } from "./structures/ISwagger";
-import type { ISwaggerInfo } from "./structures/ISwaggerInfo";
-import type { ISwaggerSecurityScheme } from "./structures/ISwaggerSecurityScheme";
+import { OpenApi } from "@samchon/openapi";
 
 /**
  * Definition for the `nestia.config.ts` file.
@@ -193,17 +191,31 @@ export namespace INestiaConfig {
      */
     beautify?: boolean | number;
 
+    /**
+     * Whether to include additional information or not.
+     *
+     * If configured to be `true`, those properties would be added into each
+     * API endpoinnt.
+     *
+     * - `x-nestia-method`
+     * - `x-nestia-namespace`
+     * ` `x-nestia-jsDocTags`
+     *
+     * @default false
+     */
+    additional?: boolean;
+
     /**
      * API information.
      *
      * If omitted, `package.json` content would be used instead.
      */
-    info?: Partial<ISwaggerInfo>;
+    info?: Partial<OpenApi.IDocument.IInfo>;
 
     /**
      * List of server addresses.
      */
-    servers?: ISwagger.IServer[];
+    servers?: OpenApi.IServer[];
 
     /**
      * Security schemes.
@@ -212,7 +224,19 @@ export namespace INestiaConfig {
      * theirs methods have a security key which is not enrolled in here property,
      * it would be an error.
      */
-    security?: Record<string, ISwaggerSecurityScheme>;
+    security?: Record<string, OpenApi.ISecurityScheme>;
+
+    /**
+     * List of tag names with description.
+     *
+     * It is possible to omit this property or skip some tag name even if
+     * the tag name is used in the API routes. In that case, the tag name
+     * would be used without description.
+     *
+     * Of course, if you've written a comment like `@tag {name} {descrition}`,
+     * you can entirely replace this property specification.
+     */
+    tags?: OpenApi.IDocument.ITag[];
 
     /**
      * Decompose query DTO.

package/src/NestiaSdkApplication.ts

@@ -1,253 +1,255 @@
-import fs from "fs";
-import path from "path";
-import ts from "typescript";
-
-import { INestiaConfig } from "./INestiaConfig";
-import { AccessorAnalyzer } from "./analyses/AccessorAnalyzer";
-import { ConfigAnalyzer } from "./analyses/ConfigAnalyzer";
-import { ControllerAnalyzer } from "./analyses/ControllerAnalyzer";
-import { ReflectAnalyzer } from "./analyses/ReflectAnalyzer";
-import { E2eGenerator } from "./generates/E2eGenerator";
-import { SdkGenerator } from "./generates/SdkGenerator";
-import { SwaggerGenerator } from "./generates/SwaggerGenerator";
-import { IController } from "./structures/IController";
-import { IErrorReport } from "./structures/IErrorReport";
-import { INestiaProject } from "./structures/INestiaProject";
-import { IRoute } from "./structures/IRoute";
-import { MapUtil } from "./utils/MapUtil";
-
-export class NestiaSdkApplication {
-  public constructor(
-    private readonly config: INestiaConfig,
-    private readonly compilerOptions: ts.CompilerOptions,
-  ) {}
-
-  public async e2e(): Promise<void> {
-    if (!this.config.output)
-      throw new Error(
-        "Error on NestiaApplication.e2e(): output path of SDK is not specified.",
-      );
-    else if (!this.config.e2e)
-      throw new Error(
-        "Error on NestiaApplication.e2e(): output path of e2e test files is not specified.",
-      );
-
-    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);
-
-    print_title("Nestia E2E Generator");
-    await this.generate(
-      "e2e",
-      (config) => config,
-      (checker) => (config) => async (routes) => {
-        await SdkGenerator.generate(checker)(config)(routes);
-        await E2eGenerator.generate(config)(routes);
-      },
-    );
-  }
-
-  public async sdk(): Promise<void> {
-    if (!this.config.output)
-      throw new Error(
-        "Error on NestiaApplication.sdk(): output path is not specified.",
-      );
-
-    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.",
-      );
-
-    print_title("Nestia SDK Generator");
-    await this.generate("sdk", (config) => config, SdkGenerator.generate);
-  }
-
-  public async swagger(): Promise<void> {
-    if (!this.config.swagger?.output)
-      throw new Error(
-        `Error on NestiaApplication.swagger(): output path of the "swagger.json" is not specified.`,
-      );
-
-    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.",
-      );
-
-    print_title("Nestia Swagger Generator");
-    await this.generate(
-      "swagger",
-      (config) => config.swagger!,
-      SwaggerGenerator.generate,
-    );
-  }
-
-  private async generate<Config>(
-    method: string,
-    config: (entire: INestiaConfig) => Config,
-    archiver: (
-      checker: ts.TypeChecker,
-    ) => (config: Config) => (routes: IRoute[]) => Promise<void>,
-  ): Promise<void> {
-    //----
-    // ANALYZE REFLECTS
-    //----
-    const unique: WeakSet<any> = new WeakSet();
-    const controllers: IController[] = [];
-    const project: INestiaProject = {
-      config: this.config,
-      input: await ConfigAnalyzer.input(this.config),
-      checker: null!,
-      errors: [],
-      warnings: [],
-    };
-
-    console.log("Analyzing reflections");
-    for (const include of (await ConfigAnalyzer.input(this.config)).include)
-      controllers.push(
-        ...(await ReflectAnalyzer.analyze(project)(
-          unique,
-          include.file,
-          include.paths,
-          include.controller,
-        )),
-      );
-
-    const agg: number = (() => {
-      const set: Set<string> = new Set();
-      for (const c of controllers)
-        for (const cPath of c.paths)
-          for (const f of c.functions)
-            for (const fPath of f.paths)
-              set.add(`${f.method}::${cPath}/${fPath}`);
-      return set.size;
-    })();
-
-    console.log(`  - controllers: #${controllers.length}`);
-    console.log(`  - paths: #${agg}`);
-    console.log(
-      `  - routes: #${controllers
-        .map(
-          (c) =>
-            c.paths.length *
-            c.functions.map((f) => f.paths.length).reduce((a, b) => a + b, 0),
-        )
-        .reduce((a, b) => a + b, 0)}`,
-    );
-
-    //----
-    // ANALYZE TYPESCRIPT CODE
-    //----
-    console.log("Analyzing source codes");
-
-    const program: ts.Program = ts.createProgram(
-      controllers.map((c) => c.file),
-      this.compilerOptions,
-    );
-    project.checker = program.getTypeChecker();
-
-    const routeList: IRoute[] = [];
-    for (const c of controllers) {
-      const file: ts.SourceFile | undefined = program.getSourceFile(c.file);
-      if (file === undefined) continue;
-      routeList.push(...(await ControllerAnalyzer.analyze(project)(file, c)));
-    }
-
-    // REPORT ERRORS
-    if (project.errors.length) {
-      report_errors("error")(project.errors);
-      process.exit(-1);
-    }
-    if (project.warnings.length) report_errors("warning")(project.warnings);
-
-    // FIND IMPLICIT TYPES
-    const implicit: IRoute[] = routeList.filter(is_implicit_return_typed);
-    if (implicit.length > 0)
-      throw new Error(
-        `NestiaApplication.${method}(): implicit return type is not allowed.\n` +
-          "\n" +
-          "List of implicit return typed routes:\n" +
-          implicit
-            .map(
-              (it) =>
-                `  - ${it.symbol.class}.${it.symbol.function} at "${it.location}"`,
-            )
-            .join("\n"),
-      );
-
-    // DO GENERATE
-    AccessorAnalyzer.analyze(routeList);
-    await archiver(project.checker)(config(this.config))(routeList);
-  }
-}
-
-const print_title = (str: string): void => {
-  console.log("-----------------------------------------------------------");
-  console.log(` ${str}`);
-  console.log("-----------------------------------------------------------");
-};
-
-const is_implicit_return_typed = (route: IRoute): boolean => {
-  const name: string = route.output.typeName;
-  if (name === "void") return false;
-  else if (name.indexOf("readonly [") !== -1) return true;
-
-  const pos: number = name.indexOf("__object");
-  if (pos === -1) return false;
-
-  const before: number = pos - 1;
-  const after: number = pos + "__object".length;
-  for (const i of [before, after])
-    if (name[i] === undefined) continue;
-    else if (VARIABLE.test(name[i])) return false;
-  return true;
-};
-
-const report_errors =
-  (type: "error" | "warning") =>
-  (errors: IErrorReport[]): void => {
-    // key: file
-    // key: controller
-    // key: function
-    // value: message
-    const map: Map<string, Map<string, Map<string, Set<string>>>> = new Map();
-    for (const e of errors) {
-      const file = MapUtil.take(map, e.file, () => new Map());
-      const controller = MapUtil.take(file, e.controller, () => new Map());
-      const func = MapUtil.take(controller, e.function, () => new Set());
-      func.add(e.message);
-    }
-
-    console.log("");
-    print_title(`Nestia ${type[0].toUpperCase()}${type.slice(1)} Report`);
-    for (const [file, cMap] of map) {
-      for (const [controller, fMap] of cMap)
-        for (const [func, messages] of fMap) {
-          const location: string = path.relative(process.cwd(), file);
-          console.log(
-            `${location} - ${
-              func !== null ? `${controller}.${func}()` : controller
-            }`,
-          );
-          for (const msg of messages) console.log(`  - ${msg}`);
-          console.log("");
-        }
-    }
-  };
-
-const VARIABLE = /[a-zA-Z_$0-9]/;
+import fs from "fs";
+import path from "path";
+import ts from "typescript";
+
+import { INestiaConfig } from "./INestiaConfig";
+import { AccessorAnalyzer } from "./analyses/AccessorAnalyzer";
+import { ConfigAnalyzer } from "./analyses/ConfigAnalyzer";
+import { ControllerAnalyzer } from "./analyses/ControllerAnalyzer";
+import { ReflectAnalyzer } from "./analyses/ReflectAnalyzer";
+import { E2eGenerator } from "./generates/E2eGenerator";
+import { SdkGenerator } from "./generates/SdkGenerator";
+import { SwaggerGenerator } from "./generates/SwaggerGenerator";
+import { IController } from "./structures/IController";
+import { IErrorReport } from "./structures/IErrorReport";
+import { INestiaProject } from "./structures/INestiaProject";
+import { IRoute } from "./structures/IRoute";
+import { MapUtil } from "./utils/MapUtil";
+
+export class NestiaSdkApplication {
+  public constructor(
+    private readonly config: INestiaConfig,
+    private readonly compilerOptions: ts.CompilerOptions,
+  ) {}
+
+  public async e2e(): Promise<void> {
+    if (!this.config.output)
+      throw new Error(
+        "Error on NestiaApplication.e2e(): output path of SDK is not specified.",
+      );
+    else if (!this.config.e2e)
+      throw new Error(
+        "Error on NestiaApplication.e2e(): output path of e2e test files is not specified.",
+      );
+
+    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);
+
+    print_title("Nestia E2E Generator");
+    await this.generate(
+      "e2e",
+      (config) => config,
+      (checker) => (config) => async (routes) => {
+        await SdkGenerator.generate(checker)(config)(routes);
+        await E2eGenerator.generate(checker)(config)(routes);
+      },
+    );
+  }
+
+  public async sdk(): Promise<void> {
+    if (!this.config.output)
+      throw new Error(
+        "Error on NestiaApplication.sdk(): output path is not specified.",
+      );
+
+    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.",
+      );
+
+    print_title("Nestia SDK Generator");
+    await this.generate("sdk", (config) => config, SdkGenerator.generate);
+  }
+
+  public async swagger(): Promise<void> {
+    if (!this.config.swagger?.output)
+      throw new Error(
+        `Error on NestiaApplication.swagger(): output path of the "swagger.json" is not specified.`,
+      );
+
+    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.",
+      );
+
+    print_title("Nestia Swagger Generator");
+    await this.generate(
+      "swagger",
+      (config) => config.swagger!,
+      SwaggerGenerator.generate,
+    );
+  }
+
+  private async generate<Config>(
+    method: string,
+    config: (entire: INestiaConfig) => Config,
+    archiver: (
+      checker: ts.TypeChecker,
+    ) => (config: Config) => (routes: IRoute[]) => Promise<void>,
+  ): Promise<void> {
+    //----
+    // ANALYZE REFLECTS
+    //----
+    const unique: WeakSet<any> = new WeakSet();
+    const controllers: IController[] = [];
+    const project: INestiaProject = {
+      config: this.config,
+      input: await ConfigAnalyzer.input(this.config),
+      checker: null!,
+      errors: [],
+      warnings: [],
+    };
+
+    console.log("Analyzing reflections");
+    for (const include of (await ConfigAnalyzer.input(this.config)).include)
+      controllers.push(
+        ...(await ReflectAnalyzer.analyze(project)(
+          unique,
+          include.file,
+          include.paths,
+          include.controller,
+        )),
+      );
+
+    const agg: number = (() => {
+      const set: Set<string> = new Set();
+      for (const c of controllers)
+        for (const cPath of c.paths)
+          for (const f of c.functions)
+            for (const fPath of f.paths)
+              set.add(`${f.method}::${cPath}/${fPath}`);
+      return set.size;
+    })();
+
+    console.log(`  - controllers: #${controllers.length}`);
+    console.log(`  - paths: #${agg}`);
+    console.log(
+      `  - routes: #${controllers
+        .map(
+          (c) =>
+            c.paths.length *
+            c.functions.map((f) => f.paths.length).reduce((a, b) => a + b, 0),
+        )
+        .reduce((a, b) => a + b, 0)}`,
+    );
+
+    //----
+    // ANALYZE TYPESCRIPT CODE
+    //----
+    console.log("Analyzing source codes");
+
+    const program: ts.Program = ts.createProgram(
+      controllers.map((c) => c.file),
+      this.compilerOptions,
+    );
+    project.checker = program.getTypeChecker();
+
+    const routeList: IRoute[] = [];
+    for (const c of controllers) {
+      const file: ts.SourceFile | undefined = program.getSourceFile(c.file);
+      if (file === undefined) continue;
+      routeList.push(...(await ControllerAnalyzer.analyze(project)(file, c)));
+    }
+
+    // REPORT ERRORS
+    if (project.errors.length) {
+      report_errors("error")(project.errors);
+      process.exit(-1);
+    }
+    if (project.warnings.length) report_errors("warning")(project.warnings);
+
+    // FIND IMPLICIT TYPES
+    if (this.config.clone !== true) {
+      const implicit: IRoute[] = routeList.filter(is_implicit_return_typed);
+      if (implicit.length > 0)
+        throw new Error(
+          `NestiaApplication.${method}(): implicit return type is not allowed.\n` +
+            "\n" +
+            "List of implicit return typed routes:\n" +
+            implicit
+              .map(
+                (it) =>
+                  `  - ${it.target.class.name}.${it.target.function.name} at "${it.location}"`,
+              )
+              .join("\n"),
+        );
+    }
+
+    // DO GENERATE
+    AccessorAnalyzer.analyze(routeList);
+    await archiver(project.checker)(config(this.config))(routeList);
+  }
+}
+
+const print_title = (str: string): void => {
+  console.log("-----------------------------------------------------------");
+  console.log(` ${str}`);
+  console.log("-----------------------------------------------------------");
+};
+
+const is_implicit_return_typed = (route: IRoute): boolean => {
+  const name: string = route.output.typeName;
+  if (name === "void") return false;
+  else if (name.indexOf("readonly [") !== -1) return true;
+
+  const pos: number = name.indexOf("__object");
+  if (pos === -1) return false;
+
+  const before: number = pos - 1;
+  const after: number = pos + "__object".length;
+  for (const i of [before, after])
+    if (name[i] === undefined) continue;
+    else if (VARIABLE.test(name[i])) return false;
+  return true;
+};
+
+const report_errors =
+  (type: "error" | "warning") =>
+  (errors: IErrorReport[]): void => {
+    // key: file
+    // key: controller
+    // key: function
+    // value: message
+    const map: Map<string, Map<string, Map<string, Set<string>>>> = new Map();
+    for (const e of errors) {
+      const file = MapUtil.take(map, e.file, () => new Map());
+      const controller = MapUtil.take(file, e.controller, () => new Map());
+      const func = MapUtil.take(controller, e.function, () => new Set());
+      func.add(e.message);
+    }
+
+    console.log("");
+    print_title(`Nestia ${type[0].toUpperCase()}${type.slice(1)} Report`);
+    for (const [file, cMap] of map) {
+      for (const [controller, fMap] of cMap)
+        for (const [func, messages] of fMap) {
+          const location: string = path.relative(process.cwd(), file);
+          console.log(
+            `${location} - ${
+              func !== null ? `${controller}.${func}()` : controller
+            }`,
+          );
+          for (const msg of messages) console.log(`  - ${msg}`);
+          console.log("");
+        }
+    }
+  };
+
+const VARIABLE = /[a-zA-Z_$0-9]/;