# formstream
[![NPM version][npm-image]][npm-url]
[](https://github.com/node-modules/formstream/actions/workflows/ci.yml)
[![Test coverage][codecov-image]][codecov-url]
[![npm download][download-image]][download-url]
[npm-image]: https://img.shields.io/npm/v/formstream.svg?style=flat-square
[npm-url]: https://npmjs.org/package/formstream
[codecov-image]: https://codecov.io/github/node-modules/formstream/coverage.svg?branch=master
[codecov-url]: https://codecov.io/github/node-modules/formstream?branch=master
[download-image]: https://img.shields.io/npm/dm/formstream.svg?style=flat-square
[download-url]: https://npmjs.org/package/formstream
A [multipart/form-data](http://tools.ietf.org/html/rfc2388) encoded stream, helper for file upload.
## Install
```bash
npm install formstream
```
## Quick Start
```js
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
```js
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.
```js
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](http://nodejs.org/api/stream.html#stream_class_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
```js
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](http://nodejs.org/api/stream.html#stream_event_data) for more.
### Event 'end'
Emitted when the stream has received no more 'data' events will happen.
See [Node.js Documentation](http://nodejs.org/api/stream.html#stream_event_end) for more.
## License
[MIT](LICENSE)
## Contributors
|[
fengmk2](https://github.com/fengmk2)
|[
xingrz](https://github.com/xingrz)
|[
semantic-release-bot](https://github.com/semantic-release-bot)
|[
fjc0k](https://github.com/fjc0k)
|[
mrspeiser](https://github.com/mrspeiser)
|[
dead-horse](https://github.com/dead-horse)
|
| :---: | :---: | :---: | :---: | :---: | :---: |
[
shaozj](https://github.com/shaozj)
This project follows the git-contributor [spec](https://github.com/xudafeng/git-contributor), auto updated at `Wed May 15 2024 00:34:12 GMT+0800`.