limitkit

Rate limiting as a decision, not a middleware.

pnpm add @bitbaum/limitkit

Why this exists

Twelve near-identical rate limiters were found across nine repos of one fleet — orangecat alone carried four, and its ADR to unify them sat "Proposed" for seven months while the count doubled. What actually varied between the twelve was one thing: where the counts live. Everything else — the window arithmetic, the refusal shape, the headers, the client-IP dance — was the same idea written twelve slightly different ways, with independently re-invented bugs (one kept an unbounded Map keyed by stranger IPs: a slow memory leak fed by the public internet).

So the algorithm is fixed and the store is the seam.

Use

import { slidingWindow, clientIp, toHeaders } from '@bitbaum/limitkit';

const loginLimiter = slidingWindow({ limit: 5, windowMs: 15 * 60_000 });

export async function POST(req: Request) {
  const result = loginLimiter.check(`login:${clientIp(req.headers)}`);
  if (!result.allowed) {
    return Response.json(
      { error: 'Too many attempts' },
      { status: 429, headers: toHeaders(result) },
    );
  }
  // ... the actual work, with toHeaders(result) on the success path too if you like
}

• slidingWindow(rule, store?) — N hits per trailing window. The default;

it is what most hand-rolled "fixed" windows actually meant.

• fixedWindow(rule, store?) — N hits per aligned bucket. Cheaper, burstier

at the boundary (up to 2N around a roll). Choose it by name, not by accident.

• check counts the hit when allowed and counts nothing when refused —

a hammered key recovers the moment the attacker stops, instead of locking the legitimate user behind the same NAT out forever.

• The refusal's retryAfterSeconds is derived from the actual oldest hit,

never fabricated. "Try again shortly" on a window that opens in an hour is a lie; this package refuses to tell it.

The store seam

interface Store {
  get(key: string): { hits: number[] } | undefined;
  set(key: string, state: { hits: number[] }): void;
}

The default MemoryStore is bounded (LRU past maxKeys, default 5 000) — the unbounded-Map leak is impossible by construction. It is per-process: behind N workers the effective limit multiplies by N, which is fine for blunting scripted abuse and wrong for billing enforcement. For shared state, implement those two methods over Redis/Postgres — an adapter is a dozen lines, because the store holds and the algorithm decides.

HTTP edges

• toHeaders(result) — X-RateLimit-Limit / -Remaining / -Reset, plus

Retry-After on refusals only. A plain object you spread into your own response; constructing a Response would mean choosing your framework for you.

• clientIp(headers, { trustedProxies = 1 }) — the forwarded hop your own

proxy wrote, then x-real-ip, then "unknown". A proxy appends to X-Forwarded-For, so the header reads <what the client sent>, <what the proxy saw> and only the last entry is unforgeable. Reading the first one — which this did before v0.2.0 — lets a caller vary the header per request, mint a fresh bucket each time and never trip the limit at all. Set trustedProxies: 2 when a CDN sits in front of your proxy, or 0 when the server is exposed directly and no forwarded header can be believed.

• No HTTP client, no middleware, no framework types — the package supplies

the decision; your app keeps its conventions.

• No limit values — how many attempts a login route allows is app

semantics. Centralize the rule; assert the numbers locally.

• No distributed store — that is your Redis and your ops posture. The

seam is two methods.

Everything takes now as an argument, so all of it is testable without sleeping — which is why this package has tests and the twelve files it replaces, collectively, had almost none.

Development

pnpm run verify  # lint + typecheck + build + test (tests import by package name)

MIT.

Part of bitbaum — AI-native products on open infrastructure, built in Zürich. Every package here lists the apps that use it: which apps use limitkit.

Renamed — limitkit is now @bitbaum/limitkit

Same code, same version, same repository; the package now lives under the @bitbaum npm organization like the rest of the fleet's packages. Install @bitbaum/limitkit and import from it (limitkit stays installable and is deprecated once no adopter uses it). No API changed.

This retrospective record was added on 2026-10-27 from the immutable sources linked below. Git commit dates are source dates, not inferred npm publication dates. A GitHub release does not itself establish npm publication. Application adoption and deployment evidence are tracked separately.

0.2.0

• Tagged source v0.2.0
• Source commit, dated 2026-08-28.

No authored release notes were found for this tag when this record was made. The links identify the verified source; missing feature history is not invented.