BlueGit

blue-star danique-bot

Files

danique-bot / node_modules / form-data / README.md

README.md

Import template
timfa Tim · pushed by timfa · 4 years ago
c788ad20 History
README.md 7.0 KiB Download Raw

Form-Data NPM Module Join the chat at https://gitter.im/form-data/form-data

A library to create readable "multipart/form-data" streams. Can be used to submit forms and file uploads to other web applications.

The API of this library is inspired by the [XMLHttpRequest-2 FormData Interface][xhr2-fd].

[xhr2-fd]: http://dev.w3.org/2006/webapi/XMLHttpRequest-2/Overview.html#the-formdata-interface

Linux Build MacOS Build Windows Build

Coverage Status Dependency Status bitHound Overall Score

Install

npm install --save form-data

Usage

In this example we are constructing a form with 3 fields that contain a string, a buffer and a file stream.

var FormData = require('form-data');
var fs = require('fs');

var form = new FormData();
form.append('my_field', 'my value');
form.append('my_buffer', new Buffer(10));
form.append('my_file', fs.createReadStream('/foo/bar.jpg'));

Also you can use http-response stream:

var FormData = require('form-data');
var http = require('http');

var form = new FormData();

http.request('http://nodejs.org/images/logo.png', function(response) {
  form.append('my_field', 'my value');
  form.append('my_buffer', new Buffer(10));
  form.append('my_logo', response);
});

Or @mikeal's request stream:

var FormData = require('form-data');
var request = require('request');

var form = new FormData();

form.append('my_field', 'my value');
form.append('my_buffer', new Buffer(10));
form.append('my_logo', request('http://nodejs.org/images/logo.png'));

In order to submit this form to a web application, call submit(url, [callback]) method:

form.submit('http://example.org/', function(err, res) {
  // res – response object (http.IncomingMessage)  //
  res.resume();
});

For more advanced request manipulations submit() method returns http.ClientRequest object, or you can choose from one of the alternative submission methods.

Custom options

You can provide custom options, such as maxDataSize:

var FormData = require('form-data');

var form = new FormData({ maxDataSize: 20971520 });
form.append('my_field', 'my value');
form.append('my_buffer', /* something big */);

List of available options could be found in combined-stream

Alternative submission methods

You can use node's http client interface:

var http = require('http');

var request = http.request({
  method: 'post',
  host: 'example.org',
  path: '/upload',
  headers: form.getHeaders()
});

form.pipe(request);

request.on('response', function(res) {
  console.log(res.statusCode);
});

Or if you would prefer the 'Content-Length' header to be set for you:

form.submit('example.org/upload', function(err, res) {
  console.log(res.statusCode);
});

To use custom headers and pre-known length in parts:

var CRLF = '\r\n';
var form = new FormData();

var options = {
  header: CRLF + '--' + form.getBoundary() + CRLF + 'X-Custom-Header: 123' + CRLF + CRLF,
  knownLength: 1
};

form.append('my_buffer', buffer, options);

form.submit('http://example.com/', function(err, res) {
  if (err) throw err;
  console.log('Done');
});

