@tsed/platform-multer 8.7.0

package/src/common/decorators/multipartFile.ts

@@ -0,0 +1,91 @@
+import {DecoratorParameters, Metadata, StoreMerge, useDecorators, useMethodDecorators} from "@tsed/core";
+import {UseBefore} from "@tsed/platform-middlewares";
+import {ParamTypes, UseParam} from "@tsed/platform-params";
+import {InFile} from "@tsed/schema";
+import type {Field} from "multer";
+
+import {PLATFORM_MULTER_OPTIONS} from "../constants/constants.js";
+import type {PlatformMulterFile} from "../interfaces/PlatformMulterSettings.js";
+import {PlatformMulterMiddleware} from "../middlewares/PlatformMulterMiddleware.js";
+
+function mapOptions(name: string, maxCount: number | undefined): {fields: Field[]} {
+  return {
+    fields: [
+      {
+        name,
+        maxCount
+      }
+    ]
+  };
+}
+
+/**
+ * Define a parameter as Multipart file.
+ *
+ * ```typescript
+ * import {Post} from "@tsed/schema";
+ * import {Controller, MulterOptions, MultipartFile} from "@tsed/platform-multer";
+ * import {Controller} from "@tsed/di";
+ * import {Multer} from "@types/multer";
+ *
+ * type MulterFile = Express.Multer.File;
+ *
+ * @Controller('/')
+ * class MyCtrl {
+ *   @Post('/file')
+ *   private uploadFile(@MultipartFile("file1") file: MulterFile) {
+ *
+ *   }
+ *
+ *   @Post('/file')
+ *   @MulterOptions({dest: "/other-dir"})
+ *   private uploadFile(@MultipartFile("file1") file: MulterFile) {
+ *
+ *   }
+ *
+ *   @Post('/file2')
+ *   @MulterOptions({dest: "/other-dir"})
+ *   private uploadFile(@MultipartFile("file1") file: MulterFile, @MultipartFile("file2") file2: MulterFile) {
+ *
+ *   }
+ *
+ *   @Post('/files')
+ *   private uploadFile(@MultipartFile("file1") files: MulterFile[]) {
+ *
+ *   }
+ * }
+ * ```
+ *
+ * > See the tutorial on the [multer configuration](/docs/upload-files.md).
+ *
+ * @param name
+ * @param maxCount
+ * @returns Function
+ * @decorator
+ * @input
+ */
+export function MultipartFile(name: string, maxCount?: number): ParameterDecorator {
+  return (...args: DecoratorParameters): void => {
+    const [target, propertyKey, index] = args;
+    const multiple = Metadata.getParamTypes(target, propertyKey)[index as number] === Array;
+
+    name = (typeof name === "object" ? undefined : name)!;
+
+    const expression = [name, !multiple && "0"].filter(Boolean).join(".");
+
+    const decorators = useDecorators(
+      InFile(name),
+      useMethodDecorators(StoreMerge(PLATFORM_MULTER_OPTIONS, mapOptions(name, maxCount)), UseBefore(PlatformMulterMiddleware)),
+      UseParam({
+        paramType: ParamTypes.FILES,
+        dataPath: "$ctx.request.files",
+        expression,
+        useValidation: true
+      })
+    );
+
+    decorators(...args);
+  };
+}
+
+export type MultipartFile = PlatformMulterFile;

package/src/common/errors/MulterException.ts

@@ -0,0 +1,20 @@
+import {BadRequest} from "@tsed/exceptions";
+import type {MulterError} from "multer";
+
+/**
+ * Exception thrown when a Multer error occurs during file upload operations.
+ * Extends the BadRequest exception with Multer-specific properties.
+ */
+export class MulterException extends BadRequest {
+  origin: MulterError;
+
+  /**
+   * Creates a new MulterException
+   * @param er - The original Multer error
+   */
+  constructor(er: MulterError) {
+    super(er.message);
+    this.origin = er;
+    this.name = er.code;
+  }
+}

package/src/common/index.ts

