Node Req

> A facade over Node.js HTTP req object with no side-effects.

[![NPM Version][npm-image]][npm-url]
[![Build Status][travis-image]][travis-url]
[![Appveyor][appveyor-image]][appveyor-url]
[![Coveralls][coveralls-image]][coveralls-url]

node-req is an i/o module for parsing and returning values out of HTTP request object using helper methods.

See also

1. node-res
2. node-cookie

Http Server

``javascript
var http = require('http')
var nodeReq = require('node-req')

http.createServer(function (req, res) {

// get query string from req
var query = nodeReq.get(req)

}).listen(3000)

`

Yes, that's all, node-req makes no assumption on how to add routes or handle HTTP requests. All it does it parse request object and return values out of it.

API

* [get(req, [options])](#module_Request..get) ⇒ Object
* method(req) ⇒ String
* headers(req) ⇒ Object
* header(req, key) ⇒ String
* fresh(req, res) ⇒ Boolean
* stale(req, res) ⇒ Boolean
* [ip(req, [trust])](#module_Request..ip) ⇒ String
* [ips(req, [trust])](#module_Request..ips) ⇒ Array
* [protocol(req, [trust])](#module_Request..protocol) ⇒ String
* secure(req) ⇒ Boolean
* [subdomains(req, [trust], [offset])](#module_Request..subdomains) ⇒ Array
* ajax(req) ⇒ Boolean
* pjax(req) ⇒ Boolean
* [hostname(req, [trust])](#module_Request..hostname) ⇒ String
* url(req) ⇒ String
* originalUrl(req) ⇒ String
* is(req, keys) ⇒ String
* accepts(req, keys) ⇒ String
* types(req) ⇒ Array
* language(req, accepted) ⇒ String
* languages(req) ⇒ Array
* encoding(req, accepted) ⇒ String
* encodings(req) ⇒ Array
* charset(req, accepted) ⇒ String
* charsets(req) ⇒ Array
* hasBody(req) ⇒ Boolean

$3

Parses query string from url an returns an object.

Kind: inner method of Request

| Param | Type | Description |
| --- | --- | --- |
| req | http.IncomingMessage | |
| [options] | Object | Options are passed to https://www.npmjs.com/package/qs |

Example
`js
const queryString = nodeReq.get(req)
`


$3


Returns the exact copy of request.method. Defined
here

Kind: inner method of Request

| Param | Type |
| --- | --- |
| req | http.IncomingMessage |

Example
`js
const method = nodeReq.method(req)
`


$3

Returns an object of headers for a given
request.

Kind: inner method of Request

| Param | Type |
| --- | --- |
| req | http.IncomingMessage |

Example
`js
const headers = nodeReq.headers(req)
`


$3


Returns header value for a given key. Also
it will handle the inconsistencies between
referer and referrer header.

Kind: inner method of Request

| Param | Type |
| --- | --- |
| req | http.IncomingMessage |
| key | String |

Example
`js
const authHeader = nodeReq.header(req, 'Authorization')
`


$3


Returns the freshness of a response inside the client
cache. If client cache has the latest response, this
method will return true, otherwise it will return
false.

Also when HTTP header Cache-Control: no-cache is present
this method will return false everytime.

Kind: inner method of Request

| Param | Type |
| --- | --- |
| req | http.IncomingMessage |
| res | http.ServerResponse |

Example
`js
if (nodeReq.fresh(req, res)) {
res.writeHead(304)
}
`


$3


This method is the opposite of the nodeReq.fresh

Kind: inner method of Request

| Param | Type |
| --- | --- |
| req | http.IncomingMessage |
| res | http.ServerResponse |

Example
`js
if (!nodeReq.stale(req, res)) {
res.writeHead(304)
}
`


$3

Returns the most trusted ip address for the HTTP
request. It will handle the use cases where your
server is behind a proxy.

Make sure to check proxy-addr
for the available options for trust.

Kind: inner method of Request

| Param | Type |
| --- | --- |
| req | http.IncomingMessage |
| [trust] | Mixed |

Example
`js
nodeReq.ip(req, '127.0.0.1')
nodeReq.ip(req, ['::1/128', 'fe80::/10'])
`


$3

Returns list of all remote addresses ordered with
most trusted on the top of the list.

Make sure to check proxy-addr
for the available options for trust.

Kind: inner method of Request

| Param | Type |
| --- | --- |
| req | http.IncomingMessage |
| [trust] | Mixed |

Example
`
nodeReq.ips(req, '127.0.0.1')
nodeReq.ips(req, ['::1/128', 'fe80::/10'])
`


$3

Returns request protocol based upon encrypted
connection or X-Forwaded-Proto header.

Make sure to check proxy-addr
for the available options for trust.

Kind: inner method of Request

| Param | Type |
| --- | --- |
| req | http.IncomingMessage |
| [trust] | Mixed |

Example
`
const protocol = nodeReq.protocol(req)
`


$3

Looks for request protocol to check for
https existence or returns false.

Kind: inner method of Request

| Param | Type |
| --- | --- |
| req | http.IncomingMessage |

Example
`
const isHttps = nodeReq.secure(req)
`


$3


Returns the request subdomains as an array. Also
it will make sure to exclude www from the
subdomains list.

Make sure to check proxy-addr
for the available options for trust.

Kind: inner method of Request

| Param | Type | Default | Description |
| --- | --- | --- | --- |
| req | http.IncomingMessage | | |
| [trust] | Mixed | | |
| [offset] | Number | 2 | subdomain offset |

Example
`js
const subdomains = nodeReq.subdomains(req)
`


$3

Determines whether request is an ajax request
or not, based on X-Requested-With header.

Kind: inner method of Request

| Param | Type |
| --- | --- |
| req | http.IncomingMessage |

Example
`js
if (nodeReq.ajax(req)) {
res.writeHead(200, {"Content-type": "application/json"})
} else {
res.writeHead(200, {"Content-type": "text/html"})
}
`


$3

Tells whether request has X-Pjax
header or not.

Kind: inner method of Request

| Param | Type |
| --- | --- |
| req | http.IncomingMessage |

Example
`js
if (nodeReq.pjax(req)) {
// return partial content
} else {
// full page refresh
}
`


$3

Returns the hostname of HTTP request.

Make sure to check proxy-addr
for the available options for trust.

Kind: inner method of Request

| Param | Type |
| --- | --- |
| req | http.IncomingMessage |
| [trust] | Mixed |

Example
`js
const hostname = nodeReq.hostname(request)
`


$3

Returns request url after removing the query
string.

Kind: inner method of Request

| Param | Type |
| --- | --- |
| req | http.IncomingMessage |

Example
`js
const url = nodeReq.url(request)
`


$3

Returns the untouched url.

Kind: inner method of Request

| Param | Type |
| --- | --- |
| req | http.IncomingMessage |

Example
`js
const url = nodeReq.originalUrl(request)
`


$3

Tells whether request accept content of a given
type or not (based on Content-type) header.

Kind: inner method of Request

| Param | Type |
| --- | --- |
| req | http.IncomingMessage |
| keys | Mixed |

Example
`js
// req.headers.content-type = 'application/json'

