@nestia/core 12.0.0-rc.2 → 12.0.0-rc.4

package/src/decorators/SwaggerCustomizer.ts

@@ -1,97 +1,97 @@
-import { OpenApi } from "@typia/interface";
-
-/**
- * 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.
- *
- * @author Jeongho Nam - https://github.com/samchon
- * @param closure Callback function which can customize the swagger data
- * @returns Method decorator
- */
-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;
-  }
-}
+import { OpenApi } from "@typia/interface";
+
+/**
+ * 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.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @param closure Callback function which can customize the swagger data
+ * @returns Method decorator
+ */
+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/SwaggerExample.ts

@@ -1,180 +1,180 @@
-/**
- * Attach example values to Swagger documents.
- *
- * `SwaggerExample` is a namespace of decorators that attach example values
- * to controller methods (request/response bodies, parameters), so that
- * `@nestia/sdk`'s Swagger generator can populate the `example` / `examples`
- * fields of the generated OpenAPI document.
- *
- * The decorators only affect Swagger document generation. They do not change
- * runtime behavior, validation, or SDK function signatures.
- *
- * @example
- *
- * ```typescript
- * import core from "@nestia/core";
- * import { Controller } from "@nestjs/common";
- * import typia from "typia";
- *
- * @Controller("bbs/articles")
- * export class BbsArticlesController {
- *   // Single response example.
- *   @core.SwaggerExample.Response(typia.random<IBbsArticle>())
- *   @core.TypedRoute.Post()
- *   public async create(
- *     // Multiple named parameter examples plus a default one.
- *     @core.SwaggerExample.Parameter(typia.random<IBbsArticle.ICreate>())
- *     @core.SwaggerExample.Parameter("x", typia.random<IBbsArticle.ICreate>())
- *     @core.SwaggerExample.Parameter("y", typia.random<IBbsArticle.ICreate>())
- *     @core.TypedBody()
- *     input: IBbsArticle.ICreate,
- *   ): Promise<IBbsArticle> {
- *     // ...
- *   }
- * }
- * ```
- *
- * @author Jeongho Nam - https://github.com/samchon
- */
-export namespace SwaggerExample {
-  /**
-   * Attach an example value to the response body of a controller method.
-   *
-   * Two forms are supported:
-   *
-   * - {@link Response | `Response(value)`}: registers `value` as the single
-   *   default `example`.
-   * - {@link Response | `Response(key, value)`}: registers `value` under
-   *   `examples[key]`. May be applied multiple times to attach several
-   *   named examples.
-   *
-   * Both forms can coexist on the same method — the default `example` and
-   * any number of named `examples` will all surface in the generated
-   * Swagger document.
-   *
-   * @template T Type of the example value (typically the route's response DTO).
-   */
-  export function Response<T>(value: T): MethodDecorator;
-  export function Response<T>(key: string, value: T): MethodDecorator;
-  export function Response(...args: any[]): MethodDecorator {
-    return function SwaggerExampleResponse(
-      _target: Object,
-      _propertyKey: string | symbol,
-      descriptor: TypedPropertyDescriptor<any>,
-    ): TypedPropertyDescriptor<any> {
-      emplaceValue(emplaceOfResponse(descriptor))(args);
-      return descriptor;
-    };
-  }
-
-  /**
-   * Attach an example value to a request parameter (body, path, query, etc.)
-   * of a controller method.
-   *
-   * Two forms are supported:
-   *
-   * - {@link Parameter | `Parameter(value)`}: registers `value` as the single
-   *   default `example` for that parameter.
-   * - {@link Parameter | `Parameter(key, value)`}: registers `value` under
-   *   `examples[key]`. May be applied multiple times to attach several
-   *   named examples to the same parameter.
-   *
-   * Apply alongside the actual parameter decorator
-   * (`@TypedBody()`, `@TypedParam()`, `@TypedQuery()`, etc.); decorator
-   * order does not matter.
-   *
-   * @template T Type of the example value (typically the parameter's DTO).
-   */
-  export function Parameter<T>(value: T): ParameterDecorator;
-  export function Parameter<T>(key: string, value: T): ParameterDecorator;
-  export function Parameter(...args: any[]): ParameterDecorator {
-    return function SwaggerExampleParameter(
-      target: Object,
-      propertyKey: string | symbol | undefined,
-      index: number,
-    ): void {
-      emplaceValue(emplaceOfParameter(target, propertyKey ?? "", index))(args);
-    };
-  }
-
-  /**
-   * Internal storage shape for `SwaggerExample` metadata.
-   *
-   * Reflects the OpenAPI spec's two example fields: a single default
-   * `example`, and/or a named map `examples`. `index` is used internally
-   * to associate parameter examples with the right parameter position.
-   */
-  export interface IData<T> {
-    examples?: Record<string, T>;
-    example?: T;
-    index?: number;
-  }
-}
-
-const emplaceValue =
-  <T>(data: SwaggerExample.IData<T>) =>
-  (args: any[]) => {
-    if (args.length === 1) data.example = args[0];
-    else {
-      const key: string = args[0];
-      const value: T = args[1];
-      data.examples ??= {};
-      data.examples[key] = value;
-    }
-  };
-
-const emplaceOfResponse = <T>(
-  descriptor: TypedPropertyDescriptor<any>,
-): SwaggerExample.IData<T> => {
-  const oldbie: SwaggerExample.IData<T> | undefined = Reflect.getMetadata(
-    "nestia/SwaggerExample/Response",
-    descriptor.value,
-  );
-  if (oldbie !== undefined) return oldbie;
-  const newbie: SwaggerExample.IData<T> = {};
-  Reflect.defineMetadata(
-    "nestia/SwaggerExample/Response",
-    newbie,
-    descriptor.value,
-  );
-  return newbie;
-};
-
-const emplaceOfParameter = (
-  target: Object,
-  propertyKey: string | symbol,
-  index: number,
-): SwaggerExample.IData<any> => {
-  const array: SwaggerExample.IData<any>[] = emplaceArrayOfParameters(
-    target,
-    propertyKey,
-  );
-  const oldibe: SwaggerExample.IData<any> | undefined = array.find(
-    (e) => e.index === index,
-  );
-  if (oldibe !== undefined) return oldibe;
-
-  const data: SwaggerExample.IData<any> = { index };
-  array.push(data);
-  return data;
-};
-
-const emplaceArrayOfParameters = (
-  target: Object,
-  propertyKey: string | symbol,
-): SwaggerExample.IData<any>[] => {
-  const array: SwaggerExample.IData<any>[] | undefined = Reflect.getMetadata(
-    "nestia/SwaggerExample/Parameters",
-    target,
-    propertyKey,
-  );
-  if (array !== undefined) return array;
-  const newbie: SwaggerExample.IData<any>[] = [];
-  Reflect.defineMetadata(
-    "nestia/SwaggerExample/Parameters",
-    newbie,
-    target,
-    propertyKey,
-  );
-  return newbie;
-};
+/**
+ * Attach example values to Swagger documents.
+ *
+ * `SwaggerExample` is a namespace of decorators that attach example values
+ * to controller methods (request/response bodies, parameters), so that
+ * `@nestia/sdk`'s Swagger generator can populate the `example` / `examples`
+ * fields of the generated OpenAPI document.
+ *
+ * The decorators only affect Swagger document generation. They do not change
+ * runtime behavior, validation, or SDK function signatures.
+ *
+ * @example
+ *
+ * ```typescript
+ * import core from "@nestia/core";
+ * import { Controller } from "@nestjs/common";
+ * import typia from "typia";
+ *
+ * @Controller("bbs/articles")
+ * export class BbsArticlesController {
+ *   // Single response example.
+ *   @core.SwaggerExample.Response(typia.random<IBbsArticle>())
+ *   @core.TypedRoute.Post()
+ *   public async create(
+ *     // Multiple named parameter examples plus a default one.
+ *     @core.SwaggerExample.Parameter(typia.random<IBbsArticle.ICreate>())
+ *     @core.SwaggerExample.Parameter("x", typia.random<IBbsArticle.ICreate>())
+ *     @core.SwaggerExample.Parameter("y", typia.random<IBbsArticle.ICreate>())
+ *     @core.TypedBody()
+ *     input: IBbsArticle.ICreate,
+ *   ): Promise<IBbsArticle> {
+ *     // ...
+ *   }
+ * }
+ * ```
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export namespace SwaggerExample {
+  /**
+   * Attach an example value to the response body of a controller method.
+   *
+   * Two forms are supported:
+   *
+   * - {@link Response | `Response(value)`}: registers `value` as the single
+   *   default `example`.
+   * - {@link Response | `Response(key, value)`}: registers `value` under
+   *   `examples[key]`. May be applied multiple times to attach several
+   *   named examples.
+   *
+   * Both forms can coexist on the same method — the default `example` and
+   * any number of named `examples` will all surface in the generated
+   * Swagger document.
+   *
+   * @template T Type of the example value (typically the route's response DTO).
+   */
+  export function Response<T>(value: T): MethodDecorator;
+  export function Response<T>(key: string, value: T): MethodDecorator;
+  export function Response(...args: any[]): MethodDecorator {
+    return function SwaggerExampleResponse(
+      _target: Object,
+      _propertyKey: string | symbol,
+      descriptor: TypedPropertyDescriptor<any>,
+    ): TypedPropertyDescriptor<any> {
+      emplaceValue(emplaceOfResponse(descriptor))(args);
+      return descriptor;
+    };
+  }
+
+  /**
+   * Attach an example value to a request parameter (body, path, query, etc.)
+   * of a controller method.
+   *
+   * Two forms are supported:
+   *
+   * - {@link Parameter | `Parameter(value)`}: registers `value` as the single
+   *   default `example` for that parameter.
+   * - {@link Parameter | `Parameter(key, value)`}: registers `value` under
+   *   `examples[key]`. May be applied multiple times to attach several
+   *   named examples to the same parameter.
+   *
+   * Apply alongside the actual parameter decorator
+   * (`@TypedBody()`, `@TypedParam()`, `@TypedQuery()`, etc.); decorator
+   * order does not matter.
+   *
+   * @template T Type of the example value (typically the parameter's DTO).
+   */
+  export function Parameter<T>(value: T): ParameterDecorator;
+  export function Parameter<T>(key: string, value: T): ParameterDecorator;
+  export function Parameter(...args: any[]): ParameterDecorator {
+    return function SwaggerExampleParameter(
+      target: Object,
+      propertyKey: string | symbol | undefined,
+      index: number,
+    ): void {
+      emplaceValue(emplaceOfParameter(target, propertyKey ?? "", index))(args);
+    };
+  }
+
+  /**
+   * Internal storage shape for `SwaggerExample` metadata.
+   *
+   * Reflects the OpenAPI spec's two example fields: a single default
+   * `example`, and/or a named map `examples`. `index` is used internally
+   * to associate parameter examples with the right parameter position.
+   */
+  export interface IData<T> {
+    examples?: Record<string, T>;
+    example?: T;
+    index?: number;
+  }
+}
+
+const emplaceValue =
+  <T>(data: SwaggerExample.IData<T>) =>
+  (args: any[]) => {
+    if (args.length === 1) data.example = args[0];
+    else {
+      const key: string = args[0];
+      const value: T = args[1];
+      data.examples ??= {};
+      data.examples[key] = value;
+    }
+  };
+
+const emplaceOfResponse = <T>(
+  descriptor: TypedPropertyDescriptor<any>,
+): SwaggerExample.IData<T> => {
+  const oldbie: SwaggerExample.IData<T> | undefined = Reflect.getMetadata(
+    "nestia/SwaggerExample/Response",
+    descriptor.value,
+  );
+  if (oldbie !== undefined) return oldbie;
+  const newbie: SwaggerExample.IData<T> = {};
+  Reflect.defineMetadata(
+    "nestia/SwaggerExample/Response",
+    newbie,
+    descriptor.value,
+  );
+  return newbie;
+};
+
+const emplaceOfParameter = (
+  target: Object,
+  propertyKey: string | symbol,
+  index: number,
+): SwaggerExample.IData<any> => {
+  const array: SwaggerExample.IData<any>[] = emplaceArrayOfParameters(
+    target,
+    propertyKey,
+  );
+  const oldibe: SwaggerExample.IData<any> | undefined = array.find(
+    (e) => e.index === index,
+  );
+  if (oldibe !== undefined) return oldibe;
+
+  const data: SwaggerExample.IData<any> = { index };
+  array.push(data);
+  return data;
+};
+
+const emplaceArrayOfParameters = (
+  target: Object,
+  propertyKey: string | symbol,
+): SwaggerExample.IData<any>[] => {
+  const array: SwaggerExample.IData<any>[] | undefined = Reflect.getMetadata(
+    "nestia/SwaggerExample/Parameters",
+    target,
+    propertyKey,
+  );
+  if (array !== undefined) return array;
+  const newbie: SwaggerExample.IData<any>[] = [];
+  Reflect.defineMetadata(
+    "nestia/SwaggerExample/Parameters",
+    newbie,
+    target,
+    propertyKey,
+  );
+  return newbie;
+};

