@nestia/core 2.5.8 → 2.5.9-dev.20240223

package/src/decorators/internal/load_controller.ts

@@ -1,51 +1,51 @@
-import is_ts_node from "detect-ts-node";
-
-import { Creator } from "../../typings/Creator";
-import { SourceFinder } from "../../utils/SourceFinder";
-
-/**
- * @internal
- */
-export const load_controllers = async (
-  path: string | string[] | { include: string[]; exclude?: string[] },
-): Promise<Creator<object>[]> => {
-  const sources: string[] = await SourceFinder.find({
-    include: Array.isArray(path)
-      ? path
-      : typeof path === "object"
-        ? path.include
-        : [path],
-    exclude:
-      typeof path === "object" && !Array.isArray(path)
-        ? path.exclude ?? []
-        : [],
-    filter:
-      EXTENSION === "ts"
-        ? (file) =>
-            file.substring(file.length - 3) === ".ts" &&
-            file.substring(file.length - 5) !== ".d.ts"
-        : (flle) => flle.substring(flle.length - 3) === ".js",
-  });
-  return mount(sources);
-};
-
-/**
- * @internal
- */
-async function mount(sources: string[]): Promise<any[]> {
-  const controllers: any[] = [];
-  for (const file of sources) {
-    const external: any = await import(file);
-    for (const key in external) {
-      const instance: Creator<object> = external[key];
-      if (Reflect.getMetadata("path", instance) !== undefined)
-        controllers.push(instance);
-    }
-  }
-  return controllers;
-}
-
-/**
- * @internal
- */
-const EXTENSION = is_ts_node ? "ts" : "js";
+import is_ts_node from "detect-ts-node";
+
+import { Creator } from "../../typings/Creator";
+import { SourceFinder } from "../../utils/SourceFinder";
+
+/**
+ * @internal
+ */
+export const load_controllers = async (
+  path: string | string[] | { include: string[]; exclude?: string[] },
+): Promise<Creator<object>[]> => {
+  const sources: string[] = await SourceFinder.find({
+    include: Array.isArray(path)
+      ? path
+      : typeof path === "object"
+        ? path.include
+        : [path],
+    exclude:
+      typeof path === "object" && !Array.isArray(path)
+        ? path.exclude ?? []
+        : [],
+    filter:
+      EXTENSION === "ts"
+        ? (file) =>
+            file.substring(file.length - 3) === ".ts" &&
+            file.substring(file.length - 5) !== ".d.ts"
+        : (flle) => flle.substring(flle.length - 3) === ".js",
+  });
+  return mount(sources);
+};
+
+/**
+ * @internal
+ */
+async function mount(sources: string[]): Promise<any[]> {
+  const controllers: any[] = [];
+  for (const file of sources) {
+    const external: any = await import(file);
+    for (const key in external) {
+      const instance: Creator<object> = external[key];
+      if (Reflect.getMetadata("path", instance) !== undefined)
+        controllers.push(instance);
+    }
+  }
+  return controllers;
+}
+
+/**
+ * @internal
+ */
+const EXTENSION = is_ts_node ? "ts" : "js";

package/src/decorators/internal/validate_request_body.ts

@@ -1,72 +1,72 @@
-import { BadRequestException } from "@nestjs/common";
-import typia, { IValidation, TypeGuardError } from "typia";
-
-import { IRequestBodyValidator } from "../../options/IRequestBodyValidator";
-import { NoTransformConfigureError } from "./NoTransformConfigureError";
-
-/**
- * @internal
- */
-export const validate_request_body =
-  (method: string) =>
-  <T>(validator?: IRequestBodyValidator<T>) => {
-    if (!validator) return () => NoTransformConfigureError(method);
-    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.${method}(): invalid typed validator.`);
-  };
-
-/**
- * @internal
- */
-const assert =
-  <T>(closure: (data: T) => T) =>
-  (input: T) => {
-    try {
-      closure(input);
-      return null;
-    } 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: (data: T) => boolean) =>
-  (input: T) => {
-    const success: boolean = closure(input);
-    return success ? null : new BadRequestException(MESSAGE);
-  };
-
-/**
- * @internal
- */
-const validate =
-  <T>(closure: (data: T) => IValidation<T>) =>
-  (input: T) => {
-    const result: IValidation<T> = closure(input);
-    return result.success
-      ? null
-      : new BadRequestException({
-          errors: result.errors,
-          message: MESSAGE,
-        });
-  };
-
-/**
- * @internal
- */
-const MESSAGE = "Request body data is not following the promised type.";
+import { BadRequestException } from "@nestjs/common";
+import typia, { IValidation, TypeGuardError } from "typia";
+
+import { IRequestBodyValidator } from "../../options/IRequestBodyValidator";
+import { NoTransformConfigureError } from "./NoTransformConfigureError";
+
+/**
+ * @internal
+ */
+export const validate_request_body =
+  (method: string) =>
+  <T>(validator?: IRequestBodyValidator<T>) => {
+    if (!validator) return () => NoTransformConfigureError(method);
+    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.${method}(): invalid typed validator.`);
+  };
+
+/**
+ * @internal
+ */
+const assert =
+  <T>(closure: (data: T) => T) =>
+  (input: T) => {
+    try {
+      closure(input);
+      return null;
+    } 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: (data: T) => boolean) =>
+  (input: T) => {
+    const success: boolean = closure(input);
+    return success ? null : new BadRequestException(MESSAGE);
+  };
+
+/**
+ * @internal
+ */
+const validate =
+  <T>(closure: (data: T) => IValidation<T>) =>
+  (input: T) => {
+    const result: IValidation<T> = closure(input);
+    return result.success
+      ? null
+      : new BadRequestException({
+          errors: result.errors,
+          message: MESSAGE,
+        });
+  };
+
+/**
+ * @internal
+ */
+const MESSAGE = "Request body data is not following the promised type.";

