Token bucket

A token bucket starts with a finite capacity. Each accepted request spends one token, while tokens return at a steady rate up to the configured maximum.

Use it when

• Short bursts are legitimate.
• Sustained traffic must settle at a predictable average rate.
• Your users perform naturally bursty actions.

const limiter = createRateLimiter({
  algorithm: Algorithms.TOKEN_BUCKET,
  limit: 20,
  windowMs: 10_000,
  store,
});

Here, the bucket holds 20 tokens and refills from empty to full over ten seconds. Token accounting is continuous — refill is calculated from elapsed time on every call rather than snapped to a boundary — so partially refilled buckets are never mistaken for full ones. remaining is always a whole number; resetAt is the time the bucket reaches full capacity given the current decision, and retryAfterMs (present when denied) is the shorter wait until just one token becomes available.