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

package/src/generates/SwaggerGenerator.ts

@@ -1,23 +1,20 @@
 import fs from "fs";
 import path from "path";
-import { Singleton } from "tstl/thread/Singleton";
+import { Singleton } from "tstl";
 import ts from "typescript";
-import typia, { IJsonApplication, IJsonComponents } from "typia";
+import typia, { IJsonApplication } from "typia";
 import { MetadataCollection } from "typia/lib/factories/MetadataCollection";
 import { JsonApplicationProgrammer } from "typia/lib/programmers/json/JsonApplicationProgrammer";
 
 import { INestiaConfig } from "../INestiaConfig";
 import { IRoute } from "../structures/IRoute";
-import { ISwagger } from "../structures/ISwagger";
-import { ISwaggerError } from "../structures/ISwaggerError";
-import { ISwaggerInfo } from "../structures/ISwaggerInfo";
-import { ISwaggerLazyProperty } from "../structures/ISwaggerLazyProperty";
-import { ISwaggerLazySchema } from "../structures/ISwaggerLazySchema";
-import { ISwaggerRoute } from "../structures/ISwaggerRoute";
-import { ISwaggerSecurityScheme } from "../structures/ISwaggerSecurityScheme";
 import { FileRetriever } from "../utils/FileRetriever";
 import { MapUtil } from "../utils/MapUtil";
 import { SwaggerSchemaGenerator } from "./internal/SwaggerSchemaGenerator";
