@fortify-ts/rate-limit

Token bucket rate limiter for the Fortify-TS resilience library.

Installation

npm install @fortify-ts/rate-limit
# or
pnpm add @fortify-ts/rate-limit

Features

• Token Bucket Algorithm: Smooth rate limiting with burst support
• Per-Key Limiting: Rate limit by user ID, IP, or custom key
• External Storage: Support for Redis, DynamoDB, or custom storage
• Sync and Async APIs: Both allow() and allowAsync() methods
• Wait Support: Block until tokens available with wait()

Usage

Basic Usage

import { RateLimiter } from '@fortify-ts/rate-limit';

const limiter = new RateLimiter({
  rate: 100,      // 100 requests
  interval: 1000, // per second
});

// Check if request is allowed
if (limiter.allow('user-123')) {
  // Process request
} else {
  // Rate limited
}

With Burst

const limiter = new RateLimiter({
  rate: 10,       // 10 requests per second steady state
  burst: 50,      // Allow bursts up to 50 requests
  interval: 1000,
});

Wait for Token

// Block until token available (with timeout via signal)
await limiter.wait('user-123', signal);
// Token acquired, process request

Execute with Rate Limiting

// Throws RateLimitExceededError if rate limited
const result = await limiter.execute(
  async (signal) => fetch('/api/data', { signal }),
  'user-123'
);

External Storage (Redis)

import { RateLimiter, type RateLimitStorage } from '@fortify-ts/rate-limit';
import Redis from 'ioredis';

const redis = new Redis();

const storage: RateLimitStorage = {
  async get(key) {
    const data = await redis.get(`ratelimit:${key}`);
    return data ? JSON.parse(data) : null;
  },
  async set(key, state) {
    await redis.set(`ratelimit:${key}`, JSON.stringify(state), 'EX', 3600);
  },
  async delete(key) {
    await redis.del(`ratelimit:${key}`);
  },
};

const limiter = new RateLimiter({
  rate: 100,
  interval: 1000,
  storage,
});

Configuration Options

const limiter = new RateLimiter({
  // Requests per interval
  rate: 100,

  // Interval in milliseconds
  interval: 1000,

  // Maximum burst size (defaults to rate)
  burst: 200,

  // Tokens consumed per request
  tokensPerRequest: 1,

  // Maximum buckets in memory
  maxBuckets: 10000,

  // External storage adapter
  storage: myRedisStorage,

  // Storage timeout
  storageTimeoutMs: 1000,

  // Failure mode: 'fail-open' | 'fail-closed' | 'throw'
  storageFailureMode: 'fail-open',

  // Sanitize keys (prevents injection)
  sanitizeKeys: true,

  // Rate limit exceeded callback
  onLimit: (key) => console.log(`Rate limited: ${key}`),

  // Optional logger
  logger: myLogger,
});

API Reference

| Method | Description | |--------|-------------| | allow(key) | Sync check if request allowed | | allowAsync(key) | Async check with external storage | | wait(key, signal?) | Wait for token availability | | execute(op, key, signal?) | Execute with rate limiting | | getTokens(key) | Get current token count | | reset(key) | Reset bucket for key | | close() | Clean up resources |

Configuration Reference

| Option | Type | Default | Description | |--------|------|---------|-------------| | rate | number | 100 | Requests per interval | | interval | number | 1000 | Interval (ms) | | burst | number | rate | Maximum burst | | tokensPerRequest | number | 1 | Tokens per request | | maxBuckets | number | 10000 | Max memory buckets | | storage | RateLimitStorage | - | External storage | | storageTimeoutMs | number | 1000 | Storage timeout | | storageFailureMode | string | 'fail-open' | Failure handling | | sanitizeKeys | boolean | true | Sanitize keys | | onLimit | function | - | Rate limit callback | | logger | FortifyLogger | - | Optional logger |

License

MIT