@nestia/core 3.0.0-dev.20231209 → 3.0.0

package/src/decorators/TypedFormData.ts

@@ -0,0 +1,219 @@
+import type { MultipartFile } from "@fastify/multipart";
+import {
+  BadRequestException,
+  ExecutionContext,
+  InternalServerErrorException,
+  createParamDecorator,
+} from "@nestjs/common";
+import type { HttpArgumentsHost } from "@nestjs/common/interfaces";
+import type express from "express";
+import type { FastifyReply, FastifyRequest } from "fastify";
+import multer from "multer";
+import typia from "typia";
+
+import type { IRequestFormDataProps } from "../options/IRequestFormDataProps";
+import { Singleton } from "../utils/Singleton";
+import { validate_request_form_data } from "./internal/validate_request_form_data";
+
+/**
+ * Type safe multipart/form-data decorator.
+ *
+ * `TypedFormData.Body()` is a request body decorator function for the
+ * `multipart/form-data` content type. It automatically casts property type
+ * following its DTO definition, and performs the type validation too.
+ *
+ * Also, `TypedFormData.Body()` is much easier and type safer than `@nest.UploadFile()`.
+ * If you're considering the [SDK library](https://nestia.io/docs/sdk/sdk) generation,
+ * only `TypedFormData.Body()` can do it. Therefore, I recommend you to use
+ * `TypedFormData.Body()` instead of the `@nest.UploadFile()` function.
+ *
+ * For reference, target type `T` must follow such restriction. Of course, if actual
+ * form-data values are different with their promised type `T`,
+ * `BadRequestException` error (status code: 400) would be thrown.
+ *
+ * 1. Type `T` must be an object type
+ * 2. Do not allow dynamic property
+ * 3. Only `boolean`, `bigint`, `number`, `string`, `Blob`, `File` or their array types are allowed
+ * 4. By the way, union type never be not allowed
+ *
+ * By the way, if you're using `fastify`, you have to setup `@fastify/multipart`
+ * and configure like below when composing the NestJS application. If you don't do
+ * that, `@TypedFormData.Body()` will not work properly, and throw 500 internal
+ * server error when `Blob` or `File` type being utilized.
+ *
+ * ```typescript
+ * import multipart from "fastify-multipart";
+ * import { NestFactory } from "@nestjs/core";
+ * import {
+ *   FastifyAdapter,
+ *   NestFastifyApplication
+ * } from "@nestjs/platform-fastify";
+ *
+ * export async function main() {
+ *   const app = await NestFactory.create<NestFastifyApplication>(
+ *     AppModule,
+ *     new FastifyAdapter(),
+ *   );
+ *   app.register(multipart);
+ *   await app.listen(3000);
+ * }
+ * ```
+ *
+ * @todo Change to ReadableStream through configuring storage engine of multer
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export namespace TypedFormData {
+  /**
+   * Request body decorator.
+   *
+   * Request body decorator for the `multipart/form-data` type.
+   *
+   * Much easier and type safer than `@nest.UploadFile()` decorator.
+   *
+   * @param props Automatically filled by transformer
+   */
+  export function Body<T extends object>(
+    props?: IRequestFormDataProps<T>,
+  ): ParameterDecorator {
+    const checker = validate_request_form_data(props);
+    const predicator = (type: "express" | "fastify") =>
+      new Singleton(() =>
+        type === "express" ? decodeExpress(props!) : decodeFastify(props!),
+      );
+    return createParamDecorator(async function TypedFormDataBody(
+      _unknown: any,
+      context: ExecutionContext,
+    ) {
+      const http: HttpArgumentsHost = context.switchToHttp();
+      const request: express.Request = http.getRequest();
+      if (isMultipartFormData(request.headers["content-type"]) === false)
+        throw new BadRequestException(
+          `Request body type is not "multipart/form-data".`,
+        );
+
+      const decoder = isExpressRequest(request)
+        ? predicator("express").get()
+        : predicator("fastify").get();
+      const data: FormData = await decoder({
+        request: request as any,
+        response: http.getResponse(),
+      });
+      const output: T | Error = checker(data);
+      if (output instanceof Error) throw output;
+      return output;
+    })();
+  }
+  Object.assign(Body, typia.http.assertFormData);
+  Object.assign(Body, typia.http.isFormData);
+  Object.assign(Body, typia.http.validateFormData);
+}
+
+/**
+ * @internal
+ */
+const decodeExpress = <T>(props: IRequestFormDataProps<T>) => {
+  const upload = multerApplication.get().fields(
+    props!.files.map((file) => ({
+      name: file.name,
+      ...(file.limit === 1 ? { maxCount: 1 } : {}),
+    })),
+  );
+  const interceptor = (request: express.Request, response: express.Response) =>
+    new Promise<void>((resolve, reject) =>
+      upload(request, response, (error) => {
+        if (error) reject(error);
+        else resolve();
+      }),
+    );
+  return async (socket: {
+    request: express.Request;
+    response: express.Response;
+  }): Promise<FormData> => {
+    await interceptor(socket.request, socket.response);
+
+    const data: FormData = new FormData();
+    for (const [key, value] of Object.entries(socket.request.body))
+      for (const elem of String(value).split(",")) data.append(key, elem);
+
+    if (socket.request.files) parseFiles(data)(socket.request.files);
+    return data;
+  };
+};
+
+/**
+ * @internal
+ */
+const decodeFastify =
+  <T>(_props: IRequestFormDataProps<T>) =>
+  async (socket: {
+    request: FastifyRequest & {
+      files?(): AsyncIterableIterator<MultipartFile>;
+    };
+    response: FastifyReply;
+  }): Promise<FormData> => {
+    if (
+      socket.request.files === undefined ||
+      typeof socket.request.files !== "function"
+    )
+      throw new InternalServerErrorException(
+        "Have not configured the `fastify-multipart` plugin yet. Inquiry to the backend developer.",
+      );
+    const data: FormData = new FormData();
+    for (const [key, value] of Object.entries(socket.request.body ?? {}))
+      for (const elem of String(value).split(",")) data.append(key, elem);
+    for await (const file of socket.request.files())
+      data.append(
+        file.fieldname,
+        new File([await file.toBuffer()], file.filename, {
+          type: file.mimetype,
+        }),
+      );
+    return data;
+  };
+
+/**
+ * @internal
+ */
+const parseFiles =
+  (data: FormData) =>
+  (files: Express.Multer.File[] | Record<string, Express.Multer.File[]>) => {
+    if (Array.isArray(files))
+      for (const file of files)
+        data.append(
+          file.fieldname,
+          new File([file.buffer], file.originalname, {
+            type: file.mimetype,
+          }),
+        );
+    else
+      for (const [key, value] of Object.entries(files))
+        for (const file of value)
+          data.append(
+            key,
+            new File([file.buffer], file.originalname, {
+              type: file.mimetype,
+            }),
+          );
+  };
+
+/**
+ * @internal
+ */
+const isMultipartFormData = (text?: string): boolean =>
+  text !== undefined &&
+  text
+    .split(";")
+    .map((str) => str.trim())
+    .some((str) => str === "multipart/form-data");
+
+/**
+ * @internal
+ */
+const isExpressRequest = (
+  request: express.Request | FastifyRequest,
+): request is express.Request => (request as express.Request).app !== undefined;
+
+/**
+ * @internal
+ */
+const multerApplication = new Singleton(() => multer());

