flex-rate-limit

flex-rate-limit

A framework-agnostic Node.js rate limiting library with multiple algorithms, Memory / Redis / cache-hub backed storage, and Express-style middleware.

Documentation · 中文文档 · Examples

Why Use It

• Framework-agnostic core: call check() from Express, Koa, Egg.js, Hapi, Fastify, workers, queues, or any custom adapter.
• Express-style middleware: use limiter.middleware() directly in Express-compatible stacks.
• Four algorithms: sliding window, fixed window, token bucket, and leaky bucket.
• Multiple stores: in-memory storage, Redis storage, CacheHubStore, or your own store adapter.
• Distributed-ready options: use Redis or cache-hub Redis atomic backends when counters must be shared across instances.
• Standard metadata: each check returns allowed, limit, current, remaining, resetTime, and retryAfter.
• Type definitions included: CommonJS, ESM, and TypeScript consumers are supported.

Requirements

• Node.js >=18.0.0
• npm, pnpm, or another package manager compatible with the npm registry
• Redis is optional and only needed for Redis-backed distributed rate limiting

Installation

npm install flex-rate-limit

Redis-backed usage:

npm install flex-rate-limit ioredis

cache-hub atomic backend usage:

npm install flex-rate-limit cache-hub ioredis

Quick Start

Direct check()

const { RateLimiter } = require('flex-rate-limit');

const limiter = new RateLimiter({
  windowMs: 15 * 60 * 1000,
  max: 100,
});

const result = await limiter.check('user:123');

if (!result.allowed) {
  console.log(`Retry after ${result.retryAfter} ms`);
}

Express Middleware

const express = require('express');
const { RateLimiter } = require('flex-rate-limit');

const app = express();

const globalLimiter = new RateLimiter({
  windowMs: 15 * 60 * 1000,
  max: 100,
});

app.use(globalLimiter.middleware());

const loginLimiter = new RateLimiter({
  windowMs: 15 * 60 * 1000,
  max: 5,
});

app.post('/api/login', loginLimiter.middleware(), (_req, res) => {
  res.json({ message: 'login accepted' });
});

app.listen(3000);

Koa, Egg.js, Hapi, Fastify, and Other Frameworks

Use check() and map the result to the framework's own middleware, hook, or pre-handler shape:

const { RateLimiter } = require('flex-rate-limit');

const limiter = new RateLimiter({
  windowMs: 60 * 1000,
  max: 60,
});

async function guard(ctx, next) {
  const key = `user:${ctx.user?.id || ctx.ip}:${ctx.path}`;
  const result = await limiter.check(key, { route: ctx.path });

  if (!result.allowed) {
    ctx.status = 429;
    ctx.body = { error: 'Too Many Requests', retryAfter: result.retryAfter };
    return;
  }

  await next();
}

See the runnable framework examples on GitHub and the quickstart guide.

Storage Backends

Memory Store

The default store is fast and simple. Use it for single-process services, local development, tests, and cases where counters do not need to be shared across instances.

const limiter = new RateLimiter({
  windowMs: 60 * 1000,
  max: 100,
  store: 'memory',
});

RedisStore

Use RedisStore when multiple application instances must share counters.

const Redis = require('ioredis');
const { RateLimiter, RedisStore } = require('flex-rate-limit');

const redis = new Redis(process.env.REDIS_URL || 'redis://127.0.0.1:6379');

const limiter = new RateLimiter({
  windowMs: 60 * 1000,
  max: 100,
  store: new RedisStore({ client: redis, prefix: 'rl:' }),
});

If you pass store: 'redis://...', RateLimiter creates and owns the Redis client; call await limiter.close() during shutdown. When you pass your own Redis client to RedisStore, that client remains caller-owned unless you set ownsClient: true.

CacheHubStore

CacheHubStore keeps flex-rate-limit as the algorithm and middleware layer while delegating high-concurrency state updates to cache-hub atomic primitives. Pass a Redis client for distributed production usage; omit the client only when an in-memory cache-hub backend is acceptable. The in-memory cache-hub path prunes expired rate-limit state automatically, and await limiter.close() closes store-owned cleanup timers or cache resources.

const Redis = require('ioredis');
const { RateLimiter, CacheHubStore } = require('flex-rate-limit');

const redis = new Redis(process.env.REDIS_URL || 'redis://127.0.0.1:6379');

const limiter = new RateLimiter({
  algorithm: 'sliding-window',
  windowMs: 60 * 1000,
  max: 100,
  store: new CacheHubStore({ client: redis, prefix: 'rl:' }),
});

Read more in the storage guide.

Algorithms

