A Medley plugin for parsing multipart/form-data request bodies, which are primarily used for uploading files. It is written on top of Busboy and inspired by multer.

# npm
npm install @medley/multipart

# yarn
yarn add @medley/multipart

Registering the plugin on an app adds a .multipart() method to the app that can be used to create a preHandler hook that will parse multipart/form-data bodies.

The hook adds a body and a files property to the req object if it completes successfully, where req.body will contain the text values of the form and req.files will contain the uploaded files.

If an error occurs, req.body and req.files will remain undefined.

Example:

<form action="/profile" method="post" enctype="multipart/form-data">
  <input type="text" name="firstName" />
  <input type="file" name="profilePhoto" />
</form>

const medley = require('@medley/medley');
const app = medley();

app.register(require('@medley/multipart'));

app.post('/profile', [
  app.multipart({
    profilePhoto: {maxCount: 1},
  }),
], (req, res, next) => {
  req.files.profilePhoto // The uploaded file (see File Object below)
  req.body.firstName // The user's first name
});

Specifying the limits can help protect your site against denial of service (DoS) attacks.

const medley = require('@medley/medley');
const app = medley();

app.register(require('@medley/multipart'), {
  limits: {
    fieldSize: 100 * 1024, // 100 KiB
    fileSize: 5 * 1024 * 1024, // 5 MiB
    files: 4,
  },
});

The options parameter allows for route-specific control over upload limits.

app.multipart({
  profilePhoto: {maxCount: 1},
}, {
  limits: {
    fields: 1,
    fileSize: 8 * 1024 * 1024, // 8 MiB
  },
})

Specifies the expected file fields and limits the number of files that can be received for those fields. If unexpected files are received, the upload will be cancelled with an error.

{
  fieldName: { maxCount: integer, optional?: boolean} | integer
}

app.multipart({
  someFile: {maxCount: 1},
  multipleFiles: {maxCount: 6},
  moreFiles: 5, // maxCount shorthand
})

Expected files are required by default, so an error will be thrown if an expected file is not uploaded. Set optional: true to allow the upload to complete without receiving any files for a particular field.

app.post('/upload', [
  app.multipart({
    requiredFile: {maxCount: 1},
    optionalFiles: {maxCount: 5, optional: true},
  }),
], (req, res, next) => {
  req.files.requiredFile // Will always exist
  req.files.optionalFiles // May be `undefined` or an array of files
});

The maxCount value determines the value type of the property in the req.files object. If maxCount is 1, the value will be a file object. If maxCount > 1, the value will be an array of file objects (even if only a single file is received).

app.post('/upload', [
  app.multipart({
    oneFile: {maxCount: 1},
    multipleFiles: {maxCount: 5},
  }),
], (req, res, next) => {
  req.files.oneFile // { ... }
  req.files.multipleFiles // [ { ... }, { ... }, { ... } ]
});

If expectedFiles is the special string 'ANY_FILES', any files may be uploaded and file objects will always be stored in an array. Note that it is not advised to use this option in a production environment.

Exported directly by the module, this method can be used to safely discard all of the files in the req.files object.

This is only needed when the multipart preHandler hook completes successfully but the files aren't handled after (e.g. if an error happens).

const multipart = require('@medley/multipart');

// ...

// Something went wrong and all of the files need to be discarded
multipart.discardFiles(req.files);

The error constructor that this plugin uses to create errors when something goes wrong. It may sometimes be helpful to check if an error was generated by multipart inside an error handler.

const {MultipartError} = require('@medley/multipart');

app.setErrorHandler((err, req, res) => {
  if (err instanceof MultipartError) {
    // This is a multipart error
  }
});

See the code for the properties attached to MultipartError objects.

Note: The file stream must be handled in some way (even discarded by doing stream.destroy()) to ensure that the underlying file descriptor gets closed and the temporary file gets deleted.

app.post('/profile', [
  app.multipart({
    profilePhoto: {maxCount: 1},
  }),
], (req, res, next) => {
  const {profilePhoto} = req.files;

  profilePhoto.stream // ReadStream {}
  profilePhoto.fileName // 'me.jpg'
  profilePhoto.mimeType // 'image/jpeg'
  profilePhoto.size // 3483297
});

When encountering an error, multipart will delegate the error to Medley. Note that if multipart did not create the error, you may need to discard the uploaded files.

const multipart = require('@medley/multipart');

app.setErrorHandler((err, req, res) => {
  if (err instanceof multipart.MultipartError) {
    // This is a multipart error
  } else if (req.files !== undefined) {
    multipart.discardFiles(req.files);
  }
});