@nestia/core 3.0.0-dev.20231209 → 3.0.0

package/src/decorators/PlainBody.ts

@@ -1,72 +1,75 @@
-import {
-  BadRequestException,
-  ExecutionContext,
-  createParamDecorator,
-} from "@nestjs/common";
-import type express from "express";
-import type { FastifyRequest } from "fastify";
-import { assert } from "typia";
-
-import { get_text_body } from "./internal/get_text_body";
-import { validate_request_body } from "./internal/validate_request_body";
-
-/**
- * Plain body decorator.
- *
- * `PlainBody` is a decorator function getting full body text from the HTTP request.
- *
- * If you adjust the regular {@link Body} decorator function to the body parameter,
- * you can't get the full body text because the {@link Body} tries to convert the
- * body text to JSON object. Therefore, `@nestia/core` provides this `PlainBody`
- * decorator function to get the full body text.
- *
- * ```typescript
- * \@TypedRoute.Post("memo")
- * public store
- *     (
- *         \@PlainBody() body: string
- *     ): void;
- * ```
- *
- * @return Parameter decorator
- * @author Jeongho Nam - https://github.com/samchon
- */
-export function PlainBody(): ParameterDecorator;
-
-/**
- * @internal
- */
-export function PlainBody(
-  assert?: (input: unknown) => string,
-): ParameterDecorator {
-  const checker = assert
-    ? validate_request_body("PlainBody")({
-        type: "assert",
-        assert,
-      })
-    : null;
-  return createParamDecorator(async function PlainBody(
-    _data: any,
-    context: ExecutionContext,
-  ) {
-    const request: express.Request | FastifyRequest = context
-      .switchToHttp()
-      .getRequest();
-    if (!isTextPlain(request.headers["content-type"]))
-      throw new BadRequestException(`Request body type is not "text/plain".`);
-    const value: string = await get_text_body(request);
-    if (checker) {
-      const error: Error | null = checker(value);
-      if (error !== null) throw error;
-    }
-    return value;
-  })();
-}
-Object.assign(PlainBody, assert);
-
-const isTextPlain = (text?: string): boolean =>
-  text !== undefined &&
-  text
-    .split(";")
-    .map((str) => str.trim())
-    .some((str) => str === "text/plain");
+import {
+  BadRequestException,
+  ExecutionContext,
+  createParamDecorator,
+} from "@nestjs/common";
+import type express from "express";
+import type { FastifyRequest } from "fastify";
+import { assert } from "typia";
+
+import { get_text_body } from "./internal/get_text_body";
+import { validate_request_body } from "./internal/validate_request_body";
+
+/**
+ * Plain body decorator.
+ *
+ * `PlainBody` is a decorator function getting full body text from the HTTP request.
+ *
+ * If you adjust the regular {@link Body} decorator function to the body parameter,
+ * you can't get the full body text because the {@link Body} tries to convert the
+ * body text to JSON object. Therefore, `@nestia/core` provides this `PlainBody`
+ * decorator function to get the full body text.
+ *
+ * ```typescript
+ * \@TypedRoute.Post("memo")
+ * public store
+ *     (
+ *         \@PlainBody() body: string
+ *     ): void;
+ * ```
+ *
+ * @return Parameter decorator
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export function PlainBody(): ParameterDecorator;
+
+/**
+ * @internal
+ */
+export function PlainBody(
+  assert?: (input: unknown) => string,
+): ParameterDecorator {
+  const checker = assert
+    ? validate_request_body("PlainBody")({
+        type: "assert",
+        assert,
+      })
+    : null;
+  return createParamDecorator(async function PlainBody(
+    _data: any,
+    context: ExecutionContext,
+  ) {
+    const request: express.Request | FastifyRequest = context
+      .switchToHttp()
+      .getRequest();
+    if (!isTextPlain(request.headers["content-type"]))
+      throw new BadRequestException(`Request body type is not "text/plain".`);
+    const value: string = await get_text_body(request);
+    if (checker) {
+      const error: Error | null = checker(value);
+      if (error !== null) throw error;
+    }
+    return value;
+  })();
+}
+Object.assign(PlainBody, assert);
+
+/**
+ * @internal
+ */
+const isTextPlain = (text?: string): boolean =>
+  text !== undefined &&
+  text
+    .split(";")
+    .map((str) => str.trim())
+    .some((str) => str === "text/plain");

