1 | # body-parser
|
2 |
|
3 | [![NPM Version][npm-version-image]][npm-url]
|
4 | [![NPM Downloads][npm-downloads-image]][npm-url]
|
5 | [![Build Status][ci-image]][ci-url]
|
6 | [![Test Coverage][coveralls-image]][coveralls-url]
|
7 |
|
8 | Node.js body parsing middleware.
|
9 |
|
10 | Parse incoming request bodies in a middleware before your handlers, available
|
11 | under the `req.body` property.
|
12 |
|
13 | **Note** As `req.body`'s shape is based on user-controlled input, all
|
14 | properties and values in this object are untrusted and should be validated
|
15 | before trusting. For example, `req.body.foo.toString()` may fail in multiple
|
16 | ways, for example the `foo` property may not be there or may not be a string,
|
17 | and `toString` may not be a function and instead a string or other user input.
|
18 |
|
19 | [Learn about the anatomy of an HTTP transaction in Node.js](https://nodejs.org/en/docs/guides/anatomy-of-an-http-transaction/).
|
20 |
|
21 | _This does not handle multipart bodies_, due to their complex and typically
|
22 | large nature. For multipart bodies, you may be interested in the following
|
23 | modules:
|
24 |
|
25 | * [busboy](https://www.npmjs.org/package/busboy#readme) and
|
26 | [connect-busboy](https://www.npmjs.org/package/connect-busboy#readme)
|
27 | * [multiparty](https://www.npmjs.org/package/multiparty#readme) and
|
28 | [connect-multiparty](https://www.npmjs.org/package/connect-multiparty#readme)
|
29 | * [formidable](https://www.npmjs.org/package/formidable#readme)
|
30 | * [multer](https://www.npmjs.org/package/multer#readme)
|
31 |
|
32 | This module provides the following parsers:
|
33 |
|
34 | * [JSON body parser](#bodyparserjsonoptions)
|
35 | * [Raw body parser](#bodyparserrawoptions)
|
36 | * [Text body parser](#bodyparsertextoptions)
|
37 | * [URL-encoded form body parser](#bodyparserurlencodedoptions)
|
38 |
|
39 | Other body parsers you might be interested in:
|
40 |
|
41 | - [body](https://www.npmjs.org/package/body#readme)
|
42 | - [co-body](https://www.npmjs.org/package/co-body#readme)
|
43 |
|
44 | ## Installation
|
45 |
|
46 | ```sh
|
47 | $ npm install body-parser
|
48 | ```
|
49 |
|
50 | ## API
|
51 |
|
52 | ```js
|
53 | var bodyParser = require('body-parser')
|
54 | ```
|
55 |
|
56 | The `bodyParser` object exposes various factories to create middlewares. All
|
57 | middlewares will populate the `req.body` property with the parsed body when
|
58 | the `Content-Type` request header matches the `type` option, or an empty
|
59 | object (`{}`) if there was no body to parse, the `Content-Type` was not matched,
|
60 | or an error occurred.
|
61 |
|
62 | The various errors returned by this module are described in the
|
63 | [errors section](#errors).
|
64 |
|
65 | ### bodyParser.json([options])
|
66 |
|
67 | Returns middleware that only parses `json` and only looks at requests where
|
68 | the `Content-Type` header matches the `type` option. This parser accepts any
|
69 | Unicode encoding of the body and supports automatic inflation of `gzip` and
|
70 | `deflate` encodings.
|
71 |
|
72 | A new `body` object containing the parsed data is populated on the `request`
|
73 | object after the middleware (i.e. `req.body`).
|
74 |
|
75 | #### Options
|
76 |
|
77 | The `json` function takes an optional `options` object that may contain any of
|
78 | the following keys:
|
79 |
|
80 | ##### inflate
|
81 |
|
82 | When set to `true`, then deflated (compressed) bodies will be inflated; when
|
83 | `false`, deflated bodies are rejected. Defaults to `true`.
|
84 |
|
85 | ##### limit
|
86 |
|
87 | Controls the maximum request body size. If this is a number, then the value
|
88 | specifies the number of bytes; if it is a string, the value is passed to the
|
89 | [bytes](https://www.npmjs.com/package/bytes) library for parsing. Defaults
|
90 | to `'100kb'`.
|
91 |
|
92 | ##### reviver
|
93 |
|
94 | The `reviver` option is passed directly to `JSON.parse` as the second
|
95 | argument. You can find more information on this argument
|
96 | [in the MDN documentation about JSON.parse](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse#Example.3A_Using_the_reviver_parameter).
|
97 |
|
98 | ##### strict
|
99 |
|
100 | When set to `true`, will only accept arrays and objects; when `false` will
|
101 | accept anything `JSON.parse` accepts. Defaults to `true`.
|
102 |
|
103 | ##### type
|
104 |
|
105 | The `type` option is used to determine what media type the middleware will
|
106 | parse. This option can be a string, array of strings, or a function. If not a
|
107 | function, `type` option is passed directly to the
|
108 | [type-is](https://www.npmjs.org/package/type-is#readme) library and this can
|
109 | be an extension name (like `json`), a mime type (like `application/json`), or
|
110 | a mime type with a wildcard (like `*/*` or `*/json`). If a function, the `type`
|
111 | option is called as `fn(req)` and the request is parsed if it returns a truthy
|
112 | value. Defaults to `application/json`.
|
113 |
|
114 | ##### verify
|
115 |
|
116 | The `verify` option, if supplied, is called as `verify(req, res, buf, encoding)`,
|
117 | where `buf` is a `Buffer` of the raw request body and `encoding` is the
|
118 | encoding of the request. The parsing can be aborted by throwing an error.
|
119 |
|
120 | ### bodyParser.raw([options])
|
121 |
|
122 | Returns middleware that parses all bodies as a `Buffer` and only looks at
|
123 | requests where the `Content-Type` header matches the `type` option. This
|
124 | parser supports automatic inflation of `gzip` and `deflate` encodings.
|
125 |
|
126 | A new `body` object containing the parsed data is populated on the `request`
|
127 | object after the middleware (i.e. `req.body`). This will be a `Buffer` object
|
128 | of the body.
|
129 |
|
130 | #### Options
|
131 |
|
132 | The `raw` function takes an optional `options` object that may contain any of
|
133 | the following keys:
|
134 |
|
135 | ##### inflate
|
136 |
|
137 | When set to `true`, then deflated (compressed) bodies will be inflated; when
|
138 | `false`, deflated bodies are rejected. Defaults to `true`.
|
139 |
|
140 | ##### limit
|
141 |
|
142 | Controls the maximum request body size. If this is a number, then the value
|
143 | specifies the number of bytes; if it is a string, the value is passed to the
|
144 | [bytes](https://www.npmjs.com/package/bytes) library for parsing. Defaults
|
145 | to `'100kb'`.
|
146 |
|
147 | ##### type
|
148 |
|
149 | The `type` option is used to determine what media type the middleware will
|
150 | parse. This option can be a string, array of strings, or a function.
|
151 | If not a function, `type` option is passed directly to the
|
152 | [type-is](https://www.npmjs.org/package/type-is#readme) library and this
|
153 | can be an extension name (like `bin`), a mime type (like
|
154 | `application/octet-stream`), or a mime type with a wildcard (like `*/*` or
|
155 | `application/*`). If a function, the `type` option is called as `fn(req)`
|
156 | and the request is parsed if it returns a truthy value. Defaults to
|
157 | `application/octet-stream`.
|
158 |
|
159 | ##### verify
|
160 |
|
161 | The `verify` option, if supplied, is called as `verify(req, res, buf, encoding)`,
|
162 | where `buf` is a `Buffer` of the raw request body and `encoding` is the
|
163 | encoding of the request. The parsing can be aborted by throwing an error.
|
164 |
|
165 | ### bodyParser.text([options])
|
166 |
|
167 | Returns middleware that parses all bodies as a string and only looks at
|
168 | requests where the `Content-Type` header matches the `type` option. This
|
169 | parser supports automatic inflation of `gzip` and `deflate` encodings.
|
170 |
|
171 | A new `body` string containing the parsed data is populated on the `request`
|
172 | object after the middleware (i.e. `req.body`). This will be a string of the
|
173 | body.
|
174 |
|
175 | #### Options
|
176 |
|
177 | The `text` function takes an optional `options` object that may contain any of
|
178 | the following keys:
|
179 |
|
180 | ##### defaultCharset
|
181 |
|
182 | Specify the default character set for the text content if the charset is not
|
183 | specified in the `Content-Type` header of the request. Defaults to `utf-8`.
|
184 |
|
185 | ##### inflate
|
186 |
|
187 | When set to `true`, then deflated (compressed) bodies will be inflated; when
|
188 | `false`, deflated bodies are rejected. Defaults to `true`.
|
189 |
|
190 | ##### limit
|
191 |
|
192 | Controls the maximum request body size. If this is a number, then the value
|
193 | specifies the number of bytes; if it is a string, the value is passed to the
|
194 | [bytes](https://www.npmjs.com/package/bytes) library for parsing. Defaults
|
195 | to `'100kb'`.
|
196 |
|
197 | ##### type
|
198 |
|
199 | The `type` option is used to determine what media type the middleware will
|
200 | parse. This option can be a string, array of strings, or a function. If not
|
201 | a function, `type` option is passed directly to the
|
202 | [type-is](https://www.npmjs.org/package/type-is#readme) library and this can
|
203 | be an extension name (like `txt`), a mime type (like `text/plain`), or a mime
|
204 | type with a wildcard (like `*/*` or `text/*`). If a function, the `type`
|
205 | option is called as `fn(req)` and the request is parsed if it returns a
|
206 | truthy value. Defaults to `text/plain`.
|
207 |
|
208 | ##### verify
|
209 |
|
210 | The `verify` option, if supplied, is called as `verify(req, res, buf, encoding)`,
|
211 | where `buf` is a `Buffer` of the raw request body and `encoding` is the
|
212 | encoding of the request. The parsing can be aborted by throwing an error.
|
213 |
|
214 | ### bodyParser.urlencoded([options])
|
215 |
|
216 | Returns middleware that only parses `urlencoded` bodies and only looks at
|
217 | requests where the `Content-Type` header matches the `type` option. This
|
218 | parser accepts only UTF-8 encoding of the body and supports automatic
|
219 | inflation of `gzip` and `deflate` encodings.
|
220 |
|
221 | A new `body` object containing the parsed data is populated on the `request`
|
222 | object after the middleware (i.e. `req.body`). This object will contain
|
223 | key-value pairs, where the value can be a string or array (when `extended` is
|
224 | `false`), or any type (when `extended` is `true`).
|
225 |
|
226 | #### Options
|
227 |
|
228 | The `urlencoded` function takes an optional `options` object that may contain
|
229 | any of the following keys:
|
230 |
|
231 | ##### extended
|
232 |
|
233 | The `extended` option allows to choose between parsing the URL-encoded data
|
234 | with the `querystring` library (when `false`) or the `qs` library (when
|
235 | `true`). The "extended" syntax allows for rich objects and arrays to be
|
236 | encoded into the URL-encoded format, allowing for a JSON-like experience
|
237 | with URL-encoded. For more information, please
|
238 | [see the qs library](https://www.npmjs.org/package/qs#readme).
|
239 |
|
240 | Defaults to `true`, but using the default has been deprecated. Please
|
241 | research into the difference between `qs` and `querystring` and choose the
|
242 | appropriate setting.
|
243 |
|
244 | ##### inflate
|
245 |
|
246 | When set to `true`, then deflated (compressed) bodies will be inflated; when
|
247 | `false`, deflated bodies are rejected. Defaults to `true`.
|
248 |
|
249 | ##### limit
|
250 |
|
251 | Controls the maximum request body size. If this is a number, then the value
|
252 | specifies the number of bytes; if it is a string, the value is passed to the
|
253 | [bytes](https://www.npmjs.com/package/bytes) library for parsing. Defaults
|
254 | to `'100kb'`.
|
255 |
|
256 | ##### parameterLimit
|
257 |
|
258 | The `parameterLimit` option controls the maximum number of parameters that
|
259 | are allowed in the URL-encoded data. If a request contains more parameters
|
260 | than this value, a 413 will be returned to the client. Defaults to `1000`.
|
261 |
|
262 | ##### type
|
263 |
|
264 | The `type` option is used to determine what media type the middleware will
|
265 | parse. This option can be a string, array of strings, or a function. If not
|
266 | a function, `type` option is passed directly to the
|
267 | [type-is](https://www.npmjs.org/package/type-is#readme) library and this can
|
268 | be an extension name (like `urlencoded`), a mime type (like
|
269 | `application/x-www-form-urlencoded`), or a mime type with a wildcard (like
|
270 | `*/x-www-form-urlencoded`). If a function, the `type` option is called as
|
271 | `fn(req)` and the request is parsed if it returns a truthy value. Defaults
|
272 | to `application/x-www-form-urlencoded`.
|
273 |
|
274 | ##### verify
|
275 |
|
276 | The `verify` option, if supplied, is called as `verify(req, res, buf, encoding)`,
|
277 | where `buf` is a `Buffer` of the raw request body and `encoding` is the
|
278 | encoding of the request. The parsing can be aborted by throwing an error.
|
279 |
|
280 | ## Errors
|
281 |
|
282 | The middlewares provided by this module create errors using the
|
283 | [`http-errors` module](https://www.npmjs.com/package/http-errors). The errors
|
284 | will typically have a `status`/`statusCode` property that contains the suggested
|
285 | HTTP response code, an `expose` property to determine if the `message` property
|
286 | should be displayed to the client, a `type` property to determine the type of
|
287 | error without matching against the `message`, and a `body` property containing
|
288 | the read body, if available.
|
289 |
|
290 | The following are the common errors created, though any error can come through
|
291 | for various reasons.
|
292 |
|
293 | ### content encoding unsupported
|
294 |
|
295 | This error will occur when the request had a `Content-Encoding` header that
|
296 | contained an encoding but the "inflation" option was set to `false`. The
|
297 | `status` property is set to `415`, the `type` property is set to
|
298 | `'encoding.unsupported'`, and the `charset` property will be set to the
|
299 | encoding that is unsupported.
|
300 |
|
301 | ### entity parse failed
|
302 |
|
303 | This error will occur when the request contained an entity that could not be
|
304 | parsed by the middleware. The `status` property is set to `400`, the `type`
|
305 | property is set to `'entity.parse.failed'`, and the `body` property is set to
|
306 | the entity value that failed parsing.
|
307 |
|
308 | ### entity verify failed
|
309 |
|
310 | This error will occur when the request contained an entity that could not be
|
311 | failed verification by the defined `verify` option. The `status` property is
|
312 | set to `403`, the `type` property is set to `'entity.verify.failed'`, and the
|
313 | `body` property is set to the entity value that failed verification.
|
314 |
|
315 | ### request aborted
|
316 |
|
317 | This error will occur when the request is aborted by the client before reading
|
318 | the body has finished. The `received` property will be set to the number of
|
319 | bytes received before the request was aborted and the `expected` property is
|
320 | set to the number of expected bytes. The `status` property is set to `400`
|
321 | and `type` property is set to `'request.aborted'`.
|
322 |
|
323 | ### request entity too large
|
324 |
|
325 | This error will occur when the request body's size is larger than the "limit"
|
326 | option. The `limit` property will be set to the byte limit and the `length`
|
327 | property will be set to the request body's length. The `status` property is
|
328 | set to `413` and the `type` property is set to `'entity.too.large'`.
|
329 |
|
330 | ### request size did not match content length
|
331 |
|
332 | This error will occur when the request's length did not match the length from
|
333 | the `Content-Length` header. This typically occurs when the request is malformed,
|
334 | typically when the `Content-Length` header was calculated based on characters
|
335 | instead of bytes. The `status` property is set to `400` and the `type` property
|
336 | is set to `'request.size.invalid'`.
|
337 |
|
338 | ### stream encoding should not be set
|
339 |
|
340 | This error will occur when something called the `req.setEncoding` method prior
|
341 | to this middleware. This module operates directly on bytes only and you cannot
|
342 | call `req.setEncoding` when using this module. The `status` property is set to
|
343 | `500` and the `type` property is set to `'stream.encoding.set'`.
|
344 |
|
345 | ### stream is not readable
|
346 |
|
347 | This error will occur when the request is no longer readable when this middleware
|
348 | attempts to read it. This typically means something other than a middleware from
|
349 | this module read the request body already and the middleware was also configured to
|
350 | read the same request. The `status` property is set to `500` and the `type`
|
351 | property is set to `'stream.not.readable'`.
|
352 |
|
353 | ### too many parameters
|
354 |
|
355 | This error will occur when the content of the request exceeds the configured
|
356 | `parameterLimit` for the `urlencoded` parser. The `status` property is set to
|
357 | `413` and the `type` property is set to `'parameters.too.many'`.
|
358 |
|
359 | ### unsupported charset "BOGUS"
|
360 |
|
361 | This error will occur when the request had a charset parameter in the
|
362 | `Content-Type` header, but the `iconv-lite` module does not support it OR the
|
363 | parser does not support it. The charset is contained in the message as well
|
364 | as in the `charset` property. The `status` property is set to `415`, the
|
365 | `type` property is set to `'charset.unsupported'`, and the `charset` property
|
366 | is set to the charset that is unsupported.
|
367 |
|
368 | ### unsupported content encoding "bogus"
|
369 |
|
370 | This error will occur when the request had a `Content-Encoding` header that
|
371 | contained an unsupported encoding. The encoding is contained in the message
|
372 | as well as in the `encoding` property. The `status` property is set to `415`,
|
373 | the `type` property is set to `'encoding.unsupported'`, and the `encoding`
|
374 | property is set to the encoding that is unsupported.
|
375 |
|
376 | ## Examples
|
377 |
|
378 | ### Express/Connect top-level generic
|
379 |
|
380 | This example demonstrates adding a generic JSON and URL-encoded parser as a
|
381 | top-level middleware, which will parse the bodies of all incoming requests.
|
382 | This is the simplest setup.
|
383 |
|
384 | ```js
|
385 | var express = require('express')
|
386 | var bodyParser = require('body-parser')
|
387 |
|
388 | var app = express()
|
389 |
|
390 | // parse application/x-www-form-urlencoded
|
391 | app.use(bodyParser.urlencoded({ extended: false }))
|
392 |
|
393 | // parse application/json
|
394 | app.use(bodyParser.json())
|
395 |
|
396 | app.use(function (req, res) {
|
397 | res.setHeader('Content-Type', 'text/plain')
|
398 | res.write('you posted:\n')
|
399 | res.end(JSON.stringify(req.body, null, 2))
|
400 | })
|
401 | ```
|
402 |
|
403 | ### Express route-specific
|
404 |
|
405 | This example demonstrates adding body parsers specifically to the routes that
|
406 | need them. In general, this is the most recommended way to use body-parser with
|
407 | Express.
|
408 |
|
409 | ```js
|
410 | var express = require('express')
|
411 | var bodyParser = require('body-parser')
|
412 |
|
413 | var app = express()
|
414 |
|
415 | // create application/json parser
|
416 | var jsonParser = bodyParser.json()
|
417 |
|
418 | // create application/x-www-form-urlencoded parser
|
419 | var urlencodedParser = bodyParser.urlencoded({ extended: false })
|
420 |
|
421 | // POST /login gets urlencoded bodies
|
422 | app.post('/login', urlencodedParser, function (req, res) {
|
423 | res.send('welcome, ' + req.body.username)
|
424 | })
|
425 |
|
426 | // POST /api/users gets JSON bodies
|
427 | app.post('/api/users', jsonParser, function (req, res) {
|
428 | // create user in req.body
|
429 | })
|
430 | ```
|
431 |
|
432 | ### Change accepted type for parsers
|
433 |
|
434 | All the parsers accept a `type` option which allows you to change the
|
435 | `Content-Type` that the middleware will parse.
|
436 |
|
437 | ```js
|
438 | var express = require('express')
|
439 | var bodyParser = require('body-parser')
|
440 |
|
441 | var app = express()
|
442 |
|
443 | // parse various different custom JSON types as JSON
|
444 | app.use(bodyParser.json({ type: 'application/*+json' }))
|
445 |
|
446 | // parse some custom thing into a Buffer
|
447 | app.use(bodyParser.raw({ type: 'application/vnd.custom-type' }))
|
448 |
|
449 | // parse an HTML body into a string
|
450 | app.use(bodyParser.text({ type: 'text/html' }))
|
451 | ```
|
452 |
|
453 | ## License
|
454 |
|
455 | [MIT](LICENSE)
|
456 |
|
457 | [ci-image]: https://badgen.net/github/checks/expressjs/body-parser/master?label=ci
|
458 | [ci-url]: https://github.com/expressjs/body-parser/actions/workflows/ci.yml
|
459 | [coveralls-image]: https://badgen.net/coveralls/c/github/expressjs/body-parser/master
|
460 | [coveralls-url]: https://coveralls.io/r/expressjs/body-parser?branch=master
|
461 | [node-version-image]: https://badgen.net/npm/node/body-parser
|
462 | [node-version-url]: https://nodejs.org/en/download
|
463 | [npm-downloads-image]: https://badgen.net/npm/dm/body-parser
|
464 | [npm-url]: https://npmjs.org/package/body-parser
|
465 | [npm-version-image]: https://badgen.net/npm/v/body-parser
|