limiter

The library provides two main classes for rate limiting:

1. TokenBucket: A lower-level interface that uses a configurable burst rate and drip rate. It is useful for scenarios like byte-level throttling.
2. RateLimiter: A higher-level abstraction built on top of TokenBucket. It is designed to comply with common API restrictions (e.g., "150 requests per hour") by adding a restriction on the maximum number of tokens that can be removed each interval.

When using these classes, it is recommended to use them with a message queue to prevent multiple simultaneous calls to removeTokens(). Without a queue, earlier messages might be held up for long periods if newer messages continually drain the bucket, potentially causing out-of-order or seemingly "lost" messages.

Install the limiter package using yarn:

yarn add limiter

Both RateLimiter and TokenBucket provide a synchronous method tryRemoveTokens(tokens). This method returns immediately with a boolean: true if the tokens were successfully removed, or false if they were not.

import { RateLimiter } from "limiter";

const limiter = new RateLimiter({ tokensPerInterval: 10, interval: "second" });

if (limiter.tryRemoveTokens(5)) {
  console.log('Tokens removed');
} else {
  console.log('No tokens removed');
}

Use TokenBucket for more granular control, such as throttling data at the byte level. It allows you to define a bucketSize (burst capacity) and a tokensPerInterval (sustained drip rate).

Configuration Options:

• bucketSize: The maximum number of tokens the bucket can hold (burst capacity).
• tokensPerInterval: The number of tokens added to the bucket per interval.
• interval: The duration of the interval (e.g., 'second', 'minute', or milliseconds).

import { TokenBucket } from "limiter";

const BURST_RATE = 1024 * 1024 * 150; // 150KB/sec burst rate
const FILL_RATE = 1024 * 1024 * 50; // 50KB/sec sustained rate

const bucket = new TokenBucket({
  bucketSize: BURST_RATE,
  tokensPerInterval: FILL_RATE,
  interval: "second"
});

async function handleData(myData) {
  await bucket.removeTokens(myData.byteLength);
  sendMyData(myData);
}

To check how many tokens are currently available without triggering the waiting behavior of removeTokens(), use the getTokensRemaining() method.

import { RateLimiter } from "limiter";

const limiter = new RateLimiter({ tokensPerInterval: 1, interval: 250 });

// Returns the current count of available tokens
console.log(limiter.getTokensRemaining());

The RateLimiter class manages request intervals using a token bucket mechanism. When initializing, you must provide a RateLimiterOpts object.

Options:

• tokensPerInterval (number): The maximum number of tokens that can be removed at any given moment and over the course of one interval.
• interval (Interval): The interval length. This can be a number representing milliseconds, or one of the following strings: 'second', 'minute', 'hour', or 'day'.
• fireImmediately (boolean, optional): If true, the removeTokens method will resolve immediately (returning -1) when rate limiting is in effect. If false (default), it will wait until enough tokens become available.

The tryRemoveTokens(count: number) method attempts to remove tokens without waiting. It is useful for logic that needs to skip an action rather than queue it.

• Returns true: If the tokens were successfully removed.
• Returns false: If the request exceeds the maximum allowed tokens or if the interval limit has already been reached.

The TokenBucket class implements a hierarchical token bucket algorithm for rate limiting. You can instantiate it by passing a TokenBucketOpts object.

Configuration Options