@nestia/core 2.5.8 → 2.5.9

package/src/decorators/internal/validate_request_query.ts

@@ -1,71 +1,71 @@
-import { BadRequestException } from "@nestjs/common";
-import typia, { IValidation, TypeGuardError } from "typia";
-
-import { IRequestQueryValidator } from "../../options/IRequestQueryValidator";
-import { NoTransformConfigureError } from "./NoTransformConfigureError";
-
-/**
- * @internal
- */
-export const validate_request_query = <T>(
-  validator?: IRequestQueryValidator<T>,
-) => {
-  if (!validator) return () => NoTransformConfigureError("TypedQuery");
-  else if (validator.type === "assert") return assert(validator.assert);
-  else if (validator.type === "is") return is(validator.is);
-  else if (validator.type === "validate") return validate(validator.validate);
-  return () =>
-    new Error(`Error on nestia.core.TypedQuery(): invalid typed validator.`);
-};
-
-/**
- * @internal
- */
-const assert =
-  <T>(closure: (input: URLSearchParams) => T) =>
-  (input: URLSearchParams): T | BadRequestException => {
-    try {
-      return closure(input);
-    } catch (exp) {
-      if (typia.is<TypeGuardError>(exp)) {
-        return new BadRequestException({
-          path: exp.path,
-          reason: exp.message,
-          expected: exp.expected,
-          value: exp.value,
-          message: MESSAGE,
-        });
-      }
-      throw exp;
-    }
-  };
-
-/**
- * @internal
- */
-const is =
-  <T>(closure: (input: URLSearchParams) => T | null) =>
-  (input: URLSearchParams): T | BadRequestException => {
-    const result: T | null = closure(input);
-    return result !== null ? result : new BadRequestException(MESSAGE);
-  };
-
-/**
- * @internal
- */
-const validate =
-  <T>(closure: (input: URLSearchParams) => IValidation<T>) =>
-  (input: URLSearchParams): T | BadRequestException => {
-    const result: IValidation<T> = closure(input);
-    return result.success
-      ? result.data
-      : new BadRequestException({
-          errors: result.errors,
-          message: MESSAGE,
-        });
-  };
-
-/**
- * @internal
- */
-const MESSAGE = "Request query data is not following the promised type.";
+import { BadRequestException } from "@nestjs/common";
+import typia, { IValidation, TypeGuardError } from "typia";
+
+import { IRequestQueryValidator } from "../../options/IRequestQueryValidator";
+import { NoTransformConfigureError } from "./NoTransformConfigureError";
+
+/**
+ * @internal
+ */
+export const validate_request_query = <T>(
+  validator?: IRequestQueryValidator<T>,
+) => {
+  if (!validator) return () => NoTransformConfigureError("TypedQuery");
+  else if (validator.type === "assert") return assert(validator.assert);
+  else if (validator.type === "is") return is(validator.is);
+  else if (validator.type === "validate") return validate(validator.validate);
+  return () =>
+    new Error(`Error on nestia.core.TypedQuery(): invalid typed validator.`);
+};
+
+/**
+ * @internal
+ */
+const assert =
+  <T>(closure: (input: URLSearchParams) => T) =>
+  (input: URLSearchParams): T | BadRequestException => {
+    try {
+      return closure(input);
+    } catch (exp) {
+      if (typia.is<TypeGuardError>(exp)) {
+        return new BadRequestException({
+          path: exp.path,
+          reason: exp.message,
+          expected: exp.expected,
+          value: exp.value,
+          message: MESSAGE,
+        });
+      }
+      throw exp;
+    }
+  };
+
+/**
+ * @internal
+ */
+const is =
+  <T>(closure: (input: URLSearchParams) => T | null) =>
+  (input: URLSearchParams): T | BadRequestException => {
+    const result: T | null = closure(input);
+    return result !== null ? result : new BadRequestException(MESSAGE);
+  };
+
+/**
+ * @internal
+ */
+const validate =
+  <T>(closure: (input: URLSearchParams) => IValidation<T>) =>
+  (input: URLSearchParams): T | BadRequestException => {
+    const result: IValidation<T> = closure(input);
+    return result.success
+      ? result.data
+      : new BadRequestException({
+          errors: result.errors,
+          message: MESSAGE,
+        });
+  };
+
+/**
+ * @internal
+ */
+const MESSAGE = "Request query data is not following the promised type.";

package/src/module.ts

