Learn about our RFC process, Open RFC meetings & more.Join in the discussion! »


1.0.0 • Public • Published

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:



npm i bagofrequest

DownloadsWeekly Downloads






Last publish


  • avatar