@nestia/sdk 3.0.5 → 3.1.0-dev.20240426

package/src/analyses/ReflectControllerAnalyzer.ts

@@ -0,0 +1,155 @@
+import {
+  HOST_METADATA,
+  PATH_METADATA,
+  SCOPE_OPTIONS_METADATA,
+} from "@nestjs/common/constants";
+
+import { INestiaProject } from "../structures/INestiaProject";
+import { IReflectController } from "../structures/IReflectController";
+import { IReflectHttpOperation } from "../structures/IReflectHttpOperation";
+import { IReflectWebSocketOperation } from "../structures/IReflectWebSocketOperation";
+import { ArrayUtil } from "../utils/ArrayUtil";
+import { ReflectHttpOperationAnalyzer } from "./ReflectHttpOperationAnalyzer";
+import { ReflectMetadataAnalyzer } from "./ReflectMetadataAnalyzer";
+import { ReflectWebSocketOperationAnalyzer } from "./ReflectWebSocketOperationAnalyzer";
+
+type IModule = {
+  [key: string]: any;
+};
+
+export namespace ReflectControllerAnalyzer {
+  export const analyze =
+    (project: INestiaProject) =>
+    async (
+      unique: WeakSet<any>,
+      file: string,
+      prefixes: string[],
+      target?: Function,
+    ): Promise<IReflectController[]> => {
+      const module: IModule = await (async () => {
+        try {
+          return await import(file);
+        } catch (exp) {
+          console.log(
+            ">>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>",
+          );
+          console.log(`Error on "${file}" file. Check your code.`);
+          console.log(exp);
+          console.log(
+            ">>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>",
+          );
+          process.exit(-1);
+        }
+      })();
+      const ret: IReflectController[] = [];
+
+      for (const [key, value] of Object.entries(module)) {
+        if (typeof value !== "function" || unique.has(value)) continue;
+        else if ((target ?? value) !== value) continue;
+        else unique.add(value);
+
+        const result: IReflectController | null = _Analyze_controller(project)({
+          file,
+          name: key,
+          creator: value,
+          prefixes,
+        });
+        if (result !== null) ret.push(result);
+      }
+      return ret;
+    };
+
+  /* ---------------------------------------------------------
+        CONTROLLER
+    --------------------------------------------------------- */
+  const _Analyze_controller =
+    (project: INestiaProject) =>
+    (props: {
+      file: string;
+      name: string;
+      creator: any;
+      prefixes: string[];
+    }): IReflectController | null => {
+      //----
+      // VALIDATIONS
+      //----
+      // MUST BE TYPE OF A CREATOR WHO HAS THE CONSTRUCTOR
+      if (
+        !(
+          props.creator instanceof Function &&
+          props.creator.constructor instanceof Function
+        )
+      )
+        return null;
+      // MUST HAVE THOSE MATADATA
+      else if (
+        ArrayUtil.has(
+          Reflect.getMetadataKeys(props.creator),
+          PATH_METADATA,
+          HOST_METADATA,
+          SCOPE_OPTIONS_METADATA,
+        ) === false
+      )
+        return null;
+
+      //----
+      // CONSTRUCTION
+      //----
+      // BASIC INFO
+      const meta: IReflectController = {
+        constructor: props.creator,
+        prototype: props.creator.prototype,
+        file: props.file,
+        name: props.name,
+        operations: [],
+        prefixes: props.prefixes,
+        paths: ReflectMetadataAnalyzer.paths(props.creator).filter((str) => {
+          if (str.includes("*") === true) {
+            project.warnings.push({
+              file: props.file,
+              controller: props.name,
+              function: null,
+              message: "@nestia/sdk does not compose wildcard controller.",
+            });
+            return false;
+          }
+          return true;
+        }),
+        versions: ReflectMetadataAnalyzer.versions(props.creator),
+        security: ReflectMetadataAnalyzer.securities(props.creator),
+        swaggerTgas:
+          Reflect.getMetadata("swagger/apiUseTags", props.creator) ?? [],
+      };
+
+      // PARSE CHILDREN DATA
+      for (const [key, value] of _Get_prototype_entries(props.creator)) {
+        if (typeof value !== "function") continue;
+        const next = {
+          controller: meta,
+          name: key,
+          function: value,
+        };
+        const child: IReflectHttpOperation | IReflectWebSocketOperation | null =
+          ReflectWebSocketOperationAnalyzer.analyze(project)(next) ??
+          ReflectHttpOperationAnalyzer.analyze(project)(next);
+        if (child !== null) meta.operations.push(child);
+      }
+
+      // RETURNS
+      return meta;
+    };
+
+  function _Get_prototype_entries(creator: any): Array<[string, unknown]> {
+    const keyList = Object.getOwnPropertyNames(creator.prototype);
+    const entries: Array<[string, unknown]> = keyList.map((key) => [
+      key,
+      creator.prototype[key],
+    ]);
+
+    const parent = Object.getPrototypeOf(creator);
+    if (parent.prototype !== undefined)
+      entries.push(..._Get_prototype_entries(parent));
+
+    return entries;
+  }
+}