@@ -5,6 +5,7 @@ export * from "./decorators/EncryptedModule";
 export * from "./decorators/EncryptedRoute";
 export * from "./utils/ExceptionManager";
 export * from "./decorators/PlainBody";
+export * from "./decorators/SwaggerCustomizer";
 export * from "./decorators/TypedBody";
 export * from "./decorators/TypedException";
 export * from "./decorators/TypedHeaders";

package/src/structures/ISwagger.ts

@@ -0,0 +1,91 @@
+import { ISwaggerComponents } from "./ISwaggerComponents";
+import { ISwaggerInfo } from "./ISwaggerInfo";
+import { ISwaggerRoute } from "./ISwaggerRoute";
+
+/**
+ * Swagger Document.
+ *
+ * `ISwagger` is a data structure representing content of `swagger.json` file
+ * generated by Nestia. Note that, this is not an universal structure, but a dedicated
+ * structure only for Nestia.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export interface ISwagger {
+  /**
+   * The version of the OpenAPI document.
+   *
+   * Nestia always generate OpenAPI 3.0.x document.
+   */
+  openapi: `3.0.${number}`;
+
+  /**
+   * List of servers that provide the API.
+   */
+  servers: ISwagger.IServer[];
+
+  /**
+   * Information about the API.
+   */
+  info: ISwaggerInfo;
+
+  /**
+   * The available paths and operations for the API.
+   *
+   * The 1st key is the path, and the 2nd key is the HTTP method.
+   */
+  paths: Record<string, Record<string, ISwaggerRoute>>;
+
+  /**
+   * An object to hold reusable data structures.
+   *
+   * It stores both DTO schemas and security schemes.
+   *
+   * For reference, `nestia` defines every object and alias types as reusable DTO
+   * schemas. The alias type means that defined by `type` keyword in TypeScript.
+   */
+  components: ISwaggerComponents;
+
+  // /**
+  //  * A declaration of which security mechanisms can be used across the API.
+  //  *
+  //  * When this property be configured, it would be overwritten in every API routes.
+  //  *
+  //  * For reference, key means the name of security scheme and value means the `scopes`.
+  //  * The `scopes` can be used only when target security scheme is `oauth2` type,
+  //  * especially for {@link ISwaggerSecurityScheme.IOAuth2.IFlow.scopes} property.
+  //  */
+  // security?: Record<string, string[]>[];
+}
+export namespace ISwagger {
+  /**
+   * Remote server definition.
+   */
+  export interface IServer {
+    /**
+     * A URL to the target host.
+     *
+     * @format uri
+     */
+    url: string;
+
+    /**
+     * An optional string describing the target server.
+     */
+    description?: string;
+  }
+
+  export interface IExternalDocs {
+    /**
+     * The URL for target documentation.
+     *
+     * @format uri
+     */
+    url: string;
+
+    /**
+     * A short description of the target documentation.
+     */
+    description?: string;
+  }
+}

package/src/structures/ISwaggerComponents.ts

@@ -0,0 +1,29 @@
+import { IJsonComponents } from "typia";
+
+import { ISwaggerSecurityScheme } from "./ISwaggerSecurityScheme";
+
+/**
+ * Reusable components in Swagger.
+ *
+ * `ISwaggerComponents` is a data structure representing content of `components` object
+ * in `swagger.json` file generated by Nestia. Note that, this is not an universal
+ * structure, but a dedicated structure only for Nestia.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export interface ISwaggerComponents {
+  /**
+   * An object to hold reusable DTO schemas.
+   *
+   * For reference, `nestia` stores every object and alias types as reusable DTO
+   * schemas. The alias type means that defined by `type` keyword in TypeScript.
+   */
+  schemas?: Record<string, IJsonComponents.IAlias>;
+
+  /**
+   * An object to hold reusable security schemes.
+   *
+   * This property be configured by user in `nestia.config.ts` file.
+   */
+  securitySchemes?: Record<string, ISwaggerSecurityScheme>;
+}

package/src/structures/ISwaggerInfo.ts

