# body [![build status][1]][2]
Body parsing
Originally taken from [npm-www](https://github.com/isaacs/npm-www)
## Example
```js
var textBody = require("body")
var jsonBody = require("body/json")
var formBody = require("body/form")
var anyBody = require("body/any")
var http = require("http")
var sendJson = require("send-data/json")
http.createServer(function handleRequest(req, res) {
function send(err, body) {
sendJson(req, res, body)
}
if (req.url === "/body") {
// all functions can be called with (req, cb)
textBody(req, send)
} else if (req.url === "/form") {
// all functions can be called with (req, opts, cb)
formBody(req, {}, send)
} else if (req.url === "/json") {
// all functions can be called with (req, res, cb)
jsonBody(req, res, send)
} else if (req.url === "/any") {
// all functions can be called with (req, res, opts, cb)
anyBody(req, res, {}, send)
}
})
```
`body` simply parses the request body and returns it in the callback. `jsonBody` and `formBody` call JSON.parse and querystring.parse respectively on the body.
anyBody will detect the content-type of the request and use the appropiate body method.
## Example generators
You can use `body` with generators as the body functions will
return a continuable if you don't pass a callback.
```js
var http = require("http")
var Router = require("routes-router")
var jsonBody = require("body/json")
var formBody = require("body/form")
// async turns a generator into an async function taking a cb
var async = require("gens")
// the router works with normal async functions.
// router automatically handles errors as 500 responses
var app = Router({
// do whatever you want. the jsonBody error would go here
errorHandler: function (req, res, err) {
res.statusCode = 500
res.end(err.message)
}
})
app.addRoute("/json", async(function* (req, res) {
// if jsonBody has an error it just goes to the cb
// in the called in the router. and it does the correct thing
// it shows your 500 page.
var body = yield jsonBody(req, res)
res.setHeader("content-type", "application/json")
res.end(JSON.stringify(body))
}))
app.addRoute("/form", async(function* (req, res) {
var body = yield formBody(req, res)
res.setHeader("content-type", "application/json")
res.end(JSON.stringify(body))
}))
// app returned from the router is just a function(req, res) {}
// that dispatches the req/res to the correct route based on
// the routers routing table & req.url
http.createServer(app).listen(8080)
```
## Documentation
### `textBody(req, res?, opts?, cb<Error, String>)`
```ocaml
textBody := (
req: HttpRequest,
res?: HttpResponse,
opts?: {
limit?: Number,
cache?: Boolean,
encoding?: String
},
cb: Callback<err: Error, bodyPayload: String>
) => void
```
`textBody` allows you to get the body from any readable stream.
It will read the entire content of the stream into memory and
give it back to you in the callback.
- `limit`: You can set `opts.limit` to a custom number to change the
limit at which `textBody` gives up. By default it will only
read a 1MB body, if a stream contains more then 1MB it returns
an error. This prevents someone attacking your HTTP server
with an infinite body causing an out of memory attack.
- `encoding`: You can set `encoding`. All encodings that are valid on a
[`Buffer`](http://nodejs.org/api/buffer.html#buffer_buffer) are
valid options. It defaults to `'utf8'`
```js
var textBody = require("body")
var http = require("http")
http.createServer(function (req, res) {
textBody(req, res, function (err, body) {
// err probably means invalid HTTP protocol or some shiz.
if (err) {
res.statusCode = 500
return res.end("NO U")
}
// I am an echo server
res.end(body)
})
}).listen(8080)
```
### `formBody(req, res?, opts?, cb<Error, Any>)`
```ocaml
formBody := (
req: HttpRequest,
res?: HttpResponse,
opts?: {
limit?: Number,
encoding?: String,
querystring: {
parse: (String, Callback<Error, Any>) => void
}
},
cb: Callback<err: Error, bodyPayload: Any>
) => void
```
`formBody` allows you to get the body of a readable stream. It
does the same as `textBody` but assumes the content is querystring
encoded and parses just like it was a <form> submit.
- `limit`: same as `textBody`
- `encoding`: same as `textBody`
- `querystring`: You can pass a custom querystring parser if
you want. It should have a `parse` method that takes a
string and a callback. It should return the value in the
callback or a parsing error
```js
var formBody = require("body/form")
var http = require("http")
http.createServer(function (req, res) {
formBody(req, res, function (err, body) {
// err probably means invalid HTTP protocol or some shiz.
if (err) {
res.statusCode = 500
return res.end("NO U")
}
// I am an echo server
res.setHeader("content-type", "application/json")
res.end(JSON.stringify(body))
})
}).listen(8080)
```
### `jsonBody(req, res?, opts?, cb<Error, Any>)`
```ocaml
jsonBody := (
req: HttpRequest,
res?: HttpResponse,
opts?: {
limit?: Number,
encoding?: String,
reviver?: (Any) => Any
JSON?: {
parse: (String, reviver?: Function, Callback<Error, Any>) => void
}
},
cb: Callback<err: Error, bodyPayload: Any>
) => void
```
`jsonBody` allows you to get the body of a readable stream. It
does the same as `textbody` but assumes the content it a JSON
value and parses it using `JSON.parse`. If `JSON.parse` throws
an exception then it calls the callback with the exception.
- `limit`: same as `textBody`
- `encoding`: same as `textBody`
- `reviver`: A reviver function that will be passed to `JSON.parse`
as the second argument
- `JSON`: You can pass a custom JSON parser if you want.
It should have a `parse` method that takes a string, an
optional reviver and a callback. It should return the value
in the callback or a parsing error.
```js
var jsonBody = require("body/json")
var http = require("http")
http.createServer(function (req, res) {
jsonBody(req, res, function (err, body) {
// err is probably an invalid json error
if (err) {
res.statusCode = 500
return res.end("NO U")
}
// I am an echo server
res.setHeader("content-type", "application/json")
res.end(JSON.stringify(body))
})
}).listen(8080)
```
### `anyBody(req, res?, opts?, cb<Error, Any>)`
```ocaml
anyBody := (
req: HttpRequest,
res?: HttpResponse,
opts?: {
limit?: Number,
encoding?: String,
reviver?: (Any) => Any
JSON?: {
parse: (String, reviver?: Function, Callback<Error, Any>) => void
},
querystring: {
parse: (String, Callback<Error, Any>) => void
}
},
cb: Callback<err: Error, bodyPayload: Any>
) => void
```
`anyBody` allows you to get the body of a HTTPRequest. It
does the same as `textBody` except it parses the `content-type`
header and uses either the jsonBody or the formBody function.
This allows you to write POST route handlers that work with
both ajax and html form submits.
- `limit`: same as `textBody`
- `encoding`: same as `textBody`
- `reviver`: same as `jsonBody`
- `JSON`: same as `jsonBody`
- `querystring`: same as `formBody`
```js
var anyBody = require("body/any")
var http = require("http")
http.createServer(function (req, res) {
anyBody(req, res, function (err, body) {
// err is probably an invalid json error
if (err) {
res.statusCode = 500
return res.end("NO U")
}
// I am an echo server
res.setHeader("content-type", "application/json")
res.end(JSON.stringify(body))
})
}).listen(8080)
```
## Installation
`npm install body`
## Tests
`npm test`
## Contributors
- Raynos
## MIT Licenced
[1]: https://secure.travis-ci.org/Raynos/body.png
[2]: http://travis-ci.org/Raynos/body