@nestia/sdk 3.0.5-dev.20240418 → 3.1.0-dev.20240426

package/src/analyses/TypedWebSocketOperationAnalyzer.ts

@@ -0,0 +1,368 @@
+import path from "path";
+import { HashMap } from "tstl";
+import ts from "typescript";
+import { CommentFactory } from "typia/lib/factories/CommentFactory";
+
+import { IErrorReport } from "../structures/IErrorReport";
+import { INestiaProject } from "../structures/INestiaProject";
+import { IReflectController } from "../structures/IReflectController";
+import { IReflectWebSocketOperation } from "../structures/IReflectWebSocketOperation";
+import { ITypeTuple } from "../structures/ITypeTuple";
+import { ITypedWebSocketRoute } from "../structures/ITypedWebSocketRoute";
+import { PathUtil } from "../utils/PathUtil";
+import { VersioningStrategy } from "../utils/VersioningStrategy";
+import { GenericAnalyzer } from "./GenericAnalyzer";
+import { ImportAnalyzer } from "./ImportAnalyzer";
+import { PathAnalyzer } from "./PathAnalyzer";
+
+export namespace TypedWebSocketOperationAnalyzer {
+  export const analyze =
+    (project: INestiaProject) =>
+    (props: {
+      controller: IReflectController;
+      operation: IReflectWebSocketOperation;
+      declaration: ts.MethodDeclaration;
+      symbol: ts.Symbol;
+      generics: GenericAnalyzer.Dictionary;
+    }): ITypedWebSocketRoute[] => {
+      // CHECK TYPE
+      const type: ts.Type = project.checker.getTypeOfSymbolAtLocation(
+        props.symbol,
+        props.symbol.valueDeclaration!,
+      );
+      const signature: ts.Signature | undefined =
+        project.checker.getSignaturesOfType(type, ts.SignatureKind.Call)[0];
+      if (signature === undefined) {
+        project.errors.push({
+          file: props.controller.file,
+          controller: props.controller.name,
+          function: props.operation.name,
+          message: "unable to get the type signature.",
+        });
+        return [];
+      }
+
+      // SKIP @IGNORE TAG
+      const jsDocTags = signature.getJsDocTags();
+      if (jsDocTags.some((tag) => tag.name === "ignore")) return [];
+
+      // EXPLORE CHILDREN TYPES
+      const importDict: ImportAnalyzer.Dictionary = new HashMap();
+      const errors: IErrorReport[] = [];
+      const parameters: Array<ITypedWebSocketRoute.IParameter> =
+        props.operation.parameters.map(
+          (param) =>
+            _Analyze_parameter({
+              ...project,
+              errors,
+            })({
+              generics: props.generics,
+              imports: importDict,
+              controller: props.controller,
+              function: props.operation.name,
+              parameter: param,
+              symbol: signature.getParameters()[param.index],
+            })!,
+        );
+      if (errors.length) {
+        project.errors.push(...errors);
+        return [];
+      }
+
+      const imports: [string, string[]][] = importDict
+        .toJSON()
+        .map((pair) => [pair.first, pair.second.toJSON()]);
+      const common: Omit<ITypedWebSocketRoute, "path" | "accessors"> = {
+        ...props.operation,
+        controller: props.controller,
+        parameters,
+        imports,
+        location: (() => {
+          const file = props.declaration.getSourceFile();
+          const { line, character } = file.getLineAndCharacterOfPosition(
+            props.declaration.pos,
+          );
+          return `${path.relative(process.cwd(), file.fileName)}:${line + 1}:${
+            character + 1
+          }`;
+        })(),
+        description: CommentFactory.description(props.symbol),
+      };
+
+      // CONFIGURE PATHS
+      const pathList: Set<string> = new Set();
+      const versions: string[] = VersioningStrategy.merge(project)([
+        ...(props.controller.versions ?? []),
+        ...(props.operation.versions ?? []),
+      ]);
+      for (const v of versions)
+        for (const prefix of wrapPaths(props.controller.prefixes))
+          for (const cPath of wrapPaths(props.controller.paths))
+            for (const filePath of wrapPaths(props.operation.paths))
+              pathList.add(
+                PathAnalyzer.join(
+                  project.input.globalPrefix?.prefix ?? "",
+                  v,
+                  prefix,
+                  cPath,
+                  filePath,
+                ),
+              );
+
+      return [...pathList]
+        .filter((path) => {
+          const escaped: string | null = PathAnalyzer.escape(path);
+          if (escaped === null)
+            project.errors.push({
+              file: props.controller.file,
+              controller: props.controller.name,
+              function: props.operation.name,
+              message: `unable to escape the path "${path}".`,
+            });
+          return escaped !== null;
+        })
+        .map((path) => ({
+          ...common,
+          path: PathAnalyzer.escape(path)!,
+          accessors: [...PathUtil.accessors(path), props.operation.name],
+        }));
+    };
+
+  const _Analyze_parameter =
+    (project: INestiaProject) =>
+    (props: {
+      generics: GenericAnalyzer.Dictionary;
+      imports: ImportAnalyzer.Dictionary;
+      controller: IReflectController;
+      function: string;
+      parameter: IReflectWebSocketOperation.IParameter;
+      symbol: ts.Symbol;
+    }): ITypedWebSocketRoute.IParameter => {
+      if (props.parameter.category === "acceptor")
+        return _Analyze_acceptor(project)(props);
+      else if (props.parameter.category === "driver")
+        return _Analyze_driver(project)(props);
+
+      const type: ts.Type = project.checker.getTypeOfSymbolAtLocation(
+        props.symbol,
+        props.symbol.valueDeclaration!,
+      );
+      const name: string = props.symbol.getEscapedName().toString();
+
+      // VALIDATIONS
+      const errors: IErrorReport[] = [];
+      const tuple: ITypeTuple | null = ImportAnalyzer.analyze(project.checker)({
+        generics: props.generics,
+        imports: props.imports,
+        type,
+      });
+      if (
+        tuple === null ||
+        tuple.typeName === "__type" ||
+        tuple.typeName === "__object"
+      )
+        errors.push({
+          file: props.controller.file,
+          controller: props.controller.name,
+          function: props.function,
+          message: `implicit (unnamed) parameter type from ${JSON.stringify(name)}.`,
+        });
+      _Check_optional({
+        ...project,
+        errors,
+      })({
+        ...props,
+        parameter: {
+          name,
+          symbol: props.symbol,
+        },
+      });
+      if (errors.length) {
+        project.errors.push(...errors);
+        return null!;
+      }
+      return {
+        ...props.parameter,
+        category: props.parameter.category,
+        name,
+        type: tuple!.type,
+        typeName: tuple!.typeName,
+      };
+    };
+
+  const _Analyze_acceptor =
+    (project: INestiaProject) =>
+    (props: {
+      generics: GenericAnalyzer.Dictionary;
+      imports: ImportAnalyzer.Dictionary;
+      controller: IReflectController;
+      function: string;
+      parameter: IReflectWebSocketOperation.IParameter;
+      symbol: ts.Symbol;
+    }): ITypedWebSocketRoute.IAcceptorParameter => {
+      // VALIDATIONS
+      const type: ts.Type = project.checker.getTypeOfSymbolAtLocation(
+        props.symbol,
+        props.symbol.valueDeclaration!,
+      );
+      const name: string = props.symbol.getEscapedName().toString();
+      const generics: readonly ts.Type[] =
+        type.aliasTypeArguments ??
+        project.checker.getTypeArguments(type as ts.TypeReference) ??
+        [];
+
+      const errors: IErrorReport[] = [];
+      _Check_optional({
+        ...project,
+        errors,
+      })({
+        ...props,
+        parameter: {
+          name,
+          symbol: props.symbol,
+        },
+      });
+      if (generics.length !== 3)
+        errors.push({
+          file: props.controller.file,
+          controller: props.controller.name,
+          function: props.function,
+          message: `@WebSocketRoute.Acceptor() must have three type arguments of WebAcceptor<Header, Provider, Listener>`,
+        });
+      const [header, provider, listener] = [
+        "header",
+        "provider",
+        "listener",
+      ].map((key, i) => {
+        const tuple: ITypeTuple | null = ImportAnalyzer.analyze(
+          project.checker,
+        )({
+          generics: props.generics,
+          imports: props.imports,
+          type: generics[i],
+        });
+        if (tuple === null)
+          errors.push({
+            file: props.controller.file,
+            controller: props.controller.name,
+            function: props.function,
+            message: `unable to analyze the "${key}" argument type of WebAcceptor<Header, Provider, Listener>.`,
+          });
+        return tuple!;
+      });
+
+      if (errors.length) {
+        project.errors.push(...errors);
+        return null!;
+      }
+      return {
+        ...props.parameter,
+        category: "acceptor",
+        name,
+        header,
+        provider,
+        listener: listener,
+      };
+    };
+
+  const _Analyze_driver =
+    (project: INestiaProject) =>
+    (props: {
+      generics: GenericAnalyzer.Dictionary;
+      imports: ImportAnalyzer.Dictionary;
+      controller: IReflectController;
+      function: string;
+      parameter: IReflectWebSocketOperation.IParameter;
+      symbol: ts.Symbol;
+    }): ITypedWebSocketRoute.IDriverParameter => {
+      // VALIDATIONS
+      const type: ts.Type = project.checker.getTypeOfSymbolAtLocation(
+        props.symbol,
+        props.symbol.valueDeclaration!,
+      );
+      const name: string = props.symbol.getEscapedName().toString();
+      const generics: readonly ts.Type[] =
+        type.aliasTypeArguments ??
+        project.checker.getTypeArguments(type as ts.TypeReference) ??
+        [];
+
+      const errors: IErrorReport[] = [];
+      _Check_optional({
+        ...project,
+        errors,
+      })({
+        ...props,
+        parameter: {
+          name,
+          symbol: props.symbol,
+        },
+      });
+      const tuple: ITypeTuple = (() => {
+        if (generics.length !== 1) {
+          errors.push({
+            file: props.controller.file,
+            controller: props.controller.name,
+            function: props.function,
+            message: `@WebSocketRoute.Driver() must have one type argument of WebDriver<T>`,
+          });
+          return null!;
+        } else {
+          const tuple: ITypeTuple | null = ImportAnalyzer.analyze(
+            project.checker,
+          )({
+            generics: props.generics,
+            imports: props.imports,
+            type: generics[0],
+          });
+          if (tuple === null)
+            errors.push({
+              file: props.controller.file,
+              controller: props.controller.name,
+              function: props.function,
+              message: `unable to analyze the "type" argument of WebDriver<T>.`,
+            });
+          return tuple!;
+        }
+      })();
+      if (errors.length) {
+        project.errors.push(...errors);
+        return null!;
+      }
+      return {
+        ...props.parameter,
+        category: "driver",
+        name,
+        type: tuple.type,
+        typeName: tuple.typeName,
+      };
+    };
+
+  const _Check_optional =
+    (project: INestiaProject) =>
+    (props: {
+      controller: IReflectController;
+      function: string;
+      parameter: {
+        name: string;
+        symbol: ts.Symbol;
+      };
+    }) => {
+      const optional: boolean = !!project.checker.symbolToParameterDeclaration(
+        props.parameter.symbol,
+        undefined,
+        undefined,
+      )?.questionToken;
+      if (optional === true)
+        project.errors.push({
+          file: props.controller.file,
+          controller: props.controller.name,
+          function: props.function,
+          message: `@WebSocketRoute() does not allow optional parameter, but be detected from ${JSON.stringify(
+            props.parameter.symbol.getEscapedName().toString(),
+          )}.`,
+        });
+    };
+}
+
+const wrapPaths = (paths: string[]): string[] =>
+  paths.length === 0 ? [""] : paths;

