formstream

A multipart/form-data encoded stream, helper for file upload.

Install

npm install formstream

Quick Start

var formstream = require('formstream');
var http = require('http');

var form = formstream();

// form.file('file', filepath, filename);
form.file('file', './logo.png', 'upload-logo.png');

// other form fields
form.field('foo', 'fengmk2').field('love', 'aerdeng');

// even send file content buffer directly
// form.buffer(name, buffer, filename, mimeType)
form.buffer('file2', new Buffer('This is file2 content.'), 'foo.txt');

var options = {
  method: 'POST',
  host: 'upload.cnodejs.net',
  path: '/store',
  headers: form.headers()
};
var req = http.request(options, function (res) {
  console.log('Status: %s', res.statusCode);
  res.on('data', function (data) {
    console.log(data.toString());
  });
});

form.pipe(req);

Chaining

var fs = require('fs');
var formstream = require('formstream');

var filepath = './logo.png';
fs.stat(filepath, function (err, stat) {
  formstream()
    .field('status', 'share picture')
    .field('access_token', 'your access token')
    .file('pic', filepath, 'logo.png', stat.size)
    .pipe(process.stdout); // your request stream
});

Set min chunk buffer size

Some web servers have a limit on the number of chunks, and you can set minChunkSize to ensure the size of chunk sent to the server.

var fs = require('fs');
var FormStream = require('formstream');

var filepath = './big-file.zip';
fs.stat(filepath, function (err, stat) {
  new FormStream({
    // send >= 2MB chunk buffer size to the server
    minChunkSize: 1024 * 1024 * 2,
  }).field('status', 'share file')
    .field('access_token', 'your access token')
    .file('file', filepath, 'big-file.zip', stat.size)
    .pipe(process.stdout); // your request stream
});

API Doc

formstream([options])

Create a form instance.

Arguments

• options.minChunkSize Number - min chunk size to emit data event

Returns

Form - form instance

FormStream#field(name, value)

Add a normal field to the form.

Arguments

• name String - Name of field
• value String - Value of field

Returns

Form - form instance

FormStream#file(name, filepath[, filename][, filesize])

Add a local file to be uploaded to the form.

Arguments

• name String - Name of file field
• filepath String - Local path of the file to be uploaded
• filename String - Optional. Name of the file (will be the base name of filepath if empty)
• filesize Number - Optional. Size of the file (will not generate Content-Length header if not specified)

Returns

Form - form instance

FormStream#buffer(name, buffer, filename[, contentType])

Add a buffer as a file to upload.

Arguments

• name String - Name of field
• buffer Buffer - The buffer to be uploaded
• filename String - The file name that tells the remote server
• contentType String - Optional. Content-Type (aka. MIME Type) of content (will be infered with filename if empty)

Returns

Form - form instance

FormStream#stream(name, stream, filename[, contentType][, size])

Add a readable stream as a file to upload. Event 'error' will be emitted if an error occured.

Arguments

• name String - Name of field
• stream stream.Readable - A readable stream to be piped
• filename String - The file name that tells the remote server
• contentType String - Optional. Content-Type (aka. MIME Type) of content (will be infered with filename if empty)
• size Number - Optional. Size of the stream (will not generate Content-Length header if not specified)

Returns

Form - form instance

FormStream#headers([headers])

Get headers for the request.

Arguments

• headers Object - Additional headers

Example

var headers = form.headers({
  'Authorization': 'Bearer kei2akc92jmznvnkeh09sknzdk',
  'Accept': 'application/vnd.github.v3.full+json'
});

Returns

Object - Headers to be sent.

Event 'error'

Emitted if there was an error receiving data.

Event 'data'

The 'data' event emits when a Buffer was used.

See Node.js Documentation for more.

Event 'end'

Emitted when the stream has received no more 'data' events will happen.

See Node.js Documentation for more.

License

MIT

Contributors

|fengmk2|xingrz|semantic-release-bot|fjc0k|mrspeiser|dead-horse| | :---: | :---: | :---: | :---: | :---: | :---: | shaozj

This project follows the git-contributor spec, auto updated at Wed May 15 2024 00:34:12 GMT+0800.