Algorithm	Best For	Notes
sliding-window	Precise rolling limits	Default algorithm; stores more per-key state
fixed-window	High-throughput coarse windows	Fast, but requests can cluster around window boundaries
token-bucket	Controlled bursts	Allows bursts up to capacity and refills over time
leaky-bucket	Smoothing traffic	Drains at a steady rate

Choose semantics first, then optimize storage and hot paths. See algorithm comparison and deep analysis.

Common Configuration

const limiter = new RateLimiter({
  windowMs: 60 * 1000,
  max: 100,
  algorithm: 'sliding-window',
  headers: true,
  keyGenerator: (req) => `user:${req.user?.id || req.ip}:${req.path}`,
  skip: (req) => req.path === '/health',
  handler: (req, res) => {
    res.status(429).json({ error: 'Too Many Requests' });
  },
  perRoute: {
    '/api/login': { max: 5, windowMs: 15 * 60 * 1000 },
    '/api/users': { max: 100, windowMs: 60 * 1000 },
  },
});

Option	Default	Description
windowMs	60000	Time window in milliseconds
max	100	Max requests per window; may be a function
algorithm	sliding-window	One of the four supported algorithms
store	memory	Store instance or 'memory'
keyGenerator	IP-based	Builds the rate-limit key from request context
skip	() => false	Return true to bypass rate limiting
handler	built-in 429 response	Custom over-limit handler
headers	true	Write X-RateLimit-* and Retry-After headers
perRoute	null	Route-specific overrides
skipSuccessfulRequests	false	Roll back successful responses
skipFailedRequests	false	Roll back failed responses

Full details are in the configuration guide and API reference.

Result Shape

{
  allowed: true,
  limit: 100,
  current: 1,
  remaining: 99,
  resetTime: 1767225600000,
  retryAfter: 0
}

Benchmarks

The repository includes reproducible local benchmark scripts for Memory direct checks, Redis direct checks, and HTTP middleware scenarios.

Run these from a cloned repository after installing development dependencies:

npm install
npm run benchmark:memory
npm run benchmark:redis
npm run benchmark:http

The npm runtime package does not require benchmark dependencies. Redis and HTTP benchmark output records the Node.js version, Redis URL, key distribution, concurrency, and other parameters. Use BENCH_JSON=1 when you need machine-readable output.

See Benchmark and Performance for commands, environment variables, and interpretation notes.

Documentation

Entry	Description
Documentation index	English documentation navigation
Chinese documentation	Simplified Chinese documentation navigation
Quickstart	First integration path and framework examples
Configuration	Complete option reference and practical presets
Storage	Memory, Redis, and CacheHubStore selection
Business lock guide	User + route scoped rate limiting
Algorithm comparison	Choosing the right algorithm
API reference	Classes, options, stores, and exports
Benchmark guide	Local benchmark commands and caveats

The website is built with Rspress and reuses the docs/ directory:

npm run docs:dev
npm run docs:validate
npm run docs:build

Examples

Runnable examples are available on GitHub:

Category	Files
Quickstart	quickstart-express.js, quickstart-koa.js, quickstart-egg.js, quickstart-hapi.js, quickstart-fastify.js
Router examples	express-router-example.js, koa-router-example.js, egg-router-example.js, fastify-router-example.js
IP whitelist examples	express-ip-whitelist-independent.js, koa-ip-whitelist-independent.js, ip-whitelist-example.js
Standalone usage	standalone-example.js
Business lock	egg-business-lock-example.js

Development

npm test
npm run test:unit
npm run test:integration
npm run typecheck
npm run lint
npm run coverage

Troubleshooting

• Counters are not shared across instances: use RedisStore or CacheHubStore with a Redis client instead of the default Memory store.
• Redis benchmarks are skipped: start Redis locally or set REDIS_URL / BENCH_REDIS_URL.
• Package installs but Redis code fails at runtime: install and configure a Redis client such as ioredis.
• Short-lived scripts keep running after Redis usage: call await limiter.close() when using store: 'redis://...', or pass ownsClient: true to RedisStore if the store should close your client.
• Koa/Fastify/Hapi integration feels awkward: call check() directly and wrap the result in the framework's native middleware or hook style.
• Benchmark numbers differ from the docs or CI: local CPU, Node.js version, Redis latency, key distribution, and HTTP app work all affect throughput.

Related Projects

• monSQLize - MongoDB ORM with caching
• schema-dsl (GitHub) - JSON Schema validation
• jrpc - JSON-RPC 2.0 implementation

Support

• GitHub Issues
• GitHub Discussions

License

Apache-2.0