Description

A storage engine of Express Multer middleware that can store your file on disk or/and S3-compatible object storage. It also can be set to generate custom resolutions of your uploaded image files. It utilizes AWS-SDK v3 for managing object storage files and Sharp for image resizing. Usage example can be found in samples/express.js.

Features

1. Save to S3-compatible storage
2. Save to disk
3. Image resizing

Usage

1. Install the package to your project

   1yarn add multer-object-storage

   or

   1npm i multer-object-storage

2. Create storage instance

   1const { ObjectStorage } = require('multer-object-storage');
   2const storage = new ObjectStorage({ ...options });

3. Add the storage instance as the multer constructor parameter

   1const multer = require('multer');
   2// set the storage option
   3const upload = multer({ storage });
   4// create middleware function that accept multiple fields & multiple files
   5const uploadHandler = upload.fields([
   6  { name: 'image', maxCount: 10 }, 
   7  { name: 'file', maxCount: 2 },
   8]);
   9// set the middleware as a request handler
   10app.post('/upload', uploadHandler, (req, res) => {
   11  res.json(req.files); // req.files will contain the uploaded files
   12});

Constructor Option Parameters

All storage option parameters are formatted as a function with a callback parameter to follow guidance from multer documentation and keep the storage to be flexible and customisable.

• filename: (req: express.Request, file: Express.Multer.File, cb: (err: Error, result) => void) => void By default the result will be shortUUID.generate() + file.originalname. Example:

  1const storage = new ObjectStorage({
  2  filename: (req, file, cb) => {
  3    const result = Math.ceil(Math.random() * 1000000) + file.originalname;
  4    cb(null, result);
  5  }
  6});

• destination: (req: express.Request, file: Express.Multer.File, cb: (err: Error, result) => void) => void By default, the storage will store uploaded files into uploads/ diriectory. NOTE: You must make sure that the directory exists. Example:

  1const storage = new ObjectStorage({
  2  destination: (req, file, cb) => {
  3    const result = null; // set storage to ignore file storing to disk
  4    cb(null, result);
  5  }
  6});

• bucket: (req: express.Request, file: Express.Multer.File, cb: (err, result) => void) => void By default, its result is null that means the storage won't store the file to any S3-compatible storage. Example:

  1const storage = new ObjectStorage({
  2  bucket: (req, file, cb) => {
  3    const result = {
  4      name: 'bucket name',
  5      endpoint: 'object storage endpoint', // must include the protocol, eg. https://us.storage.com
  6      accessKeyId: 'object storage access ID',
  7      secretAccessKey: 'object storage secret key',
  8    };
  9    cb(null, result);
  10  }
  11});

• resize: (req: express.Request, file: Express.Multer.File, cb: (err, result) => void) => void By default, its result is null that means the storage won't resize any image files. This parameter only affects image files. If non-image file is passed, the storage won't apply any resizing process to that file. Currently, an image file is a file with Mime-Type image/jpeg, image/png, or image/webp. Example:

  1const storage = new ObjectStorage({
  2  resize: (req, file, cb) => {
  3    const result = {
  4      // additional mime-type filtering, to resize only specific types
  5      mimeTypes: ['image/jpeg'],
  6      
  7      // it alligns with Sharp resize options with an additional field
  8      options: [
  9        {
  10          width: 200,
  11          height: 150,
  12          fit: 'cover', // other options: contain, fill, inside, outside
  13          // set custom string to be appended to the end of file name
  14          // if the file name contains extension, it will be inserted before the extension
  15          // by default, file name will be appended by a string with format "w{width}-h{height}"
  16          fileNameTail: 'thumb', 
  17        },
  18        {
  19          width: 300, // height will auto based on image ratio
  20        },
  21      ],
  22    };
  23    cb(null, result);
  24  }
  25});
  26

Example Result

This is an example of req.files result based on specific configuration.

1{
2    "image": [
3        {
4            "fieldname": "image",
5            "originalname": "ace-2.jpg",
6            "encoding": "7bit",
7            "mimetype": "image/jpeg",
8            "destination": "uploads/",
9            "filename": "3147ace-2.jpg",
10            "path": "C:\\path\\to\\uploads\\3147ace-2.jpg", // location of the original file
11            "size": 111083, // file size in bytes
12            "url": "https://xxx.yyy.digitaloceanspaces.com/3147ace-2.jpg", // S3 object location of the original file
13            "width": 669, // only for image
14            "height": 562, // only for image
15            "resize": [ // only for image
16                {
17                    "path": "C:\\path\\to\\uploads\\3147ace-2thumb.jpg",
18                    "url": "https://xxx.yyy.digitaloceanspaces.com/3147ace-2thumb.jpg",
19                    "width": 200,
20                    "height": 150
21                },
22                {
23                    "path": "C:\\path\\to\\uploads\\3147ace-2w300hauto.jpg",
24                    "url": "https://xxx.yyy.digitaloceanspaces.com/3147ace-2w300hauto.jpg",
25                    "width": 300,
26                    "height": null // auto size will be set to null
27                }
28            ]
29        },
30        {
31            "fieldname": "image",
32            "originalname": "ace-3.jpg",
33            "encoding": "7bit",
34            "mimetype": "image/jpeg",
35            "destination": "uploads/",
36            "filename": "5995ace-3.jpg",
37            "path": "C:\\path\\to\\uploads\\5995ace-3.jpg",
38            "size": 72135,
39            "url": "https://xxx.yyy.digitaloceanspaces.com/5995ace-3.jpg",
40            "width": 640,
41            "height": 427,
42            "resize": [
43                {
44                    "path": "C:\\\path\\to\\uploads\\5995ace-3thumb.jpg",
45                    "url": "https://xxx.yyy.digitaloceanspaces.com/5995ace-3thumb.jpg",
46                    "width": 200,
47                    "height": 150
48                },
49                {
50                    "path": "C:\\path\\to\\uploads\\5995ace-3w300hauto.jpg",
51                    "url": "https://xxx.yyy.digitaloceanspaces.com/5995ace-3w300hauto.jpg",
52                    "width": 300,
53                    "height": null
54                }
55            ]
56        }
57    ]
58}

Support and Feature Requests

You can submit issues on the Github page.