formstream
v1.5.3
Published
A multipart/form-data encoded stream, helper for file upload.
Readme
formstream
A multipart/form-data encoded stream, helper for file upload.
Install
npm install formstreamQuick 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
filepathif empty) - filesize Number - Optional. Size of the file (will not generate
Content-Lengthheader 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
filenameif 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
filenameif empty) - size Number - Optional. Size of the stream (will not generate
Content-Lengthheader 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
Contributors
Made with contributors-img.