package/src/analyses/ReflectHttpOperationAnalyzer.ts

@@ -0,0 +1,290 @@
+import {
+  HEADERS_METADATA,
+  HTTP_CODE_METADATA,
+  INTERCEPTORS_METADATA,
+  METHOD_METADATA,
+  PATH_METADATA,
+  ROUTE_ARGS_METADATA,
+} from "@nestjs/common/constants";
+import { RouteParamtypes } from "@nestjs/common/enums/route-paramtypes.enum";
+import { ranges } from "tstl";
+
+import { IErrorReport } from "../structures/IErrorReport";
+import { INestiaProject } from "../structures/INestiaProject";
+import { IReflectController } from "../structures/IReflectController";
+import { IReflectHttpOperation } from "../structures/IReflectHttpOperation";
+import { ParamCategory } from "../structures/ParamCategory";
+import { ArrayUtil } from "../utils/ArrayUtil";
+import { PathAnalyzer } from "./PathAnalyzer";
+import { ReflectMetadataAnalyzer } from "./ReflectMetadataAnalyzer";
+
+export namespace ReflectHttpOperationAnalyzer {
+  export const analyze =
+    (project: INestiaProject) =>
+    (props: {
+      controller: IReflectController;
+      function: Function;
+      name: string;
+    }): IReflectHttpOperation | null => {
+      if (
+        ArrayUtil.has(
+          Reflect.getMetadataKeys(props.function),
+          PATH_METADATA,
+          METHOD_METADATA,
+        ) === false
+      )
+        return null;
+
+      const errors: IErrorReport[] = [];
+
+      //----
+      // CONSTRUCTION
+      //----
+      // BASIC INFO
+      const encrypted: boolean = hasInterceptor("EncryptedRouteInterceptor")(
+        props.function,
+      );
+      const query: boolean = hasInterceptor("TypedQueryRouteInterceptor")(
+        props.function,
+      );
+      const method: string =
+        METHODS[Reflect.getMetadata(METHOD_METADATA, props.function)];
+      if (method === undefined || method === "OPTIONS") return null;
+
+      const parameters: IReflectHttpOperation.IParameter[] = (() => {
+        const nestParameters: NestParameters | undefined = Reflect.getMetadata(
+          ROUTE_ARGS_METADATA,
+          props.controller.constructor,
+          props.name,
+        );
+        if (nestParameters === undefined) return [];
+
+        const output: IReflectHttpOperation.IParameter[] = [];
+        for (const tuple of Object.entries(nestParameters)) {
+          const child: IReflectHttpOperation.IParameter | null =
+            _Analyze_http_parameter(...tuple);
+          if (child !== null) output.push(child);
+        }
+        return output.sort((x, y) => x.index - y.index);
+      })();
+
+      // VALIDATE BODY
+      const body: IReflectHttpOperation.IParameter | undefined =
+        parameters.find((param) => param.category === "body");
+      if (body !== undefined && (method === "GET" || method === "HEAD")) {
+        project.errors.push({
+          file: props.controller.file,
+          controller: props.controller.name,
+          function: props.name,
+          message: `"body" parameter cannot be used in the "${method}" method.`,
+        });
+        return null;
+      }
+
+      // DO CONSTRUCT
+      const meta: IReflectHttpOperation = {
+        protocol: "http",
+        function: props.function,
+        name: props.name,
+        method: method === "ALL" ? "POST" : method,
+        paths: ReflectMetadataAnalyzer.paths(props.function).filter((str) => {
+          if (str.includes("*") === true) {
+            project.warnings.push({
+              file: props.controller.file,
+              controller: props.controller.name,
+              function: props.name,
+              message: "@nestia/sdk does not compose wildcard method.",
+            });
+            return false;
+          }
+          return true;
+        }),
+        versions: ReflectMetadataAnalyzer.versions(props.function),
+        parameters,
+        status: Reflect.getMetadata(HTTP_CODE_METADATA, props.function),
+        encrypted,
+        contentType: encrypted
+          ? "text/plain"
+          : query
+            ? "application/x-www-form-urlencoded"
+            : Reflect.getMetadata(HEADERS_METADATA, props.function)?.find(
+                (h: Record<string, string>) =>
+                  typeof h?.name === "string" &&
+                  typeof h?.value === "string" &&
+                  h.name.toLowerCase() === "content-type",
+              )?.value ?? "application/json",
+        security: ReflectMetadataAnalyzer.securities(props.function),
+        exceptions: ReflectMetadataAnalyzer.exceptions(props.function),
+        swaggerTags: [
+          ...new Set([
+            ...props.controller.swaggerTgas,
+            ...(Reflect.getMetadata("swagger/apiUseTags", props.function) ??
+              []),
+          ]),
+        ],
+      };
+
+      // VALIDATE PATH ARGUMENTS
+      for (const controllerLocation of props.controller.paths)
+        for (const metaLocation of meta.paths) {
+          // NORMALIZE LOCATION
+          const location: string = PathAnalyzer.join(
+            controllerLocation,
+            metaLocation,
+          );
+          if (location.includes("*")) continue;
+
+          // LIST UP PARAMETERS
+          const binded: string[] | null = PathAnalyzer.parameters(location);
+          if (binded === null) {
+            project.errors.push({
+              file: props.controller.file,
+              controller: props.controller.name,
+              function: props.name,
+              message: `invalid path (${JSON.stringify(location)})`,
+            });
+            continue;
+          }
+          const parameters: string[] = meta.parameters
+            .filter((param) => param.category === "param")
+            .map((param) => param.field!)
+            .sort();
+
+          // DO VALIDATE
+          if (ranges.equal(binded.sort(), parameters) === false)
+            errors.push({
+              file: props.controller.file,
+              controller: props.controller.name,
+              function: props.name,
+              message: `binded arguments in the "path" between function's decorator and parameters' decorators are different (function: [${binded.join(
+                ", ",
+              )}], parameters: [${parameters.join(", ")}]).`,
+            });
+        }
+
+      // RETURNS
+      if (errors.length) {
+        project.errors.push(...errors);
+        return null;
+      }
+      return meta;
+    };
+
+  function _Analyze_http_parameter(
+    key: string,
+    param: INestParam,
+  ): IReflectHttpOperation.IParameter | null {
+    const symbol: string = key.split(":")[0];
+    if (symbol.indexOf("__custom") !== -1)
+      return _Analyze_http_custom_parameter(param);
+
+    const typeIndex: RouteParamtypes = Number(symbol[0]) as RouteParamtypes;
+    if (isNaN(typeIndex) === true) return null;
+
+    const type: ParamCategory | undefined = getNestParamType(typeIndex);
+    if (type === undefined) return null;
+
+    return {
+      custom: false,
+      name: key,
+      category: type,
+      index: param.index,
+      field: param.data,
+    };
+  }
+
+  function _Analyze_http_custom_parameter(
+    param: INestParam,
+  ): IReflectHttpOperation.IParameter | null {
+    if (param.factory === undefined) return null;
+    else if (
+      param.factory.name === "EncryptedBody" ||
+      param.factory.name === "PlainBody" ||
+      param.factory.name === "TypedQueryBody" ||
+      param.factory.name === "TypedBody" ||
+      param.factory.name === "TypedFormDataBody"
+    )
+      return {
+        custom: true,
+        category: "body",
+        index: param.index,
+        name: param.name,
+        field: param.data,
+        encrypted: param.factory.name === "EncryptedBody",
+        contentType:
+          param.factory.name === "PlainBody" ||
+          param.factory.name === "EncryptedBody"
+            ? "text/plain"
+            : param.factory.name === "TypedQueryBody"
+              ? "application/x-www-form-urlencoded"
+              : param.factory.name === "TypedFormDataBody"
+                ? "multipart/form-data"
+                : "application/json",
+      };
+    else if (param.factory.name === "TypedHeaders")
+      return {
+        custom: true,
+        category: "headers",
+        name: param.name,
+        index: param.index,
+        field: param.data,
+      };
+    else if (param.factory.name === "TypedParam")
+      return {
+        custom: true,
+        category: "param",
+        name: param.name,
+        index: param.index,
+        field: param.data,
+      };
+    else if (param.factory.name === "TypedQuery")
+      return {
+        custom: true,
+        name: param.name,
+        category: "query",
+        index: param.index,
+        field: undefined,
+      };
+    else return null;
+  }
+}
+
+interface INestParam {
+  name: string;
+  index: number;
+  factory?: (...args: any) => any;
+  data: string | undefined;
+}
+
+type NestParameters = {
+  [key: string]: INestParam;
+};
+
+const hasInterceptor =
+  (name: string) =>
+  (proto: any): boolean => {
+    const meta = Reflect.getMetadata(INTERCEPTORS_METADATA, proto);
+    if (Array.isArray(meta) === false) return false;
+    return meta.some((elem) => elem?.constructor?.name === name);
+  };
+
+// https://github.com/nestjs/nest/blob/master/packages/common/enums/route-paramtypes.enum.ts
+const getNestParamType = (value: RouteParamtypes) => {
+  if (value === RouteParamtypes.BODY) return "body";
+  else if (value === RouteParamtypes.HEADERS) return "headers";
+  else if (value === RouteParamtypes.QUERY) return "query";
+  else if (value === RouteParamtypes.PARAM) return "param";
+  return undefined;
+};
+
+// node_modules/@nestjs/common/lib/enums/request-method.enum.ts
+const METHODS = [
+  "GET",
+  "POST",
+  "PUT",
+  "DELETE",
+  "PATCH",
+  "ALL",
+  "OPTIONS",
+  "HEAD",
+];

