API Reference

import { rateLimit } from 'universal-rate-limit';

const limiter = rateLimit(options);
const result: RateLimitResult = await limiter(request);

interface RateLimitResult {
    limited: boolean;
    limit: number;
    remaining: number;
    resetTime: Date;
    headers: Record<string, string>;
}

import { buildRateLimitResponse } from 'universal-rate-limit';

const response = await buildRateLimitResponse(request, result, {
    handler: undefined,
    message: 'Too Many Requests',
    statusCode: 429
});

import { extractClientIp } from 'universal-rate-limit';

// Use as part of a custom keyGenerator:
const limiter = rateLimit({
    keyGenerator: req => `${getUserId(req)}:${extractClientIp(req)}`
});

import { IP_HEADERS } from 'universal-rate-limit';
// ['x-forwarded-for', 'x-real-ip', 'cf-connecting-ip', 'fly-client-ip']

import { rateLimit } from 'universal-rate-limit';
import { RedisStore } from '@universal-rate-limit/redis';

const store = new RedisStore({ sendCommand, prefix: 'rl:' });

const authLimiter = rateLimit({ prefix: 'auth', limit: 30, store });
const apiLimiter = rateLimit({ prefix: 'api', limit: 120, store });

┌──────────────┬───────────────┬─────────────────┐
│ Store prefix │ Limiter prefix│ keyGenerator()  │
│ rl:          │ auth:         │ 203.0.113.1     │
└──────────────┴───────────────┴─────────────────┘
 → final key: rl:auth:203.0.113.1

import { MemoryStore } from 'universal-rate-limit';

const store = new MemoryStore({ prefix: 'my-app:', cleanupIntervalMs: 30_000 });

import { RedisStore } from '@universal-rate-limit/redis';

const store = new RedisStore({
    sendCommand: (...args) => redis.call(...args),
    prefix: 'rl:'
});

interface Store {
    prefix?: string;
    consume(key: string, algorithm: Algorithm, limit: number, cost?: number): MaybePromise<ConsumeResult>;
    peek?(key: string, algorithm: Algorithm, limit: number): MaybePromise<ConsumeResult | undefined>;
    unconsume?(key: string, algorithm: Algorithm, limit: number, cost?: number): MaybePromise<void>;
    resetKey(key: string): MaybePromise<void>;
    resetAll(): MaybePromise<void>;
    shutdown?(): MaybePromise<void>;
}

interface ConsumeResult {
    limited: boolean;
    remaining: number;
    resetTime: Date;
    retryAfterMs: number;
}

type AlgorithmConfig =
    | { type: 'fixed-window'; windowMs: number }
    | { type: 'sliding-window'; windowMs: number }
    | { type: 'token-bucket'; refillRate: number; refillMs?: number };

type HeadersVersion = 'draft-6' | 'draft-7';

import { RedisStore } from '@universal-rate-limit/redis';

import { expressRateLimit } from '@universal-rate-limit/express';

import { fastifyRateLimit } from '@universal-rate-limit/fastify';

import { honoRateLimit } from '@universal-rate-limit/hono';

import { withRateLimit, nextjsRateLimit } from '@universal-rate-limit/nextjs';