nodeReq.is(req, ['json']) // json
nodeReq.is(req, ['json', 'html']) // json
nodeReq.is(req, ['application/*']) // application/json

nodeReq.is(req, ['html']) // ''
`


$3


Return the best possible response accepted by the
client. This is based on the Accept header.
Learn more about it

Kind: inner method of Request

| Param | Type |
| --- | --- |
| req | http.IncomingMessage |
| keys | Mixed |

Example
`js
const type = nodeReq.accepts(req, ['json', 'html'])

switch(type) {
case 'json':
res.setHeader('Content-Type', 'application/json')
res.write('{"hello":"world!"}')
break

case 'html':
res.setHeader('Content-Type', 'text/html')
res.write('hello, world!')
break

default:
res.setHeader('Content-Type', 'text/plain')
res.write('hello, world!')
}
`


$3

This method is similar to {{#crossLink "Request/accepts"}}{{/crossLink}},
instead it will return an array of types from most to least preferred
one.

Kind: inner method of Request

| Param | Type |
| --- | --- |
| req | http.IncomingMessage |

$3

Returns one of the most preferrable language.

Kind: inner method of Request

| Param | Type |
| --- | --- |
| req | http.IncomingMessage |
| accepted | Array |

$3

Returns list of all accepted languages from most
to least preferred one.

Kind: inner method of Request

| Param | Type |
| --- | --- |
| req | http.IncomingMessage |

$3

Returns the best maching encoding

Kind: inner method of Request

| Param | Type |
| --- | --- |
| req | http.IncomingMessage |
| accepted | Array |

$3

Returns list of all encodings from most
to least preferred one.

Kind: inner method of Request

| Param | Type |
| --- | --- |
| req | http.IncomingMessage |

$3

Returns the best maching charset based upon
Accept-Charset header.

Kind: inner method of Request

| Param | Type |
| --- | --- |
| req | http.IncomingMessage |
| accepted | Array |

$3

Returns a list of all charsets from most
to least preferred one based upon
Accept-Charset header.

Kind: inner method of Request

| Param | Type |
| --- | --- |
| req | http.IncomingMessage |

$3

Tells whether request has body or
not to be read by any body parser.

Kind: inner method of Request

| Param | Type |
| --- | --- |
| req | http.IncomingMessage |

Example
`js
if (nodeReq.hasBody(request)) {
// use body parser
}
``

[appveyor-image]: https://img.shields.io/appveyor/ci/thetutlage/node-req/master.svg?style=flat-square
[appveyor-url]: https://ci.appveyor.com/project/thetutlage/node-req

[npm-image]: https://img.shields.io/npm/v/node-req.svg?style=flat-square
[npm-url]: https://npmjs.org/package/node-req

[travis-image]: https://img.shields.io/travis/poppinss/node-req/master.svg?style=flat-square
[travis-url]: https://travis-ci.org/poppinss/node-req

[coveralls-image]: https://img.shields.io/coveralls/poppinss/node-req/develop.svg?style=flat-square
[coveralls-url]: https://coveralls.io/github/poppinss/node-req