package/src/analyses/ReflectMetadataAnalyzer.ts

@@ -0,0 +1,53 @@
+import { VERSION_NEUTRAL } from "@nestjs/common";
+import { PATH_METADATA, VERSION_METADATA } from "@nestjs/common/constants";
+import { VersionValue } from "@nestjs/common/interfaces";
+
+import { IReflectHttpOperation } from "../structures/IReflectHttpOperation";
+import { SecurityAnalyzer } from "./SecurityAnalyzer";
+
+export namespace ReflectMetadataAnalyzer {
+  export const exceptions = (
+    value: any,
+  ): Record<
+    number | "2XX" | "3XX" | "4XX" | "5XX",
+    IReflectHttpOperation.IException
+  > => {
+    const entire: IReflectHttpOperation.IException[] | undefined =
+      Reflect.getMetadata("nestia/TypedException", value);
+    return Object.fromEntries(
+      (entire ?? []).map((exp) => [exp.status, exp]),
+    ) as Record<
+      number | "2XX" | "3XX" | "4XX" | "5XX",
+      IReflectHttpOperation.IException
+    >;
+  };
+
+  export const paths = (target: any): string[] => {
+    const value: string | string[] = Reflect.getMetadata(PATH_METADATA, target);
+    if (typeof value === "string") return [value];
+    else if (value.length === 0) return [""];
+    else return value;
+  };
+
+  export const securities = (value: any): Record<string, string[]>[] => {
+    const entire: Record<string, string[]>[] | undefined = Reflect.getMetadata(
+      "swagger/apiSecurity",
+      value,
+    );
+    return entire ? SecurityAnalyzer.merge(...entire) : [];
+  };
+
+  export const versions = (
+    target: any,
+  ): Array<string | typeof VERSION_NEUTRAL> | undefined => {
+    const value: VersionValue | undefined = Reflect.getMetadata(
+      VERSION_METADATA,
+      target,
+    );
+    return value === undefined
+      ? undefined
+      : Array.isArray(value)
+        ? value
+        : [value];
+  };
+}

