UNPKG

8.53 kB Markdown View Raw
1Description
2===========
3
4A node.js module for parsing incoming HTML form data.
5
6
7Requirements
8============
9
10* [node.js](http://nodejs.org/) -- v4.5.0 or newer
11
12
13Install
14=======
15
16 npm install busboy
17
18
19Examples
20========
21
22* Parsing (multipart) with default options:
23
24```javascript
25var http = require('http'),
26 inspect = require('util').inspect;
27
28var Busboy = require('busboy');
29
30http.createServer(function(req, res) {
31 if (req.method === 'POST') {
32 var busboy = new Busboy({ headers: req.headers });
33 busboy.on('file', function(fieldname, file, filename, encoding, mimetype) {
34 console.log('File [' + fieldname + ']: filename: ' + filename + ', encoding: ' + encoding + ', mimetype: ' + mimetype);
35 file.on('data', function(data) {
36 console.log('File [' + fieldname + '] got ' + data.length + ' bytes');
37 });
38 file.on('end', function() {
39 console.log('File [' + fieldname + '] Finished');
40 });
41 });
42 busboy.on('field', function(fieldname, val, fieldnameTruncated, valTruncated, encoding, mimetype) {
43 console.log('Field [' + fieldname + ']: value: ' + inspect(val));
44 });
45 busboy.on('finish', function() {
46 console.log('Done parsing form!');
47 res.writeHead(303, { Connection: 'close', Location: '/' });
48 res.end();
49 });
50 req.pipe(busboy);
51 } else if (req.method === 'GET') {
52 res.writeHead(200, { Connection: 'close' });
53 res.end('<html><head></head><body>\
54 <form method="POST" enctype="multipart/form-data">\
55 <input type="text" name="textfield"><br />\
56 <input type="file" name="filefield"><br />\
57 <input type="submit">\
58 </form>\
59 </body></html>');
60 }
61}).listen(8000, function() {
62 console.log('Listening for requests');
63});
64
65// Example output, using http://nodejs.org/images/ryan-speaker.jpg as the file:
66//
67// Listening for requests
68// File [filefield]: filename: ryan-speaker.jpg, encoding: binary
69// File [filefield] got 11971 bytes
70// Field [textfield]: value: 'testing! :-)'
71// File [filefield] Finished
72// Done parsing form!
73```
74
75* Save all incoming files to disk:
76
77```javascript
78var http = require('http'),
79 path = require('path'),
80 os = require('os'),
81 fs = require('fs');
82
83var Busboy = require('busboy');
84
85http.createServer(function(req, res) {
86 if (req.method === 'POST') {
87 var busboy = new Busboy({ headers: req.headers });
88 busboy.on('file', function(fieldname, file, filename, encoding, mimetype) {
89 var saveTo = path.join(os.tmpDir(), path.basename(fieldname));
90 file.pipe(fs.createWriteStream(saveTo));
91 });
92 busboy.on('finish', function() {
93 res.writeHead(200, { 'Connection': 'close' });
94 res.end("That's all folks!");
95 });
96 return req.pipe(busboy);
97 }
98 res.writeHead(404);
99 res.end();
100}).listen(8000, function() {
101 console.log('Listening for requests');
102});
103```
104
105* Parsing (urlencoded) with default options:
106
107```javascript
108var http = require('http'),
109 inspect = require('util').inspect;
110
111var Busboy = require('busboy');
112
113http.createServer(function(req, res) {
114 if (req.method === 'POST') {
115 var busboy = new Busboy({ headers: req.headers });
116 busboy.on('file', function(fieldname, file, filename, encoding, mimetype) {
117 console.log('File [' + fieldname + ']: filename: ' + filename);
118 file.on('data', function(data) {
119 console.log('File [' + fieldname + '] got ' + data.length + ' bytes');
120 });
121 file.on('end', function() {
122 console.log('File [' + fieldname + '] Finished');
123 });
124 });
125 busboy.on('field', function(fieldname, val, fieldnameTruncated, valTruncated) {
126 console.log('Field [' + fieldname + ']: value: ' + inspect(val));
127 });
128 busboy.on('finish', function() {
129 console.log('Done parsing form!');
130 res.writeHead(303, { Connection: 'close', Location: '/' });
131 res.end();
132 });
133 req.pipe(busboy);
134 } else if (req.method === 'GET') {
135 res.writeHead(200, { Connection: 'close' });
136 res.end('<html><head></head><body>\
137 <form method="POST">\
138 <input type="text" name="textfield"><br />\
139 <select name="selectfield">\
140 <option value="1">1</option>\
141 <option value="10">10</option>\
142 <option value="100">100</option>\
143 <option value="9001">9001</option>\
144 </select><br />\
145 <input type="checkbox" name="checkfield">Node.js rules!<br />\
146 <input type="submit">\
147 </form>\
148 </body></html>');
149 }
150}).listen(8000, function() {
151 console.log('Listening for requests');
152});
153
154// Example output:
155//
156// Listening for requests
157// Field [textfield]: value: 'testing! :-)'
158// Field [selectfield]: value: '9001'
159// Field [checkfield]: value: 'on'
160// Done parsing form!
161```
162
163
164API
165===
166
167_Busboy_ is a _Writable_ stream
168
169Busboy (special) events
170-----------------------
171
172* **file**(< _string_ >fieldname, < _ReadableStream_ >stream, < _string_ >filename, < _string_ >transferEncoding, < _string_ >mimeType) - Emitted for each new file form field found. `transferEncoding` contains the 'Content-Transfer-Encoding' value for the file stream. `mimeType` contains the 'Content-Type' value for the file stream.
173 * Note: if you listen for this event, you should always handle the `stream` no matter if you care about the file contents or not (e.g. you can simply just do `stream.resume();` if you want to discard the contents), otherwise the 'finish' event will never fire on the Busboy instance. However, if you don't care about **any** incoming files, you can simply not listen for the 'file' event at all and any/all files will be automatically and safely discarded (these discarded files do still count towards `files` and `parts` limits).
174 * If a configured file size limit was reached, `stream` will both have a boolean property `truncated` (best checked at the end of the stream) and emit a 'limit' event to notify you when this happens.
175
176* **field**(< _string_ >fieldname, < _string_ >value, < _boolean_ >fieldnameTruncated, < _boolean_ >valueTruncated, < _string_ >transferEncoding, < _string_ >mimeType) - Emitted for each new non-file field found.
177
178* **partsLimit**() - Emitted when specified `parts` limit has been reached. No more 'file' or 'field' events will be emitted.
179
180* **filesLimit**() - Emitted when specified `files` limit has been reached. No more 'file' events will be emitted.
181
182* **fieldsLimit**() - Emitted when specified `fields` limit has been reached. No more 'field' events will be emitted.
183
184
185Busboy methods
186--------------
187
188* **(constructor)**(< _object_ >config) - Creates and returns a new Busboy instance.
189
190 * The constructor takes the following valid `config` settings:
191
192 * **headers** - _object_ - These are the HTTP headers of the incoming request, which are used by individual parsers.
193
194 * **highWaterMark** - _integer_ - highWaterMark to use for this Busboy instance (Default: WritableStream default).
195
196 * **fileHwm** - _integer_ - highWaterMark to use for file streams (Default: ReadableStream default).
197
198 * **defCharset** - _string_ - Default character set to use when one isn't defined (Default: 'utf8').
199
200 * **preservePath** - _boolean_ - If paths in the multipart 'filename' field shall be preserved. (Default: false).
201
202 * **limits** - _object_ - Various limits on incoming data. Valid properties are:
203
204 * **fieldNameSize** - _integer_ - Max field name size (in bytes) (Default: 100 bytes).
205
206 * **fieldSize** - _integer_ - Max field value size (in bytes) (Default: 1MB).
207
208 * **fields** - _integer_ - Max number of non-file fields (Default: Infinity).
209
210 * **fileSize** - _integer_ - For multipart forms, the max file size (in bytes) (Default: Infinity).
211
212 * **files** - _integer_ - For multipart forms, the max number of file fields (Default: Infinity).
213
214 * **parts** - _integer_ - For multipart forms, the max number of parts (fields + files) (Default: Infinity).
215
216 * **headerPairs** - _integer_ - For multipart forms, the max number of header key=>value pairs to parse **Default:** 2000 (same as node's http).
217
218 * The constructor can throw errors:
219
220 * **Unsupported content type: $type** - The `Content-Type` isn't one Busboy can parse.
221
222 * **Missing Content-Type** - The provided headers don't include `Content-Type` at all.