@trellisorg/distributed-rate-limiter NPM

@trellisorg/distributed-rate-limiter

This library is designed for distributed rate limiting using Redis to ensure that rate limits are not exceeded for internal or external services.

Installation

npm install @trellisorg/distributed-rate-limiter ioredis

Setup

Standalone TypeScript

import { DistributedRateLimiter } from '@trellisorg/distributed-rate-limiter';

const rateLimiter = new DistributedRateLimiter({
    client: {
        host: 'localhost',
        port: 6379,
    },
    retryOptions: {},
    rateLimiterPrefix: '@trellisorg/distributed-rate-limiter',
    window: 1_000,
    maximum: 10,
    retryFunctions: [],
});

// Limit the number of calls to the function to 10 per second.
await rateLimiter.withLimit('my-resource', async () => {
    // Do something here.
});

NestJS

import { Module } from '@nestjs/common';
import { DistributedRateLimiterModule } from '@trellisorg/distributed-rate-limiter/nest';

@Module({
    imports: [
        DistributedRateLimiterModule.forRoot([
            {
                config: {
                    client: {
                        host: 'localhost',
                        port: 6379,
                    },
                    retryOptions: {},
                    rateLimiterPrefix: '@trellisorg/distributed-rate-limiter',
                    window: 1_000,
                    maximum: 10,
                    retryFunctions: [],
                },
                name: 'rateLimiter',
            },
        ]),
    ],
})
export class AppModule {}

Configuration Options

Option	Type	Default	Description
`client`	`RedisOptions`	`{ host: 'localhost', port: 6379 }`	The connection options for Redis, these will be passed into `ioredis` if a string or redis options or will just use the Redis instance otherwise.
`retryOptions`	`RetryOptions`	`{}`	Configuration for retrying, how long, how many times, backoff, etc. These options are directly from promiseRetry and will be passed directly into it.
`rateLimiterPrefix`	`string`	`'@trellisorg/distributed-rate-limiter'`	A rate limiter prefix that will be used to save the rate limit information "under" (will be used as the Redis key prefix).
`window`	`number`	`1_000`	The window size for the rate limiter, this will determine the amount of operations per this window. For example, if this is set to 1000 (ms) and {@link maximum} is 10 then there can be 10 operations per second.
`maximum`	`number`	`10`	The maximum number of operations per the {@link window}.
`retryFunctions`	`ShouldRetry[]`	`[]`	A series of functions that will be run on errors thrown by the limited function when using the `withLimit` function of the `DistributedRateLimiter` class. If any of these functions return true, the function will be run again after awaiting rate limit.

Usage

Standalone TypeScript

import { DistributedRateLimiter } from '@trellisorg/distributed-rate-limiter';

const rateLimiter = new DistributedRateLimiter({
    client: {
        host: 'localhost',
        port: 6379,
    },
    retryOptions: {},
    rateLimiterPrefix: '@trellisorg/distributed-rate-limiter',
    window: 1_000,
    maximum: 10,
    retryFunctions: [],
});

// Limit the number of calls to the function to 10 per second.
await rateLimiter.withLimit('my-resource', async () => {
    // Do something here.
});

NestJS

import { Injectable } from '@nestjs/common';
import { DistributedRateLimiter } from '@trellisorg/distributed-rate-limiter';
import { InjectRateLimiter } from '@trellisorg/distributed-rate-limiter/nest';

@Injectable()
export class MyService {
    constructor(
        @InjectRateLimiter('rateLimiter') private readonly rateLimiter: DistributedRateLimiter
    ) {}

    async myMethod() {
        await this.rateLimiter.withLimit('my-resource', async () => {
            // Do something here.
        });
    }
}