@nestia/sdk 3.11.0-dev.20240813-10 → 3.11.0-dev.20240814

package/src/analyses/ReflectHttpOperationExceptionAnalyzer.ts

@@ -0,0 +1,71 @@
+import { TypedException } from "@nestia/core";
+import { JsonMetadataFactory } from "typia/lib/factories/JsonMetadataFactory";
+
+import { IReflectController } from "../structures/IReflectController";
+import { IReflectHttpOperationException } from "../structures/IReflectHttpOperationException";
+import { IReflectOperationError } from "../structures/IReflectOperationError";
+import { IOperationMetadata } from "../transformers/IOperationMetadata";
+
+export namespace ReflectHttpOperationExceptionAnalyzer {
+  export interface IContext {
+    controller: IReflectController;
+    function: Function;
+    functionName: string;
+    httpMethod: string;
+    metadata: IOperationMetadata;
+    errors: IReflectOperationError[];
+  }
+  export const analyze = (
+    ctx: IContext,
+  ): Record<string, IReflectHttpOperationException> => {
+    const preconfigured: TypedException.IProps<any>[] = analyzePreconfigured(
+      ctx.function,
+    )
+      .slice()
+      .reverse();
+    const errors: IReflectOperationError[] = [];
+    const exceptions: IReflectHttpOperationException[] = preconfigured
+      .map((pre, i) => {
+        const matched: IOperationMetadata.IException | null =
+          ctx.metadata.exceptions[i];
+        if (matched === undefined) {
+          errors.push({
+            file: ctx.controller.file,
+            class: ctx.controller.class.name,
+            function: ctx.functionName,
+            from: `exception (status: ${pre.status})`,
+            contents: ["Unable to find exception type."],
+          });
+          return null;
+        } else if (matched.type === null) {
+          errors.push({
+            file: ctx.controller.file,
+            class: ctx.controller.class.name,
+            function: ctx.functionName,
+            from: `exception (status: ${pre.status})`,
+            contents: ["Failed to get the type info."],
+          });
+        }
+        const schema: IOperationMetadata.ISchema | null = matched.primitive
+          .success
+          ? matched.primitive.data
+          : null;
+        if (schema === null || matched.type === null) return null; // unreachable
+        return {
+          status: pre.status,
+          description: pre.description ?? null,
+          example: pre.example,
+          examples: pre.examples,
+          type: matched.type,
+          ...schema,
+          validate: JsonMetadataFactory.validate,
+        } satisfies IReflectHttpOperationException;
+      })
+      .filter((e) => e !== null);
+    if (errors.length) ctx.errors.push(...errors);
+    return Object.fromEntries(exceptions.map((e) => [e.status, e]));
+  };
+
+  const analyzePreconfigured = (func: Function): TypedException.IProps<any>[] =>
+    Reflect.getMetadata("nestia/TypedException", func) ?? [];
+}

package/src/analyses/ReflectHttpOperationParameterAnalyzer.ts

@@ -1,3 +1,4 @@
+import { SwaggerExample } from "@nestia/core";
 import { ROUTE_ARGS_METADATA } from "@nestjs/common/constants";
 import { RouteParamtypes } from "@nestjs/common/enums/route-paramtypes.enum";
 import { JsonMetadataFactory } from "typia/lib/factories/JsonMetadataFactory";
@@ -9,9 +10,10 @@ import { HttpQueryProgrammer } from "typia/lib/programmers/http/HttpQueryProgram
 import { IReflectController } from "../structures/IReflectController";
 import { IReflectHttpOperationParameter } from "../structures/IReflectHttpOperationParameter";
 import { IReflectOperationError } from "../structures/IReflectOperationError";
-import { IReflectTypeImport } from "../structures/IReflectTypeImport";
 import { IOperationMetadata } from "../transformers/IOperationMetadata";
 import { TextPlainValidator } from "../transformers/TextPlainValidator";
