Opal-Estate-Pro/node_modules/body/README.md

body

Body parsing

Originally taken from npm-www

Example

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.

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>)

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 are valid options. It defaults to 'utf8'

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>)

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

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>)

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.

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>)

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

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