limiterx

Universal production-ready rate limiting for JavaScript/TypeScript. Works in Node.js, browsers, edge runtimes, and Bun.

---

Why limiterx?

Feature	limiterx	express-rate-limit	rate-limiter-flexible
Algorithms	fixed window, sliding window, token bucket	fixed window only	many
Adapters	Express, Koa, Node HTTP, Next.js (API + Edge), React, fetch, Axios	Express only	manual integration
Edge Runtime support	✅ (Next.js middleware, no Node built-ins)	❌	❌
React / browser	✅ hook + fetch + Axios	❌	❌
Redis built-in	✅ (limiterx/redis)	via plugin	✅
Dynamic max per request	✅ async function	✅	manual
Zero runtime dependencies	✅	✅	❌
IETF RateLimit-* headers	✅ (draft-6/7/8)	✅	manual
TypeScript-first	✅ strict types	partial	partial
Tree-shakeable	✅ subpath imports	❌	❌

---

Features

• Three algorithms: fixed window, sliding window, and token bucket
• Zero runtime dependencies in core
• Backend adapters: Express, Node HTTP, Next.js (API + Edge), Koa
• Frontend adapters: React hook, fetch wrapper, Axios interceptor
• In-memory store with LRU eviction (default 10,000 keys)
• Optional Redis store (limiterx/redis) for multi-process deployments
• Standard RateLimit-* headers (IETF draft-6, draft-7, draft-8 selectable)
• Optional legacy X-RateLimit-* headers for GitHub/Twitter API compatibility
• Dynamic max as async function — per-user tier limits
• skipSuccessfulRequests / skipFailedRequests — only count what matters
• Custom handler — replace built-in 429 response entirely
• IPv6 subnet masking (default /56) for fair per-user tracking
• Tree-shakeable subpath exports (sideEffects: false)
• Dual ESM/CJS output
• TypeScript-first with strict types

---

Installation

npm install limiterx

---

Quick Start

Express

import express from 'express';
import { rateLimitExpress } from 'limiterx/express';

const app = express();

app.use(rateLimitExpress({
  max: 100,
  window: '15m',
}));

app.get('/api/data', (req, res) => {
  res.json({ message: 'Hello!' });
});

app.listen(3000);

Koa

import Koa from 'koa';
import { rateLimitKoa } from 'limiterx/koa';

const app = new Koa();

app.use(rateLimitKoa({
  max: 100,
  window: '15m',
}));

app.use((ctx) => {
  ctx.body = { message: 'Hello!' };
});

app.listen(3000);

Node HTTP

import http from 'http';
import { rateLimitNode } from 'limiterx/node';

const limiter = rateLimitNode({ max: 100, window: '15m' });

http.createServer(async (req, res) => {
  const result = await limiter(req, res);
  if (!result.allowed) {
    res.writeHead(429, { 'Content-Type': 'text/plain' });
    res.end('Too many requests');
    return;
  }
  res.writeHead(200);
  res.end('Hello!');
}).listen(3000);

Next.js API Route

import { rateLimitNext } from 'limiterx/next';

const limiter = rateLimitNext({ max: 20, window: '1m' });

export async function GET(req: Request) {
  const result = await limiter.check(req);
  if (!result.allowed) return;
  return Response.json({ data: 'ok' });
}

Next.js Edge Middleware

import { rateLimitEdge } from 'limiterx/next';

export const middleware = rateLimitEdge({
  max: 10,
  window: '30s',
});

export const config = { matcher: ['/api/:path*'] };

React Hook

import { useRateLimit } from 'limiterx/react';

function SubmitButton() {
  const { allowed, remaining, attempt } = useRateLimit('form-submit', {
    max: 5,
    window: '1m',
  });

  return (
    <button onClick={() => attempt() && submitForm()} disabled={!allowed}>
      Submit ({remaining} left)
    </button>
  );
}

Fetch Wrapper

import { rateLimitFetch } from 'limiterx/fetch';

const guardedFetch = rateLimitFetch(fetch, {
  max: 10,
  window: '1m',
});

const res = await guardedFetch('https://api.example.com/data');

Axios Interceptor

import axios from 'axios';
import { rateLimitAxios } from 'limiterx/axios';

const client = axios.create();

rateLimitAxios(client, {
  max: 10,
  window: '1m',
});

// Throws RateLimitError when limit exceeded
const res = await client.get('https://api.example.com/data');

Core API (No Framework)

import { createRateLimiter } from 'limiterx';

const limiter = createRateLimiter({
  max: 100,
  window: '15m',
  onLimit: (result) => console.log(`Blocked: ${result.key}`),
});

const result = await limiter.check('user-123');
// { allowed: true, remaining: 99, limit: 100, retryAfter: 0, resetAt: Date, key: 'user-123' }

