node_modules/raw-body/README.md

   1 # raw-body
   2
   3 [![NPM Version][npm-image]][npm-url]
   4 [![NPM Downloads][downloads-image]][downloads-url]
   5 [![Node.js Version][node-version-image]][node-version-url]
   6 [![Build status][travis-image]][travis-url]
   7 [![Test coverage][coveralls-image]][coveralls-url]
   8
   9 Gets the entire buffer of a stream either as a `Buffer` or a string.
  10 Validates the stream's length against an expected length and maximum limit.
  11 Ideal for parsing request bodies.
  12
  13 ## Install
  14
  15 This is a [Node.js](https://nodejs.org/en/) module available through the
  16 [npm registry](https://www.npmjs.com/). Installation is done using the
  17 [`npm install` command](https://docs.npmjs.com/getting-started/installing-npm-packages-locally):
  18
  19 ```sh
  20 $ npm install raw-body
  21 ```
  22
  23 ### TypeScript
  24
  25 This module includes a [TypeScript](https://www.typescriptlang.org/)
  26 declaration file to enable auto complete in compatible editors and type
  27 information for TypeScript projects. This module depends on the Node.js
  28 types, so install `@types/node`:
  29
  30 ```sh
  31 $ npm install @types/node
  32 ```
  33
  34 ## API
  35
  36 <!-- eslint-disable no-unused-vars -->
  37
  38 ```js
  39 var getRawBody = require('raw-body')
  40 ```
  41
  42 ### getRawBody(stream, [options], [callback])
  43
  44 **Returns a promise if no callback specified and global `Promise` exists.**
  45
  46 Options:
  47
  48 - `length` - The length of the stream.
  49   If the contents of the stream do not add up to this length,
  50   an `400` error code is returned.
  51 - `limit` - The byte limit of the body.
  52   This is the number of bytes or any string format supported by
  53   [bytes](https://www.npmjs.com/package/bytes),
  54   for example `1000`, `'500kb'` or `'3mb'`.
  55   If the body ends up being larger than this limit,
  56   a `413` error code is returned.
  57 - `encoding` - The encoding to use to decode the body into a string.
  58   By default, a `Buffer` instance will be returned when no encoding is specified.
  59   Most likely, you want `utf-8`, so setting `encoding` to `true` will decode as `utf-8`.
  60   You can use any type of encoding supported by [iconv-lite](https://www.npmjs.org/package/iconv-lite#readme).
  61
  62 You can also pass a string in place of options to just specify the encoding.
  63
  64 If an error occurs, the stream will be paused, everything unpiped,
  65 and you are responsible for correctly disposing the stream.
  66 For HTTP requests, no handling is required if you send a response.
  67 For streams that use file descriptors, you should `stream.destroy()` or `stream.close()` to prevent leaks.
  68
  69 ## Errors
  70
  71 This module creates errors depending on the error condition during reading.
  72 The error may be an error from the underlying Node.js implementation, but is
  73 otherwise an error created by this module, which has the following attributes:
  74
  75   * `limit` - the limit in bytes
  76   * `length` and `expected` - the expected length of the stream
  77   * `received` - the received bytes
  78   * `encoding` - the invalid encoding
  79   * `status` and `statusCode` - the corresponding status code for the error
  80   * `type` - the error type
  81
  82 ### Types
  83
  84 The errors from this module have a `type` property which allows for the progamatic
  85 determination of the type of error returned.
  86
  87 #### encoding.unsupported
  88
  89 This error will occur when the `encoding` option is specified, but the value does
  90 not map to an encoding supported by the [iconv-lite](https://www.npmjs.org/package/iconv-lite#readme)
  91 module.
  92
  93 #### entity.too.large
  94
  95 This error will occur when the `limit` option is specified, but the stream has
  96 an entity that is larger.
  97
  98 #### request.aborted
  99
 100 This error will occur when the request stream is aborted by the client before
 101 reading the body has finished.
 102
 103 #### request.size.invalid
 104
 105 This error will occur when the `length` option is specified, but the stream has
 106 emitted more bytes.
 107
 108 #### stream.encoding.set
 109
 110 This error will occur when the given stream has an encoding set on it, making it
 111 a decoded stream. The stream should not have an encoding set and is expected to
 112 emit `Buffer` objects.
 113
 114 ## Examples
 115
 116 ### Simple Express example
 117
 118 ```js
 119 var contentType = require('content-type')
 120 var express = require('express')
 121 var getRawBody = require('raw-body')
 122
 123 var app = express()
 124
 125 app.use(function (req, res, next) {
 126   getRawBody(req, {
 127     length: req.headers['content-length'],
 128     limit: '1mb',
 129     encoding: contentType.parse(req).parameters.charset
 130   }, function (err, string) {
 131     if (err) return next(err)
 132     req.text = string
 133     next()
 134   })
 135 })
 136
 137 // now access req.text
 138 ```
 139
 140 ### Simple Koa example
 141
 142 ```js
 143 var contentType = require('content-type')
 144 var getRawBody = require('raw-body')
 145 var koa = require('koa')
 146
 147 var app = koa()
 148
 149 app.use(function * (next) {
 150   this.text = yield getRawBody(this.req, {
 151     length: this.req.headers['content-length'],
 152     limit: '1mb',
 153     encoding: contentType.parse(this.req).parameters.charset
 154   })
 155   yield next
 156 })
 157
 158 // now access this.text
 159 ```
 160
 161 ### Using as a promise
 162
 163 To use this library as a promise, simply omit the `callback` and a promise is
 164 returned, provided that a global `Promise` is defined.
 165
 166 ```js
 167 var getRawBody = require('raw-body')
 168 var http = require('http')
 169
 170 var server = http.createServer(function (req, res) {
 171   getRawBody(req)
 172     .then(function (buf) {
 173       res.statusCode = 200
 174       res.end(buf.length + ' bytes submitted')
 175     })
 176     .catch(function (err) {
 177       res.statusCode = 500
 178       res.end(err.message)
 179     })
 180 })
 181
 182 server.listen(3000)
 183 ```
 184
 185 ### Using with TypeScript
 186
 187 ```ts
 188 import * as getRawBody from 'raw-body';
 189 import * as http from 'http';
 190
 191 const server = http.createServer((req, res) => {
 192   getRawBody(req)
 193   .then((buf) => {
 194     res.statusCode = 200;
 195     res.end(buf.length + ' bytes submitted');
 196   })
 197   .catch((err) => {
 198     res.statusCode = err.statusCode;
 199     res.end(err.message);
 200   });
 201 });
 202
 203 server.listen(3000);
 204 ```
 205
 206 ## License
 207
 208 [MIT](LICENSE)
 209
 210 [npm-image]: https://img.shields.io/npm/v/raw-body.svg
 211 [npm-url]: https://npmjs.org/package/raw-body
 212 [node-version-image]: https://img.shields.io/node/v/raw-body.svg
 213 [node-version-url]: https://nodejs.org/en/download/
 214 [travis-image]: https://img.shields.io/travis/stream-utils/raw-body/master.svg
 215 [travis-url]: https://travis-ci.org/stream-utils/raw-body
 216 [coveralls-image]: https://img.shields.io/coveralls/stream-utils/raw-body/master.svg
 217 [coveralls-url]: https://coveralls.io/r/stream-utils/raw-body?branch=master
 218 [downloads-image]: https://img.shields.io/npm/dm/raw-body.svg
 219 [downloads-url]: https://npmjs.org/package/raw-body