package/src/generates/CloneGenerator.ts

@@ -1,30 +1,32 @@
 import fs from "fs";
 import ts from "typescript";
 
-import { INestiaConfig } from "../INestiaConfig";
-import { IRoute } from "../structures/IRoute";
+import { INestiaProject } from "../structures/INestiaProject";
+import { ITypedHttpRoute } from "../structures/ITypedHttpRoute";
 import { FilePrinter } from "./internal/FilePrinter";
 import { ImportDictionary } from "./internal/ImportDictionary";
-import { SdkCloneProgrammer } from "./internal/SdkCloneProgrammer";
+import { SdkHttpCloneProgrammer } from "./internal/SdkHttpCloneProgrammer";
 
 export namespace CloneGenerator {
   export const write =
-    (checker: ts.TypeChecker) =>
-    (config: INestiaConfig) =>
-    async (routes: IRoute[]): Promise<void> => {
-      const dict: Map<string, SdkCloneProgrammer.IModule> =
-        SdkCloneProgrammer.write(checker)(config)(routes);
+    (project: INestiaProject) =>
+    async (routes: ITypedHttpRoute[]): Promise<void> => {
+      const dict: Map<string, SdkHttpCloneProgrammer.IModule> =
+        SdkHttpCloneProgrammer.write(project)(routes);
       if (dict.size === 0) return;
       try {
-        await fs.promises.mkdir(`${config.output}/structures`);
+        await fs.promises.mkdir(`${project.config.output}/structures`);
       } catch {}
-      for (const [key, value] of dict) await writeDtoFile(config)(key, value);
+      for (const [key, value] of dict) await writeDtoFile(project)(key, value);
     };
 
   const writeDtoFile =
-    (config: INestiaConfig) =>
-    async (key: string, value: SdkCloneProgrammer.IModule): Promise<void> => {
-      const location: string = `${config.output}/structures/${key}.ts`;
+    (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;
@@ -32,7 +34,7 @@ export namespace CloneGenerator {
       await FilePrinter.write({
         location,
         statements: [
-          ...importer.toStatements(`${config.output}/structures`),
+          ...importer.toStatements(`${project.config.output}/structures`),
           ...(importer.empty() ? [] : [FilePrinter.enter()]),
           ...statements,
         ],
@@ -41,7 +43,7 @@ export namespace CloneGenerator {
 
   const iterate =
     (importer: ImportDictionary) =>
-    (modulo: SdkCloneProgrammer.IModule): ts.Statement[] => {
+    (modulo: SdkHttpCloneProgrammer.IModule): ts.Statement[] => {
       const output: ts.Statement[] = [];
       if (modulo.programmer !== null) output.push(modulo.programmer(importer));
       if (modulo.children.size) {

package/src/generates/E2eGenerator.ts

@@ -1,39 +1,37 @@
 import fs from "fs";
 import path from "path";
-import ts from "typescript";
 
-import { INestiaConfig } from "../INestiaConfig";
 import { ConfigAnalyzer } from "../analyses/ConfigAnalyzer";
-import { IRoute } from "../structures/IRoute";
+import { INestiaProject } from "../structures/INestiaProject";
+import { ITypedHttpRoute } from "../structures/ITypedHttpRoute";
 import { E2eFileProgrammer } from "./internal/E2eFileProgrammer";
 
 export namespace E2eGenerator {
   export const generate =
-    (checker: ts.TypeChecker) =>
-    (config: INestiaConfig) =>
-    async (routeList: IRoute[]): Promise<void> => {
+    (project: INestiaProject) =>
+    async (routeList: ITypedHttpRoute[]): Promise<void> => {
       console.log("Generating E2E Test Functions");
 
       // PREPARE DIRECTORIES
-      const output: string = path.resolve(config.e2e!);
+      const output: string = path.resolve(project.config.e2e!);
       await mkdir(output);
       await mkdir(path.join(output, "features"));
       await mkdir(path.join(output, "features", "api"));
       await mkdir(path.join(output, "features", "api", "automated"));
 
       // GENERATE TEST INDEX FILE
-      await index(config)(path.join(config.e2e!, "index.ts"));
+      await index(project)(path.join(project.config.e2e!, "index.ts"));
 
       // GENERATE EACH TEST FILES
       for (const route of routeList)
-        await E2eFileProgrammer.generate(checker)(config)({
-          api: path.resolve(config.output!),
+        await E2eFileProgrammer.generate(project)({
+          api: path.resolve(project.config.output!),
           current: path.join(output, "features", "api", "automated"),
         })(route);
     };
 
   const index =
-    (config: INestiaConfig) =>
+    (project: INestiaProject) =>
     async (output: string): Promise<void> => {
       if (fs.existsSync(output)) return;
 
@@ -52,7 +50,7 @@ export namespace E2eGenerator {
         output,
         content.replace(
           "${input}",
-          JSON.stringify(await ConfigAnalyzer.input(config)),
+          JSON.stringify(await ConfigAnalyzer.input(project.config)),
         ),
         "utf8",
       );

package/src/generates/SdkGenerator.ts

@@ -1,31 +1,32 @@
 import fs from "fs";
 import NodePath from "path";
 import { IPointer } from "tstl";
-import ts from "typescript";
 
-import { INestiaConfig } from "../INestiaConfig";
-import { IRoute } from "../structures/IRoute";
+import { INestiaProject } from "../structures/INestiaProject";
+import { ITypedHttpRoute } from "../structures/ITypedHttpRoute";
+import { ITypedWebSocketRoute } from "../structures/ITypedWebSocketRoute";
 import { CloneGenerator } from "./CloneGenerator";
 import { SdkDistributionComposer } from "./internal/SdkDistributionComposer";
 import { SdkFileProgrammer } from "./internal/SdkFileProgrammer";
 
 export namespace SdkGenerator {
   export const generate =
-    (checker: ts.TypeChecker) =>
-    (config: INestiaConfig) =>
-    async (routes: IRoute[]): Promise<void> => {
+    (project: INestiaProject) =>
+    async (
+      routes: Array<ITypedHttpRoute | ITypedWebSocketRoute>,
+    ): Promise<void> => {
       console.log("Generating SDK Library");
 
       // PREPARE NEW DIRECTORIES
       try {
-        await fs.promises.mkdir(config.output!);
+        await fs.promises.mkdir(project.config.output!);
       } catch {}
 
       // BUNDLING
       const bundle: string[] = await fs.promises.readdir(BUNDLE_PATH);
       for (const file of bundle) {
         const current: string = `${BUNDLE_PATH}/${file}`;
-        const target: string = `${config.output}/${file}`;
+        const target: string = `${project.config.output}/${file}`;
         const stats: fs.Stats = await fs.promises.stat(current);
 
         if (stats.isFile() === true) {
@@ -44,14 +45,20 @@ export namespace SdkGenerator {
       }
 
       // STRUCTURES
-      if (config.clone) await CloneGenerator.write(checker)(config)(routes);
+      if (project.config.clone)
+        await CloneGenerator.write(project)(
+          routes.filter((r) => r.protocol === "http") as ITypedHttpRoute[],
+        );
 
       // FUNCTIONAL
-      await SdkFileProgrammer.generate(checker)(config)(routes);
+      await SdkFileProgrammer.generate(project)(routes);
 
       // DISTRIBUTION
-      if (config.distribute !== undefined)
-        await SdkDistributionComposer.compose(config);
+      if (project.config.distribute !== undefined)
+        await SdkDistributionComposer.compose(
+          project.config,
+          routes.some((r) => r.protocol === "websocket"),
+        );
     };
 
   export const BUNDLE_PATH = NodePath.join(