package/src/analyses/ReflectWebSocketOperationAnalyzer.ts

@@ -0,0 +1,96 @@
+import { ranges } from "tstl";
+
+import { IErrorReport } from "../structures/IErrorReport";
+import { INestiaProject } from "../structures/INestiaProject";
+import { IReflectController } from "../structures/IReflectController";
+import { IReflectWebSocketOperation } from "../structures/IReflectWebSocketOperation";
+import { PathAnalyzer } from "./PathAnalyzer";
+import { ReflectMetadataAnalyzer } from "./ReflectMetadataAnalyzer";
+
+export namespace ReflectWebSocketOperationAnalyzer {
+  export const analyze =
+    (project: INestiaProject) =>
+    (props: {
+      controller: IReflectController;
+      function: Function;
+      name: string;
+    }): IReflectWebSocketOperation | null => {
+      const route: { paths: string[] } | undefined = Reflect.getMetadata(
+        "nestia/WebSocketRoute",
+        props.function,
+      );
+      if (route === undefined) return null;
+
+      const errors: IErrorReport[] = [];
+      const parameters: IReflectWebSocketOperation.IParameter[] = (
+        (Reflect.getMetadata(
+          "nestia/WebSocketRoute/Parameters",
+          props.controller.prototype,
+          props.name,
+        ) ?? []) as IReflectWebSocketOperation.IParameter[]
+      ).sort((a, b) => a.index - b.index);
+      if (parameters.find((p) => (p.category === "acceptor") === undefined))
+        errors.push({
+          file: props.controller.file,
+          controller: props.controller.name,
+          function: props.name,
+          message: "@WebSocketRoute.Acceptor() is essentially required",
+        });
+      if (parameters.length !== props.function.length)
+        errors.push({
+          file: props.controller.file,
+          controller: props.controller.name,
+          function: props.name,
+          message: [
+            "Every parameters must be one of below:",
+            "  - @WebSocketRoute.Acceptor()",
+            "  - @WebSocketRoute.Driver()",
+            "  - @WebSocketRoute.Header()",
+            "  - @WebSocketRoute.Param()",
+            "  - @WebSocketRoute.Query()",
+          ].join("\n"),
+        });
+
+      const fields: string[] = parameters
+        .filter((p) => p.category === "param")
+        .map((p) => p.field)
+        .sort();
+      for (const cLoc of props.controller.paths)
+        for (const mLoc of route.paths) {
+          const location: string = PathAnalyzer.join(cLoc, mLoc);
+          if (location.includes("*")) continue;
+
+          const binded: string[] | null = PathAnalyzer.parameters(location);
+          if (binded === null) {
+            errors.push({
+              file: props.controller.file,
+              controller: props.controller.name,
+              function: props.name,
+              message: `invalid path (${JSON.stringify(location)})`,
+            });
+            continue;
+          }
+          if (ranges.equal(binded.sort(), fields) === false)
+            errors.push({
+              file: props.controller.file,
+              controller: props.controller.name,
+              function: props.name,
+              message: `binded arguments in the "path" between function's decorator and parameters' decorators are different (function: [${binded.join(
+                ", ",
+              )}], parameters: [${fields.join(", ")}]).`,
+            });
+        }
+      if (errors.length) {
+        project.errors.push(...errors);
+        return null;
+      }
+      return {
+        protocol: "websocket",
+        target: props.function,
+        name: props.name,
+        paths: route.paths,
+        versions: ReflectMetadataAnalyzer.versions(props.function),
+        parameters,
+      };
+    };
+}

