multer-object-storage
TypeScript icon, indicating that this package has built-in type declarations

0.1.6 • Public • Published

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
    yarn add multer-object-storage
    or
    npm i multer-object-storage
  2. Create storage instance
    const { ObjectStorage } = require('multer-object-storage');
    const storage = new ObjectStorage({ ...options });
  3. Add the storage instance as the multer constructor parameter
    const multer = require('multer');
    // set the storage option
    const upload = multer({ storage });
    // create middleware function that accept multiple fields & multiple files
    const uploadHandler = upload.fields([
      { name: 'image', maxCount: 10 }, 
      { name: 'file', maxCount: 2 },
    ]);
    // set the middleware as a request handler
    app.post('/upload', uploadHandler, (req, res) => {
      res.json(req.files); // req.files will contain the uploaded files
    });

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:

    const storage = new ObjectStorage({
      filename: (req, file, cb) => {
        const result = Math.ceil(Math.random() * 1000000) + file.originalname;
        cb(null, result);
      }
    });
  • 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:

    const storage = new ObjectStorage({
      destination: (req, file, cb) => {
        const result = null; // set storage to ignore file storing to disk
        cb(null, result);
      }
    });
  • 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:

    const storage = new ObjectStorage({
      bucket: (req, file, cb) => {
        const result = {
          name: 'bucket name',
          endpoint: 'object storage endpoint', // must include the protocol, eg. https://us.storage.com
          accessKeyId: 'object storage access ID',
          secretAccessKey: 'object storage secret key',
        };
        cb(null, result);
      }
    });
  • 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:

    const storage = new ObjectStorage({
      resize: (req, file, cb) => {
        const result = {
          // additional mime-type filtering, to resize only specific types
          mimeTypes: ['image/jpeg'],
          
          // it alligns with Sharp resize options with an additional field
          options: [
            {
              width: 200,
              height: 150,
              fit: 'cover', // other options: contain, fill, inside, outside
              // set custom string to be appended to the end of file name
              // if the file name contains extension, it will be inserted before the extension
              // by default, file name will be appended by a string with format "w{width}-h{height}"
              fileNameTail: 'thumb', 
            },
            {
              width: 300, // height will auto based on image ratio
            },
          ],
        };
        cb(null, result);
      }
    });

Example Result

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

{
    "image": [
        {
            "fieldname": "image",
            "originalname": "ace-2.jpg",
            "encoding": "7bit",
            "mimetype": "image/jpeg",
            "destination": "uploads/",
            "filename": "3147ace-2.jpg",
            "path": "C:\\path\\to\\uploads\\3147ace-2.jpg", // location of the original file
            "size": 111083, // file size in bytes
            "url": "https://xxx.yyy.digitaloceanspaces.com/3147ace-2.jpg", // S3 object location of the original file
            "width": 669, // only for image
            "height": 562, // only for image
            "resize": [ // only for image
                {
                    "path": "C:\\path\\to\\uploads\\3147ace-2thumb.jpg",
                    "url": "https://xxx.yyy.digitaloceanspaces.com/3147ace-2thumb.jpg",
                    "width": 200,
                    "height": 150
                },
                {
                    "path": "C:\\path\\to\\uploads\\3147ace-2w300hauto.jpg",
                    "url": "https://xxx.yyy.digitaloceanspaces.com/3147ace-2w300hauto.jpg",
                    "width": 300,
                    "height": null // auto size will be set to null
                }
            ]
        },
        {
            "fieldname": "image",
            "originalname": "ace-3.jpg",
            "encoding": "7bit",
            "mimetype": "image/jpeg",
            "destination": "uploads/",
            "filename": "5995ace-3.jpg",
            "path": "C:\\path\\to\\uploads\\5995ace-3.jpg",
            "size": 72135,
            "url": "https://xxx.yyy.digitaloceanspaces.com/5995ace-3.jpg",
            "width": 640,
            "height": 427,
            "resize": [
                {
                    "path": "C:\\\path\\to\\uploads\\5995ace-3thumb.jpg",
                    "url": "https://xxx.yyy.digitaloceanspaces.com/5995ace-3thumb.jpg",
                    "width": 200,
                    "height": 150
                },
                {
                    "path": "C:\\path\\to\\uploads\\5995ace-3w300hauto.jpg",
                    "url": "https://xxx.yyy.digitaloceanspaces.com/5995ace-3w300hauto.jpg",
                    "width": 300,
                    "height": null
                }
            ]
        }
    ]
}

Support and Feature Requests

You can submit issues on the Github page.

Package Sidebar

Install

npm i multer-object-storage

Weekly Downloads

7

Version

0.1.6

License

MIT

Unpacked Size

85.9 kB

Total Files

27

Last publish

Collaborators

  • lukibsubekti