package/src/decorators/SwaggerCustomizer.ts

@@ -0,0 +1,115 @@
+import { OpenApi } from "@samchon/openapi";
+
+/**
+ * Swagger customization decorator.
+ *
+ * `SwaggerCustomizer` is a method decorator function which can used for
+ * customizing the swagger data with `npx nestia swagger` command. Furthermore,
+ * it is possible to add plugin properties starting with `x-` characters.
+ *
+ * In other words, this decorator function does not affect to the runtime,
+ * but only for the swagger data customization.
+ *
+ * @param closure Callback function which can customize the swagger data
+ * @returns Method decorator
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export function SwaggerCustomizer(
+  closure: (props: SwaggerCustomizer.IProps) => unknown,
+): MethodDecorator {
+  return function SwaggerCustomizer(
+    target: Object,
+    propertyKey: string | symbol,
+    descriptor: TypedPropertyDescriptor<any>,
+  ) {
+    const array: Array<(props: SwaggerCustomizer.IProps) => unknown> = (() => {
+      if (Reflect.hasMetadata("nestia/SwaggerCustomizer", target, propertyKey))
+        return Reflect.getMetadata(
+          "nestia/SwaggerCustomizer",
+          target,
+          propertyKey,
+        );
+      const array: Array<(props: SwaggerCustomizer.IProps) => unknown> = [];
+      Reflect.defineMetadata(
+        "nestia/SwaggerCustomizer",
+        array,
+        target,
+        propertyKey,
+      );
+      return array;
+    })();
+    array.push(closure);
+    return descriptor;
+  };
+}
+export namespace SwaggerCustomizer {
+  /**
+   * Properties for the `SwaggerCustomizer` decorator.
+   *
+   * `SwaggerCustomizer.IProps` is a type for the `closure` parameter of the
+   * `SwaggerCustomizer` decorator. It's a callback function which can customize
+   * the swagger data.
+   */
+  export interface IProps {
+    /**
+     * Swagger data.
+     */
+    swagger: OpenApi.IDocument;
+
+    /**
+     * Method of the route.
+     */
+    method: string;
+
+    /**
+     * Path of the route.
+     */
+    path: string;
+
+    /**
+     * Route data.
+     */
+    route: OpenApi.IOperation;
+
+    /**
+     * Get neighbor endpoint data through the controller method.
+     *
+     * @param func Controller method to find the neighbor endpoint
+     * @returns Neighbor endpoint data
+     */
+    at(func: Function): ISwaggerEndpoint | undefined;
+
+    /**
+     * Get neighbor route data.
+     *
+     * @param accessor Accessor for getting neighbor route data
+     * @returns Neighbor route data
+     */
+    get(accessor: IAccessor): OpenApi.IOperation | undefined;
+  }
+
+  /**
+   * Accessor for getting neighbor route data.
+   */
+  export interface IAccessor {
+    /**
+     * Path of the neighbor route.
+     */
+    path: string;
+
+    /**
+     * Method of the neighbor route.
+     */
+    method: string;
+  }
+
+  /**
+   * Endpoint info of the route.
+   */
+  export interface ISwaggerEndpoint extends IAccessor {
+    /**
+     * Route data.
+     */
+    route: OpenApi.IOperation;
+  }
+}

package/src/decorators/TypedBody.ts