package/src/analyses/SecurityAnalyzer.ts

@@ -1,7 +1,6 @@
 import { MapUtil } from "../utils/MapUtil";
 
 export namespace SecurityAnalyzer {
-  const none = Symbol("none");
   export const merge = (...entire: Record<string, string[]>[]) => {
     const dict: Map<string | typeof none, Set<string>> = new Map();
     for (const obj of entire) {
@@ -21,4 +20,6 @@ export namespace SecurityAnalyzer {
           });
     return output;
   };
+
+  const none = Symbol("none");
 }

package/src/analyses/TypedControllerAnalyzer.ts

@@ -0,0 +1,92 @@
+import ts from "typescript";
+
+import { INestiaProject } from "../structures/INestiaProject";
+import { IReflectController } from "../structures/IReflectController";
+import { IReflectHttpOperation } from "../structures/IReflectHttpOperation";
+import { IReflectWebSocketOperation } from "../structures/IReflectWebSocketOperation";
+import { ITypedHttpRoute } from "../structures/ITypedHttpRoute";
+import { ITypedWebSocketRoute } from "../structures/ITypedWebSocketRoute";
+import { GenericAnalyzer } from "./GenericAnalyzer";
+import { TypedHttpOperationAnalyzer } from "./TypedHttpOperationAnalyzer";
+import { TypedWebSocketOperationAnalyzer } from "./TypedWebSocketOperationAnalyzer";
+
+export namespace TypedControllerAnalyzer {
+  export const analyze =
+    (project: INestiaProject) =>
+    async (
+      sourceFile: ts.SourceFile,
+      controller: IReflectController,
+    ): Promise<Array<ITypedHttpRoute | ITypedWebSocketRoute>> => {
+      // FIND CONTROLLER CLASS
+      const ret: Array<ITypedHttpRoute | ITypedWebSocketRoute> = [];
+      ts.forEachChild(sourceFile, (node) => {
+        if (
+          ts.isClassDeclaration(node) &&
+          node.name?.escapedText === controller.name
+        ) {
+          // ANALYZE THE CONTROLLER
+          ret.push(..._Analyze_controller(project)(controller, node));
+          return;
+        }
+      });
+      return ret;
+    };
+
+  /* ---------------------------------------------------------
+        CLASS
+    --------------------------------------------------------- */
+  const _Analyze_controller =
+    (project: INestiaProject) =>
+    (
+      controller: IReflectController,
+      classNode: ts.ClassDeclaration,
+    ): Array<ITypedHttpRoute | ITypedWebSocketRoute> => {
+      const classType: ts.InterfaceType = project.checker.getTypeAtLocation(
+        classNode,
+      ) as ts.InterfaceType;
+      const generics: GenericAnalyzer.Dictionary = GenericAnalyzer.analyze(
+        project.checker,
+        classNode,
+      );
+
+      const ret: Array<ITypedHttpRoute | ITypedWebSocketRoute> = [];
+      for (const symbol of classType.getProperties()) {
+        // GET METHOD DECLARATION
+        const declaration: ts.Declaration | undefined = (symbol.declarations ||
+          [])[0];
+        if (!declaration || !ts.isMethodDeclaration(declaration)) continue;
+
+        // IDENTIFIER MUST BE
+        const identifier = declaration.name;
+        if (!ts.isIdentifier(identifier)) continue;
+
+        // ANALYZED WITH THE REFLECTED-FUNCTION
+        const operation:
+          | IReflectHttpOperation
+          | IReflectWebSocketOperation
+          | undefined = controller.operations.find(
+          (f) => f.name === identifier.escapedText,
+        );
+        if (operation === undefined) continue;
+
+        const routes: ITypedHttpRoute[] | ITypedWebSocketRoute[] =
+          operation.protocol === "http"
+            ? TypedHttpOperationAnalyzer.analyze(project)({
+                controller,
+                generics,
+                operation,
+                declaration,
+                symbol,
+              })
+            : TypedWebSocketOperationAnalyzer.analyze(project)({
+                controller,
+                operation,
+                declaration,
+                symbol,
+                generics,
+              });
+        ret.push(...routes);
+      }
+      return ret;
+    };
+}