Home

ThrottleKit Wiki

Rate limiting you can prove — a machine-checked, fleet-size-independent overshoot bound, on one small core, from a ~320 ns in-process check to a global cluster.

ThrottleKit rests on three ideas: algorithms are pure functions of time, storage is one atomic primitive, and adapters are thin glue. That separation lets the same configuration run as an allocation-free in-process check or atomically across a cluster — and makes the distributed behaviour something you can verify rather than hope for.

New here? Start with Getting Started, then Distributed & provable for the part most libraries hand-wave.

What makes it different

• A formally-verified overshoot bound — independent of fleet size. The two-tier leasing path is model-checked in TLA⁺/TLC: worst-case global admissions collapse to exactly Limit under windowCoupled, no matter how many nodes. See Distributed & provable.
• One algorithm, every backend, proven identical. The same strategy code runs in-memory, on Redis (atomic Lua), and on Postgres — a dual-path conformance suite proves the decisions bit-identical.
• A real synchronous API. checkSync is allocation-free at ~320 ns/op — uncommon among JS limiters.
• Breadth on one core. Seven algorithms, three backends, six frameworks + edge, multi-dimensional single-round-trip checks, fixed-memory DDoS sketches, adaptive concurrency, weighted fair-share admission, and an LLM cost-control stack — tokenBudget metering paired with learnedReservation admission pacing.
• Research-backed, and shipping. The GALE and TALE research programs underpin the distributed guarantees; their results land as real features.

Guides

Page	What's in it
Getting Started	Install, your first limiter, the Decision object, checkSync, batch checks, deterministic time
Choosing a strategy	The seven algorithms and when to use each
Frameworks & the edge	Express, Web fetch/edge, Hono, Next.js, Fastify, Koa
Distributed & provable	Redis, Postgres, two-tier leasing, multi-region, and the formally-verified bound
Advanced limiting	Multi-dimensional limits, adaptive concurrency, leaky-bucket shaping
Overload, fairness & DDoS	Adaptive load-shedding, fair-share & weighted fairness, fixed-memory sketches
Operations	Standards headers, trusted-proxy IP keys, PII-safe HMAC keys, OpenTelemetry, failure modes
Performance	Benchmarks, the honest head-to-head, and where it loses
Migrating	Drop-in paths from express-rate-limit and rate-limiter-flexible, plus recipes
Research: GALE & TALE	The provable distributed-leasing and LLM token-budget-escrow programs

In the repository

• README — the short version of this page.
• THROTTLEKIT.md — full design and architecture.
• SCOREBOARD.md — benchmarks, correctness guarantees, feature matrix.
• docs/FORMAL-MODEL.md — the formally-verified leasing bound.
• research/ — the GALE and TALE tracks.
• examples/ — a runnable file for every feature.
• CHANGELOG.md — release history.