+import { OpenApi } from "@samchon/openapi";
+import { ISwaggerError } from "../structures/ISwaggerError";
+import { ISwaggerLazyProperty } from "../structures/ISwaggerLazyProperty";
+import { ISwaggerLazySchema } from "../structures/ISwaggerLazySchema";
 
 export namespace SwaggerGenerator {
   export interface IProps {
@@ -27,6 +24,7 @@ export namespace SwaggerGenerator {
     lazySchemas: Array<ISwaggerLazySchema>;
     lazyProperties: Array<ISwaggerLazyProperty>;
     errors: ISwaggerError[];
+    swagger: OpenApi.IDocument;
   }
 
   export const generate =
@@ -62,13 +60,13 @@ export namespace SwaggerGenerator {
       const errors: ISwaggerError[] = [];
       const lazySchemas: Array<ISwaggerLazySchema> = [];
       const lazyProperties: Array<ISwaggerLazyProperty> = [];
-      const swagger: ISwagger = await initialize(config);
-      const pathDict: Map<string, Record<string, ISwaggerRoute>> = new Map();
+      const swagger: OpenApi.IDocument = await initialize(config);
+      const pathDict: Map<string, Record<string, OpenApi.IOperation>> = new Map();
 
       for (const route of routeList) {
         if (route.jsDocTags.find((tag) => tag.name === "internal")) continue;
 
-        const path: Record<string, ISwaggerRoute> = MapUtil.take(
+        const path: Record<string, OpenApi.IOperation> = MapUtil.take(
           pathDict,
           get_path(route.path, route.parameters),
           () => ({}),
@@ -80,15 +78,14 @@ export namespace SwaggerGenerator {
           lazySchemas,
           lazyProperties,
           errors,
+          swagger,
         })(route);
       }
       swagger.paths = {};
       for (const [path, routes] of pathDict) swagger.paths[path] = routes;
 
       // FILL JSON-SCHEMAS
-      const application: IJsonApplication = JsonApplicationProgrammer.write({
-        purpose: "swagger",
-      })(lazySchemas.map(({ metadata }) => metadata));
+      const application: IJsonApplication<"3.1"> = JsonApplicationProgrammer.write("3.1")(lazySchemas.map(({ metadata }) => metadata)) as IJsonApplication<"3.1">;
       swagger.components = {
         ...(swagger.components ?? {}),
         ...(application.components ?? {}),
@@ -102,8 +99,8 @@ export namespace SwaggerGenerator {
           (
             application.components.schemas?.[
               p.object
-            ] as IJsonComponents.IObject
-          )?.properties[p.property],
+            ] as OpenApi.IJsonSchema.IObject
+          )?.properties?.[p.property] ?? {},
         );
 
       // CONFIGURE SECURITY
@@ -114,8 +111,8 @@ export namespace SwaggerGenerator {
         for (const e of errors)
           console.error(
             `${path.relative(e.route.location, process.cwd())}:${
-              e.route.symbol.class
-            }.${e.route.symbol.function}:${
+              e.route.target.class.name
+            }.${e.route.target.function.name}:${
               e.from
             } - error TS(@nestia/sdk): invalid type detected.\n\n` +
               e.messages.map((m) => `  - ${m}`).join("\n"),
@@ -124,6 +121,66 @@ export namespace SwaggerGenerator {
         throw new TypeError("Invalid type detected");
       }
 
+      // SWAGGER CUSTOMIZER
+      const customizer = {
+        at: new Singleton(() => {
+          const functor: Map<Function, Endpoint> = new Map();
+          for (const route of routeList) {
+            const method: OpenApi.Method = route.method.toLowerCase() as OpenApi.Method;
+            const path: string = get_path(route.path, route.parameters);
+            functor.set(route.target.function, {
+              method,
+              path,
+              route: swagger.paths![path][method]!,
+            });
+          }
+          return functor;
+        }),
+        get: new Singleton(() => (key: Accessor): OpenApi.IOperation | undefined => {
+          const method: OpenApi.Method = key.method.toLowerCase() as OpenApi.Method;
+          const path: string =
+            "/" +
+            key.path
+              .split("/")
+              .filter((str) => !!str.length)
+              .map((str) =>
+                str.startsWith(":") ? `{${str.substring(1)}}` : str,
+              )
+              .join("/");
+          return swagger.paths?.[path]?.[method];
+        }),
+      };
+      for (const route of routeList) {
+        if (
+          false ===
+          Reflect.hasMetadata(
+            "nestia/SwaggerCustomizer",
+            route.controller.prototype,
+            route.target.function.name,
+          )
+        )
+          continue;
+
+        const path: string = get_path(route.path, route.parameters);
+        const method: OpenApi.Method = route.method.toLowerCase() as OpenApi.Method;
+        const target: OpenApi.IOperation = swagger.paths![path][method]!;
+        const closure: Function | Function[] = Reflect.getMetadata(
+          "nestia/SwaggerCustomizer",
+          route.controller.prototype,
+          route.target.function.name,
+        );
+        const array: Function[] = Array.isArray(closure) ? closure : [closure];
+        for (const fn of array)
+          fn({
+            route: target,
+            method,
+            path,
+            swagger,
+            at: (func: Function) => customizer.at.get().get(func),
+            get: (accessor: Accessor) => customizer.get.get()(accessor),
+          });
+      }
+
       // DO GENERATE
       await fs.promises.writeFile(
         location,
@@ -143,7 +200,7 @@ export namespace SwaggerGenerator {
     (routeList: IRoute[]): void | never => {
       const securityMap: Map<
         string,
-        { scheme: ISwaggerSecurityScheme; scopes: Set<string> }
+        { scheme: OpenApi.ISecurityScheme; scopes: Set<string> }
       > = new Map();
       for (const [key, value] of Object.entries(config.security ?? {}))
         securityMap.set(key, {
@@ -183,7 +240,7 @@ export namespace SwaggerGenerator {
           for (const [key, scopes] of Object.entries(record))
             validate((str) =>
               violations.push(
-                `  - ${str} (${route.symbol} at "${route.location}")`,
+                `  - ${str} (${route.target.class.name}.${route.target.function.name}() at "${route.location}")`,
               ),
             )(key, scopes);
 
@@ -201,9 +258,9 @@ export namespace SwaggerGenerator {
     --------------------------------------------------------- */
   const initialize = async (
     config: INestiaConfig.ISwaggerConfig,
-  ): Promise<ISwagger> => {
+  ): Promise<OpenApi.IDocument> => {
     const pack = new Singleton(
-      async (): Promise<Partial<ISwaggerInfo> | null> => {
+      async (): Promise<Partial<OpenApi.IDocument.IInfo> | null> => {
         const location: string | null = await FileRetriever.file(
           "package.json",
         )(process.cwd());
@@ -220,7 +277,7 @@ export namespace SwaggerGenerator {
               | {
                   type: string;
                   /**
-                   * @format url
+                   * @format uri
                    */
                   url: string;
                 };
@@ -233,11 +290,11 @@ export namespace SwaggerGenerator {
               ? typeof data.license === "string"
                 ? { name: data.license }
                 : typeof data.license === "object"
-                ? {
-                    name: data.license.type,
-                    url: data.license.url,
-                  }
-                : undefined
+                  ? {
+                      name: data.license.type,
+                      url: data.license.url,
+                    }
+                  : undefined
               : undefined,
           };
         } catch {
@@ -247,7 +304,7 @@ export namespace SwaggerGenerator {
     );
 
     return {
-      openapi: "3.0.1",
+      openapi: "3.1.0",
       servers: config.servers ?? [
         {
           url: "https://github.com/samchon/nestia",
@@ -268,7 +325,10 @@ export namespace SwaggerGenerator {
         license: config.info?.license ?? (await pack.get())?.license,
       },
       paths: {},
-      components: {},
+      components: {
+        schemas: {},
+      },
+      tags: config.tags ?? [],
     };
   };
 
@@ -283,9 +343,12 @@ export namespace SwaggerGenerator {
 
   const generate_route =
     (props: IProps) =>
-    (route: IRoute): ISwaggerRoute => {
+    (route: IRoute): OpenApi.IOperation => {
+      // FIND REQUEST BODY
       const body = route.parameters.find((param) => param.category === "body");
-      const getJsDocTexts = (name: string) =>
+
+      // CONSTRUCT SUMMARY & DESCRIPTION
+      const getJsDocTexts = (name: string): string[] =>
         route.jsDocTags
           .filter(
             (tag) =>
@@ -296,7 +359,6 @@ export namespace SwaggerGenerator {
               ) !== undefined,
           )
           .map((tag) => tag.text!.find((elem) => elem.kind === "text")!.text);
-
       const description: string | undefined = route.description?.length
         ? route.description
         : undefined;
@@ -306,24 +368,40 @@ export namespace SwaggerGenerator {
         const [explicit] = getJsDocTexts("summary");
         if (explicit?.length) return explicit;
 
-        const index: number = description.indexOf(".");
-        if (index <= 0) return undefined;
-
-        const content: string = description.substring(0, index).trim();
-        return content.length ? content : undefined;
+        const index: number = description.indexOf("\n");
+        const top: string = (
+          index === -1 ? description : description.substring(0, index)
+        ).trim();
+        return top.endsWith(".") ? top.substring(0, top.length - 1) : undefined;
       })();
       const deprecated = route.jsDocTags.find(
         (tag) => tag.name === "deprecated",
       );
 
+      // CONSTRUCT TAGS
+      const tagSet: Set<string> = new Set([
+        ...route.swaggerTags,
+        ...getJsDocTexts("tag").map((tag) => tag.split(" ")[0]),
+      ]);
+      for (const tag of tagSet)
+        if (props.swagger.tags!.find((elem) => elem.name === tag) === undefined)
+          props.swagger.tags!.push({ name: tag });
+      for (const texts of getJsDocTexts("tag")) {
+        const [name, ...description] = texts.split(" ");
+        if (description.length)
+          props.swagger.tags!.find((elem) => elem.name === name)!.description ??=
+            description.join(" ");
+      }
+
+      // FINALIZE
       return {
         deprecated: deprecated ? true : undefined,
-        tags: [...route.swaggerTags, ...new Set([...getJsDocTexts("tag")])],
+        tags: [...tagSet],
         operationId:
           route.operationId ??
           props.config.operationId?.({
-            class: route.symbol.class,
-            function: route.symbol.function,
+            class: route.target.class.name,
+            function: route.target.function.name,
             method: route.method as "GET",
             path: route.path,
           }),
@@ -338,20 +416,24 @@ export namespace SwaggerGenerator {
         summary,
         description,
         security: route.security.length ? route.security : undefined,
-        "x-nestia-namespace": [
-          ...route.path
-            .split("/")
-            .filter((str) => str.length && str[0] !== ":"),
-          route.name,
-        ].join("."),
-        "x-nestia-jsDocTags": route.jsDocTags,
-        "x-nestia-method": route.method,
+        ...(props.config.additional === true
+          ? {
+              "x-nestia-namespace": [
+                ...route.path
+                  .split("/")
+                  .filter((str) => str.length && str[0] !== ":"),
+                route.name,
+              ].join("."),
+              "x-nestia-jsDocTags": route.jsDocTags,
+              "x-nestia-method": route.method,
+            }
+          : {}),
       };
     };
 
   function fill_security(
     security: Required<INestiaConfig.ISwaggerConfig>["security"],
-    swagger: ISwagger,
+    swagger: OpenApi.IDocument,
   ): void {
     swagger.components.securitySchemes = {};
     for (const [key, value] of Object.entries(security))
@@ -359,8 +441,8 @@ export namespace SwaggerGenerator {
   }
 
   function emend_security(
-    input: ISwaggerSecurityScheme,
-  ): ISwaggerSecurityScheme {
+    input: OpenApi.ISecurityScheme,
+  ): OpenApi.ISecurityScheme {
     if (input.type === "apiKey")
       return {
         ...input,
@@ -370,3 +452,13 @@ export namespace SwaggerGenerator {
     return input;
   }
 }
+
+interface Accessor {
+  method: string;
+  path: string;
+}
+interface Endpoint {
+  method: string;
+  path: string;
+  route: OpenApi.IOperation;
+}

package/src/generates/internal/E2eFileProgrammer.ts

@@ -1,123 +1,182 @@
-import fs from "fs";
-
-import { INestiaConfig } from "../../INestiaConfig";
-import { IRoute } from "../../structures/IRoute";
-import { ImportDictionary } from "../../utils/ImportDictionary";
-import { SdkDtoGenerator } from "./SdkDtoGenerator";
-import { SdkImportWizard } from "./SdkImportWizard";
-import { SdkTypeDefiner } from "./SdkTypeDefiner";
-
-export namespace E2eFileProgrammer {
-  export const generate =
-    (config: INestiaConfig) =>
-    (props: { api: string; current: string }) =>
-    async (route: IRoute): Promise<void> => {
-      const importer: ImportDictionary = new ImportDictionary(
-        `${props.current}/${name(route)}.ts`,
-      );
-      if (config.clone !== true)
-        for (const tuple of route.imports)
-          for (const instance of tuple[1])
-            importer.internal({
-              file: tuple[0],
-              type: true,
-              instance,
-            });
-      importer.internal({
-        type: false,
-        file: props.api,
-        instance: null,
-        name: "api",
-      });
-
-      const body: string = arrow(config)(importer)(route);
-      const content: string = [importer.toScript(props.current), "", body].join(
-        "\n",
-      );
-
-      await fs.promises.writeFile(importer.file, content, "utf8");
-    };
-
-  const arrow =
-    (config: INestiaConfig) =>
-    (importer: ImportDictionary) =>
-    (route: IRoute): string => {
-      const tab: number = 2;
-      const headers = route.parameters.find(
-        (p) => p.category === "headers" && p.field === undefined,
-      );
-      const output = [
-        `await ${accessor(route)}(`,
-        headers !== undefined
-          ? [
-              "{",
-              "    ...connection,",
-              "    headers: {",
-              "        ...(connection.headers ?? {}),",
-              `        ...${SdkImportWizard.typia(
-                importer,
-              )}.random<${getTypeName(config)(importer)(headers)}>(),`,
-              "    },",
-              "},",
-            ]
-              .map((line) => `${" ".repeat(tab * 4)}${line}`)
-              .join("\n")
-          : `${" ".repeat(tab * 4)}connection,`,
-        ...route.parameters
-          .filter((param) => param.category !== "headers")
-          .map(parameter(config)(importer)(tab)),
-        `${" ".repeat((tab - 1) * 4)});`,
-      ].join("\n");
-      return [
-        `export const ${name(route)} = async (`,
-        `    connection: api.IConnection`,
-        `): Promise<void> => {`,
-        ...(route.output.typeName === "void"
-          ? [`    ${output}`]
-          : [
-              `    const output: ${SdkTypeDefiner.output(config)(importer)(
-                route,
-              )} = ${output}`,
-              `    ${SdkImportWizard.typia(importer)}.assert(output);`,
-            ]),
-        `};`,
-      ].join("\n");
-    };
-
-  const parameter =
-    (config: INestiaConfig) =>
-    (importer: ImportDictionary) =>
-    (tab: number) =>
-    (param: IRoute.IParameter): string => {
-      const middle: string = `${SdkImportWizard.typia(importer)}.random<${wrap(
-        config,
-      )(importer)(
-        getTypeName(config)(importer)(param),
-        param.category === "body",
-      )}>()`;
-      return `${" ".repeat(4 * tab)}${middle},`;
-    };
-
-  const name = (route: IRoute): string =>
-    ["test", "api", ...route.accessors].join("_");
-
-  const accessor = (route: IRoute): string =>
-    ["api", "functional", ...route.accessors].join(".");
-
-  const wrap =
-    (config: INestiaConfig) =>
-    (importer: ImportDictionary) =>
-    (name: string, body: boolean): string =>
-      config.primitive === false
-        ? name
-        : `${(body ? SdkImportWizard.Primitive : SdkImportWizard.Resolved)(
-            importer,
-          )}<${name}>`;
-}
-const getTypeName =
-  (config: INestiaConfig) =>
-  (importer: ImportDictionary) =>
-  (p: IRoute.IParameter | IRoute.IOutput) =>
-    p.metadata
-      ? SdkDtoGenerator.decode(config)(importer)(p.metadata)
-      : p.typeName;
+import ts from "typescript";
+import { IdentifierFactory } from "typia/lib/factories/IdentifierFactory";
+
+import { INestiaConfig } from "../../INestiaConfig";
+import { IRoute } from "../../structures/IRoute";
+import { FilePrinter } from "./FilePrinter";
+import { ImportDictionary } from "./ImportDictionary";
+import { SdkAliasCollection } from "./SdkAliasCollection";
+import { SdkImportWizard } from "./SdkImportWizard";
+import { SdkTypeProgrammer } from "./SdkTypeProgrammer";
+
+export namespace E2eFileProgrammer {
+  export const generate =
+    (checker: ts.TypeChecker) =>
+    (config: INestiaConfig) =>
+    (props: { api: string; current: string }) =>
+    async (route: IRoute): Promise<void> => {
+      const importer: ImportDictionary = new ImportDictionary(
+        `${props.current}/${getFunctionName(route)}.ts`,
+      );
+      if (config.clone !== true)
+        for (const tuple of route.imports)
+          for (const instance of tuple[1])
+            importer.internal({
+              file: tuple[0],
+              type: true,
+              instance,
+            });
+      importer.internal({
+        type: false,
+        file: props.api,
+        instance: null,
+        name: "api",
+      });
+
+      const functor = generate_function(checker)(config)(importer)(route);
+      await FilePrinter.write({
+        location: importer.file,
+        statements: [
+          ...importer.toStatements(props.current),
+          FilePrinter.enter(),
+          functor,
+        ],
+      });
+    };
+
+  const generate_function =
+    (checker: ts.TypeChecker) =>
+    (config: INestiaConfig) =>
+    (importer: ImportDictionary) =>
+    (route: IRoute): ts.Statement =>
+      ts.factory.createVariableStatement(
+        [ts.factory.createModifier(ts.SyntaxKind.ExportKeyword)],
+        ts.factory.createVariableDeclarationList(
+          [
+            ts.factory.createVariableDeclaration(
+              ts.factory.createIdentifier(getFunctionName(route)),
+              undefined,
+              undefined,
+              generate_arrow(checker)(config)(importer)(route),
+            ),
+          ],
+          ts.NodeFlags.Const,
+        ),
+      );
+
+  const generate_arrow =
+    (checker: ts.TypeChecker) =>
+    (config: INestiaConfig) =>
+    (importer: ImportDictionary) =>
+    (route: IRoute) => {
+      const headers = route.parameters.find(
+        (p) => p.category === "headers" && p.field === undefined,
+      );
+      const connection = headers
+        ? ts.factory.createObjectLiteralExpression(
+            [
+              ts.factory.createSpreadAssignment(
+                ts.factory.createIdentifier("connection"),
+              ),
+              ts.factory.createPropertyAssignment(
+                "headers",
+                ts.factory.createObjectLiteralExpression(
+                  [
+                    ts.factory.createSpreadAssignment(
+                      IdentifierFactory.access(
+                        ts.factory.createIdentifier("connection"),
+                      )("headers"),
+                    ),
+                    ts.factory.createSpreadAssignment(
+                      ts.factory.createCallExpression(
+                        IdentifierFactory.access(
+                          ts.factory.createIdentifier(
+                            SdkImportWizard.typia(importer),
+                          ),
+                        )("random"),
+                        [getTypeName(config)(importer)(headers)],
+                        undefined,
+                      ),
+                    ),
+                  ],
+                  true,
+                ),
+              ),
+            ],
+            true,
+          )
+        : ts.factory.createIdentifier("connection");
+      const caller = ts.factory.createCallExpression(
+        ts.factory.createIdentifier(
+          ["api", "functional", ...route.accessors].join("."),
+        ),
+        undefined,
+        [
+          connection,
+          ...route.parameters
+            .filter((p) => p.category !== "headers")
+            .map((p) =>
+              ts.factory.createCallExpression(
+                IdentifierFactory.access(
+                  ts.factory.createIdentifier(SdkImportWizard.typia(importer)),
+                )("random"),
+                [getTypeName(config)(importer)(p)],
+                undefined,
+              ),
+            ),
+        ],
+      );
+      const assert = ts.factory.createCallExpression(
+        IdentifierFactory.access(
+          ts.factory.createIdentifier(SdkImportWizard.typia(importer)),
+        )("assert"),
+        undefined,
+        [ts.factory.createIdentifier("output")],
+      );
+
+      return ts.factory.createArrowFunction(
+        [ts.factory.createModifier(ts.SyntaxKind.AsyncKeyword)],
+        undefined,
+        [
+          IdentifierFactory.parameter(
+            "connection",
+            ts.factory.createTypeReferenceNode("api.IConnection"),
+          ),
+        ],
+        undefined,
+        undefined,
+        ts.factory.createBlock([
+          ts.factory.createVariableStatement(
+            [],
+            ts.factory.createVariableDeclarationList(
+              [
+                ts.factory.createVariableDeclaration(
+                  "output",
+                  undefined,
+                  config.propagate !== true && route.output.typeName === "void"
+                    ? undefined
+                    : SdkAliasCollection.output(checker)(config)(importer)(
+                        route,
+                      ),
+                  ts.factory.createAwaitExpression(caller),
+                ),
+              ],
+              ts.NodeFlags.Const,
+            ),
+          ),
+          ts.factory.createExpressionStatement(assert),
+        ]),
+      );
+    };
+}
+
+const getFunctionName = (route: IRoute): string =>
+  ["test", "api", ...route.accessors].join("_");
+
+const getTypeName =
+  (config: INestiaConfig) =>
+  (importer: ImportDictionary) =>
+  (p: IRoute.IParameter | IRoute.IOutput) =>
+    p.metadata
+      ? SdkTypeProgrammer.write(config)(importer)(p.metadata)
+      : ts.factory.createTypeReferenceNode(p.typeName);