package/src/decorators/TypedHeaders.ts

@@ -1,69 +1,69 @@
-import { ExecutionContext, createParamDecorator } from "@nestjs/common";
-import type express from "express";
-import type { FastifyRequest } from "fastify";
-import typia from "typia";
-
-import { IRequestHeadersValidator } from "../options/IRequestHeadersValidator";
-import { validate_request_headers } from "./internal/validate_request_headers";
-
-/**
- * Type safe HTTP headers decorator.
- *
- * `TypedHeaders` is a decorator function that can parse HTTP headers. It is almost
- * same with {@link nest.Headers}, but it can automatically cast property type following
- * its DTO definition. Also, `TypedHeaders` performs type validation.
- *
- * For reference, target type `T` must follow such restrictions. Also, if actual HTTP
- * header values are different with their promised type `T`, `BadRequestException`
- * error (status code: 400) would be thrown.
- *
- * 1. Type `T` must be an object type
- * 2. Do not allow dynamic property
- * 3. Property key must be lower case
- * 4. Property value cannot be `null`, but `undefined` is possible
- * 5. Only `boolean`, `bigint`, `number`, `string` or their array types are allowed
- * 6. By the way, union type never be not allowed
- * 7. Property `set-cookie` must be array type
- * 8. Those properties cannot be array type
- *   - age
- *   - authorization
- *   - content-length
- *   - content-type
- *   - etag
- *   - expires
- *   - from
- *   - host
- *   - if-modified-since
- *   - if-unmodified-since
- *   - last-modified
- *   - location
- *   - max-forwards
- *   - proxy-authorization
- *   - referer
- *   - retry-after
- *   - server
- *   - user-agent
- *
- * @returns Parameter decorator
- * @author Jeongho Nam - https://github.com/samchon
- */
-export function TypedHeaders<T extends object>(
-  validator?: IRequestHeadersValidator<T>,
-): ParameterDecorator {
-  const checker = validate_request_headers(validator);
-  return createParamDecorator(function TypedHeaders(
-    _unknown: any,
-    context: ExecutionContext,
-  ) {
-    const request: express.Request | FastifyRequest = context
-      .switchToHttp()
-      .getRequest();
-
-    const output: T | Error = checker(request.headers);
-    if (output instanceof Error) throw output;
-    return output;
-  })();
-}
-Object.assign(TypedHeaders, typia.http.assertHeaders);
-Object.assign(TypedHeaders, typia.http.isHeaders);
-Object.assign(TypedHeaders, typia.http.validateHeaders);
+import { ExecutionContext, createParamDecorator } from "@nestjs/common";
+import type express from "express";
+import type { FastifyRequest } from "fastify";
+import typia from "typia";
+
+import { IRequestHeadersValidator } from "../options/IRequestHeadersValidator";
+import { validate_request_headers } from "./internal/validate_request_headers";
+
+/**
+ * Type safe HTTP headers decorator.
+ *
+ * `TypedHeaders` is a decorator function that can parse HTTP headers. It is almost
+ * same with {@link nest.Headers}, but it can automatically cast property type following
+ * its DTO definition. Also, `TypedHeaders` performs type validation.
+ *
+ * For reference, target type `T` must follow such restrictions. Also, if actual HTTP
+ * header values are different with their promised type `T`, `BadRequestException`
+ * error (status code: 400) would be thrown.
+ *
+ * 1. Type `T` must be an object type
+ * 2. Do not allow dynamic property
+ * 3. Property key must be lower case
+ * 4. Property value cannot be `null`, but `undefined` is possible
+ * 5. Only `boolean`, `bigint`, `number`, `string` or their array types are allowed
+ * 6. By the way, union type never be not allowed
+ * 7. Property `set-cookie` must be array type
+ * 8. Those properties cannot be array type
+ *   - age
+ *   - authorization
+ *   - content-length
+ *   - content-type
+ *   - etag
+ *   - expires
+ *   - from
+ *   - host
+ *   - if-modified-since
+ *   - if-unmodified-since
+ *   - last-modified
+ *   - location
+ *   - max-forwards
+ *   - proxy-authorization
+ *   - referer
+ *   - retry-after
+ *   - server
+ *   - user-agent
+ *
+ * @returns Parameter decorator
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export function TypedHeaders<T extends object>(
+  validator?: IRequestHeadersValidator<T>,
+): ParameterDecorator {
+  const checker = validate_request_headers(validator);
+  return createParamDecorator(function TypedHeaders(
+    _unknown: any,
+    context: ExecutionContext,
+  ) {
+    const request: express.Request | FastifyRequest = context
+      .switchToHttp()
+      .getRequest();
+
+    const output: T | Error = checker(request.headers);
+    if (output instanceof Error) throw output;
+    return output;
+  })();
+}
+Object.assign(TypedHeaders, typia.http.assertHeaders);
+Object.assign(TypedHeaders, typia.http.isHeaders);
+Object.assign(TypedHeaders, typia.http.validateHeaders);

package/src/decorators/TypedParam.ts

@@ -1,65 +1,65 @@
-import {
-  BadRequestException,
-  ExecutionContext,
-  createParamDecorator,
-} from "@nestjs/common";
-import type express from "express";
-import type { FastifyRequest } from "fastify";
-import typia, { TypeGuardError } from "typia";
-
-import { NoTransformConfigureError } from "./internal/NoTransformConfigureError";
-
-/**
- * Type safe URL parameter decorator.
- *
- * `TypedParam` is a decorator function getting specific typed parameter from the
- * HTTP request URL. It's almost same with the {@link nest.Param}, but `TypedParam`
- * automatically casts parameter value to be following its type, and validates it.
- *
- * ```typescript
- * import { tags } from "typia";
- *
- * \@TypedRoute.Get("shopping/sales/:id/:no/:paused")
- * public async pause
- *     (
- *         \@TypedParam("id", "uuid"), id: string & tags.Format<"uuid">,
- *         \@TypedParam("no") id: number & tags.Type<"uint32">
- *         \@TypedParam("paused") paused: boolean | null
- *     ): Promise<void>;
- * ```
- *
- * @param name URL Parameter name
- * @returns Parameter decorator
- *
- * @author Jeongho Nam - https://github.com/samchon
- */
-export function TypedParam<T extends boolean | bigint | number | string | null>(
-  name: string,
-  assert?: (value: string) => T,
-): ParameterDecorator {
-  if (assert === undefined) throw NoTransformConfigureError("TypedParam");
-
-  return createParamDecorator(function TypedParam(
-    {}: any,
-    context: ExecutionContext,
-  ) {
-    const request: express.Request | FastifyRequest = context
-      .switchToHttp()
-      .getRequest();
-    const str: string = (request.params as any)[name];
-    try {
-      return assert(str);
-    } catch (exp) {
-      if (typia.is<TypeGuardError>(exp))
-        throw new BadRequestException({
-          path: exp.path,
-          reason: exp.message,
-          expected: exp.expected,
-          value: exp.value,
-          message: `Invalid URL parameter value on "${name}".`,
-        });
-      throw exp;
-    }
-  })(name);
-}
-Object.assign(TypedParam, typia.http.parameter);
+import {
+  BadRequestException,
+  ExecutionContext,
+  createParamDecorator,
+} from "@nestjs/common";
+import type express from "express";
+import type { FastifyRequest } from "fastify";
+import typia, { TypeGuardError } from "typia";
+
+import { NoTransformConfigureError } from "./internal/NoTransformConfigureError";
+
+/**
+ * Type safe URL parameter decorator.
+ *
+ * `TypedParam` is a decorator function getting specific typed parameter from the
+ * HTTP request URL. It's almost same with the {@link nest.Param}, but `TypedParam`
+ * automatically casts parameter value to be following its type, and validates it.
+ *
+ * ```typescript
+ * import { tags } from "typia";
+ *
+ * \@TypedRoute.Get("shopping/sales/:id/:no/:paused")
+ * public async pause
+ *     (
+ *         \@TypedParam("id", "uuid"), id: string & tags.Format<"uuid">,
+ *         \@TypedParam("no") id: number & tags.Type<"uint32">
+ *         \@TypedParam("paused") paused: boolean | null
+ *     ): Promise<void>;
+ * ```
+ *
+ * @param name URL Parameter name
+ * @returns Parameter decorator
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export function TypedParam<T extends boolean | bigint | number | string | null>(
+  name: string,
+  assert?: (value: string) => T,
+): ParameterDecorator {
+  if (assert === undefined) throw NoTransformConfigureError("TypedParam");
+
+  return createParamDecorator(function TypedParam(
+    {}: any,
+    context: ExecutionContext,
+  ) {
+    const request: express.Request | FastifyRequest = context
+      .switchToHttp()
+      .getRequest();
+    const str: string = (request.params as any)[name];
+    try {
+      return assert(str);
+    } catch (exp) {
+      if (typia.is<TypeGuardError>(exp))
+        throw new BadRequestException({
+          path: exp.path,
+          reason: exp.message,
+          expected: exp.expected,
+          value: exp.value,
+          message: `Invalid URL parameter value on "${name}".`,
+        });
+      throw exp;
+    }
+  })(name);
+}
+Object.assign(TypedParam, typia.http.parameter);