node_modules/body-parser/README.md

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