formdata-parser v1.0.2

formdata-parser

Install

npm install formdata-parser

Usage

Express

var express = require('express'),
    app = express(),
    formdata = require('formdata-parser')
    
app.use(formdata({
    /* Options */
    dataKey = 'formData',
    uploadTo: __dirname + '/tmp',
    maxFileSize: '2.5M'
}))

app.post('/', (req, res) => {
    /* 
        Received data available on req.formData 
        Uploaded files that are less than or equal to 2.5M in size
        will be stored in the 'tmp' directory off the main project directory
    */
})

Options

• dataKey: (String) The name of the data object to add to req. Defaults to form
• encoding: (String) The data encoding type. Defaults to 'utf-8'
• lineEndings: (String) How to convert line endings in the submitted data for text input such as <textarea> tags. Defaults to the operating system specific end of line marker for the server (\n on POSIX machines, \r\n on Windows machines).
• uploadTo: (String) The directory where uploaded files will be stored. Defaults to the operating system's default directory for temporary files.
• maxFileSize: (String) The maximum file size that will be accepted by the server. Defaults to '0' for no file size limit. The string can consist of any number followed by an optional unit. The available units are K, M, and G. Units are case-insensitive.

Results

The submitted form data will be placed on the req object as an object under the key name provided in the dataKey option. The form data will be organized as key-value pairs, with the form input name as the key. If an input name is repeated in the form, the values sent will be placed in an array under the key name.

Files will be checked against the size limit given in the maxFileSize option, and saved in the directory given in the uploadTo option. File names will be pre-pended with a timestamp to reduce the chance of another upload accidentally overwriting a file before it is processed. For each file that is successfully uploaded, an object will be placed in the results with the following keys:

• filename: The original name of the file
• path: The path of the uploaded file
• size: The size of the uploaded file

If the file a file is too large, a RangeError object will be placed in the results. If the file could not be saved to the server, an Error object will be placed in the results. If no file is selected to be uploaded on a form with a file input, the value of the result key will be null.

Examples

• A simple form to get the name and email address of a visitor

<form action="/form" method="POST">
    <input type="text" name="name" />
    <input type="email" name="email" />
    <input type="submit">
</form>

Result

req: {
    form: {
        name: 'Entered Name',
        email: 'Entered Email'
    }
}

• A form to upload a file

<form action="/form" method="POST" enctype="multipart/form-data">
    <input type="file" name="upload">
    <input type="submit">
</form>

Result

// If the file is successfully uploaded:
req: {
    form: {
        upload: {
            filename: 'myfile.ext',
            path: '/project_dir/tmp',
            temp_name: '1488558312973_myfile.ext',
            size: 1999
        }
    }
}

// If the file is too large
req: {
    form: {
        upload: <RangeError Object>
    }
}

// If the file can't be saved
req: {
    form: {
        upload: <Error Object>
    }
}

// If no file was chosen to be uploaded
req: {
    form: {
        upload: null
    }
}

• A form with repeated input names

<form action="/form" method="POST">
    <input type="text" name="loginInfo" placeholder="User ID" />
    <input type="password" name="loginInfo" placeholder="Password" />
    <input type="submit">
</form>

Result

req: {
    form: {
        loginInfo: ['myUserID', 'myPassword']
    }
}

A form that accepts multiple files

<form action="/form" method="POST" enctype="multipart/form-data">
    <input type="file" name="upload" multiple>
    <input type="submit">
</form>

Result

req: {
    form: {
        upload: [
            {
                filename: 'myfile1.ext',
                path: '/project_dir/tmp',
                temp_name: '1488558312973_myfile1.ext',
                size: 1999
            },
            {
                filename: 'myfile2.ext',
                path: '/project_dir/tmp',
                temp_name: '1488558312977_myfile2.ext',
                size: 8437
            }
        ]
    }
}