package/src/decorators/internal/validate_request_headers.ts

@@ -1,83 +1,83 @@
-import { BadRequestException } from "@nestjs/common";
-import typia, { IValidation, TypeGuardError } from "typia";
-
-import { IRequestHeadersValidator } from "../../options/IRequestHeadersValidator";
-import { NoTransformConfigureError } from "./NoTransformConfigureError";
-
-/**
- * @internal
- */
-export const validate_request_headers = <T>(
-  validator?: IRequestHeadersValidator<T>,
-) => {
-  if (!validator) return () => NoTransformConfigureError("TypedHeaders");
-  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.TypedHeaders(): invalid typed validator.`);
-};
-
-/**
- * @internal
- */
-const assert =
-  <T>(closure: (input: Record<string, string | string[] | undefined>) => T) =>
-  (
-    input: Record<string, string | string[] | undefined>,
-  ): 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: Record<string, string | string[] | undefined>) => T | null,
-  ) =>
-  (
-    input: Record<string, string | string[] | undefined>,
-  ): T | BadRequestException => {
-    const result: T | null = closure(input);
-    return result !== null ? result : new BadRequestException(MESSAGE);
-  };
-
-/**
- * @internal
- */
-const validate =
-  <T>(
-    closure: (
-      input: Record<string, string | string[] | undefined>,
-    ) => IValidation<T>,
-  ) =>
-  (
-    input: Record<string, string | string[] | undefined>,
-  ): T | BadRequestException => {
-    const result: IValidation<T> = closure(input);
-    return result.success
-      ? result.data
-      : new BadRequestException({
-          errors: result.errors,
-          message: MESSAGE,
-        });
-  };
-
-/**
- * @internal
- */
-const MESSAGE = "Request headers data is not following the promised type.";
+import { BadRequestException } from "@nestjs/common";
+import typia, { IValidation, TypeGuardError } from "typia";
+
+import { IRequestHeadersValidator } from "../../options/IRequestHeadersValidator";
+import { NoTransformConfigureError } from "./NoTransformConfigureError";
+
+/**
+ * @internal
+ */
+export const validate_request_headers = <T>(
+  validator?: IRequestHeadersValidator<T>,
+) => {
+  if (!validator) return () => NoTransformConfigureError("TypedHeaders");
+  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.TypedHeaders(): invalid typed validator.`);
+};
+
+/**
+ * @internal
+ */
+const assert =
+  <T>(closure: (input: Record<string, string | string[] | undefined>) => T) =>
+  (
+    input: Record<string, string | string[] | undefined>,
+  ): 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: Record<string, string | string[] | undefined>) => T | null,
+  ) =>
+  (
+    input: Record<string, string | string[] | undefined>,
+  ): T | BadRequestException => {
+    const result: T | null = closure(input);
+    return result !== null ? result : new BadRequestException(MESSAGE);
+  };
+
+/**
+ * @internal
+ */
+const validate =
+  <T>(
+    closure: (
+      input: Record<string, string | string[] | undefined>,
+    ) => IValidation<T>,
+  ) =>
+  (
+    input: Record<string, string | string[] | undefined>,
+  ): T | BadRequestException => {
+    const result: IValidation<T> = closure(input);
+    return result.success
+      ? result.data
+      : new BadRequestException({
+          errors: result.errors,
+          message: MESSAGE,
+        });
+  };
+
+/**
+ * @internal
+ */
+const MESSAGE = "Request headers data is not following the promised type.";

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;
+  }
+}