@nestia/sdk 3.10.0 → 3.11.0-dev.20240812

package/src/analyses/ReflectHttpOperationParameterAnalyzer.ts

@@ -0,0 +1,319 @@
+import { ROUTE_ARGS_METADATA } from "@nestjs/common/constants";
+import { RouteParamtypes } from "@nestjs/common/enums/route-paramtypes.enum";
+import { JsonMetadataFactory } from "typia/lib/factories/JsonMetadataFactory";
+import { HttpFormDataProgrammer } from "typia/lib/programmers/http/HttpFormDataProgrammer";
+import { HttpHeadersProgrammer } from "typia/lib/programmers/http/HttpHeadersProgrammer";
+import { HttpParameterProgrammer } from "typia/lib/programmers/http/HttpParameterProgrammer";
+import { HttpQueryProgrammer } from "typia/lib/programmers/http/HttpQueryProgrammer";
+
+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";
+
+export namespace ReflectHttpOperationParameterAnalyzer {
+  export interface IContext {
+    controller: IReflectController;
+    function: Function;
+    functionName: string;
+    httpMethod: string;
+    metadata: IOperationMetadata;
+    errors: IReflectOperationError[];
+  }
+  export const analyze = (ctx: IContext): IReflectHttpOperationParameter[] => {
+    const preconfigured: IReflectHttpOperationParameter.IPreconfigured[] =
+      analyzePreconfigured(ctx);
+    const imports: IReflectTypeImport[] = [];
+    const errors: IReflectOperationError[] = [];
+
+    //----
+    // FIND CONTRADICTIONS
+    //----
+    // GET AND HEAD METHOD
+    const contradictErrors: string[] = [];
+    const contradict = (message: string) => {
+      contradictErrors.push(message);
+    };
+    if (
+      (ctx.httpMethod === "GET" || ctx.httpMethod === "HEAD") &&
+      preconfigured.some((x) => x.category === "body")
+    )
+      contradict(`@Body() is not allowed in the ${ctx.httpMethod} method.`);
+
+    // FIND DUPLICATED BODY
+    if (
+      preconfigured.filter(
+        (x) => x.category === "body" && x.field === undefined,
+      ).length > 1
+    )
+      contradict(`Duplicated @Body() is not allowed.`);
+    if (
+      preconfigured.filter(
+        (x) => x.category === "query" && x.field === undefined,
+      ).length > 1
+    )
+      contradict(`Duplicated @Query() without field name is not allowed.`);
+    if (
+      preconfigured.filter(
+        (x) => x.category === "headers" && x.field === undefined,
+      ).length > 1
+    )
+      contradict(`Duplicated @Headers() without field name is not allowed.`);
+
+    // FIND DUPLICATED FIELDS
+    if (
+      isUnique(
+        preconfigured
+          .filter((x) => x.category === "param")
+          .map((x) => x.field)
+          .filter((field) => field !== undefined),
+      ) === false
+    )
+      contradict(`Duplicated field names of path are not allowed.`);
+    if (
+      isUnique(
+        preconfigured
+          .filter((x) => x.category === "query")
+          .map((x) => x.field)
+          .filter((field) => field !== undefined),
+      ) === false
+    )
+      contradict(`Duplicated field names of query are not allowed.`);
+    if (
+      isUnique(
+        preconfigured
+          .filter((x) => x.category === "headers")
+          .map((x) => x.field)
+          .filter((field) => field !== undefined),
+      ) === false
+    )
+      contradict(`Duplicated field names of headers are not allowed.`);
+    if (contradictErrors.length)
+      errors.push({
+        file: ctx.controller.file,
+        class: ctx.controller.class.name,
+        function: ctx.functionName,
+        from: "",
+        contents: contradictErrors,
+      });
+
+    //----
+    // COMPOSE PARAMETERS
+    //----
+    const parameters: IReflectHttpOperationParameter[] = preconfigured
+      .map((p): IReflectHttpOperationParameter | null => {
+        // METADATA INFO
+        const pErrorContents: Array<string | IOperationMetadata.IError> = [];
+        const matched: IOperationMetadata.IParameter | undefined =
+          ctx.metadata.parameters.find((x) => x.index === p.index);
+        const report = () => {
+          errors.push({
+            file: ctx.controller.file,
+            class: ctx.controller.class.name,
+            function: ctx.functionName,
+            from: `parameter ${matched ? JSON.stringify(matched.name) : `of ${p.index} th`}`,
+            contents: pErrorContents,
+          });
+          return null;
+        };
+
+        // VALIDATE TYPE
+        if (matched === undefined)
+          pErrorContents.push(`Unable to find parameter type.`);
+        else if (matched.type === null)
+          pErrorContents.push(`Failed to get the type info.`);
+
+        // CONSIDER KIND
+        const schema: IOperationMetadata.ISchema | null = (() => {
+          if (matched === undefined) return null;
+          const result =
+            p.category === "body" &&
+            (p.contentType === "application/json" || p.encrypted === true)
+              ? matched.primitive
+              : matched.resolved;
+          return result.success ? result.data : null;
+        })();
+        if (p.category === "body" && p.field !== undefined)
+          pErrorContents.push(`@Body() must not have a field name.`);
+        else if (p.category === "param" && p.field === undefined)
+          pErrorContents.push(`@Param() must have a field name.`);
+
+        if (pErrorContents.length) return report();
+        else if (
+          matched === undefined ||
+          matched.type === null ||
+          schema === null
+        )
+          return null; // unreachable
+
+        // COMPOSITION
+        imports.push(...matched.imports);
+        if (p.category === "param")
+          return {
+            category: p.category,
+            index: p.index,
+            field: p.field!,
+            name: matched.name,
+            type: matched.type,
+            validate: HttpParameterProgrammer.validate,
+            description: matched.description,
+            jsDocTags: matched.jsDocTags,
+            ...schema,
+          };
+        else if (p.category === "query" || p.category === "headers")
+          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,
+            description: matched.description,
+            jsDocTags: matched.jsDocTags,
+            ...schema,
+          };
+        else if (p.category === "body")
+          return {
+            category: p.category,
+            index: p.index,
+            encrypted: !!p.encrypted,
+            contentType: p.contentType,
+            name: matched.name,
+            type: matched.type,
+            validate:
+              p.contentType === "application/json" || p.encrypted === true
+                ? JsonMetadataFactory.validate
+                : p.contentType === "application/x-www-form-urlencoded"
+                  ? HttpQueryProgrammer.validate
+                  : p.contentType === "multipart/form-data"
+                    ? HttpFormDataProgrammer.validate
+                    : TextPlainValidator.validate,
+            description: matched.description,
+            jsDocTags: matched.jsDocTags,
+            ...schema,
+          };
+        else {
+          pErrorContents.push(`Unknown kind of the parameter.`);
+          return report();
+        }
+      })
+      .filter((x): x is IReflectHttpOperationParameter => x !== null);
+
+    if (errors.length) ctx.errors.push(...errors);
+    return parameters;
+  };
+
+  const analyzePreconfigured = (
+    props: IContext,
+  ): IReflectHttpOperationParameter.IPreconfigured[] => {
+    const dict: NestParameters | undefined = Reflect.getMetadata(
+      ROUTE_ARGS_METADATA,
+      props.controller.class,
+      props.functionName,
+    );
+    if (dict === undefined) return [];
+    return Object.entries(dict)
+      .map(([key, param]) => analyzeHttpParameter(key, param))
+      .filter(
+        (x): x is IReflectHttpOperationParameter.IPreconfigured => x !== null,
+      )
+      .sort((x, y) => x.index - y.index);
+  };
+
+  const analyzeHttpParameter = (
+    key: string,
+    param: INestParam,
+  ): IReflectHttpOperationParameter.IPreconfigured | null => {
+    const symbol: string = key.split(":")[0];
+    if (symbol.indexOf("__custom") !== -1) return analyzeCustomParameter(param);
+
+    const category:
+      | IReflectHttpOperationParameter.IPreconfigured["category"]
+      | null = getNestParamType(Number(symbol[0]) as RouteParamtypes);
+    if (category === null) return null;
+    if (category === "body")
+      return {
+        category: "body",
+        index: param.index,
+        field: param.data,
+        contentType: "application/json",
+      };
+    else
+      return {
+        category,
+        index: param.index,
+        field: param.data,
+      };
+  };
+
+  const analyzeCustomParameter = (
+    param: INestParam,
+  ): IReflectHttpOperationParameter.IPreconfigured | 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 {
+        category: "body",
+        index: param.index,
+        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 {
+        category: "headers",
+        index: param.index,
+        field: param.data,
+      };
+    else if (param.factory.name === "TypedParam")
+      return {
+        category: "param",
+        index: param.index,
+        field: param.data,
+      };
+    else if (param.factory.name === "TypedQuery")
+      return {
+        category: "query",
+        index: param.index,
+        field: undefined,
+      };
+    else return null;
+  };
+
+  const isUnique = (values: string[]) => new Set(values).size === values.length;
+}
+
+type NestParameters = {
+  [key: string]: INestParam;
+};
+interface INestParam {
+  name: string;
+  index: number;
+  factory?: (...args: any) => any;
+  data: string | undefined;
+}
+
+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 null;
+};