@@ -0,0 +1,10 @@
+/**
+ * @file Automatically generated by @tsed/barrels.
+ */
+export * from "./constants/constants.js";
+export * from "./decorators/multerFileSize.js";
+export * from "./decorators/multerOptions.js";
+export * from "./decorators/multipartFile.js";
+export * from "./errors/MulterException.js";
+export * from "./interfaces/PlatformMulterSettings.js";
+export * from "./middlewares/PlatformMulterMiddleware.js";

package/src/common/interfaces/PlatformMulterSettings.ts

@@ -0,0 +1,45 @@
+import type {Readable} from "node:stream";
+
+import type {Field, Multer, Options} from "multer";
+
+declare global {
+  namespace TsED {
+    export interface Configuration {
+      multer?: Options;
+    }
+  }
+}
+
+export type PlatformMulter = Multer;
+export type PlatformMulterSettings = Options;
+export interface PlatformMulterFile {
+  /** Name of the form field associated with this file. */
+  fieldname: string;
+  /** Name of the file on the uploader's computer. */
+  originalname: string;
+  /**
+   * Value of the `Content-Transfer-Encoding` header for this file.
+   * @deprecated since July 2015
+   * @see RFC 7578, Section 4.7
+   */
+  encoding: string;
+  /** Value of the `Content-Type` header for this file. */
+  mimetype: string;
+  /** Size of the file in bytes. */
+  size: number;
+  /**
+   * A readable stream of this file. Only available to the `_handleFile`
+   * callback for custom `StorageEngine`s.
+   */
+  stream: Readable;
+  /** `DiskStorage` only: Directory to which this file has been uploaded. */
+  destination: string;
+  /** `DiskStorage` only: Name of this file within `destination`. */
+  filename: string;
+  /** `DiskStorage` only: Full path to the uploaded file. */
+  path: string;
+  /** `MemoryStorage` only: A Buffer containing the entire file. */
+  buffer: Buffer;
+}
+
+export type PlatformMulterField = Field;

package/src/common/middlewares/PlatformMulterMiddleware.spec.ts

@@ -0,0 +1,98 @@
+import {catchAsyncError} from "@tsed/core";
+import {inject, injectable} from "@tsed/di";
+import {Exception} from "@tsed/exceptions";
+import {EndpointMetadata} from "@tsed/platform-http";
+import {PlatformTest} from "@tsed/platform-http/testing";
+import {MulterError} from "multer";
+
+import {MULTER_MODULE} from "../constants/constants.js";
+import {MulterOptions} from "../decorators/multerOptions.js";
+import {MultipartFile} from "../decorators/multipartFile.js";
+import {PlatformMulterMiddleware} from "./PlatformMulterMiddleware.js";
+
+async function getFixture(options = {}) {
+  class Test {
+    @MulterOptions(options)
+    upload(@MultipartFile("file1") file1: any) {}
+  }
+
+  const multerMiddleware = vi.fn();
+  const multer = {
+    fields: vi.fn().mockReturnValue(multerMiddleware)
+  };
+
+  injectable(MULTER_MODULE).factory(() => {
+    return {
+      get: vi.fn().mockReturnValue(multer)
+    };
+  });
+
+  const middleware = await inject<PlatformMulterMiddleware>(PlatformMulterMiddleware);
+  const ctx: any = PlatformTest.createRequestContext();
+  ctx.endpoint = EndpointMetadata.get(Test, "upload");
+
+  const multerModuleFactory = inject<{get: any}>(MULTER_MODULE);
+
+  return {middleware, ctx, multer, multerModuleFactory, multerMiddleware};
+}
+
+describe("PlatformMulterMiddleware", () => {
+  beforeEach(() =>
+    PlatformTest.create({
+      multer: {
+        dest: "/dest"
+      }
+    })
+  );
+  afterEach(() => PlatformTest.reset());
+  it("should create middleware", async () => {
+    const {middleware, ctx, multer, multerModuleFactory, multerMiddleware} = await getFixture({});
+
+    await middleware.use(ctx);
+
+    expect(multerModuleFactory.get).toHaveBeenCalledWith({
+      dest: "/dest"
+    });
+    expect(multer.fields).toHaveBeenCalledWith([{maxCount: undefined, name: "file1"}]);
+    expect(multerMiddleware).toHaveBeenCalledWith(ctx.request.raw, ctx.response.raw);
+  });
+  it("should create middleware with storage", async () => {
+    const {middleware, ctx, multer, multerModuleFactory, multerMiddleware} = await getFixture({
+      storage: "storage"
+    });
+
+    await middleware.use(ctx);
+
+    expect(multerModuleFactory.get).toHaveBeenCalledWith({
+      storage: "storage"
+    });
+    expect(multer.fields).toHaveBeenCalledWith([{maxCount: undefined, name: "file1"}]);
+    expect(multerMiddleware).toHaveBeenCalledWith(ctx.request.raw, ctx.response.raw);
+  });
+  it("should catch error with code", async () => {
+    const {middleware, ctx, multerMiddleware} = await getFixture();
+    const error = new MulterError("LIMIT_FILE_SIZE", "field");
+
+    multerMiddleware.mockRejectedValue(error);
+
+    const actualError: any | undefined = await catchAsyncError(() => middleware.use(ctx));
+
+    expect(actualError).toBeInstanceOf(Exception);
+    expect(actualError?.message).toEqual("File too large");
+    expect(actualError?.status).toEqual(400);
+  });
+  it("should throw error without code", async () => {
+    const {middleware, ctx, multerMiddleware} = await getFixture();
+
+    multerMiddleware.mockRejectedValue(new Error("test"));
+
+    let actualError: any;
+    try {
+      await middleware.use(ctx);
+    } catch (er) {
+      actualError = er;
+    }
+
+    expect(actualError.message).toEqual("test");
+  });
+});

