A bag-of-holding containing request utility functions.

Downloads in past


111.0.08 years ago11 years agoMinified + gzip package size for bagofrequest in KB


Build Status Dependencies Status Coverage Status Published Version
npm Badge

Bag Of Request

Bag Of Request contains request utility functions.
Send http request using mikeal/request, with the following additional features:
  • status code-based response handlers registration
  • wildcard status code support (e.g. 2xx, 50x)
  • unexpected status code error handling with request body included in message
  • request retry with increasing delay and maximum retries
  • proxy setting based on env vars httpproxy, HTTPPROXY, httpsproxy, HTTPSPROXY
  • proxy exclusion for localhost and
  • request timeout of 30 seconds
  • follow redirects
  • accepts self-signed SSL certificates
  • all of the above defaults can be overridden

Proxy retrieval based on URL and environment variables:
  • if URL uses http, then sets proxy to httpproxy or HTTPPROXY
  • if URL uses https, then sets proxy to htpsproxy or HTTPSPROXY, otherwise fallback to httpproxy or HTTPPROXY
  • if URL does not have a protocol, assume http protocol
  • if URL is not provided, then set proxy to httpproxy or HTTPPROXY, otherwise fallback to httpsproxy or HTTPSPROXY
  • proxy will be ignored if host is on noproxy or NOPROXY when provided, otherwise ignore and localhost


npm install bagofrequest
or as a dependency in package.json file:
"dependencies": {
  "bagofrequest": "x.y.z"


var bag = require('bagofrequest');
// send http get request with query strings, timeout, and specified status code-based handlers
bag.request('get', 'http://somehost', {
    queryStrings: {
      param1: 'value1',
      param2: 'value2'
    timeout: 30000,
    handlers: {
      '2xx': function (result, cb) {
        cb(null, result.somedata);
      404: function (result, cb) {
        cb(new Error('Item ' + result.itemId + ' cannot be found'));
  function (err, result) {
    // response with unexpected status code (no registered handler) will be passed as error

// send http post request
bag.request('post', 'http://somehost', {
    headers: {
      'content-type': 'application/json'
    json: {
      prop1: 'value1',
      prop2: 'value2'
  function (err, result) {

// send request with options to override any bagofrequest defaults (will be passed to mikeal/request)
bag.request('get', 'http://somehost', {
    requestOpts: {
      foo: 'bar'
  function (err, result) {

// send request with retry settings
bag.request('get', 'http://somehost', {
    retry: {
      errorCodes: true, // retry on any error
      statusCodes: [404, 503], // retry when response status code is 404 or 503
      scale: 0.5, // increase delay by half on each retry
      delay: 1000, // wait 1 second before retrying
      maxRetries: 10 // only retry 10 times at most
  function (err, result) {

// send request with custom proxy
bag.request('get', 'http://somehost', {
    proxy: 'http://user:pass@someproxy:1234'
  function (err, result) {
// get proxy based on URL protocol
// will return undefined when host is localhost or
var proxy = bag.proxy('https://somehost');

// get proxy with custom proxy exclusion
var proxy = bag.proxy('http://somelocalhost', {
  noProxyHosts: ['somelocalhost']


Developer's Guide
Build reports: