dgbuilder/dgeflows/node_modules/body-parser/node_modules/raw-body/README.md

   1 # raw-body
   2
   3 [![NPM version][npm-image]][npm-url]
   4 [![Build status][travis-image]][travis-url]
   5 [![Test coverage][coveralls-image]][coveralls-url]
   6 [![Dependency Status][david-image]][david-url]
   7 [![License][license-image]][license-url]
   8 [![Downloads][downloads-image]][downloads-url]
   9
  10 Gets the entire buffer of a stream either as a `Buffer` or a string.
  11 Validates the stream's length against an expected length and maximum limit.
  12 Ideal for parsing request bodies.
  13
  14 ## API
  15
  16 ```js
  17 var getRawBody = require('raw-body')
  18 var typer      = require('media-typer')
  19
  20 app.use(function (req, res, next) {
  21   getRawBody(req, {
  22     length: req.headers['content-length'],
  23     limit: '1mb',
  24     encoding: typer.parse(req.headers['content-type']).parameters.charset
  25   }, function (err, string) {
  26     if (err)
  27       return next(err)
  28
  29     req.text = string
  30     next()
  31   })
  32 })
  33 ```
  34
  35 or in a Koa generator:
  36
  37 ```js
  38 app.use(function* (next) {
  39   var string = yield getRawBody(this.req, {
  40     length: this.length,
  41     limit: '1mb',
  42     encoding: this.charset
  43   })
  44 })
  45 ```
  46
  47 ### getRawBody(stream, [options], [callback])
  48
  49 Returns a thunk for yielding with generators.
  50
  51 Options:
  52
  53 - `length` - The length length of the stream.
  54   If the contents of the stream do not add up to this length,
  55   an `400` error code is returned.
  56 - `limit` - The byte limit of the body.
  57   If the body ends up being larger than this limit,
  58   a `413` error code is returned.
  59 - `encoding` - The requested encoding.
  60   By default, a `Buffer` instance will be returned.
  61   Most likely, you want `utf8`.
  62   You can use any type of encoding supported by [iconv-lite](https://www.npmjs.org/package/iconv-lite#readme).
  63
  64 You can also pass a string in place of options to just specify the encoding.
  65
  66 `callback(err, res)`:
  67
  68 - `err` - the following attributes will be defined if applicable:
  69
  70     - `limit` - the limit in bytes
  71     - `length` and `expected` - the expected length of the stream
  72     - `received` - the received bytes
  73     - `encoding` - the invalid encoding
  74     - `status` and `statusCode` - the corresponding status code for the error
  75     - `type` - either `entity.too.large`, `request.size.invalid`, `stream.encoding.set`, or `encoding.unsupported`
  76
  77 - `res` - the result, either as a `String` if an encoding was set or a `Buffer` otherwise.
  78
  79 If an error occurs, the stream will be paused, everything unpiped,
  80 and you are responsible for correctly disposing the stream.
  81 For HTTP requests, no handling is required if you send a response.
  82 For streams that use file descriptors, you should `stream.destroy()` or `stream.close()` to prevent leaks.
  83
  84 [npm-image]: https://img.shields.io/npm/v/raw-body.svg?style=flat-square
  85 [npm-url]: https://npmjs.org/package/raw-body
  86 [travis-image]: https://img.shields.io/travis/stream-utils/raw-body.svg?style=flat-square
  87 [travis-url]: https://travis-ci.org/stream-utils/raw-body
  88 [coveralls-image]: https://img.shields.io/coveralls/stream-utils/raw-body.svg?style=flat-square
  89 [coveralls-url]: https://coveralls.io/r/stream-utils/raw-body
  90 [david-image]: http://img.shields.io/david/stream-utils/raw-body.svg?style=flat-square
  91 [david-url]: https://david-dm.org/stream-utils/raw-body
  92 [license-image]: http://img.shields.io/npm/l/raw-body.svg?style=flat-square
  93 [license-url]: LICENSE
  94 [downloads-image]: http://img.shields.io/npm/dm/raw-body.svg?style=flat-square
  95 [downloads-url]: https://npmjs.org/package/raw-body