@nestia/core 12.0.0-rc.4 → 12.1.0

package/src/decorators/SwaggerExample.ts

@@ -1,40 +1,38 @@
 /**
  * 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
+ * `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.
  *
+ * @author Jeongho Nam - https://github.com/samchon
  * @example
+ *   ```typescript
+ *   import core from "@nestia/core";
+ *   import { Controller } from "@nestjs/common";
+ *   import typia from "typia";
  *
- * ```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> {
- *     // ...
+ *   @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 {
   /**
@@ -45,12 +43,12 @@ export namespace SwaggerExample {
    * - {@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.
+   *   `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.
+   * 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).
    */
@@ -68,20 +66,19 @@ export namespace SwaggerExample {
   }
 
   /**
-   * Attach an example value to a request parameter (body, path, query, etc.)
-   * of a controller method.
+   * 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.
+   *   `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.
+   * 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).
    */
@@ -100,9 +97,9 @@ export namespace SwaggerExample {
   /**
    * 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.
+   * 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>;
@@ -163,11 +160,12 @@ const emplaceArrayOfParameters = (
   target: Object,
   propertyKey: string | symbol,
 ): SwaggerExample.IData<any>[] => {
-  const array: SwaggerExample.IData<any>[] | undefined = Reflect.getMetadata(
-    "nestia/SwaggerExample/Parameters",
-    target,
-    propertyKey,
-  );
+  const array: SwaggerExample.IData<any>[] | undefined =
+    Reflect.getOwnMetadata(
+      "nestia/SwaggerExample/Parameters",
+      target,
+      propertyKey,
+    );
   if (array !== undefined) return array;
   const newbie: SwaggerExample.IData<any>[] = [];
   Reflect.defineMetadata(

package/src/decorators/TypedBody.ts

@@ -7,6 +7,7 @@ import type express from "express";
 import type { FastifyRequest } from "fastify";
 
 import { IRequestBodyValidator } from "../options/IRequestBodyValidator";
+import { is_media_type } from "./internal/is_media_type";
 import { is_request_body_undefined } from "./internal/is_request_body_undefined";
 import { validate_request_body } from "./internal/validate_request_body";
 
@@ -37,7 +38,10 @@ export function TypedBody<T>(
       .getRequest();
     if (is_request_body_undefined(request) && checker(undefined as T) === null)
       return undefined;
-    else if (isApplicationJson(request.headers["content-type"]) === false)
+    else if (
+      is_media_type(request.headers["content-type"], "application/json") ===
+      false
+    )
       throw new BadRequestException(
         `Request body type is not "application/json".`,
       );
@@ -47,11 +51,3 @@ export function TypedBody<T>(
     return request.body;
   })();
 }
-
-/** @internal */
-const isApplicationJson = (text?: string): boolean =>
-  text !== undefined &&
-  text
-    .split(";")
-    .map((str) => str.trim())
-    .some((str) => str === "application/json");

package/src/decorators/TypedException.ts

@@ -76,7 +76,7 @@ export function TypedException<T>(
  * @author Jeongho Nam - https://github.com/samchon
  * @deprecated Use {@link TypedException.IProps} typed function instead. This
  *   typed function is deprecated and will be removed in the next major update.
- * @template T Type of the exception
+ * @template T Type of the exception, consumed by the transformer only
  * @param status Status number or pattern like "2XX", "3XX", "4XX", "5XX"
  * @param description Description about the exception
  * @returns Method decorator
@@ -84,7 +84,7 @@ export function TypedException<T>(
 export function TypedException<T>(
   status: number | "2XX" | "3XX" | "4XX" | "5XX",
   description?: string | undefined,
-): MethodDecorator;
+): MethodDecorator & Pick<TypedException.IProps<T>, never>;
 
 /** @internal */
 export function TypedException<T>(...args: any[]): MethodDecorator {

package/src/decorators/TypedFormData.ts

@@ -9,6 +9,7 @@ import type ExpressMulter from "multer";
 
 import type { IRequestFormDataProps } from "../options/IRequestFormDataProps";
 import { Singleton } from "../utils/Singleton";
+import { is_media_type } from "./internal/is_media_type";
 import { validate_request_form_data } from "./internal/validate_request_form_data";
 
 /**
@@ -95,7 +96,12 @@ export namespace TypedFormData {
     ): Promise<T> {
       const http: HttpArgumentsHost = context.switchToHttp();
       const request: express.Request = http.getRequest();
-      if (isMultipartFormData(request.headers["content-type"]) === false)
+      if (
+        is_media_type(
+          request.headers["content-type"],
+          "multipart/form-data",
+        ) === false
+      )
         throw new BadRequestException(
           `Request body type is not "multipart/form-data".`,
         );
@@ -177,11 +183,3 @@ const parseFiles =
             }),
           );
   };
-
-/** @internal */
-const isMultipartFormData = (text?: string): boolean =>
-  text !== undefined &&
-  text
-    .split(";")
-    .map((str) => str.trim())
-    .some((str) => str === "multipart/form-data");

package/src/decorators/TypedQuery.ts

@@ -21,6 +21,7 @@ import typia from "typia";
 import { IRequestQueryValidator } from "../options/IRequestQueryValidator";
 import { IResponseBodyQuerifier } from "../options/IResponseBodyQuerifier";
 import { get_path_and_querify } from "./internal/get_path_and_querify";
+import { is_media_type } from "./internal/is_media_type";
 import { route_error } from "./internal/route_error";
 import { validate_request_query } from "./internal/validate_request_query";
 
@@ -79,7 +80,12 @@ export namespace TypedQuery {
       const request: express.Request | FastifyRequest = context
         .switchToHttp()
         .getRequest();
-      if (isApplicationQuery(request.headers["content-type"]) === false)
+      if (
+        is_media_type(
+          request.headers["content-type"],
+          "application/x-www-form-urlencoded",
+        ) === false
+      )
         throw new BadRequestException(
           `Request body type is not "application/x-www-form-urlencoded".`,
         );
@@ -172,17 +178,6 @@ function tail(url: string): string {
   return index === -1 ? "" : url.substring(index + 1);
 }
 
-/** @internal */
-function isApplicationQuery(text?: string): boolean {
-  return (
-    text !== undefined &&
-    text
-      .split(";")
-      .map((str) => str.trim())
-      .some((str) => str === "application/x-www-form-urlencoded")
-  );
-}
-
 /** @internal */
 class FakeURLSearchParams {
   public constructor(private readonly target: Record<string, string[]>) {}

package/src/decorators/WebSocketRoute.ts

@@ -225,7 +225,7 @@ export namespace WebSocketRoute {
     value: IWebSocketRouteReflect.IArgument,
   ) => {
     const array: IWebSocketRouteReflect.IArgument[] | undefined =
-      Reflect.getMetadata(
+      Reflect.getOwnMetadata(
         "nestia/WebSocketRoute/Parameters",
         target,
         propertyKey,

package/src/decorators/internal/get_path_and_querify.ts

@@ -42,7 +42,7 @@ const take =
 const querify = (input: Record<string, any>): URLSearchParams => {
   const output: URLSearchParams = new URLSearchParams();
   for (const [key, value] of Object.entries(input))
-    if (key === undefined) continue;
+    if (value === undefined) continue;
     else if (Array.isArray(value))
       for (const elem of value) output.append(key, String(elem));
     else output.append(key, String(value));

package/src/decorators/internal/is_media_type.ts

@@ -0,0 +1,10 @@
+/** @internal */
+export const is_media_type = (
+  text: string | undefined,
+  expected: string,
+): boolean =>
+  text !== undefined &&
+  text
+    .split(";")
+    .map((str) => str.trim().toLowerCase())
+    .some((str) => str === expected.toLowerCase());

package/src/decorators/internal/validate_request_query.ts

@@ -35,7 +35,8 @@ const assert =
           message: MESSAGE,
         });
       }
-      if (is_missing_query_property(exp)) return new BadRequestException(MESSAGE);
+      if (is_missing_query_property(exp))
+        return new BadRequestException(MESSAGE);
       throw exp;
     }
   };