package/src/analyses/ReflectHttpOperationResponseAnalyzer.ts

@@ -0,0 +1,117 @@
+import {
+  HEADERS_METADATA,
+  HTTP_CODE_METADATA,
+  INTERCEPTORS_METADATA,
+} from "@nestjs/common/constants";
+import typia from "typia";
+import { JsonMetadataFactory } from "typia/lib/factories/JsonMetadataFactory";
+import { HttpQueryProgrammer } from "typia/lib/programmers/http/HttpQueryProgrammer";
+
+import { IReflectController } from "../structures/IReflectController";
+import { IReflectHttpOperationSuccess } from "../structures/IReflectHttpOperationSuccess";
+import { IReflectOperationError } from "../structures/IReflectOperationError";
+import { IOperationMetadata } from "../transformers/IOperationMetadata";
+import { TextPlainValidator } from "../transformers/TextPlainValidator";
+
+export namespace ReflectHttpOperationResponseAnalyzer {
+  export interface IContext {
+    controller: IReflectController;
+    function: Function;
+    functionName: string;
+    httpMethod: string;
+    metadata: IOperationMetadata;
+    errors: IReflectOperationError[];
+  }
+
+  export const analyze = (
+    ctx: IContext,
+  ): IReflectHttpOperationSuccess | null => {
+    const errors: Array<string | IOperationMetadata.IError> = [];
+    const report = () => {
+      ctx.errors.push({
+        file: ctx.controller.file,
+        class: ctx.controller.class.name,
+        function: ctx.functionName,
+        from: "return",
+        contents: errors,
+      });
+      return null;
+    };
+
+    const encrypted: boolean = hasInterceptor({
+      name: "EncryptedRouteInterceptor",
+      function: ctx.function,
+    });
+    const contentType: string | null = encrypted
+      ? "text/plain"
+      : hasInterceptor({
+            name: "TypedQueryRouteInterceptor",
+            function: ctx.function,
+          })
+        ? "application/x-www-form-urlencoded"
+        : Reflect.getMetadata(HEADERS_METADATA, ctx.function)?.find(
+            (h: Record<string, string>) =>
+              typeof h?.name === "string" &&
+              typeof h?.value === "string" &&
+              h.name.toLowerCase() === "content-type",
+          )?.value ?? (ctx.httpMethod === "HEAD" ? null : "application/json");
+
+    const schema =
+      contentType === "application/json"
+        ? ctx.metadata.success.primitive
+        : ctx.metadata.success.resolved;
+    if (schema.success === false) errors.push(...schema.errors);
+    if (ctx.httpMethod === "HEAD" && contentType !== null)
+      errors.push(`HEAD method must not have a content type.`);
+    if (
+      typia.is<IReflectHttpOperationSuccess["contentType"]>(contentType) ===
+      false
+    )
+      errors.push(
+        `@nestia/sdk does not support ${JSON.stringify(contentType)} content type.`,
+      );
+
+    if (errors.length) return report();
+    else if (
+      ctx.metadata.success.type === null ||
+      schema.success === false ||
+      !typia.is<IReflectHttpOperationSuccess["contentType"]>(contentType)
+    )
+      return null;
+    return {
+      contentType: contentType,
+      encrypted,
+      status:
+        getStatus(ctx.function) ?? (ctx.httpMethod === "POST" ? 201 : 200),
+      type: ctx.metadata.success.type,
+      ...schema.data,
+      validate:
+        contentType === "application/json" || encrypted === true
+          ? JsonMetadataFactory.validate
+          : contentType === "application/x-www-form-urlencoded"
+            ? HttpQueryProgrammer.validate
+            : contentType === "text/plain"
+              ? TextPlainValidator.validate
+              : (meta) =>
+                  meta.size()
+                    ? ["HEAD method must not have any return value."]
+                    : [],
+    };
+  };
+
+  const getStatus = (func: Function): number | null => {
+    const text = Reflect.getMetadata(HTTP_CODE_METADATA, func);
+    if (text === undefined) return null;
+    const value: number = Number(text);
+    return isNaN(value) ? null : value;
+  };
+
+  const hasInterceptor = (props: {
+    name: string;
+    function: Function;
+  }): boolean => {
+    const meta = Reflect.getMetadata(INTERCEPTORS_METADATA, props.function);
+    if (Array.isArray(meta) === false) return false;
+    return meta.some((elem) => elem?.constructor?.name === props.name);
+  };
+}

package/src/analyses/ReflectMetadataAnalyzer.ts

@@ -2,27 +2,10 @@ 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[] => {
+  export const paths = (target: Function): string[] => {
     const value: string | string[] = Reflect.getMetadata(PATH_METADATA, target);
     if (typeof value === "string") return [value];
     else if (value.length === 0) return [""];