A bag-of-holding containing request utility functions
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.



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 http_proxy, HTTP_PROXY, https_proxy, HTTPS_PROXY
  • 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 http_proxy or HTTP_PROXY
  • if URL uses https, then sets proxy to htps_proxy or HTTPS_PROXY, otherwise fallback to http_proxy or HTTP_PROXY
  • if URL does not have a protocol, assume http protocol
  • if URL is not provided, then set proxy to http_proxy or HTTP_PROXY, otherwise fallback to https_proxy or HTTPS_PROXY
  • proxy will be ignored if host is on no_proxy or NO_PROXY 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: