@tsed/platform-multer 8.7.0

package/package.json

@@ -0,0 +1,102 @@
+{
+  "name": "@tsed/platform-multer",
+  "description": "Multer adapter package for Ts.ED framework",
+  "type": "module",
+  "version": "8.7.0",
+  "source": "./src/index.ts",
+  "main": "./lib/esm/index.js",
+  "module": "./lib/esm/index.js",
+  "typings": "./lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "tsed-source": "./src/index.ts",
+      "types": "./lib/types/index.d.ts",
+      "import": "./lib/esm/index.js",
+      "default": "./lib/esm/index.js"
+    },
+    "./express": {
+      "tsed-source": "./src/adapters/express/MulterModule.ts",
+      "types": "./lib/types/adapters/express/MulterModule.d.ts",
+      "import": "./lib/esm/adapters/express/MulterModule.js",
+      "default": "./lib/esm/adapters/express/MulterModule.js"
+    },
+    "./koa": {
+      "tsed-source": "./src/adapters/koa/MulterModule.ts",
+      "types": "./lib/types/adapters/koa/MulterModule.d.ts",
+      "import": "./lib/esm/adapters/koa/MulterModule.js",
+      "default": "./lib/esm/adapters/koa/MulterModule.js"
+    }
+  },
+  "scripts": {
+    "build": "yarn barrels && yarn build:ts",
+    "barrels": "barrels",
+    "test": "vitest run",
+    "build:ts": "tsc --build tsconfig.esm.json",
+    "test:ci": "vitest run --coverage.thresholds.autoUpdate=true"
+  },
+  "keywords": [
+    "Multer",
+    "TypeScript",
+    "typescript",
+    "Decorator",
+    "decorators",
+    "decorator",
+    "ESM",
+    "multipartfile",
+    "Ts.ED"
+  ],
+  "author": "Romain Lenzotti",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/tsedio/tsed/issues"
+  },
+  "homepage": "https://github.com/tsedio/tsed/tree/production/packages/platform/platform-multer",
+  "repository": "https://github.com/tsedio/tsed",
+  "devDependencies": {
+    "@tsed/barrels": "8.7.0",
+    "@tsed/core": "8.7.0",
+    "@tsed/di": "8.7.0",
+    "@tsed/platform-middlewares": "8.7.0",
+    "@tsed/typescript": "8.7.0",
+    "eslint": "9.12.0",
+    "typescript": "5.4.5",
+    "vitest": "3.0.9"
+  },
+  "dependencies": {
+    "multer": "^1.4.5-lts.1",
+    "tslib": "2.7.0"
+  },
+  "peerDependencies": {
+    "@tsed/core": ">=8.7.0",
+    "@tsed/di": ">=8.7.0",
+    "@tsed/json-mapper": ">=8.7.0",
+    "@tsed/logger": ">=7.0.1",
+    "@tsed/openspec": ">=8.7.0",
+    "@tsed/platform-middlewares": ">=8.7.0",
+    "@tsed/schema": ">=8.7.0",
+    "cross-env": "7.0.3"
+  },
+  "peerDependenciesMeta": {
+    "@tsed/core": {
+      "optional": false
+    },
+    "@tsed/di": {
+      "optional": false
+    },
+    "@tsed/json-mapper": {
+      "optional": false
+    },
+    "@tsed/logger": {
+      "optional": false
+    },
+    "@tsed/openspec": {
+      "optional": false
+    },
+    "@tsed/platform-middlewares": {
+      "optional": false
+    },
+    "@tsed/schema": {
+      "optional": false
+    }
+  }
+}

package/src/adapters/express/MulterModule.ts

@@ -0,0 +1,40 @@
+import {promisify} from "node:util";
+
+import {injectable} from "@tsed/di";
+import type {Options} from "multer";
+
+import {MULTER_MODULE} from "../../common/index.js";
+
+async function factory() {
+  const {default: multer} = await import("multer");
+
+  return {
+    multer,
+    get(options: Options) {
+      const instance = multer(options);
+
+      const makePromise = (multer: any, name: string) => {
+        // istanbul ignore next
+        if (!multer[name]) return;
+
+        const fn = multer[name];
+
+        multer[name] = function apply(...args: any[]) {
+          const middleware: any = Reflect.apply(fn, this, args);
+
+          return (req: any, res: any) => promisify(middleware)(req, res);
+        };
+      };
+
+      makePromise(instance, "any");
+      makePromise(instance, "array");
+      makePromise(instance, "fields");
+      makePromise(instance, "none");
+      makePromise(instance, "single");
+
+      return instance;
+    }
+  };
+}
+
+injectable(MULTER_MODULE).asyncFactory(factory).token();

package/src/adapters/koa/MulterModule.ts

@@ -0,0 +1,73 @@
+import {promisify} from "node:util";
+
+import {injectable} from "@tsed/di";
+import Koa from "koa";
+import type {Options} from "multer";
+
+import {MULTER_MODULE} from "../../common/index.js";
+
+/**
+ * @ignore
+ */
+function createRawMiddleware(middleware: any) {
+  return async (request: Koa.Request) => {
+    const ctx: any = request.ctx;
+
+    await middleware(ctx.req, ctx.res);
+
+    const forwardKey = (key: string) => {
+      if (ctx.req[key]) {
+        ctx.request[key] = ctx.req[key];
+        ctx[key] = ctx.req[key];
+        delete ctx.req[key];
+      }
+    };
+
+    if ("request" in ctx) {
+      if (ctx.req.body) {
+        ctx.request.body = ctx.req.body;
+        delete ctx.req.body;
+      }
+
+      forwardKey("file");
+      forwardKey("files");
+    }
+  };
+}
+
+/**
+ * @ignore
+ */
+function makePromise(multer: any, name: string) {
+  // istanbul ignore next
+  if (!multer[name]) return;
+
+  const fn = multer[name];
+
+  multer[name] = function apply(...args: any[]) {
+    const middleware: any = Reflect.apply(fn, this, args);
+
+    return createRawMiddleware(promisify(middleware));
+  };
+}
+
+async function factory() {
+  const {default: multer} = await import("multer");
+
+  return {
+    multer,
+    get(options: Options) {
+      const instance = multer(options);
+
+      makePromise(instance, "any");
+      makePromise(instance, "array");
+      makePromise(instance, "fields");
+      makePromise(instance, "none");
+      makePromise(instance, "single");
+
+      return instance;
+    }
+  };
+}
+
+injectable(MULTER_MODULE).asyncFactory(factory).token();

package/src/common/constants/constants.ts

@@ -0,0 +1,10 @@
+import type {Multer, Options} from "multer";
+
+export interface MULTER_MODULE {
+  multer: Multer;
+
+  get(options: Options): Multer;
+}
+
+export const MULTER_MODULE = Symbol.for("MULTER_MODULE");
+export const PLATFORM_MULTER_OPTIONS = Symbol.for("PLATFORM_MULTER_OPTIONS");

package/src/common/decorators/multerFileSize.spec.ts

@@ -0,0 +1,22 @@
+import {Store} from "@tsed/core";
+
+import {PLATFORM_MULTER_OPTIONS} from "../constants/constants.js";
+import {MulterFileSize} from "./multerFileSize.js";
+
+describe("MulterFileSize", () => {
+  it("should set the file size", () => {
+    class Test {
+      @MulterFileSize(100)
+      file() {}
+    }
+
+    const store = Store.fromMethod(Test, "file");
+    expect(store.get(PLATFORM_MULTER_OPTIONS)).toEqual({
+      options: {
+        limits: {
+          fileSize: 100
+        }
+      }
+    });
+  });
+});

package/src/common/decorators/multerFileSize.ts

@@ -0,0 +1,32 @@
+import {MulterOptions} from "./multerOptions.js";
+
+/**
+ * Define file size limit.
+ *
+ * ```typescript
+ * import {Post} from "@tsed/schema";
+ * import {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('/file2')
+ *   @MulterFileSize(1024) // (Ko). Applied for all fields
+ *   private uploadFile(@MultipartFile("file1") file: MulterFile, @MultipartFile("file2") file2: MulterFile) {
+ *
+ *   }
+ * }
+ * ```
+ *
+ * > See the tutorial on the [multer configuration](/docs/upload-files.md).
+ * @param fileSize
+ * @returns {(target: any, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor}
+ * @decorator
+ * @multer
+ */
+export function MulterFileSize(fileSize: number): MethodDecorator {
+  return MulterOptions({limits: {fileSize}});
+}

package/src/common/decorators/multerOptions.spec.ts

@@ -0,0 +1,21 @@
+import {Store} from "@tsed/core";
+
+import {PLATFORM_MULTER_OPTIONS} from "../constants/constants.js";
+import {MulterOptions} from "./multerOptions.js";
+
+describe("@MulterOptions()", () => {
+  it("should store metadata", () => {
+    class Test {
+      @MulterOptions({dest: "/"})
+      test() {}
+    }
+
+    const store = Store.fromMethod(Test.prototype, "test");
+
+    expect(store.get(PLATFORM_MULTER_OPTIONS)).toEqual({
+      options: {
+        dest: "/"
+      }
+    });
+  });
+});

package/src/common/decorators/multerOptions.ts

@@ -0,0 +1,53 @@
+import {StoreMerge} from "@tsed/core";
+import type {Options} from "multer";
+
+import {PLATFORM_MULTER_OPTIONS} from "../constants/constants.js";
+
+/**
+ * Define multer option for all MultipartFile
+ *
+ * ```typescript
+ * import {PlatformMulterFile, MultipartFile, MulterOptions} from "@tsed/platform-multer";
+ * import {Controller} from "@tsed/di";
+ * import {Post} from "@tsed/schema";
+ *
+ * @Controller('/')
+ * class MyCtrl {
+ *   @Post('/file')
+ *   private uploadFile(@MultipartFile("file1") file: PlatformMulterFile) {
+ *
+ *   }
+ *
+ *   @Post('/file')
+ *   @MulterOptions({dest: "/other-dir"})
+ *   private uploadFile(@MultipartFile("file1") file: PlatformMulterFile) {
+ *
+ *   }
+ *
+ *   @Post('/file2')
+ *   @MulterOptions({dest: "/other-dir"})
+ *   private uploadFile(@MultipartFile("file1") file: PlatformMulterFile, @MultipartFile("file2") file2: PlatformMulterFile) {
+ *
+ *   }
+ *
+ *   @Post('/files')
+ *   private uploadFile(@MultipartFile("file1") files: PlatformMulterFile[]) {
+ *
+ *   }
+ * }
+ * ```
+ *
+ * See the tutorial on the [multer configuration](/docs/upload-files.md).
+ *
+ * @param {multer.Options} options
+ * @returns {(target: any, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor}
+ * @decorator
+ * @multer
+ */
+export function MulterOptions(options: Options): MethodDecorator {
+  return (target: any, propertyKey: string, descriptor: PropertyDescriptor) => {
+    StoreMerge(PLATFORM_MULTER_OPTIONS, {options})(target, propertyKey, descriptor);
+
+    return descriptor;
+  };
+}

package/src/common/decorators/multipartFile.spec.ts

@@ -0,0 +1,260 @@
+import "@tsed/exceptions";
+import "@tsed/platform-exceptions";
+
+import {descriptorOf, Metadata, Store} from "@tsed/core";
+import {ParamTypes} from "@tsed/platform-params";
+import {getSpec, JsonParameterStore, Post, SpecTypes} from "@tsed/schema";
+
+import {PLATFORM_MULTER_OPTIONS} from "../constants/constants.js";
+import {MultipartFile} from "./multipartFile.js";
+
+class Test {
+  test() {}
+}
+
+describe("@MultipartFile()", () => {
+  describe("one file", () => {
+    // WHEN
+    class TestController {
+      @Post("/")
+      test(@MultipartFile("file1", 1) file: any) {}
+    }
+
+    // THEN
+    const store = Store.fromMethod(TestController, "test");
+    const param = JsonParameterStore.get(TestController, "test", 0);
+
+    it("should set params properly", () => {
+      expect(store.get(PLATFORM_MULTER_OPTIONS)).toEqual({
+        fields: [
+          {
+            maxCount: 1,
+            name: "file1"
+          }
+        ]
+      });
+      expect(param.expression).toEqual("file1.0");
+      expect(param.paramType).toEqual(ParamTypes.FILES);
+    });
+
+    it("should set endpoint metadata - OS3", () => {
+      expect(getSpec(TestController, {specType: SpecTypes.OPENAPI})).toEqual({
+        paths: {
+          "/": {
+            post: {
+              operationId: "testControllerTest",
+              parameters: [],
+              responses: {
+                "400": {
+                  content: {"application/json": {schema: {$ref: "#/components/schemas/BadRequest"}}},
+                  description:
+                    "<File too long | Too many parts | Too many files | Field name too long | Field value too long | Too many fields | Unexpected field>  [fieldName] Example: File too long file1"
+                }
+              },
+              requestBody: {
+                required: false,
+                content: {
+                  "multipart/form-data": {
+                    schema: {
+                      properties: {file1: {type: "string", format: "binary"}},
+                      type: "object"
+                    }
+                  }
+                }
+              },
+              tags: ["TestController"]
+            }
+          }
+        },
+        tags: [{name: "TestController"}],
+        components: {
+          schemas: {
+            GenericError: {
+              additionalProperties: true,
+              properties: {
+                message: {
+                  description: "An error message",
+                  minLength: 1,
+                  type: "string"
+                },
+                name: {
+                  description: "The error name",
+                  minLength: 1,
+                  type: "string"
+                }
+              },
+              required: ["name", "message"],
+              type: "object"
+            },
+            BadRequest: {
+              type: "object",
+              properties: {
+                name: {
+                  type: "string",
+                  minLength: 1,
+                  description: "The error name",
+                  example: "BAD_REQUEST",
+                  default: "BAD_REQUEST"
+                },
+                message: {type: "string", minLength: 1, description: "An error message"},
+                status: {type: "number", description: "The status code of the exception", example: 400, default: 400},
+                errors: {
+                  type: "array",
+                  items: {
+                    $ref: "#/components/schemas/GenericError"
+                  },
+                  description: "A list of related errors"
+                },
+                stack: {
+                  type: "string",
+                  description: "The stack trace (only in development mode)"
+                }
+              },
+              required: ["name", "message", "status"]
+            }
+          }
+        }
+      });
+    });
+  });
+
+  describe("multiple file schema", () => {
+    // WHEN
+    class TestController {
+      @Post("/")
+      test(@MultipartFile("file1", 4) file: any[]) {}
+    }
+
+    // THEN
+    const store = Store.fromMethod(TestController, "test");
+    const param = JsonParameterStore.get(TestController, "test", 0);
+
+    it("should set params properly", () => {
+      expect(store.get(PLATFORM_MULTER_OPTIONS)).toEqual({
+        fields: [
+          {
+            maxCount: 4,
+            name: "file1"
+          }
+        ]
+      });
+      expect(param.expression).toEqual("file1");
+      expect(param.paramType).toEqual(ParamTypes.FILES);
+    });
+
+    it("should set endpoint metadata - OS3", () => {
+      expect(getSpec(TestController, {specType: SpecTypes.OPENAPI})).toEqual({
+        paths: {
+          "/": {
+            post: {
+              operationId: "testControllerTest",
+              parameters: [],
+              responses: {
+                "400": {
+                  content: {"application/json": {schema: {$ref: "#/components/schemas/BadRequest"}}},
+                  description:
+                    "<File too long | Too many parts | Too many files | Field name too long | Field value too long | Too many fields | Unexpected field>  [fieldName] Example: File too long file1"
+                }
+              },
+              requestBody: {
+                required: false,
+                content: {
+                  "multipart/form-data": {
+                    schema: {
+                      properties: {file1: {type: "array", items: {type: "string", format: "binary"}}},
+                      type: "object"
+                    }
+                  }
+                }
+              },
+              tags: ["TestController"]
+            }
+          }
+        },
+        tags: [{name: "TestController"}],
+        components: {
+          schemas: {
+            GenericError: {
+              additionalProperties: true,
+              properties: {
+                message: {
+                  description: "An error message",
+                  minLength: 1,
+                  type: "string"
+                },
+                name: {
+                  description: "The error name",
+                  minLength: 1,
+                  type: "string"
+                }
+              },
+              required: ["name", "message"],
+              type: "object"
+            },
+            BadRequest: {
+              type: "object",
+              properties: {
+                name: {
+                  type: "string",
+                  minLength: 1,
+                  description: "The error name",
+                  example: "BAD_REQUEST",
+                  default: "BAD_REQUEST"
+                },
+                message: {
+                  type: "string",
+                  minLength: 1,
+                  description: "An error message"
+                },
+                status: {type: "number", description: "The status code of the exception", example: 400, default: 400},
+                errors: {
+                  type: "array",
+                  items: {
+                    $ref: "#/components/schemas/GenericError"
+                  },
+                  description: "A list of related errors"
+                },
+                stack: {
+                  type: "string",
+                  description: "The stack trace (only in development mode)"
+                }
+              },
+              required: ["name", "message", "status"]
+            }
+          }
+        }
+      });
+    });
+  });
+
+  describe("multiple files", () => {
+    afterAll(() => {
+      vi.clearAllMocks();
+    });
+
+    it("should set params metadata", () => {
+      const store = Store.from(Test.prototype, "test", descriptorOf(Test.prototype, "test"));
+      store.delete("multipartAdded");
+
+      // @ts-ignore
+      store.delete(PLATFORM_MULTER_OPTIONS);
+      vi.spyOn(Store, "fromMethod").mockReturnValue(store);
+      vi.spyOn(Metadata, "getParamTypes").mockReturnValue([Array]);
+
+      MultipartFile("file1", 8)(Test.prototype, "test", 0);
+
+      expect(store.get(PLATFORM_MULTER_OPTIONS)).toEqual({
+        fields: [
+          {
+            maxCount: 8,
+            name: "file1"
+          }
+        ]
+      });
+
+      const param = JsonParameterStore.get(Test, "test", 0);
+      expect(param.expression).toEqual("file1");
+      expect(param.paramType).toEqual(ParamTypes.FILES);
+    });
+  });
+});