node package manager
Easy sharing. Manage teams and permissions with one click. Create a free org »



NPM version build status Test coverage Gittip

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


var request = require('cogent')
var uri = ''
// Pipe stdout 
var res = yield* request(uri)
// 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:

var co = require('co')
var request = co(require('cogent'))
request('', function (err, res) {

var response = yield* request(url, [options])

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.buffer
  • string - buffer the response as a string and save it as res.text
  • json - buffer the response as an object and save it as res.body
  • destination - cojs/cogent the response to the file destination
  • timeout - response header timeout per try, default 5000 milliseconds
  • retries - number of retries when request fails due to common server errors, default 0
  • redirects - resolve redirects, default 1

If options === true, it defaults to { json: true }. If typeof options === 'string', it defaults to { destination: string }.

response will have the following properties:

  • res.req - the request object
  • res.res - the response object, itself if the response was not gzipped
  • res.statusCode
  • res.headers
  • res.destination - populated only if the file was successfully saved on a 200
  • res.buffer
  • res.text
  • res.body - JSON body populated only on a 200

request = request.extend(options)

Create a new cogent instance with default options. This allows you to avoid setting the same options every time. See the options listed above.

  • retries
  • redirects
  • timeout
  • method
  • gunzip
  • netrc
  • agent
var request = require('cogent').extend({
  auth: 'username:password'
var res = yield* request('http://localhost/', true)
// will send with auth header