Home

Awesome

superagent-throttle

nodei.co npm github-issues stars forks

A plugin for superagent that throttles requests. Useful for rate or concurrency limited APIs.

Features

Install

  npm i --save superagent-throttle

Basic Usage

const request     = require('superagent')
const Throttle    = require('superagent-throttle')

let throttle = new Throttle({
  active: true,     // set false to pause queue
  rate: 5,          // how many requests can be sent every `ratePer`
  ratePer: 10000,   // number of ms in which `rate` requests may be sent
  concurrent: 2     // how many requests can be sent concurrently
})

request
.get('http://placekitten.com/100/100')
.use(throttle.plugin())
.end((err, res) => { ... })

Events

const request     = require('superagent')
const Throttle    = require('superagent-throttle')

let throttle = new Throttle()
.on('sent', (request) => { ... }) // sent a request
.on('received', (request) => { ... }) // received a response
.on('drained', () => { ... }) // received last response

Compatibility

// node 6
import Throttle from 'superagent-throttle'
// node 4
var Throttle = require('superagent-throttle/dist/node4')
// all browsers supported by superagent
var Throttle = require('superagent-throttle/dist/browser')

Serialised Sub Queues

When using API's to update a client, you may want some serialised requests which still count towards your rate limit, but do not block other requests. You can do that by passing a uri (not necessarily a valid url) to throttle.plugin, for those requests you want to serialise, and leave it out for other async requests. This can be done on the fly, you don't need to initialise subqueues first.

let endpoint = 'http://example.com/endpoint'
request
.get(endpoint)
.set('someData': someData)
.use(throttle.plugin(endpoint))
.end(callback)

it's common to use an endpoint for the uri, simply to serialise requests to that endpoint without interfering with requests to other endpoints

Options

Options can be set after instantiation using the options method.


    var throttle = new require('./index')({ active: false }) // start paused
    throttle.options('active', true) // unpause

Scripts

 - **npm run jsdoc** : `rm -fr ./docs/* && jsdoc lib -d docs`

Api

See the fancy annotated code.

Changelog

0.2.2

0.2.1

0.2.0

Author

Levi Wheatcroft levi@wht.cr

Contributing

Contributions welcome; Please submit all pull requests against the master branch.

License