leaky-bucket

A fast and efficient leaky bucket implementation

installation

npm i leaky-bucket

build status

usage

var LeakyBucket = require('leaky-bucket');

Constructor

The constructor accepts three parameters, all are optional

var instance = new LeakyBucket([capacity = 60]
                               [, Interval = 60]
                               [, maxWaitingTime = 300]);

Create a new leaky bucket which is allowed to execute 120 items per minute

var bucket = new LeakyBucket(120);

Create a new leaky bucket which is allowed to execute 200 items every 30 seconds

var bucket = new LeakyBucket(200, 30);

Create a new leaky bucket which is allowed to execute 200 items every 30 seconds with a maxWaitingTime of 60 seconds

var bucket = new LeakyBucket(200, 30, 60);

You may also use an options object instead of the parameters

var bucket = new LeakyBucket({
      capacity: 200         // items per interval, defaults to 60
    , interval: 30          // seconds, defaults to 60
    , maxWaitingTime: 60    // seconds, defaults to 300
});

Throttling

The throttle accepts two parameters, of which both are optional

The first parameter can either be a callback function or the cost of the operation
The second parameter can be the callback function

If you do not pass a callback a promise is returned. The first argument of the callback is an error object (or the promise fails) if the item could not be executed because the max waiting time was exceeded.

bucktet.throttle([cost], callback);

The cost parameter can be used to let items cost more than other. The cost of one item defaults to 1. If you execute an item with the cost of 2 it will use 2 slots instead of one.

Throttle an item

bucket.throttle(function(err) {
    // do something
});

Throttle an item with the cost of 10

bucket.throttle(10, function(err) {
    // do something
});

Throttle an using Promises

bucket.throttle().then(function() {
    // ok, do your stuff ...
}).catch(function(err) {
    // max waiting time exceeded, dont execute anything
});

Pausing the leaky bucket

You may pause the leaky bucket for any reason, this will remove items from the end if the wont be executed in time anymore.

Pause the bucket for 5 seconds

bucket.pause(5);

Re-adding items

You may want to re-add items the first position (next item to be executed). No support for promises here.

bucket.reAdd(cost, callback);

Removing left credits

If you dont know how much an item costs in advance you may remove the cost afterwards using the pay method.

let limitReached = bucket.pay(345);

Getting information from the bucket

By calling the getInfo method the bucket returns information about its internals

bucket.getInfo();

{
      left: 100
    , interval: 60
    , capacity: 100
}

Flags

You may start your app using the debug-leaky-bucket flag, this will enable logging for the module

node . --debug-leaky-bucket

Examples

Rate limit API calls on the client side, allowed are no more than 60 requests per minute

var   LeakyBucket = require('leaky-bucket')
    , request     = require('request')
    , bucket;


// create bucket instance, 60 request per minute
bucket = new LeakyBucket(60);


// this will throttle request if required
bucket.throttle(function() {

    // execute request using the request module
    request({
          method: 'get'
        , url: 'http://awesome.api/win'
    }, function(err, response, body) {

    });
});

Rate limit API calls on the server side, allowed are no more than 60 requests per minute

var   LeakyBucket = require('leaky-bucket')
    , request     = require('request')
    , bucket;


// create bucket instance, 60 request per minute, max waiting time = 0
bucket = new LeakyBucket(60, 60, 0);


// this lets pass all request that are within the limit and fail all that
// exceed it
bucket.throttle(function(err) {
    if (err) response.send(429, 'too many requests!');
    else response.send(200, '{id:4, ...}')
});

kroitor / leaky-bucket