Ts-leaky-bucket NPM

TS Leaky Bucket

Port of leaky-bucket to Typescript. Original package was using experimental modules which required a runtime flag and also didn't have nice Typescript types.

Overview

Implementation of a leaky bucket algorithm to support throttling / rate limiting. Check out ts-request-rate-limiter if you are looking for a library to limit client requests (e.g. rate limiting requests to an API).

Install

npm i ts-leaky-bucket

Usage

Create a `LeakyBucket`

Constructor Options

capacity - unit of capacity of a bucket
intervalMillis - time to fully drain the bucket
timeoutMillis - time to queue additional items over capacity

import { LeakyBucket, LeakyBucketOptions } from "ts-leaky-bucket";

const options: LeakyBucketOptions = {
  capacity: 120,
  intervalMillis: 60_000,
  timeoutMillis: 300_000,
}

// constructor takes `LeakyBucketOptions`
const bucket = new LeakyBucket(options);

// OR just use constructor directly

// constructor with options
const bucket = new LeakyBucket({
  capacity: 120,
  intervalMillis: 60_000,
  timeoutMillis: 300_000,
});

Throttling

Way to add things to a bucket and then wait for the bucket to leak them.

maybeThrottle(cost: number = 1, append: boolean = true, isPause: boolean = false): Promise<void>

cost - how much unit capacity to take for this maybeThrottle
append - add to back of queue or beginning
isPause - used to denote an item being a pause request

import { LeakyBucket, LeakyBucketOptions } from "ts-leaky-bucket";
 
const bucket = new LeakyBucket({
  capacity: 120,
  intervalMillis: 60_000,
  timeoutMillis: 300_000,
});

async myBizLogicToThrottle(): void {
  // wait for bucket to say we are ready
  await maybeThrottle(20); // 20 units of capacity

  // now do work
  myBizLogic();
}

Pausing

Two ways to pause the bucket from leaking:

pause(millis = 1000) - pause the bucket from leaking for given millis
pauseByCost(cost: number) - pauses the bucket from leaking for a given for cost

// create bucket
...

// do throttled work
...

// pause leaking for a second
await bucket.pause();

// pause for 100 units of cost
await bucket.pauseForCost(100);

// do more thottled work

Await Empty

If you want to wait for all items to leak out of a bucket you can use awaitEmpty.

// create bucket
...

// do throttled work
...

// wait for bucket to empty
await bucket.awaitEmpty();

Other Methods

pay(cost: number) - post-hoc leak after a throttle to pay down additional unit cost
stopTimerAndClearQueue - clear the timer and queue

Development Commands

npm i - install deps
npm run test - run tests
npm run publish - publish

Changes

I've changed the code a bit from the original:

Naming changes
- isEmpty => awaitEmpty to capture that a call to this waits until the queue empties
- throttle => maybeThrottle to capture that it may return immediately if there is capacity or wait if not
- interval => intervalMillis clarify unit of time
- timeout => additionalTimeoutMillis clarify unit of time and also make clear this is in addition to intervalMillis
- requestRate => requestRateInSecs clarify unit of time
API Changes
- Uses milliseconds as the time unit instead of a mix between seconds and milliseconds
- Does not allow post creation options changing; Original allows updating capacity, interval, timeout at runtime which I didn't want to encourage
- additionalTimeoutMillis is added to intervalMillis instead of treated as a independent variable
- pause(millis: number) uses milliseconds instead of seconds to be consistent
- uses getters instead of getXXX for reading options back out