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

Field names and filenames use percent encoding for carriage returns (%0D), line feeds (%0A), and double quotes (%22) in multipart headers. Other characters and field contents remain unchanged. The field(), buffer(), and stream() methods throw a TypeError synchronously if a supplied MIME type contains a carriage return or line feed.

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[, mimeType])

Add a normal field to the form.

Arguments

• name String - Name of field
• value String - Value of field
• mimeType String - Optional. Content-Type of the 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.

Releasing

Maintainers prepare releases through a pull request that updates the version in package.json and describes the changes in CHANGELOG.md. To update the version without creating a commit or tag, run npm version patch --no-git-tag-version (or use minor, major, or an explicit version).

After the PR merges into master, release.yml compares the package versions before and after the push. It publishes only when the version changes. The workflow skips versions already on npm, runs the project checks, and publishes with npm trusted publishing and provenance. Stable versions use the latest dist-tag; prerelease versions use next.

After npm publishing succeeds, the workflow creates a GitHub release with a v<version> tag at the commit that triggered the workflow and automatically generated release notes. Prerelease versions are marked as GitHub prereleases. To retry a failed release, rerun the failed workflow in GitHub Actions. If the version is already on npm, the workflow still creates the missing GitHub release. Existing GitHub releases remain unchanged.

Configure the formstream package's trusted publisher on npm with these values:

• Provider: GitHub Actions
• Organization: node-modules
• Repository: formstream
• Workflow filename: release.yml
• Environment: leave empty
• Allow direct publishing with npm publish

The workflow uses OIDC and does not require an NPM_TOKEN or GIT_TOKEN secret. See the npm trusted publishing documentation for package configuration instructions.

License

MIT

Contributors

Made with contributors-img.