package/src/common/middlewares/PlatformMulterMiddleware.ts

@@ -0,0 +1,46 @@
+import {constant, DIContext, inject, injectable, ProviderType} from "@tsed/di";
+import {MiddlewareMethods} from "@tsed/platform-middlewares";
+import {Context} from "@tsed/platform-params";
+import {JsonMethodStore} from "@tsed/schema";
+import type {Field, Options} from "multer";
+
+import {MULTER_MODULE, PLATFORM_MULTER_OPTIONS} from "../constants/constants.js";
+import {MulterException} from "../errors/MulterException.js";
+
+/**
+ * @middleware
+ */
+export class PlatformMulterMiddleware implements MiddlewareMethods {
+  async use(@Context() ctx: DIContext & {endpoint: JsonMethodStore}) {
+    try {
+      const {fields, options = {}} = ctx.endpoint.get<{
+        fields: Field[];
+        options: Options;
+      }>(PLATFORM_MULTER_OPTIONS);
+
+      const settings: Options = {
+        ...constant<Options>("multer", {}),
+        ...options
+      };
+
+      /* istanbul ignore next */
+      if (settings.storage) {
+        settings.dest = undefined;
+      }
+
+      const {get} = await inject<Promise<MULTER_MODULE>>(MULTER_MODULE);
+
+      const middleware: any = get(settings).fields(fields);
+
+      return await middleware(ctx.getRequest(), ctx.getResponse());
+    } catch (er) {
+      if (er.code) {
+        throw new MulterException(er);
+      }
+
+      throw er;
+    }
+  }
+}
+
+injectable(PlatformMulterMiddleware).type(ProviderType.MIDDLEWARE).priority(-10);

package/src/index.ts

@@ -0,0 +1 @@
+export * from "./common/index.js";

package/vitest.config.mts

@@ -0,0 +1,21 @@
+// @ts-ignore
+import {presets} from "@tsed/vitest/presets";
+import {defineConfig} from "vitest/config";
+
+export default defineConfig(
+  {
+    ...presets,
+    test: {
+      ...presets.test,
+      coverage: {
+        ...presets.test.coverage,
+        thresholds: {
+          statements: 53.17,
+          branches: 80,
+          functions: 75,
+          lines: 53.17
+        }
+      }
+    }
+  }
+);