@@ -0,0 +1,80 @@
+/**
+ * Information about the API.
+ *
+ * @author Samchon
+ */
+export interface ISwaggerInfo {
+  /**
+   * The title of the API.
+   */
+  title: string;
+
+  /**
+   * A short description of the API.
+   */
+  description?: string;
+
+  /**
+   * A URL to the Terms of Service for the API.
+   *
+   * @format uri
+   */
+  termsOfService?: string;
+
+  /**
+   * The contact information for the exposed API.
+   */
+  contact?: ISwaggerInfo.IContact;
+
+  /**
+   * The license information for the exposed API.
+   */
+  license?: ISwaggerInfo.ILicense;
+
+  /**
+   * Version of the API.
+   */
+  version: string;
+}
+export namespace ISwaggerInfo {
+  /**
+   * Contact information for the exposed API.
+   */
+  export interface IContact {
+    /**
+     * The identifying name of the contact person/organization.
+     */
+    name?: string;
+
+    /**
+     * The URL pointing to the contact information.
+     *
+     * @format uri
+     */
+    url?: string;
+
+    /**
+     * The email address of the contact person/organization.
+     *
+     * @format email
+     */
+    email?: string;
+  }
+
+  /**
+   * License information for the exposed API.
+   */
+  export interface ILicense {
+    /**
+     * The license name used for the API.
+     */
+    name: string;
+
+    /**
+     * A URL to the license used for the API.
+     *
+     * @format uri
+     */
+    url?: string;
+  }
+}

package/src/structures/ISwaggerRoute.ts

@@ -0,0 +1,50 @@
+import { IJsonSchema } from "typia";
+
+export interface ISwaggerRoute {
+  deprecated?: boolean;
+  security?: Record<string, string[]>[];
+  operationId?: string;
+  tags: string[];
+  parameters: ISwaggerRoute.IParameter[];
+  requestBody?: ISwaggerRoute.IRequestBody;
+  responses: ISwaggerRoute.IResponseBody;
+  summary?: string;
+  description?: string;
+}
+export namespace ISwaggerRoute {
+  export interface IParameter {
+    name: string;
+    in: string;
+    schema: IJsonSchema;
+    required: boolean;
+    description?: string;
+  }
+  export interface IRequestBody {
+    description?: string;
+    content: IContent;
+    required: true;
+    "x-nestia-encrypted"?: boolean;
+  }
+  export type IResponseBody = Record<
+    string,
+    {
+      description: string;
+      content?: IContent;
+      "x-nestia-encrypted"?: boolean;
+    }
+  >;
+  export interface IContent {
+    "application/x-www-form-urlencoded"?: {
+      schema: IJsonSchema;
+    };
+    "application/json"?: {
+      schema: IJsonSchema;
+    };
+    "text/plain"?: {
+      schema: IJsonSchema;
+    };
+    "multipart/form-data"?: {
+      schema: IJsonSchema;
+    };
+  }
+}

package/src/structures/ISwaggerSecurityScheme.ts

@@ -0,0 +1,65 @@
+/**
+ * Security scheme of Swagger Documents.
+ *
+ * `ISwaggerSecurityScheme` is a data structure representing content of
+ * `securitySchemes` in `swagger.json` file. It is composed with 5 types of security
+ * schemes as an union type like below.
+ *
+ * @reference https://swagger.io/specification/#security-scheme-object
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export type ISwaggerSecurityScheme =
+  | ISwaggerSecurityScheme.IHttpBasic
+  | ISwaggerSecurityScheme.IHttpBearer
+  | ISwaggerSecurityScheme.IApiKey
+  | ISwaggerSecurityScheme.IOpenId
+  | ISwaggerSecurityScheme.IOAuth2;
+export namespace ISwaggerSecurityScheme {
+  export interface IHttpBasic {
+    type: "http";
+    scheme: "basic";
+  }
+  export interface IHttpBearer {
+    type: "http";
+    scheme: "bearer";
+    bearerFormat?: string;
+  }
+  export interface IApiKey {
+    type: "apiKey";
+
+    /**
+     * @default header
+     */
+    in?: "header" | "query" | "cookie";
+
+    /**
+     * @default Authorization
+     */
+    name?: string;
+  }
+
+  export interface IOpenId {
+    type: "openIdConnect";
+    openIdConnectUrl: string;
+  }
+
+  export interface IOAuth2 {
+    type: "oauth2";
+    flows: IOAuth2.IFlowSet;
+    description?: string;
+  }
+  export namespace IOAuth2 {
+    export interface IFlowSet {
+      authorizationCode?: IFlow;
+      implicit?: Omit<IFlow, "tokenUrl">;
+      password?: Omit<IFlow, "authorizationUrl">;
+      clientCredentials?: Omit<IFlow, "authorizationUrl">;
+    }
+    export interface IFlow {
+      authorizationUrl: string;
+      tokenUrl: string;
+      refreshUrl: string;
+      scopes?: Record<string, string>;
+    }
+  }
+}

package/src/transformers/NodeTransformer.ts

