Home

ThrottleKit Wiki

Rate limiting you can prove — a machine-checked, fleet-size-independent overshoot bound, on one small core, from a 169 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), Postgres, Cloudflare (Durable Objects / D1), DynamoDB, and Deno KV — a dual-path conformance suite proves the decisions bit-identical.
• A real synchronous API. checkSync is allocation-free at 169 ns/op — uncommon among JS limiters.
• Breadth on one core. Seven rate-limit algorithms plus first-class billing quota (calendar-month/-week/-day, fixed, rolling — leap-correct), seven exact backends + a best-effort Workers KV, a dozen+ framework & transport bindings (incl. NestJS — with the new @RateLimit decorator — AWS Lambda, gRPC, tRPC, SvelteKit, Remix, Elysia + a transport-agnostic createEnforcer), non-consuming peek / forecast introspection, multi-dimensional single-round-trip checks, fixed-memory DDoS sketches, adaptive concurrency, weighted fair-share admission, an LLM cost-control stack (tokenBudget / distributedTokenBudget + learnedReservation), a .throttlekit.yaml rate-limit-as-code config, and a throttlekit CLI (benchmark / doctor / replay).
• Research-backed, and shipping. The GALE and TALE research programs underpin the distributed guarantees; their results land as real features.
• Not Node-only. A gRPC service door (throttlekit-server) + a throttlekit-py client reach the same limiter from any language — rate, cost, concurrency, and unified admission — with decisions proven bit-for-bit against language-neutral golden vectors. See Polyglot & Python.

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, fetch/edge, Hono, Next, Fastify, Koa, NestJS, SvelteKit, Remix, Elysia, AWS Lambda, tRPC, gRPC, and createEnforcer for custom transports
Distributed & provable	Redis, Postgres, Cloudflare, DynamoDB, Deno KV, two-tier leasing, multi-region, and the formally-verified bound
Federation	One global limit across regional clusters; proven Δ = 0 independent of region count K (0.8.3)
Unified admission	One Decision across rate + concurrency + cost (LLM-gateway shape); algebra-proven, sequential or Lua-fused (0.9.0)
Pillar 4 — Weighted Fair Escrow	Weighted-fair, work-conserving budget split across tenants; multi-process L2-backed (0.9.1)
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
Polyglot & Python	Reach the same limiter from any language — the throttlekit-server gRPC service + the throttlekit-py client; every axis, bit-for-bit
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.