Fn-throttler NPM

fn-throttler

fn-throttler.js uses promises to implement a generic rate limiter that can be used to throttle the rate at which promises (or functions) are run. It currently uses a MongoDB instance to synchronize across multiple cores (or clusters).

Installation

Use NPM to install:

npm install fn-throttler

Usage

1.) Initialize

var Throttler = require('fn-throttler');

    var th = new Throttler({
      max: 100,
      unit: 'second',
      retryInterval: 1000,
      db: $db,
    });

The following options are currently available:

max - Maximum attempts per time interval. Defautls to 100.
unit - Unit for time interval. Supports 'second', 'minute', 'hour' and 'day'. Defaults to 'second'. Can take a numeric value in ms to support an arbitrary time unit. For example to enforce a limit per 5 minutes, 'unit' would be 300000 (1000 60 5).
db - MongoDB connection
key - Unique key for object. Defaults to 'default_key'.
collectionName - MongoDB collection name
maxRetries - Maximum number of retries nextToken() will attempt before rejecting. If not specified, nextToken() will keep reattempting until it resolves.
retryInterval - Interval between attempts. Defautls to 1000ms.

2.) Throttle

  function throttlePromise() {
    ...
    //throttle - will check the limit and either fulfill or retry after a delay
    return th.nextToken()
    .then(()=>{
      return myPromise();
    }

}

##API

`getToken([data])`

Increases request count by 1. Promise resolves if the rate limit hasn't been reached yet. Otherwise the promise is rejected. Optional param 'data' is returned as the fulfilled value.

`nextToken([data], [retry])`

Similar to getToken(), but retries on rejection until the 'retry' limit (if any) is reached. Resolves with 'data' as the value so that nextToken() can be easily used as a promise in the promise chain.

Chaining example:

...
return getRequestParams();
.then(d => nextToken(d))
.then(d => APIrequest(d)
.then(d => 'Success')
...

`runFn(fn, args)`

Similar to nextToken(), but takes in a function (which it promisifies) and an argument array. Once successful, returns a resolved promise with the output of the function as the value.