@@ -1,59 +1,62 @@
-import {
-  BadRequestException,
-  ExecutionContext,
-  createParamDecorator,
-} from "@nestjs/common";
-import type express from "express";
-import type { FastifyRequest } from "fastify";
-import { assert, is, misc, validate } from "typia";
-
-import { IRequestBodyValidator } from "../options/IRequestBodyValidator";
-import { validate_request_body } from "./internal/validate_request_body";
-
-/**
- * Type safe body decorator.
- *
- * `TypedBody` is a decorator function getting `application/json` typed data from
- * request body. Also, it validates the request body data type through
- * [typia](https://github.com/samchon/typia) and the validation speed is
- * maximum 20,000x times faster than `class-validator`.
- *
- * For reference, when the request body data is not following the promised type `T`,
- * `BadRequestException` error (status code: 400) would be thrown.
- *
- * @param validator Custom validator if required. Default is `typia.assert()`
- * @author Jeongho Nam - https://github.com/samchon
- */
-export function TypedBody<T>(
-  validator?: IRequestBodyValidator<T>,
-): ParameterDecorator {
-  const checker = validate_request_body("TypedBody")(validator);
-  return createParamDecorator(function TypedBody(
-    _unknown: any,
-    context: ExecutionContext,
-  ) {
-    const request: express.Request | FastifyRequest = context
-      .switchToHttp()
-      .getRequest();
-    if (isApplicationJson(request.headers["content-type"]) === false)
-      throw new BadRequestException(
-        `Request body type is not "application/json".`,
-      );
-
-    const error: Error | null = checker(request.body);
-    if (error !== null) throw error;
-    return request.body;
-  })();
-}
-
-Object.assign(TypedBody, misc.clone);
-Object.assign(TypedBody, is);
-Object.assign(TypedBody, assert);
-Object.assign(TypedBody, validate);
-
-const isApplicationJson = (text?: string): boolean =>
-  text !== undefined &&
-  text
-    .split(";")
-    .map((str) => str.trim())
-    .some((str) => str === "application/json");
+import {
+  BadRequestException,
+  ExecutionContext,
+  createParamDecorator,
+} from "@nestjs/common";
+import type express from "express";
+import type { FastifyRequest } from "fastify";
+import { assert, is, misc, validate } from "typia";
+
+import { IRequestBodyValidator } from "../options/IRequestBodyValidator";
+import { validate_request_body } from "./internal/validate_request_body";
+
+/**
+ * Type safe body decorator.
+ *
+ * `TypedBody` is a decorator function getting `application/json` typed data from
+ * request body. Also, it validates the request body data type through
+ * [typia](https://github.com/samchon/typia) and the validation speed is
+ * maximum 20,000x times faster than `class-validator`.
+ *
+ * For reference, when the request body data is not following the promised type `T`,
+ * `BadRequestException` error (status code: 400) would be thrown.
+ *
+ * @param validator Custom validator if required. Default is `typia.assert()`
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export function TypedBody<T>(
+  validator?: IRequestBodyValidator<T>,
+): ParameterDecorator {
+  const checker = validate_request_body("TypedBody")(validator);
+  return createParamDecorator(function TypedBody(
+    _unknown: any,
+    context: ExecutionContext,
+  ) {
+    const request: express.Request | FastifyRequest = context
+      .switchToHttp()
+      .getRequest();
+    if (isApplicationJson(request.headers["content-type"]) === false)
+      throw new BadRequestException(
+        `Request body type is not "application/json".`,
+      );
+
+    const error: Error | null = checker(request.body);
+    if (error !== null) throw error;
+    return request.body;
+  })();
+}
+
+Object.assign(TypedBody, misc.clone);
+Object.assign(TypedBody, is);
+Object.assign(TypedBody, assert);
+Object.assign(TypedBody, validate);
+
+/**
+ * @internal
+ */
+const isApplicationJson = (text?: string): boolean =>
+  text !== undefined &&
+  text
+    .split(";")
+    .map((str) => str.trim())
+    .some((str) => str === "application/json");

package/src/decorators/TypedException.ts