Form-Data can recognize and fetch all the required information from common types of streams (fs.readStream, http.response and mikeal's request), for some other types of streams you'd need to provide "file"-related information manually:

someModule.stream(function(err, stdout, stderr) {
  if (err) throw err;

  var form = new FormData();

  form.append('file', stdout, {
    filename: 'unicycle.jpg', // ... or:
    filepath: 'photos/toys/unicycle.jpg',
    contentType: 'image/jpeg',
    knownLength: 19806
  });

  form.submit('http://example.com/', function(err, res) {
    if (err) throw err;
    console.log('Done');
  });
});

The filepath property overrides filename and may contain a relative path. This is typically used when uploading multiple files from a directory.

For edge cases, like POST request to URL with query string or to pass HTTP auth credentials, object can be passed to form.submit() as first parameter:

form.submit({
  host: 'example.com',
  path: '/probably.php?extra=params',
  auth: 'username:password'
}, function(err, res) {
  console.log(res.statusCode);
});

In case you need to also send custom HTTP headers with the POST request, you can use the headers key in first parameter of form.submit():

form.submit({
  host: 'example.com',
  path: '/surelynot.php',
  headers: {'x-test-header': 'test-header-value'}
}, function(err, res) {
  console.log(res.statusCode);
});

Integration with other libraries

Request

Form submission using request:

var formData = {
  my_field: 'my_value',
  my_file: fs.createReadStream(__dirname + '/unicycle.jpg'),
};

request.post({url:'http://service.com/upload', formData: formData}, function(err, httpResponse, body) {
  if (err) {
    return console.error('upload failed:', err);
  }
  console.log('Upload successful!  Server responded with:', body);
});

For more details see request readme.

node-fetch

You can also submit a form using node-fetch:

var form = new FormData();

form.append('a', 1);

fetch('http://example.com', { method: 'POST', body: form })
    .then(function(res) {
        return res.json();
    }).then(function(json) {
        console.log(json);
    });

Notes

  • getLengthSync() method DOESN'T calculate length for streams, use knownLength options as workaround.
  • Starting version 2.x FormData has dropped support for node@0.10.x.

License

Form-Data is released under the MIT license.

Source
1# Form-Data [![NPM Module](https://img.shields.io/npm/v/form-data.svg)](https://www.npmjs.com/package/form-data) [![Join the chat at https://gitter.im/form-data/form-data](http://form-data.github.io/images/gitterbadge.svg)](https://gitter.im/form-data/form-data)
2
3A library to create readable ```"multipart/form-data"``` streams. Can be used to submit forms and file uploads to other web applications.
4
5The API of this library is inspired by the [XMLHttpRequest-2 FormData Interface][xhr2-fd].
6
7[xhr2-fd]: http://dev.w3.org/2006/webapi/XMLHttpRequest-2/Overview.html#the-formdata-interface
8
9[![Linux Build](https://img.shields.io/travis/form-data/form-data/v2.3.2.svg?label=linux:4.x-9.x)](https://travis-ci.org/form-data/form-data)
10[![MacOS Build](https://img.shields.io/travis/form-data/form-data/v2.3.2.svg?label=macos:4.x-9.x)](https://travis-ci.org/form-data/form-data)
11[![Windows Build](https://img.shields.io/appveyor/ci/alexindigo/form-data/v2.3.2.svg?label=windows:4.x-9.x)](https://ci.appveyor.com/project/alexindigo/form-data)
12
13[![Coverage Status](https://img.shields.io/coveralls/form-data/form-data/v2.3.2.svg?label=code+coverage)](https://coveralls.io/github/form-data/form-data?branch=master)
14[![Dependency Status](https://img.shields.io/david/form-data/form-data.svg)](https://david-dm.org/form-data/form-data)
15[![bitHound Overall Score](https://www.bithound.io/github/form-data/form-data/badges/score.svg)](https://www.bithound.io/github/form-data/form-data)
16
17## Install
18
19```
20npm install --save form-data
21```
22
23## Usage
24
25In this example we are constructing a form with 3 fields that contain a string,
26a buffer and a file stream.
27
28``` javascript
29var FormData = require('form-data');
30var fs = require('fs');
31
32var form = new FormData();
33form.append('my_field', 'my value');
34form.append('my_buffer', new Buffer(10));
35form.append('my_file', fs.createReadStream('/foo/bar.jpg'));
36```
37
38Also you can use http-response stream:
39
40``` javascript
41var FormData = require('form-data');
42var http = require('http');
43
44var form = new FormData();
45
46http.request('http://nodejs.org/images/logo.png', function(response) {
47 form.append('my_field', 'my value');
48 form.append('my_buffer', new Buffer(10));
49 form.append('my_logo', response);
50});
51```
52
53Or @mikeal's [request](https://github.com/request/request) stream:
54
55``` javascript
56var FormData = require('form-data');
57var request = require('request');
58
59var form = new FormData();
60
61form.append('my_field', 'my value');
62form.append('my_buffer', new Buffer(10));
63form.append('my_logo', request('http://nodejs.org/images/logo.png'));
64```
65
66In order to submit this form to a web application, call ```submit(url, [callback])``` method:
67
68``` javascript
69form.submit('http://example.org/', function(err, res) {
70 // res – response object (http.IncomingMessage) //
71 res.resume();
72});
73
74```
75
76For more advanced request manipulations ```submit()``` method returns ```http.ClientRequest``` object, or you can choose from one of the alternative submission methods.
77
78### Custom options
79
80You can provide custom options, such as `maxDataSize`:
81
82``` javascript
83var FormData = require('form-data');
84
85var form = new FormData({ maxDataSize: 20971520 });
86form.append('my_field', 'my value');
87form.append('my_buffer', /* something big */);
88```
89
90List of available options could be found in [combined-stream](https://github.com/felixge/node-combined-stream/blob/master/lib/combined_stream.js#L7-L15)
91
92### Alternative submission methods
93
94You can use node's http client interface:
95
96``` javascript
97var http = require('http');
98
99var request = http.request({
100 method: 'post',
101 host: 'example.org',
102 path: '/upload',
103 headers: form.getHeaders()
104});
105
106form.pipe(request);
107
108request.on('response', function(res) {
109 console.log(res.statusCode);
110});
111```
112
113Or if you would prefer the `'Content-Length'` header to be set for you:
114
115``` javascript
116form.submit('example.org/upload', function(err, res) {
117 console.log(res.statusCode);
118});
119```
120
121To use custom headers and pre-known length in parts:
122
123``` javascript
124var CRLF = '\r\n';
125var form = new FormData();
126
127var options = {
128 header: CRLF + '--' + form.getBoundary() + CRLF + 'X-Custom-Header: 123' + CRLF + CRLF,
129 knownLength: 1
130};
131
132form.append('my_buffer', buffer, options);
133
134form.submit('http://example.com/', function(err, res) {
135 if (err) throw err;
136 console.log('Done');
137});
138```
139
140Form-Data can recognize and fetch all the required information from common types of streams (```fs.readStream```, ```http.response``` and ```mikeal's request```), for some other types of streams you'd need to provide "file"-related information manually:
141
142``` javascript
143someModule.stream(function(err, stdout, stderr) {
144 if (err) throw err;
145
146 var form = new FormData();
147
148 form.append('file', stdout, {
149 filename: 'unicycle.jpg', // ... or:
150 filepath: 'photos/toys/unicycle.jpg',
151 contentType: 'image/jpeg',
152 knownLength: 19806
153 });
154
155 form.submit('http://example.com/', function(err, res) {
156 if (err) throw err;
157 console.log('Done');
158 });
159});
160```
161
162The `filepath` property overrides `filename` and may contain a relative path. This is typically used when uploading [multiple files from a directory](https://wicg.github.io/entries-api/#dom-htmlinputelement-webkitdirectory).
163
164For edge cases, like POST request to URL with query string or to pass HTTP auth credentials, object can be passed to `form.submit()` as first parameter:
165
166``` javascript
167form.submit({
168 host: 'example.com',
169 path: '/probably.php?extra=params',
170 auth: 'username:password'
171}, function(err, res) {
172 console.log(res.statusCode);
173});
174```
175
176In case you need to also send custom HTTP headers with the POST request, you can use the `headers` key in first parameter of `form.submit()`:
177
178``` javascript
179form.submit({
180 host: 'example.com',
181 path: '/surelynot.php',
182 headers: {'x-test-header': 'test-header-value'}
183}, function(err, res) {
184 console.log(res.statusCode);
185});
186```
187
188### Integration with other libraries
189
190#### Request
191
192Form submission using [request](https://github.com/request/request):
193
194```javascript
195var formData = {
196 my_field: 'my_value',
197 my_file: fs.createReadStream(__dirname + '/unicycle.jpg'),
198};
199
200request.post({url:'http://service.com/upload', formData: formData}, function(err, httpResponse, body) {
201 if (err) {
202 return console.error('upload failed:', err);
203 }
204 console.log('Upload successful! Server responded with:', body);
205});
206```
207
208For more details see [request readme](https://github.com/request/request#multipartform-data-multipart-form-uploads).
209
210#### node-fetch
211
212You can also submit a form using [node-fetch](https://github.com/bitinn/node-fetch):
213
214```javascript
215var form = new FormData();
216
217form.append('a', 1);
218
219fetch('http://example.com', { method: 'POST', body: form })
220 .then(function(res) {
221 return res.json();
222 }).then(function(json) {
223 console.log(json);
224 });
225```
226
227## Notes
228
229- ```getLengthSync()``` method DOESN'T calculate length for streams, use ```knownLength``` options as workaround.
230- Starting version `2.x` FormData has dropped support for `node@0.10.x`.
231
232## License
233
234Form-Data is released under the [MIT](License) license.