@oratis/rate-limit

A zero-dependency, in-memory sliding-window rate limiter for Node. One small file, fully typed, self-pruning so it won't leak memory. Perfect for protecting an API route, a queue worker, or a CLI on a single instance — no Redis required.

• 🪶 Zero dependencies, tiny footprint
• 🎚️ True sliding window (not a coarse fixed bucket)
• 🧹 Self-pruning — an unref'd timer sweeps stale keys; never keeps your process alive
• 🧰 Class API (peek / reset / dispose) and a one-liner
• 📦 Ships ESM + CJS + types

Single-process by design. Behind a load balancer each instance limits independently — fine for coarse abuse protection; use a shared store (Redis) when you need a strict global limit.

Install

npm install @oratis/rate-limit

Quick start

import { rateLimit } from "@oratis/rate-limit";

// Allow 100 requests per minute per IP.
const { allowed, remaining, resetMs } = rateLimit(ip, 100, 60_000);
if (!allowed) {
  return new Response("Too Many Requests", {
    status: 429,
    headers: { "Retry-After": String(Math.ceil(resetMs / 1000)) },
  });
}

Class API

Reach for RateLimiter when you want peek, reset, or explicit lifecycle control:

import { RateLimiter } from "@oratis/rate-limit";

const limiter = new RateLimiter({ limit: 5, windowMs: 10_000 });

limiter.check("user:42");   // record a request → RateLimitResult
limiter.peek("user:42");    // inspect without recording
limiter.reset("user:42");   // forget one key
limiter.reset();            // forget everything
limiter.dispose();          // stop the prune timer when you're done

RateLimitResult

Field	Type	Meaning
allowed	boolean	Whether the request is within the limit.
remaining	number	Requests left in the current window (0 when blocked).
resetMs	number	Ms until capacity frees up (great for a Retry-After header).

new RateLimiter(options)

Option	Type	Default	Description
limit	number	—	Max requests per rolling window (> 0).
windowMs	number	—	Window length in ms (> 0).
pruneIntervalMs	number	300000	Stale-key sweep interval. 0 disables the timer.

How it works

Each key keeps the timestamps of its requests. On every check, timestamps older than windowMs are dropped; if what remains is below limit, the request is allowed and recorded. This gives a true rolling window — no burst at the fixed-bucket boundary that naive counters suffer from.

License

MIT © oratis