@@ -1,89 +1,90 @@
-import "reflect-metadata";
-
-/**
- * > You must configure the generic argument `T`
- *
- * Exception decorator.
- *
- * `TypedException` is a decorator function describing HTTP exception and its type
- * which could be occured in the method.
- *
- * For reference, this decorator function does not affect to the method's behavior,
- * but only affects to the swagger documents generation. Also, it does not affect to
- * the SDK library generation yet, but will be used in the future.
- *
- * @param status Status number or pattern like "2XX", "3XX", "4XX", "5XX"
- * @param description Description about the exception
- * @returns Method decorator
- *
- * @author Jeongho Nam - https://github.com/samchon
- */
-export function TypedException(
-  status: number | "2XX" | "3XX" | "4XX" | "5XX",
-  description?: string | undefined,
-): never;
-
-/**
- * Exception decorator.
- *
- * `TypedException` is a decorator function describing HTTP exception and its type
- * which could be occured in the method.
- *
- * For reference, this decorator function does not affect to the method's behavior,
- * but only affects to the swagger documents generation. Also, it does not affect to
- * the SDK library generation yet, but will be used in the future.
- *
- * @template T Type of the exception
- * @param status Status number or pattern like "2XX", "3XX", "4XX", "5XX"
- * @param description Description about the exception
- * @returns Method decorator
- *
- * @author Jeongho Nam - https://github.com/samchon
- */
-export function TypedException<T>(
-  status: number | "2XX" | "3XX" | "4XX" | "5XX",
-  description?: string | undefined,
-): MethodDecorator;
-
-/**
- * @internal
- */
-export function TypedException<T>(
-  status: number | "2XX" | "3XX" | "4XX" | "5XX",
-  description?: string | undefined,
-  type?: string | undefined,
-): MethodDecorator {
-  return function TypedException(
-    target: Object | T,
-    propertyKey: string | symbol,
-    descriptor: TypedPropertyDescriptor<any>,
-  ) {
-    const array: IProps[] = (() => {
-      const oldbie: IProps[] | undefined = Reflect.getMetadata(
-        `nestia/TypedException`,
-        (target as any)[propertyKey],
-      );
-      if (oldbie !== undefined) return oldbie;
-
-      const newbie: IProps[] = [];
-      Reflect.defineMetadata(
-        `nestia/TypedException`,
-        newbie,
-        (target as any)[propertyKey],
-      );
-      return newbie;
-    })();
-    array.push({
-      status,
-      description,
-      type: type!,
-    });
-    return descriptor;
-  };
-}
-
-interface IProps {
-  status: number | "2XX" | "3XX" | "4XX" | "5XX";
-  description?: string | undefined;
-  type: string;
-}
+/**
+ * > You must configure the generic argument `T`
+ *
+ * Exception decorator.
+ *
+ * `TypedException` is a decorator function describing HTTP exception and its type
+ * which could be occured in the method.
+ *
+ * For reference, this decorator function does not affect to the method's behavior,
+ * but only affects to the swagger documents generation. Also, it does not affect to
+ * the SDK library generation yet, but will be used in the future.
+ *
+ * @param status Status number or pattern like "2XX", "3XX", "4XX", "5XX"
+ * @param description Description about the exception
+ * @returns Method decorator
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export function TypedException(
+  status: number | "2XX" | "3XX" | "4XX" | "5XX",
+  description?: string | undefined,
+): never;
+
+/**
+ * Exception decorator.
+ *
+ * `TypedException` is a decorator function describing HTTP exception and its type
+ * which could be occured in the method.
+ *
+ * For reference, this decorator function does not affect to the method's behavior,
+ * but only affects to the swagger documents generation. Also, it does not affect to
+ * the SDK library generation yet, but will be used in the future.
+ *
+ * @template T Type of the exception
+ * @param status Status number or pattern like "2XX", "3XX", "4XX", "5XX"
+ * @param description Description about the exception
+ * @returns Method decorator
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export function TypedException<T>(
+  status: number | "2XX" | "3XX" | "4XX" | "5XX",
+  description?: string | undefined,
+): MethodDecorator;
+
+/**
+ * @internal
+ */
+export function TypedException<T>(
+  status: number | "2XX" | "3XX" | "4XX" | "5XX",
+  description?: string | undefined,
+  type?: string | undefined,
+): MethodDecorator {
+  return function TypedException(
+    target: Object | T,
+    propertyKey: string | symbol,
+    descriptor: TypedPropertyDescriptor<any>,
+  ) {
+    const array: IProps[] = (() => {
+      const oldbie: IProps[] | undefined = Reflect.getMetadata(
+        "nestia/TypedException",
+        (target as any)[propertyKey],
+      );
+      if (oldbie !== undefined) return oldbie;
+
+      const newbie: IProps[] = [];
+      Reflect.defineMetadata(
+        "nestia/TypedException",
+        newbie,
+        (target as any)[propertyKey],
+      );
+      return newbie;
+    })();
+    array.push({
+      status,
+      description,
+      type: type!,
+    });
+    return descriptor;
+  };
+}
+
+/**
+ * @internal
+ */
+interface IProps {
+  status: number | "2XX" | "3XX" | "4XX" | "5XX";
+  description?: string | undefined;
+  type: string;
+}