---

Adapters

Adapter	Import	Type	Default key
Express	limiterx/express	Backend middleware	req.ip (IPv6 /56)
Node HTTP	limiterx/node	Backend (developer-controlled response)	req.socket.remoteAddress
Next.js API	limiterx/next	Backend (API routes)	req.ip or x-forwarded-for
Next.js Edge	limiterx/next	Backend (Edge middleware)	req.ip or x-forwarded-for
Koa	limiterx/koa	Backend middleware	ctx.ip (IPv6 /56)
React	limiterx/react	Frontend hook	key param
Fetch	limiterx/fetch	Frontend wrapper	'global'
Axios	limiterx/axios	Frontend interceptor	'global'

---

Configuration

All adapters share the same configuration shape:

Option	Type	Default	Description
max	number | (ctx) => number | Promise<number>	required	Max requests per window. Pass a function for per-user tiers.
window	number | string	required	Duration: '30s', '5m', '1h', '1d', or milliseconds
algorithm	'fixed-window' | 'sliding-window' | 'token-bucket'	'fixed-window'	Rate limiting algorithm
store	StorageAdapter	new MemoryStore()	Custom storage backend
keyGenerator	(ctx) => string | Promise<string>	IP (backend) / 'global' (frontend)	Custom key resolver (supports async)
skip	(ctx) => boolean | Promise<boolean>	-	Bypass rate limiting for certain requests (supports async)
onLimit	(result, ctx) => void	-	Callback when limit exceeded
handler	(result, ctx) => void | Promise<void>	-	Replaces built-in 429 response entirely; onLimit fires first
message	string | object | (result, ctx) => string | object | Promise<…>	'Too many requests'	Response body on 429 (backend)
statusCode	number	429	HTTP status on deny (backend)
headers	boolean	true	Master gate for all rate limit headers
standardHeaders	'draft-6' | 'draft-7' | 'draft-8'	'draft-6'	IETF RateLimit-* header format
legacyHeaders	boolean	false	Also emit X-RateLimit-* headers (epoch timestamp for Reset)
requestPropertyName	string	'rateLimit'	Property on req/ctx where result is attached for downstream middleware
skipSuccessfulRequests	boolean	false	Don't count requests with 2xx/3xx responses
skipFailedRequests	boolean	false	Don't count requests with 4xx/5xx responses
requestWasSuccessful	(ctx) => boolean | Promise<boolean>	status < 400	Custom success predicate for skip* options
passOnStoreError	boolean	false	Allow requests through on storage errors (fail-open)
ipv6Subnet	number | false	56	IPv6 subnet prefix length for masking; false to disable
maxKeys	number	10000	Max distinct keys in memory (LRU eviction)
debug	boolean	false	Console diagnostics
validate	boolean | Record<string, boolean>	true	Runtime config validation warnings; false to silence all

---

Algorithms

Use the algorithm option to select a rate limiting strategy:

// Fixed window (default) — simple counter, resets on aligned wall-clock boundaries
app.use(rateLimitExpress({ max: 100, window: '15m', algorithm: 'fixed-window' }));

// Sliding window — weighted blend of previous and current window counts
// Eliminates burst-at-boundary spikes; higher memory usage (2 keys per tracked identity)
app.use(rateLimitExpress({ max: 100, window: '15m', algorithm: 'sliding-window' }));

// Token bucket — bucket starts full and refills at max/window rate
// Best for APIs with bursty-but-bounded traffic patterns
app.use(rateLimitExpress({ max: 100, window: '15m', algorithm: 'token-bucket' }));

Algorithm	Burst allowance	Memory per key	Boundary spikes
fixed-window	Full burst at window start	1 key	Yes
sliding-window	Weighted blend	2 keys	No
token-bucket	Burst up to max, then steady	1 key	No

---

HTTP Headers

Backend adapters set standard rate limit headers on every response:

RateLimit-Limit: 100
RateLimit-Remaining: 95
RateLimit-Reset: 540

When denied (429), the Retry-After header is also set:

Retry-After: 540

RateLimit-Reset is a relative countdown in seconds (IETF standard).

Legacy headers

Enable X-RateLimit-* headers for compatibility with clients expecting the GitHub/Twitter convention:

rateLimitExpress({ max: 100, window: '15m', legacyHeaders: true });
// X-RateLimit-Limit: 100
// X-RateLimit-Remaining: 95
// X-RateLimit-Reset: 1711234567   ← absolute Unix epoch (seconds)

Set headers: false to suppress all rate limit headers.

---

Advanced Usage

Dynamic max (per-user tier limits)

app.use(rateLimitExpress({
  max: async (ctx) => {
    const user = await getUserFromDb(ctx.req.user?.id);
    return user?.isPro ? 1000 : 100;
  },
  window: '15m',
}));