@@ -1,16 +1,16 @@
-import ts from "typescript";
-
-import { INestiaTransformProject } from "../options/INestiaTransformProject";
-import { MethodTransformer } from "./MethodTransformer";
-import { ParameterTransformer } from "./ParameterTransformer";
-
-export namespace NodeTransformer {
-  export const transform =
-    (project: INestiaTransformProject) =>
-    (node: ts.Node): ts.Node =>
-      ts.isMethodDeclaration(node)
-        ? MethodTransformer.transform(project)(node)
-        : ts.isParameter(node)
-          ? ParameterTransformer.transform(project)(node)
-          : node;
-}
+import ts from "typescript";
+
+import { INestiaTransformProject } from "../options/INestiaTransformProject";
+import { MethodTransformer } from "./MethodTransformer";
+import { ParameterTransformer } from "./ParameterTransformer";
+
+export namespace NodeTransformer {
+  export const transform =
+    (project: INestiaTransformProject) =>
+    (node: ts.Node): ts.Node =>
+      ts.isMethodDeclaration(node)
+        ? MethodTransformer.transform(project)(node)
+        : ts.isParameter(node)
+          ? ParameterTransformer.transform(project)(node)
+          : node;
+}

package/src/transformers/TypedExceptionTransformer.ts

@@ -1,48 +1,48 @@
-import path from "path";
-import ts from "typescript";
-
-import { INestiaTransformProject } from "../options/INestiaTransformProject";
-import { TypedExceptionProgrammer } from "../programmers/TypedExceptionProgrammer";
-
-export namespace TypedExceptionTransformer {
-  export const transform =
-    (project: INestiaTransformProject) =>
-    (decorator: ts.Decorator): ts.Decorator => {
-      if (!ts.isCallExpression(decorator.expression)) return decorator;
-
-      // CHECK SIGNATURE
-      const signature: ts.Signature | undefined =
-        project.checker.getResolvedSignature(decorator.expression);
-      if (!signature || !signature.declaration) return decorator;
-
-      // CHECK TO BE TRANSFORMED
-      const done: boolean = (() => {
-        // CHECK FILENAME
-        const location: string = path.resolve(
-          signature.declaration.getSourceFile().fileName,
-        );
-        if (location.indexOf(LIB_PATH) === -1 && location !== SRC_PATH)
-          return false;
-
-        // CHECK DUPLICATED
-        return decorator.expression.arguments.length !== 3;
-      })();
-      if (done === false) return decorator;
-
-      // DO TRANSFORM
-      return ts.factory.createDecorator(
-        TypedExceptionProgrammer.generate(project)(decorator.expression),
-      );
-    };
-
-  const LIB_PATH = path.join(
-    "@nestia",
-    "core",
-    "lib",
-    "decorators",
-    `TypedException.d.ts`,
-  );
-  const SRC_PATH = path.resolve(
-    path.join(__dirname, "..", "decorators", `TypedException.ts`),
-  );
-}
+import path from "path";
+import ts from "typescript";
+
+import { INestiaTransformProject } from "../options/INestiaTransformProject";
+import { TypedExceptionProgrammer } from "../programmers/TypedExceptionProgrammer";
+
+export namespace TypedExceptionTransformer {
+  export const transform =
+    (project: INestiaTransformProject) =>
+    (decorator: ts.Decorator): ts.Decorator => {
+      if (!ts.isCallExpression(decorator.expression)) return decorator;
+
+      // CHECK SIGNATURE
+      const signature: ts.Signature | undefined =
+        project.checker.getResolvedSignature(decorator.expression);
+      if (!signature || !signature.declaration) return decorator;
+
+      // CHECK TO BE TRANSFORMED
+      const done: boolean = (() => {
+        // CHECK FILENAME
+        const location: string = path.resolve(
+          signature.declaration.getSourceFile().fileName,
+        );
+        if (location.indexOf(LIB_PATH) === -1 && location !== SRC_PATH)
+          return false;
+
+        // CHECK DUPLICATED
+        return decorator.expression.arguments.length !== 3;
+      })();
+      if (done === false) return decorator;
+
+      // DO TRANSFORM
+      return ts.factory.createDecorator(
+        TypedExceptionProgrammer.generate(project)(decorator.expression),
+      );
+    };
+
+  const LIB_PATH = path.join(
+    "@nestia",
+    "core",
+    "lib",
+    "decorators",
+    `TypedException.d.ts`,
+  );
+  const SRC_PATH = path.resolve(
+    path.join(__dirname, "..", "decorators", `TypedException.ts`),
+  );
+}