rate-limiter

Overview#

Rate limiting protects your services from abusive traffic, runaway clients, and accidental self-denial-of-service. @backendkit-labs/rate-limiter provides four algorithms behind a single consume(key) call, so you can start in-memory with zero dependencies and migrate to Redis without changing application code.

Every call returns Result<RateLimitResult, RateLimitError> — a store failure (Redis down) is distinct from a rate-limited request (allowed: false). You decide whether to fail open or return 503 on store errors; a 429 is always an explicit branch.

Algorithms#

Configuration#

Redis Store#

All algorithm logic runs as atomic Lua scripts via EVALSHA (with EVAL fallback on NOSCRIPT). Consume + check + update is a single round-trip — no race conditions across multiple instances.

Add circuitBreaker: { fallbackToMemory: true } to keep limits enforced locally when Redis is unavailable. Each instance maintains its own counter during the outage, so the effective limit becomes maxRequests × instanceCount — an acceptable trade-off for continued availability.

NestJS Integration#

Register RateLimiterModule.forRoot() once with globalGuard: true to protect every route. Override per-route with @RateLimit(config) or disable entirely with @RateLimit(null).

Use forRootAsync when the configuration depends on ConfigService or other injectable providers. The module re-creates the limiter instance on each initialization — safe for hot-reload in development.

Trust proxy for IP-based limiting

When running behind a reverse proxy (Nginx, Cloudflare, AWS ALB), configure Express trust proxy so request.ip reflects the real client IP from X-Forwarded-For:

const app = await NestFactory.create(AppModule);
app.set('trust proxy', 1); // trust one proxy hop

Examples#

From basic to production-grade — copy and adapt.

import { RateLimiterFactory, type TokenBucketConfig } from '@backendkit-labs/rate-limiter';

const config: TokenBucketConfig = {
  algorithm:       'token-bucket',
  store:           'memory',
  bucketSize:      20,
  tokensPerSecond: 5,
  keyPrefix:       'api:',
};

const limiter = RateLimiterFactory.create(config);

app.use(async (req, res, next) => {
  const result = await limiter.consume(req.ip ?? 'unknown');
  if (!result.ok) return next(); // store error — fail open

  res.set('X-RateLimit-Limit',     String(result.value.totalLimit));
  res.set('X-RateLimit-Remaining', String(result.value.remaining));
  res.set('X-RateLimit-Reset',     String(Math.ceil(result.value.resetAt / 1000)));

  if (!result.value.allowed) {
    const retryAfter = Math.ceil((result.value.resetAt - Date.now()) / 1000);
    return res.status(429).set('Retry-After', String(retryAfter))
      .json({ error: 'too_many_requests', retryAfter });
  }
  next();
});

⚖️ vs. Alternatives#

✅ Supported  ·  ❌ Not supported  ·  ⚠️ Partial / workaround needed. Download counts are approximate weekly npm averages.