npm install cogent[![NPM version][npm-image]][npm-url]
[![build status][travis-image]][travis-url]
[![Test coverage][coveralls-image]][coveralls-url]
[![Gittip][gittip-image]][gittip-url]
[npm-image]: https://img.shields.io/npm/v/cogent.svg?style=flat
[npm-url]: https://npmjs.org/package/cogent
[travis-image]: https://img.shields.io/travis/cojs/cogent.svg?style=flat
[travis-url]: https://travis-ci.org/cojs/cogent
[coveralls-image]: https://img.shields.io/coveralls/cojs/cogent.svg?style=flat
[coveralls-url]: https://coveralls.io/r/cojs/cogent?branch=master
[gittip-image]: https://img.shields.io/gittip/jonathanong.svg?style=flat
[gittip-url]: https://www.gittip.com/jonathanong/
A simple HTTP request agent designed primarily for GETing stuff.
- Resolve redirects
- Timeout support
- Automatic gunzipping
- First-class JSON support
- Buffer the response or save it to a file
``js
var request = require('cogent')
var uri = 'https://raw.github.com/visionmedia/express/master/package.json'
// Pipe stdout
var res = yield* request(uri)
res.pipe(process.stdout)
// Save to a file
var res = yield* request(uri, require('os').tmpdir() + '/express.package.json')
if (res.destination) console.log('ok')
// Get as JSON
var res = yield* request(uri, true)
var json = res.body
`
You can also use it without generators by wrapping it with co:
`js
var co = require('co')
var request = co(require('cogent'))
request('https://github.com', function (err, res) {
res.pipe(process.stdout)
})
`
url is the URL of the request.
The options are passed to http.request().
Additional options are:
- buffer - buffer the response and save it as res.bufferstring
- - buffer the response as a string and save it as res.textjson
- - buffer the response as an object and save it as res.bodydestination
- - cojs/cogent the response to the file destinationtimeout
- - response header timeout per try, default 5000 millisecondsretries
- - number of retries when request fails due to common server errors, default 0redirects
- - resolve redirects, default 1
If options === true, it defaults to { json: true }.typeof options === 'string'
If , it defaults to { destination: string }.
response will have the following properties:
- res.req - the request objectres.res
- - the response object, itself if the response was not gzippedres.statusCode
- res.headers
- res.destination
- - populated only if the file was successfully saved on a 200res.buffer
- res.text
- res.body
- - JSON body populated only on a 200
Create a new cogent instance with default options. This allows you to avoid setting the same options every time. See the options listed above.
- retriesredirects
- timeout
- method
- gunzip
- netrc
- agent
-
`js
var request = require('cogent').extend({
auth: 'username:password'
})
var res = yield* request('http://localhost/', true)
// will send with auth header
``