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

Functions

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 |