package/src/decorators/TypedBody.ts

@@ -1,57 +1,57 @@
-import {
-  BadRequestException,
-  ExecutionContext,
-  createParamDecorator,
-} from "@nestjs/common";
-import type express from "express";
-import type { FastifyRequest } from "fastify";
-
-import { IRequestBodyValidator } from "../options/IRequestBodyValidator";
-import { is_request_body_undefined } from "./internal/is_request_body_undefined";
-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.
- *
- * @author Jeongho Nam - https://github.com/samchon
- * @param validator Custom validator if required. Default is `typia.assert()`
- */
-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 (is_request_body_undefined(request) && checker(undefined as T) === null)
-      return undefined;
-    else 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;
-  })();
-}
-
-/** @internal */
-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 { IRequestBodyValidator } from "../options/IRequestBodyValidator";
+import { is_request_body_undefined } from "./internal/is_request_body_undefined";
+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.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @param validator Custom validator if required. Default is `typia.assert()`
+ */
+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 (is_request_body_undefined(request) && checker(undefined as T) === null)
+      return undefined;
+    else 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;
+  })();
+}
+
+/** @internal */
+const isApplicationJson = (text?: string): boolean =>
+  text !== undefined &&
+  text
+    .split(";")
+    .map((str) => str.trim())
+    .some((str) => str === "application/json");