@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.
        });
    }
}

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

License

MIT