+import { HttpHeadersValidator } from "../validators/HttpHeadersValidator";
+import { HttpQueryValidator } from "../validators/HttpQueryValidator";
 
 export namespace ReflectHttpOperationParameterAnalyzer {
   export interface IContext {
@@ -25,7 +27,6 @@ export namespace ReflectHttpOperationParameterAnalyzer {
   export const analyze = (ctx: IContext): IReflectHttpOperationParameter[] => {
     const preconfigured: IReflectHttpOperationParameter.IPreconfigured[] =
       analyzePreconfigured(ctx);
-    const imports: IReflectTypeImport[] = [];
     const errors: IReflectOperationError[] = [];
 
     //----
@@ -148,8 +149,15 @@ export namespace ReflectHttpOperationParameterAnalyzer {
         )
           return null; // unreachable
 
+        const example: SwaggerExample.IData<any> | undefined = (
+          Reflect.getMetadata(
+            "nestia/SwaggerExample/Parameters",
+            ctx.controller.class.prototype,
+            ctx.functionName,
+          ) ?? []
+        ).find((x: SwaggerExample.IData<any>) => x.index === matched.index);
+
         // COMPOSITION
-        imports.push(...matched.imports);
         if (p.category === "param")
           return {
             category: p.category,
@@ -160,21 +168,40 @@ export namespace ReflectHttpOperationParameterAnalyzer {
             validate: HttpParameterProgrammer.validate,
             description: matched.description,
             jsDocTags: matched.jsDocTags,
+            example: example?.example,
+            examples: example?.examples,
             ...schema,
           };
-        else if (p.category === "query" || p.category === "headers")
+        else if (p.category === "query")
           return {
             category: p.category,
             index: p.index,
             field: p.field ?? null,
             name: matched.name,
             type: matched.type,
-            validate:
-              p.category === "query"
-                ? HttpQueryProgrammer.validate
-                : HttpHeadersProgrammer.validate,
+            validate: p.field
+              ? HttpQueryValidator.validate
+              : HttpQueryProgrammer.validate,
+            description: matched.description,
+            jsDocTags: matched.jsDocTags,
+            example: example?.example,
+            examples: example?.examples,
+            ...schema,
+          };
+        else if (p.category === "headers")
+          return {
+            category: p.category,
+            index: p.index,
+            field: p.field ?? null,
+            name: matched.name,
+            type: matched.type,
+            validate: p.field
+              ? HttpHeadersValidator.validate
+              : HttpHeadersProgrammer.validate,
             description: matched.description,
             jsDocTags: matched.jsDocTags,
+            example: example?.example,
+            examples: example?.examples,
             ...schema,
           };
         else if (p.category === "body")
@@ -195,6 +222,8 @@ export namespace ReflectHttpOperationParameterAnalyzer {
                     : TextPlainValidator.validate,
             description: matched.description,
             jsDocTags: matched.jsDocTags,
+            example: example?.example,
+            examples: example?.examples,
             ...schema,
           };
         else {

package/src/analyses/ReflectHttpOperationResponseAnalyzer.ts

@@ -1,3 +1,4 @@
+import { SwaggerExample } from "@nestia/core";
 import {
   HEADERS_METADATA,
   HTTP_CODE_METADATA,
@@ -78,6 +79,11 @@ export namespace ReflectHttpOperationResponseAnalyzer {
       !typia.is<IReflectHttpOperationSuccess["contentType"]>(contentType)
     )
       return null;
+
+    const example: SwaggerExample.IData<any> | undefined = Reflect.getMetadata(
+      "nestia/SwaggerExample/Response",
+      ctx.function,
+    );
     return {
       contentType: contentType,
       encrypted,
@@ -96,6 +102,8 @@ export namespace ReflectHttpOperationResponseAnalyzer {
                   meta.size()
                     ? ["HEAD method must not have any return value."]
                     : [],
+      example: example?.example,
+      examples: example?.examples,
     };
   };
 

package/src/analyses/ReflectWebSocketOperationAnalyzer.ts

@@ -85,7 +85,16 @@ export namespace ReflectWebSocketOperationAnalyzer {
           );
 
         // COMPLETE COMPOSITION
-        imports.push(...matched.imports);
+        imports.push(
+          ...matched.imports.filter(
+            (i) =>
+              !(
+                i.file.includes("tgrid/lib") &&
+                (i.file.endsWith("Driver.d.ts") ||
+                  i.file.endsWith("WebSocketAcceptor.d.ts"))
+              ),
+          ),
+        );
         if (
           p.category === "acceptor" ||
           p.category === "driver" ||
@@ -109,7 +118,6 @@ export namespace ReflectWebSocketOperationAnalyzer {
           } satisfies IReflectWebSocketOperationParameter.IParam;
 
         // UNKNOWN TYPE, MAYBE NEW FEATURE
-        console.log(p);
         return errors.push(
           `@WebSocketRoute.${StringUtil.capitalize(p.category)}() has not been supported yet. How about upgrading the nestia packages?`,
         );

package/src/analyses/TypedHttpRouteAnalyzer.ts

@@ -151,7 +151,10 @@ export namespace TypedHttpRouteAnalyzer {
               },
         ),
     };
-    if (errors.length) return [];
+    if (errors.length) {
+      props.errors.push(...errors);
+      return [];
+    }
     return props.paths.map((path) => ({
       ...props.operation,
       controller: props.controller,

package/src/executable/internal/NestiaSdkCommand.ts

@@ -9,12 +9,13 @@ export namespace NestiaSdkCommand {
   export const swagger = () => main((app) => app.swagger());
   export const openai = () => main((app) => app.openai());
   export const e2e = () => main((app) => app.e2e());
+  export const all = () => main((app) => app.all());
 
   const main = async (task: (app: NestiaSdkApplication) => Promise<void>) => {
-    await generate(task);
+    await _Generate(task);
   };
 
-  const generate = async (
+  const _Generate = async (
     task: (app: NestiaSdkApplication) => Promise<void>,
   ) => {
     // LOAD CONFIG INFO

package/src/executable/sdk.ts

@@ -18,6 +18,7 @@ npx @nestia/sdk [command] [options?]
   4. npx @nestia/sdk swagger --config? [config file] --project? [project file]
   5. npx @nestia/sdk openai --config? [config file] --project? [project file]
   6. npx @nestia/sdk e2e --config? [config file] --project? [project file]
+  7. npx @nestia/sdk generate --config? [config file] --project? [project file]
 `;
 
 function halt(desc: string): never {
@@ -65,6 +66,7 @@ async function main() {
   else if (type === "swagger") await execute((c) => c.swagger());
   else if (type === "openai") await execute((c) => c.openai());
   else if (type === "e2e") await execute((c) => c.e2e());
+  else if (type === "all") await execute((c) => c.all());
   else halt(USAGE);
 
   process.exit(0);

package/src/generates/CloneGenerator.ts

@@ -1,65 +1,66 @@
-// import fs from "fs";
-// import ts from "typescript";
+import fs from "fs";
+import ts from "typescript";
 
-// import { INestiaProject } from "../structures/INestiaProject";
-// import { ITypedApplication } from "../structures/ITypedApplication";
-// import { FilePrinter } from "./internal/FilePrinter";
-// import { ImportDictionary } from "./internal/ImportDictionary";
-// // import { SdkHttpCloneProgrammer } from "./internal/SdkHttpCloneProgrammer";
+import { INestiaProject } from "../structures/INestiaProject";
+import { ITypedApplication } from "../structures/ITypedApplication";
+import { FilePrinter } from "./internal/FilePrinter";
+import { ImportDictionary } from "./internal/ImportDictionary";
+import { SdkHttpCloneProgrammer } from "./internal/SdkHttpCloneProgrammer";
+import { SdkHttpCloneReferencer } from "./internal/SdkHttpCloneReferencer";
 
-// export namespace CloneGenerator {
-//   export const write = async (app: ITypedApplication): Promise<void> => {
-//     // const dict: Map<string, SdkHttpCloneProgrammer.IModule> =
-//     //   SdkHttpCloneProgrammer.write(app.project)(
-//     //     app.routes.filter((r) => r.protocol === "http"),
-//     //   );
-//     if (dict.size === 0) return;
-//     try {
-//       await fs.promises.mkdir(`${app.project.config.output}/structures`);
-//     } catch {}
-//     for (const [key, value] of dict)
-//       await writeDtoFile(app.project)(key, value);
-//   };
+export namespace CloneGenerator {
+  export const write = async (app: ITypedApplication): Promise<void> => {
+    const dict: Map<string, SdkHttpCloneProgrammer.IModule> =
+      SdkHttpCloneProgrammer.write(app);
+    if (dict.size === 0) return;
 
-//   const writeDtoFile =
-//     (project: INestiaProject) =>
-//     async (
-//       key: string,
-//       value: SdkHttpCloneProgrammer.IModule,
-//     ): Promise<void> => {
-//       const location: string = `${project.config.output}/structures/${key}.ts`;
-//       const importer: ImportDictionary = new ImportDictionary(location);
-//       const statements: ts.Statement[] = iterate(importer)(value);
-//       if (statements.length === 0) return;
+    SdkHttpCloneReferencer.replace(app);
+    try {
+      await fs.promises.mkdir(`${app.project.config.output}/structures`);
+    } catch {}
+    for (const [key, value] of dict)
+      await writeDtoFile(app.project)(key, value);
+  };
 
-//       await FilePrinter.write({
-//         location,
-//         statements: [
-//           ...importer.toStatements(`${project.config.output}/structures`),
-//           ...(importer.empty() ? [] : [FilePrinter.enter()]),
-//           ...statements,
-//         ],
-//       });
-//     };
+  const writeDtoFile =
+    (project: INestiaProject) =>
+    async (
+      key: string,
+      value: SdkHttpCloneProgrammer.IModule,
+    ): Promise<void> => {
+      const location: string = `${project.config.output}/structures/${key}.ts`;
+      const importer: ImportDictionary = new ImportDictionary(location);
+      const statements: ts.Statement[] = iterate(importer)(value);
+      if (statements.length === 0) return;
 
-//   const iterate =
-//     (importer: ImportDictionary) =>
-//     (modulo: SdkHttpCloneProgrammer.IModule): ts.Statement[] => {
-//       const output: ts.Statement[] = [];
-//       if (modulo.programmer !== null) output.push(modulo.programmer(importer));
-//       if (modulo.children.size) {
-//         const internal: ts.Statement[] = [];
-//         for (const child of modulo.children.values())
-//           internal.push(...iterate(importer)(child));
-//         output.push(
-//           ts.factory.createModuleDeclaration(
-//             [ts.factory.createModifier(ts.SyntaxKind.ExportKeyword)],
-//             ts.factory.createIdentifier(modulo.name),
-//             ts.factory.createModuleBlock(internal),
-//             ts.NodeFlags.Namespace,
-//           ),
-//         );
-//       }
-//       return output;
-//     };
-// }
+      await FilePrinter.write({
+        location,
+        statements: [
+          ...importer.toStatements(`${project.config.output}/structures`),
+          ...(importer.empty() ? [] : [FilePrinter.enter()]),
+          ...statements,
+        ],
+      });
+    };
+
+  const iterate =
+    (importer: ImportDictionary) =>
+    (modulo: SdkHttpCloneProgrammer.IModule): ts.Statement[] => {
+      const output: ts.Statement[] = [];
+      if (modulo.programmer !== null) output.push(modulo.programmer(importer));
+      if (modulo.children.size) {
+        const internal: ts.Statement[] = [];
+        for (const child of modulo.children.values())
+          internal.push(...iterate(importer)(child));
+        output.push(
+          ts.factory.createModuleDeclaration(
+            [ts.factory.createModifier(ts.SyntaxKind.ExportKeyword)],
+            ts.factory.createIdentifier(modulo.name),
+            ts.factory.createModuleBlock(internal),
+            ts.NodeFlags.Namespace,
+          ),
+        );
+      }
+      return output;
+    };
+}

package/src/generates/SdkGenerator.ts

@@ -7,7 +7,7 @@ import { IReflectOperationError } from "../structures/IReflectOperationError";
 import { IReflectType } from "../structures/IReflectType";
 import { ITypedApplication } from "../structures/ITypedApplication";
 import { ITypedHttpRoute } from "../structures/ITypedHttpRoute";
-// import { CloneGenerator } from "./CloneGenerator";
+import { CloneGenerator } from "./CloneGenerator";
 import { SdkDistributionComposer } from "./internal/SdkDistributionComposer";
 import { SdkFileProgrammer } from "./internal/SdkFileProgrammer";
 
@@ -44,8 +44,8 @@ export namespace SdkGenerator {
       }
     }
 
-    // // STRUCTURES
-    // if (app.project.config.clone === true) await CloneGenerator.write(app);
+    // STRUCTURES
+    if (app.project.config.clone === true) await CloneGenerator.write(app);
 
     // FUNCTIONAL
     await SdkFileProgrammer.generate(app);

package/src/generates/SwaggerGenerator.ts

@@ -1,3 +1,4 @@
+import { SwaggerCustomizer } from "@nestia/core";
 import { OpenApi, OpenApiV3, SwaggerV2 } from "@samchon/openapi";
 import fs from "fs";
 import path from "path";
@@ -16,6 +17,7 @@ import { SwaggerOperationComposer } from "./internal/SwaggerOperationComposer";
 export namespace SwaggerGenerator {
   export const generate = async (app: ITypedApplication): Promise<void> => {
     // GET CONFIGURATION
+    console.log("Generating Swagger Document");
     if (app.project.config.swagger === undefined)
       throw new Error("Swagger configuration is not defined.");
     const config: INestiaConfig.ISwaggerConfig = app.project.config.swagger;
@@ -92,7 +94,7 @@ export namespace SwaggerGenerator {
     const document: OpenApi.IDocument = props.document;
     document.components.schemas ??= {};
     Object.assign(document.components.schemas, json.components.schemas);
-    document.paths = writePaths({ ...props, schema });
+    fillPaths({ ...props, schema, document });
 
     return document;
   };
@@ -175,23 +177,85 @@ export namespace SwaggerGenerator {
     };
   };
 
-  const writePaths = (props: {
+  const fillPaths = (props: {
     config: INestiaConfig.ISwaggerConfig;
     document: OpenApi.IDocument;
     schema: (metadata: Metadata) => OpenApi.IJsonSchema | undefined;
     routes: ITypedHttpRoute[];
-  }): Record<string, OpenApi.IPath> => {
-    const output: Record<string, OpenApi.IPath> = {};
+  }): void => {
+    // SWAGGER CUSTOMIZER
+    const customizers: Array<() => void> = [];
+    const neighbor = {
+      at: new Singleton(() => {
+        const functor: Map<Function, Endpoint> = new Map();
+        for (const r of props.routes) {
+          const method: OpenApi.Method =
+            r.method.toLowerCase() as OpenApi.Method;
+          const path: string = getPath(r);
+          const operation: OpenApi.IOperation | undefined =
+            props.document.paths?.[path]?.[method];
+          if (operation === undefined) continue;
+          functor.set(r.function, {
+            method,
+            path,
+            route: operation,
+          });
+        }
+        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 props.document.paths?.[path]?.[method];
+          },
+      ),
+    };
+
+    // COMPOSE OPERATIONS
     for (const r of props.routes) {
+      const operation: OpenApi.IOperation = SwaggerOperationComposer.compose({
+        ...props,
+        route: r,
+      });
       const path: string = getPath(r);
-      output[path] ??= {};
-      output[path][r.method.toLowerCase() as "get"] =
-        SwaggerOperationComposer.compose({
-          ...props,
-          route: r,
+      props.document.paths ??= {};
+      props.document.paths[path] ??= {};
+      props.document.paths[path][r.method.toLowerCase() as "get"] = operation;
+
+      const closure: Function | Function[] | undefined = Reflect.getMetadata(
+        "nestia/SwaggerCustomizer",
+        r.controller.class.prototype,
+        r.name,
+      );
+      if (closure !== undefined) {
+        const array: Function[] = Array.isArray(closure) ? closure : [closure];
+        customizers.push(() => {
+          for (const closure of array)
+            closure({
+              swagger: props.document,
+              method: r.method,
+              path,
+              route: operation,
+              at: (func: Function) => neighbor.at.get().get(func),
+              get: (accessor: Accessor) => neighbor.get.get()(accessor),
+            } satisfies SwaggerCustomizer.IProps);
         });
+      }
     }
-    return output;
+
+    // DO CUSTOMIZE
+    for (const fn of customizers) fn();
   };
 
   const getPath = (route: {
@@ -207,3 +271,13 @@ export namespace SwaggerGenerator {
     return str;
   };
 }
+
+interface Accessor {
+  method: string;
+  path: string;
+}
+interface Endpoint {
+  method: string;
+  path: string;
+  route: OpenApi.IOperation;
+}

package/src/generates/internal/E2eFileProgrammer.ts

@@ -66,7 +66,7 @@ export namespace E2eFileProgrammer {
     (importer: ImportDictionary) =>
     (route: ITypedHttpRoute) => {
       const headers = route.parameters.find(
-        (p) => p.category === "headers" && p.field === undefined,
+        (p) => p.category === "headers" && p.field === null,
       );
       const connection = headers
         ? ts.factory.createObjectLiteralExpression(
@@ -90,7 +90,13 @@ export namespace E2eFileProgrammer {
                             SdkImportWizard.typia(importer),
                           ),
                         )("random"),
-                        [SdkAliasCollection.name(headers.type)],
+                        [
+                          project.config.clone === true
+                            ? SdkAliasCollection.from(project)(importer)(
+                                headers.metadata,
+                              )
+                            : SdkAliasCollection.name(headers),
+                        ],
                         undefined,
                       ),
                     ),
@@ -116,7 +122,11 @@ export namespace E2eFileProgrammer {
                 IdentifierFactory.access(
                   ts.factory.createIdentifier(SdkImportWizard.typia(importer)),
                 )("random"),
-                [SdkAliasCollection.name(p.type)],
+                [
+                  project.config.clone === true
+                    ? SdkAliasCollection.from(project)(importer)(p.metadata)
+                    : SdkAliasCollection.name(p),
+                ],
                 undefined,
               ),
             ),

package/src/generates/internal/ImportDictionary.ts

@@ -16,7 +16,7 @@ export class ImportDictionary {
 
   public external(props: ImportDictionary.IExternalProps): string {
     const composition: IComposition = this.components_.take(
-      new Pair(props.library, props.type),
+      new Pair(`node_modules/${props.library}`, props.type),
       () => ({
         location: `node_modules/${props.library}`,
         elements: new HashSet(),