TypeScripttypescriptrate-limitingapisecurityproduction-ready

Token Bucket Rate Limiter

An in-memory token bucket rate limiter with sliding window support for API endpoint protection and request throttling.

interface RateLimitConfig {
  maxTokens: number;
  refillRate: number; // tokens per second
  refillInterval: number; // ms between refills
}

interface BucketState {
  tokens: number;
  lastRefill: number;
}

export class TokenBucketRateLimiter {
  private buckets = new Map<string, BucketState>();
  private readonly config: RateLimitConfig;
  private cleanupInterval: NodeJS.Timeout;

  constructor(config: RateLimitConfig) {
    this.config = config;
    // Periodically clean up expired buckets
    this.cleanupInterval = setInterval(() => this.cleanup(), 60_000);
  }

  consume(key: string, tokens: number = 1): { allowed: boolean; remaining: number; retryAfterMs: number } {
    const bucket = this.getBucket(key);
    this.refill(bucket);

    if (bucket.tokens >= tokens) {
      bucket.tokens -= tokens;
      return { allowed: true, remaining: Math.floor(bucket.tokens), retryAfterMs: 0 };
    }

    const deficit = tokens - bucket.tokens;
    const retryAfterMs = Math.ceil((deficit / this.config.refillRate) * 1000);
    return { allowed: false, remaining: 0, retryAfterMs };
  }

  private getBucket(key: string): BucketState {
    if (!this.buckets.has(key)) {
      this.buckets.set(key, {
        tokens: this.config.maxTokens,
        lastRefill: Date.now(),
      });
    }
    return this.buckets.get(key)!;
  }

  private refill(bucket: BucketState): void {
    const now = Date.now();
    const elapsed = now - bucket.lastRefill;
    const tokensToAdd = (elapsed / 1000) * this.config.refillRate;

    if (tokensToAdd > 0) {
      bucket.tokens = Math.min(this.config.maxTokens, bucket.tokens + tokensToAdd);
      bucket.lastRefill = now;
    }
  }

  private cleanup(): void {
    const now = Date.now();
    const maxAge = (this.config.maxTokens / this.config.refillRate) * 1000 * 2;
    for (const [key, bucket] of this.buckets) {
      if (now - bucket.lastRefill > maxAge && bucket.tokens >= this.config.maxTokens) {
        this.buckets.delete(key);
      }
    }
  }

  reset(key: string): void {
    this.buckets.delete(key);
  }

  destroy(): void {
    clearInterval(this.cleanupInterval);
    this.buckets.clear();
  }
}

// Middleware factory for Express/Connect-style frameworks
export function createRateLimitMiddleware(config: RateLimitConfig) {
  const limiter = new TokenBucketRateLimiter(config);

  return function rateLimitMiddleware(req: any, res: any, next: () => void) {
    const key = req.ip || req.headers["x-forwarded-for"] || "unknown";
    const result = limiter.consume(key);

    res.setHeader("X-RateLimit-Limit", config.maxTokens);
    res.setHeader("X-RateLimit-Remaining", result.remaining);

    if (!result.allowed) {
      res.setHeader("Retry-After", Math.ceil(result.retryAfterMs / 1000));
      res.status(429).json({
        error: "Too Many Requests",
        retryAfterMs: result.retryAfterMs,
      });
      return;
    }

    next();
  };
}

title: "Token Bucket Rate Limiter" description: "An in-memory token bucket rate limiter with sliding window support for API endpoint protection and request throttling." category: "TypeScript" language: "typescript" tags: ["typescript", "rate-limiting", "api", "security", "production-ready"] createdAt: "2025-03-01" updatedAt: "2025-03-20"

Overview

A token bucket rate limiter that smoothly throttles requests while allowing short bursts. Unlike fixed window counters, the token bucket refills continuously, preventing the "thundering herd" problem at window boundaries and providing a more consistent user experience.

Code

const limiter = new TokenBucketRateLimiter({
  maxTokens: 100,        // burst capacity
  refillRate: 10,        // tokens per second (sustained rate)
  refillInterval: 1000,  // refill check interval
});
 
const result = limiter.consume(clientId);
// { allowed: true, remaining: 99, retryAfterMs: 0 }

Notes

  • Token bucket allows bursts up to maxTokens while enforcing refillRate as sustained throughput
  • The retryAfterMs field tells clients exactly when to retry, enabling cooperative rate limiting
  • Memory is bounded by the cleanup routine that removes fully-replenished buckets
  • For distributed systems, replace the Map with Redis using atomic MULTI/EXEC operations
  • Set X-RateLimit-* headers so clients can self-throttle before hitting limits