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

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/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/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

@@ -30,13 +30,6 @@ export namespace E2eFileProgrammer {
         instance: null,
         name: "api",
       });
-      for (const tuple of route.imports)
-        for (const instance of tuple.instances)
-          importer.internal({
-            type: true,
-            file: tuple.file,
-            instance,
-          });
 
       const functor = generate_function(project)(importer)(route);
       await FilePrinter.write({
@@ -73,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(
@@ -97,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,
                       ),
                     ),
@@ -123,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/SdkAliasCollection.ts

@@ -1,6 +1,7 @@
 import ts from "typescript";
 import typia from "typia";
 import { TypeFactory } from "typia/lib/factories/TypeFactory";
+import { Metadata } from "typia/lib/schemas/metadata/Metadata";
 
 import { INestiaProject } from "../../structures/INestiaProject";
 import { IReflectHttpOperationParameter } from "../../structures/IReflectHttpOperationParameter";
@@ -8,18 +9,29 @@ import { IReflectType } from "../../structures/IReflectType";
 import { ITypedHttpRoute } from "../../structures/ITypedHttpRoute";
 import { ITypedHttpRouteParameter } from "../../structures/ITypedHttpRouteParameter";
 import { ImportDictionary } from "./ImportDictionary";
+import { SdkTypeProgrammer } from "./SdkTypeProgrammer";
 
 export namespace SdkAliasCollection {
-  export const name = (type: IReflectType): ts.TypeNode =>
+  export const name = ({ type }: { type: IReflectType }): ts.TypeNode =>
     ts.factory.createTypeReferenceNode(
       type.name,
-      type.typeArguments ? type.typeArguments.map(name) : undefined,
+      type.typeArguments
+        ? type.typeArguments.map((a) => name({ type: a }))
+        : undefined,
     );
 
+  export const from =
+    (project: INestiaProject) =>
+    (importer: ImportDictionary) =>
+    (metadata: Metadata) =>
+      SdkTypeProgrammer.write(project)(importer)(metadata);
+
   export const headers =
     (project: INestiaProject) =>
     (importer: ImportDictionary) =>
     (param: ITypedHttpRouteParameter.IHeaders): ts.TypeNode => {
+      if (project.config.clone === true)
+        return from(project)(importer)(param.metadata);
       const type: ts.TypeNode = name(param);
       if (project.config.primitive === false) return type;
       return ts.factory.createTypeReferenceNode(
@@ -36,6 +48,8 @@ export namespace SdkAliasCollection {
     (project: INestiaProject) =>
     (importer: ImportDictionary) =>
     (param: ITypedHttpRouteParameter.IQuery): ts.TypeNode => {
+      if (project.config.clone === true)
+        return from(project)(importer)(param.metadata);
       const type: ts.TypeNode = name(param);
       if (project.config.primitive === false) return type;
       return ts.factory.createTypeReferenceNode(
@@ -52,9 +66,10 @@ export namespace SdkAliasCollection {
     (project: INestiaProject) =>
     (importer: ImportDictionary) =>
     (param: ITypedHttpRouteParameter): ts.TypeNode => {
-      const type: ts.TypeNode = name(param.type);
-      if (project.config.clone === true || project.config.primitive === false)
-        return type;
+      if (project.config.clone === true)
+        return from(project)(importer)(param.metadata);
+      const type: ts.TypeNode = name(param);
+      if (project.config.primitive === false) return type;
       return ts.factory.createTypeReferenceNode(
         importer.external({
           type: true,
@@ -74,11 +89,15 @@ export namespace SdkAliasCollection {
     (project: INestiaProject) =>
     (importer: ImportDictionary) =>
     (route: ITypedHttpRoute): ts.TypeNode => {
+      const schema = (p: { metadata: Metadata; type: IReflectType }) =>
+        project.config.clone === true
+          ? from(project)(importer)(p.metadata)
+          : name(p);
       if (project.config.propagate !== true) {
         if (route.success.metadata.size() === 0)
           return TypeFactory.keyword("void");
         else if (project.config.primitive === false)
-          return name(route.success.type);
+          return schema(route.success);
         return ts.factory.createTypeReferenceNode(
           importer.external({
             type: true,
@@ -89,7 +108,7 @@ export namespace SdkAliasCollection {
                 ? "Primitive"
                 : "Resolved",
           }),
-          [name(route.success.type)],
+          [schema(route.success)],
         );
       }
 
@@ -98,11 +117,11 @@ export namespace SdkAliasCollection {
           status: String(
             route.success.status ?? (route.method === "POST" ? 201 : 200),
           ),
-          type: name(route.success.type),
+          type: schema(route.success),
         },
         ...Object.entries(route.exceptions).map(([status, value]) => ({
           status,
-          type: name(value.type),
+          type: schema(value),
         })),
       ];
       return ts.factory.createTypeReferenceNode(

package/src/generates/internal/SdkFileProgrammer.ts

@@ -75,13 +75,14 @@ export namespace SdkFileProgrammer {
         `${outDir}/index.ts`,
       );
       directory.routes.forEach((route, i) => {
-        for (const tuple of route.imports)
-          for (const instance of tuple.instances)
-            importer.internal({
-              file: tuple.file,
-              instance,
-              type: true,
-            });
+        if (!(project.config.clone === true && route.protocol === "http"))
+          for (const tuple of route.imports)
+            for (const instance of tuple.instances)
+              importer.internal({
+                file: tuple.file,
+                instance,
+                type: true,
+              });
         statements.push(
           ...(route.protocol === "http"
             ? SdkHttpRouteProgrammer.write(project)(importer)(route)

package/src/generates/internal/SdkHttpCloneProgrammer.ts

@@ -23,6 +23,10 @@ export namespace SdkHttpCloneProgrammer {
   }
 
   export const write = (app: ITypedApplication): Map<string, IModule> => {
+    // console.log({
+    //   objects: Array.from(app.collection.objects.keys()).sort(),
+    //   aliases: Array.from(app.collection.aliases.keys()).sort(),
+    // });
     // COMPOSE THE DICTIONARY
     const dict: Map<string, IModule> = new Map();
     for (const [k, v] of app.collection.objects.entries())
@@ -39,7 +43,6 @@ export namespace SdkHttpCloneProgrammer {
           name: k,
           programmer: (importer) => write_alias(app.project)(importer)(v),
         });
-
     return dict;
   };
 

package/src/generates/internal/SdkHttpCloneReferencer.ts

@@ -1,5 +1,6 @@
 import { Metadata } from "typia/lib/schemas/metadata/Metadata";
 
+import { IReflectType } from "../../structures/IReflectType";
 import { ITypedApplication } from "../../structures/ITypedApplication";
 import { ITypedHttpRoute } from "../../structures/ITypedHttpRoute";
 import { StringUtil } from "../../utils/StringUtil";
@@ -24,17 +25,20 @@ export namespace SdkHttpCloneReferencer {
       visitType({
         unique,
         metadata: p.metadata,
+        type: p.type,
         name: (name) => (p.type = { name }),
       });
     for (const v of Object.values(props.route.exceptions))
       visitType({
         unique,
         metadata: v.metadata,
+        type: v.type,
         name: (name) => (v.type = { name }),
       });
     visitType({
       unique,
       metadata: props.route.success.metadata,
+      type: props.route.success.type,
       name: (name) => (props.route.success.type = { name }),
     });
     props.route.imports = Array.from(unique).map((str) => ({
@@ -46,6 +50,7 @@ export namespace SdkHttpCloneReferencer {
   const visitType = (p: {
     unique: Set<string>;
     metadata: Metadata;
+    type: IReflectType;
     name: (key: string) => void;
   }): void => {
     const enroll = (key: string) => {
@@ -59,3 +64,8 @@ export namespace SdkHttpCloneReferencer {
     p.name(p.metadata.getName());
   };
 }
+
+const getFullText = (type: IReflectType): string =>
+  type.typeArguments === undefined
+    ? type.name
+    : `${type.name}<${type.typeArguments.map(getFullText).join(", ")}>`;

package/src/generates/internal/SdkHttpFunctionProgrammer.ts

@@ -2,7 +2,6 @@ import ts from "typescript";
 import { IdentifierFactory } from "typia/lib/factories/IdentifierFactory";
 import { TypeFactory } from "typia/lib/factories/TypeFactory";
 
-import { INestiaConfig } from "../../INestiaConfig";
 import { INestiaProject } from "../../structures/INestiaProject";
 import { ITypedHttpRoute } from "../../structures/ITypedHttpRoute";
 import { ITypedHttpRouteParameter } from "../../structures/ITypedHttpRouteParameter";
@@ -56,21 +55,26 @@ export namespace SdkHttpFunctionProgrammer {
                   ? ts.factory.createTypeReferenceNode(
                       `${route.name}.${p === props.query ? "Query" : "Input"}`,
                     )
-                  : SdkAliasCollection.name(p.type),
+                  : project.config.clone === true
+                    ? SdkAliasCollection.from(project)(importer)(p.metadata)
+                    : SdkAliasCollection.name(p),
               ),
             ),
         ],
         ts.factory.createTypeReferenceNode("Promise", [
-          SdkAliasCollection.output(project)(importer)(route),
+          project.config.propagate === true ||
+          route.success.metadata.size() !== 0
+            ? ts.factory.createTypeReferenceNode(`${route.name}.Output`)
+            : ts.factory.createTypeReferenceNode("void"),
         ]),
         ts.factory.createBlock(
-          write_body(project.config)(importer)(route, props),
+          write_body(project)(importer)(route, props),
           true,
         ),
       );
 
   const write_body =
-    (config: INestiaConfig) =>
+    (project: INestiaProject) =>
     (importer: ImportDictionary) =>
     (
       route: ITypedHttpRoute,
@@ -84,10 +88,12 @@ export namespace SdkHttpFunctionProgrammer {
         ts.factory.createCallExpression(
           IdentifierFactory.access(
             ts.factory.createIdentifier(
-              SdkImportWizard.Fetcher(!!props.input?.encrypted)(importer),
+              SdkImportWizard.Fetcher(
+                !!props.input?.encrypted || route.success.encrypted,
+              )(importer),
             ),
-          )(config.propagate ? "propagate" : "fetch"),
-          config.propagate
+          )(project.config.propagate ? "propagate" : "fetch"),
+          project.config.propagate
             ? route.method.toLowerCase() === "get" ||
               route.method.toLowerCase() === "head"
               ? [TypeFactory.keyword("any")]
@@ -158,7 +164,7 @@ export namespace SdkHttpFunctionProgrammer {
             ...(props.input
               ? [ts.factory.createIdentifier(props.input.name)]
               : []),
-            ...(config.json &&
+            ...(project.config.json &&
             props.input !== undefined &&
             (props.input.contentType === "application/json" ||
               props.input.encrypted === true)
@@ -167,7 +173,7 @@ export namespace SdkHttpFunctionProgrammer {
           ],
         );
       const output = (awaiter: boolean) =>
-        config.simulate
+        project.config.simulate
           ? ts.factory.createConditionalExpression(
               ts.factory.createIdentifier("!!connection.simulate"),
               undefined,
@@ -188,7 +194,7 @@ export namespace SdkHttpFunctionProgrammer {
             ? ts.factory.createAwaitExpression(caller())
             : caller();
       return [
-        ...(config.assert
+        ...(project.config.assert
           ? route.parameters
               .filter((p) => p.category !== "headers")
               .map((p) =>
@@ -211,12 +217,13 @@ export namespace SdkHttpFunctionProgrammer {
           : []),
         ...(route.success.setHeaders.length === 0
           ? [ts.factory.createReturnStatement(output(false))]
-          : write_set_headers(config)(route)(output(true))),
+          : write_set_headers(project)(importer)(route)(output(true))),
       ];
     };
 
   const write_set_headers =
-    (config: INestiaConfig) =>
+    (project: INestiaProject) =>
+    (importer: ImportDictionary) =>
     (route: ITypedHttpRoute) =>
     (condition: ts.Expression): ts.Statement[] => {
       const accessor = (x: string) => (y: string) =>
@@ -226,7 +233,9 @@ export namespace SdkHttpFunctionProgrammer {
         ...route.parameters.map((p) => p.name),
       ])("output");
       const headers: string = accessor("connection")("headers");
-      const data: string = config.propagate ? accessor(output)("data") : output;
+      const data: string = project.config.propagate
+        ? accessor(output)("data")
+        : output;
 
       const assigners: ts.ExpressionStatement[] = [
         ts.factory.createBinaryExpression(
@@ -261,14 +270,14 @@ export namespace SdkHttpFunctionProgrammer {
               ts.factory.createVariableDeclaration(
                 output,
                 undefined,
-                SdkAliasCollection.name(route.success.type),
+                SdkAliasCollection.output(project)(importer)(route),
                 condition,
               ),
             ],
             ts.NodeFlags.Const,
           ),
         ),
-        ...(config.propagate
+        ...(project.config.propagate
           ? [
               ts.factory.createIfStatement(
                 ts.factory.createIdentifier(accessor(output)("success")),