dgbuilder/dgeflows/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 [![Gratipay][gratipay-image]][gratipay-url]
   8
   9 Node.js body parsing middleware.
  10
  11 This does not handle multipart bodies, due to their complex and typically large nature. For multipart bodies, you may be interested in the following modules:
  12
  13 - [busboy](https://www.npmjs.org/package/busboy#readme) and [connect-busboy](https://www.npmjs.org/package/connect-busboy#readme)
  14 - [multiparty](https://www.npmjs.org/package/multiparty#readme) and [connect-multiparty](https://www.npmjs.org/package/connect-multiparty#readme)
  15 - [formidable](https://www.npmjs.org/package/formidable#readme)
  16 - [multer](https://www.npmjs.org/package/multer#readme)
  17
  18 Other body parsers you might be interested in:
  19
  20 - [body](https://www.npmjs.org/package/body#readme)
  21 - [co-body](https://www.npmjs.org/package/co-body#readme)
  22
  23 ## Installation
  24
  25 ```sh
  26 $ npm install body-parser
  27 ```
  28
  29 ## API
  30
  31 ```js
  32 var bodyParser = require('body-parser')
  33 ```
  34
  35 ### bodyParser.json(options)
  36
  37 Returns middleware that only parses `json`. This parser accepts any Unicode encoding of the body and supports automatic inflation of `gzip` and `deflate` encodings.
  38
  39 The options are:
  40
  41 - `strict` - only parse objects and arrays. (default: `true`)
  42 - `inflate` - if deflated bodies will be inflated. (default: `true`)
  43 - `limit` - maximum request body size. (default: `<100kb>`)
  44 - `reviver` - passed to `JSON.parse()`
  45 - `type` - request content-type to parse (default: `json`)
  46 - `verify` - function to verify body content
  47
  48 The `type` argument is passed directly to the [type-is](https://www.npmjs.org/package/type-is#readme) library. This can be an extension name (like `json`), a mime type (like `application/json`), or a mime time with a wildcard (like `*/json`).
  49
  50 The `verify` argument, if supplied, is called as `verify(req, res, buf, encoding)`, where `buf` is a `Buffer` of the raw request body and `encoding` is the encoding of the request. The parsing can be aborted by throwing an error.
  51
  52 The `reviver` argument is passed directly to `JSON.parse` as the second argument. You can find more information on this argument [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).
  53
  54 ### bodyParser.raw(options)
  55
  56 Returns middleware that parses all bodies as a `Buffer`. This parser supports automatic inflation of `gzip` and `deflate` encodings.
  57
  58 The options are:
  59
  60 - `inflate` - if deflated bodies will be inflated. (default: `true`)
  61 - `limit` - maximum request body size. (default: `<100kb>`)
  62 - `type` - request content-type to parse (default: `application/octet-stream`)
  63 - `verify` - function to verify body content
  64
  65 The `type` argument is passed directly to the [type-is](https://www.npmjs.org/package/type-is#readme) library. This can be an extension name (like `bin`), a mime type (like `application/octet-stream`), or a mime time with a wildcard (like `application/*`).
  66
  67 The `verify` argument, if supplied, is called as `verify(req, res, buf, encoding)`, where `buf` is a `Buffer` of the raw request body and `encoding` is the encoding of the request. The parsing can be aborted by throwing an error.
  68
  69 ### bodyParser.text(options)
  70
  71 Returns middleware that parses all bodies as a string. This parser supports automatic inflation of `gzip` and `deflate` encodings.
  72
  73 The options are:
  74
  75 - `defaultCharset` - the default charset to parse as, if not specified in content-type. (default: `utf-8`)
  76 - `inflate` - if deflated bodies will be inflated. (default: `true`)
  77 - `limit` - maximum request body size. (default: `<100kb>`)
  78 - `type` - request content-type to parse (default: `text/plain`)
  79 - `verify` - function to verify body content
  80
  81 The `type` argument is passed directly to the [type-is](https://www.npmjs.org/package/type-is#readme) library. This can be an extension name (like `txt`), a mime type (like `text/plain`), or a mime time with a wildcard (like `text/*`).
  82
  83 The `verify` argument, if supplied, is called as `verify(req, res, buf, encoding)`, where `buf` is a `Buffer` of the raw request body and `encoding` is the encoding of the request. The parsing can be aborted by throwing an error.
  84
  85 ### bodyParser.urlencoded(options)
  86
  87 Returns middleware that only parses `urlencoded` bodies. This parser accepts only UTF-8 encoding of the body and supports automatic inflation of `gzip` and `deflate` encodings.
  88
  89 The options are:
  90
  91 - `extended` - parse extended syntax with the [qs](https://www.npmjs.org/package/qs#readme) module. (default: `true`, but using the default has been deprecated. Please research into the difference between `qs` and `querystring` and choose the appropriate setting)
  92 - `inflate` - if deflated bodies will be inflated. (default: `true`)
  93 - `limit` - maximum request body size. (default: `<100kb>`)
  94 - `parameterLimit` - maximum number of parameters. (default: `1000`)
  95 - `type` - request content-type to parse (default: `urlencoded`)
  96 - `verify` - function to verify body content
  97
  98 The `extended` argument allows to choose between parsing the urlencoded data with the `querystring` library (when `false`) or the `qs` library (when `true`). The "extended" syntax allows for rich objects and arrays to be encoded into the urlencoded format, allowing for a JSON-like experience with urlencoded. For more information, please [see the qs library](https://www.npmjs.org/package/qs#readme).
  99
 100 The `parameterLimit` argument controls the maximum number of parameters that are allowed in the urlencoded data. If a request contains more parameters than this value, a 413 will be returned to the client.
 101
 102 The `type` argument is passed directly to the [type-is](https://www.npmjs.org/package/type-is#readme) library. This can be an extension name (like `urlencoded`), a mime type (like `application/x-www-form-urlencoded`), or a mime time with a wildcard (like `*/x-www-form-urlencoded`).
 103
 104 The `verify` argument, if supplied, is called as `verify(req, res, buf, encoding)`, where `buf` is a `Buffer` of the raw request body and `encoding` is the encoding of the request. The parsing can be aborted by throwing an error.
 105
 106 ### req.body
 107
 108 A new `body` object containing the parsed data is populated on the `request` object after the middleware.
 109
 110 ## Examples
 111
 112 ### express/connect top-level generic
 113
 114 This example demonstrates adding a generic JSON and urlencoded parser as a top-level middleware, which will parse the bodies of all incoming requests. This is the simplest setup.
 115
 116 ```js
 117 var express = require('express')
 118 var bodyParser = require('body-parser')
 119
 120 var app = express()
 121
 122 // parse application/x-www-form-urlencoded
 123 app.use(bodyParser.urlencoded({ extended: false }))
 124
 125 // parse application/json
 126 app.use(bodyParser.json())
 127
 128 app.use(function (req, res) {
 129   res.setHeader('Content-Type', 'text/plain')
 130   res.write('you posted:\n')
 131   res.end(JSON.stringify(req.body, null, 2))
 132 })
 133 ```
 134
 135 ### express route-specific
 136
 137 This example demonstrates adding body parsers specifically to the routes that need them. In general, this is the most recommend way to use body-parser with express.
 138
 139 ```js
 140 var express = require('express')
 141 var bodyParser = require('body-parser')
 142
 143 var app = express()
 144
 145 // create application/json parser
 146 var jsonParser = bodyParser.json()
 147
 148 // create application/x-www-form-urlencoded parser
 149 var urlencodedParser = bodyParser.urlencoded({ extended: false })
 150
 151 // POST /login gets urlencoded bodies
 152 app.post('/login', urlencodedParser, function (req, res) {
 153   if (!req.body) return res.sendStatus(400)
 154   res.send('welcome, ' + req.body.username)
 155 })
 156
 157 // POST /api/users gets JSON bodies
 158 app.post('/api/users', jsonParser, function (req, res) {
 159   if (!req.body) return res.sendStatus(400)
 160   // create user in req.body
 161 })
 162 ```
 163
 164 ### change content-type for parsers
 165
 166 All the parsers accept a `type` option which allows you to change the `Content-Type` that the middleware will parse.
 167
 168 ```js
 169 // parse various different custom JSON types as JSON
 170 app.use(bodyParser.json({ type: 'application/*+json' }))
 171
 172 // parse some custom thing into a Buffer
 173 app.use(bodyParser.raw({ type: 'application/vnd.custom-type' }))
 174
 175 // parse an HTML body into a string
 176 app.use(bodyParser.text({ type: 'text/html' }))
 177 ```
 178
 179 ## License
 180
 181 [MIT](LICENSE)
 182
 183 [npm-image]: https://img.shields.io/npm/v/body-parser.svg?style=flat
 184 [npm-url]: https://npmjs.org/package/body-parser
 185 [travis-image]: https://img.shields.io/travis/expressjs/body-parser.svg?style=flat
 186 [travis-url]: https://travis-ci.org/expressjs/body-parser
 187 [coveralls-image]: https://img.shields.io/coveralls/expressjs/body-parser.svg?style=flat
 188 [coveralls-url]: https://coveralls.io/r/expressjs/body-parser?branch=master
 189 [downloads-image]: https://img.shields.io/npm/dm/body-parser.svg?style=flat
 190 [downloads-url]: https://npmjs.org/package/body-parser
 191 [gratipay-image]: https://img.shields.io/gratipay/dougwilson.svg?style=flat
 192 [gratipay-url]: https://www.gratipay.com/dougwilson/