skipSuccessfulRequests / skipFailedRequests

// Only count failed login attempts (4xx/5xx), not successful ones
app.use('/login', rateLimitExpress({
  max: 5,
  window: '15m',
  skipSuccessfulRequests: true,
}));

// Custom success predicate
app.use(rateLimitExpress({
  max: 100,
  window: '15m',
  skipSuccessfulRequests: true,
  requestWasSuccessful: (ctx) => ctx.res.statusCode < 400,
}));

Custom handler

app.use(rateLimitExpress({
  max: 100,
  window: '15m',
  handler: (result, ctx) => {
    ctx.res.status(429).json({
      error: 'Rate limit exceeded',
      retryAfter: result.retryAfter,
      resetAt: result.resetAt,
    });
  },
}));

Async keyGenerator

app.use(rateLimitExpress({
  max: 100,
  window: '15m',
  keyGenerator: async (ctx) => {
    const apiKey = ctx.req.headers['x-api-key'];
    if (apiKey) return `api:${apiKey}`;
    return ctx.req.ip;
  },
}));

Async skip

app.use(rateLimitExpress({
  max: 100,
  window: '15m',
  skip: async (ctx) => {
    return isInternalIp(ctx.req.ip);
  },
}));

requestPropertyName

// Access rate limit result in downstream middleware/routes
app.use(rateLimitExpress({
  max: 100,
  window: '15m',
  requestPropertyName: 'rateLimit',  // default
}));

app.get('/status', (req, res) => {
  res.json({ remaining: req.rateLimit.remaining });
});

IPv6 subnet masking

// Default: /56 mask groups IPv6 addresses into subnets
// Increase to /48 for broader grouping, or disable entirely
rateLimitExpress({ max: 100, window: '15m', ipv6Subnet: 48 });
rateLimitExpress({ max: 100, window: '15m', ipv6Subnet: false }); // exact match

---

Redis Store

For multi-process or multi-server deployments, use RedisStore to share counters:

import Redis from 'ioredis';
import { rateLimitExpress } from 'limiterx/express';
import { RedisStore } from 'limiterx/redis';

const client = new Redis({ host: 'localhost', port: 6379 });
const store = new RedisStore(client);

app.use(rateLimitExpress({ max: 100, window: '15m', store }));

RedisStore is compatible with both ioredis and node-redis (v4+). It uses a Lua script for atomic INCR + EXPIRE operations, ensuring correctness under concurrent load.

---

Custom Storage Adapter

Implement the StorageAdapter interface to use any storage backend:

import type { StorageAdapter } from 'limiterx';

class MyStore implements StorageAdapter {
  async get(key: string) { /* ... */ }
  async set(key: string, state: Record<string, number>, ttlMs: number) { /* ... */ }
  async increment(key: string, ttlMs: number): Promise<number> { /* ... */ }
  async decrement(key: string, ttlMs: number): Promise<void> { /* ... */ }
  async delete(key: string) { /* ... */ }
  async clear() { /* ... */ }
}

---

Public API — decrement()

The RateLimiter object returned by createRateLimiter exposes a decrement() method. Use it when you want to "un-count" a request after the fact — for example, implementing skipSuccessfulRequests manually in Node HTTP where the response status is only known after the handler runs:

const limiter = createRateLimiter({ max: 100, window: '15m' });

const result = await limiter.check('user-123');
if (!result.allowed) { /* send 429 */ return; }

// ... run handler, then check response status
if (responseWasSuccessful) {
  await limiter.decrement('user-123');
}

decrement is a no-op if the key is missing or expired (floor at 0).

---

Window Strings

Format	Example	Milliseconds
Milliseconds	'500ms'	500
Seconds	'30s'	30,000
Minutes	'5m'	300,000
Hours	'1h'	3,600,000
Days	'1d'	86,400,000

---

Error Handling

If keyGenerator throws, the error propagates:

• Backend adapters: 5xx response or framework error handler
• Frontend adapters: error thrown to caller
• The request is not treated as allowed or denied (429)

If onLimit throws, the error is silently swallowed.

---

Debug Mode

Warning: Debug output may include keys and IP addresses. Only enable in trusted environments.

const limiter = createRateLimiter({
  max: 10,
  window: '1m',
  debug: true,
});
// Console: [limiterx] ALLOW key="user-123" count=1 remaining=9 (new window)
// Console: [limiterx] DENY key="user-123" count=10 max=10 retryAfter=45000ms

---

TypeScript

Full TypeScript support with strict types:

import type { LimiterxConfig, RateLimiterResult, RateLimiter, StorageAdapter } from 'limiterx';

---

Requirements

• Node.js >= 18.0.0
• TypeScript >= 5.0 (for type consumers)

---

License

MIT