prg-uploader

Pragonauts Uploader

Busboy based utility, which helps us:

1. Processes the multipart/form-data with busboy
2. Validates uploads (mime type and size)
3. Transforms each upload to a Promise (by default to Buffer)
4. After all resolves promise

Example

 
const express = require('express');
const { Uploader, terminateStream } = require('prg-uploader');
 
const app = new express.Router();
 
app.post('/', (req, res) => {
 
    const uploader = new Uploader();
 
    uploader.addFile('image', terminateStream, '1mb', [
        'image/gif',
        'image/jpeg',
        'image/png'
    ]);
 
    uploader.process(req)
        .then((data) => {
            res.send({
                ok: 1,
                receivedMimeType: data.image.type,
                receivedFileSize; data.image.size, // same as buffer length
                receivedDataLength: data.image.data.length,
                isBuffer: Buffer.isBuffer(data.image.data) // true
            });
        })
        .catch((e) => {
            res.status(e.status) // 413=file size exceeded, 415=mime does not match
                .send(e.message);
        });
}));
 
module.exports = app;
 

Using with Pragonauts validator

Uploader uses validation rules from Validator and runs validator with given data

 
const express = require('express');
const Validator = require('prg-validator');
const { Uploader, terminateStream } = require('prg-uploader');
 
const app = new express.Router();
 
 
const validator = new Validator();
 
validator.add('file')
    .isFileMaxLength('shlould be smaller then 1Mb', '1m')
    .isFileMime('Should be an excel file', [
        'application/vnd.ms-excel',
        'application/msexcel',
        'application/x-msexcel',
        'application/x-ms-excel',
        'application/x-excel',
        'application/x-dos_ms_excel',
        'application/xls',
        'application/x-xls',
        'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'
    ])
    .toFileData(); // extracts buffer from the file
 
app.post('/', (req, res) => {
 
    const uploader = new Uploader(validator);
 
    uploader.addFile('file');
 
    uploader.process(req)
        .then((data) => {
            res.send({
                ok: 1,
                receivedDataLength: data.file.length,
                isBuffer: Buffer.isBuffer(data.file) // true
            });
        })
        .catch((e) => {
            res.status(e.status) // 413=file size exceeded, 415=mime does not match
                .send(e.message);
        });
}));
 
module.exports = app;
 

---

API

Classes

Uploader

LimitedStream ⇐ Transform

Functions

terminateStream(readableStream) ⇒ Promise.<Buffer>

Converts a stream to buffer

Uploader

Kind: global class

• Uploader
  • new Uploader()
  • instance
    • .addFile(field, [processor], [maxLength], [allowedMimes]) ⇒ this
    • .process(req, [validatorContext]) ⇒ Promise.<object>
  • static
    • .Uploader
      • new Uploader([validator])

new Uploader()

The NodeJs multipart/form-data processor

uploader.addFile(field, [processor], [maxLength], [allowedMimes]) ⇒ this

Add a file upload

Kind: instance method of Uploader

Param	Type	Default	Description
field	string		field name
[processor]	function	terminateStream	the request processor
[maxLength]	number		size limit
[allowedMimes]	Array.<string>		accept only theese mime types (strings or RegExps)

Example

// process upload on own using callback
 
uploader.addFile('fieldName', (stream, filename, encoding, mimetype) => {
    if (mimetype !== 'image/png') {
        stream.resume(); // call when stream is not used
        return Promise.resolve(null);
    }
    // process the stream and return Promise
    return Promise.resolve('the result of processing stream');
})

uploader.process(req, [validatorContext]) ⇒ Promise.<object>

Process the uploads

Kind: instance method of Uploader

Param	Type	Default	Description
req	any		the request
[validatorContext]	string	null	the context to validator

Uploader.Uploader

Kind: static class of Uploader

new Uploader([validator])

Creates an instance of Uploader.

Param	Type	Default	Description
[validator]	any		instance of prg-validator

LimitedStream ⇐ Transform

Kind: global class Extends: Transform

• LimitedStream ⇐ Transform
  • new LimitedStream()
  • .LimitedStream
    • new LimitedStream(options)

new LimitedStream()

Stream which throws error, when size of stream exceeds allowed length

Example

const stream = new LimitedStream({ maxLength: 1024 }); // 1Kb
stream.on('error', (err) => {
   if (err.code === 413) {
      // size exceeded
   }
});

LimitedStream.LimitedStream

Kind: static class of LimitedStream

new LimitedStream(options)

Creates an instance of LimitedStream.

Param	Type	Description
options	Object
[options.maxLength]	number	the maximal length in bytes

terminateStream(readableStream) ⇒ Promise.<Buffer>

Converts a stream to buffer

Kind: global function

Param	Type
readableStream	ReadableStream