GeezerVison

Summary

A limit set too tight rejects real traffic. dryRun lets a limit run in production first and only report, before it rejects anything:

 consume(key, points)
   under the limit → headers, next()
   over the limit
+    onLimited(info, context)          // every call over the limit
+    dryRun → headers, no Retry-After, next()
     else   → headers + Retry-After, throw TooManyRequests

• dryRun?: boolean | PredicateFn — default false. A predicate decides per call, e.g. to enforce for some callers first. The call still consumes its points, so the headers and context.params.rateLimit show where it stands.
• onLimited?: (info, context) => Promisable<void> — every call over the limit, rejected or let through; the hook for a log line or a metric. It gets the same RateLimitInfo as the headers.
• A store that fails is no call over the limit: it still rejects, dryRun or not, and doesn't reach onLimited.
• Breaking: the rejection no longer carries data.rateLimitRes (the TODO(next major)). An error's data goes to the client, and on a shared bucket the limiter's points tell every caller how much everyone else calls. data is { retryAfter, headers? }; the limiter's answer — or a failing store's error — stays on context.params.rateLimit.

 throw new TooManyRequests('Too many requests', {
-  rateLimitRes: res,
   retryAfter,
   ...(values ? { headers: values } : {}),
 })

Evidence

dryRun: true, 1 point / 60 s
  1st call → passes, onLimited not called
  2nd call → next() runs, RateLimit headers without Retry-After, consumedPoints 2,
             onLimited({ limit: 1, remaining: 0, reset: 60, window: 60, limited: true }, context)
dryRun: context => context.params.trial
  over the limit with trial → passes; without → TooManyRequests
onLimited without dryRun → called once, then TooManyRequests
rejection → error.data equals { retryAfter, headers } exactly; consumedPoints on context.params.rateLimit
failing store with dryRun → TooManyRequests without data, the store's error on context.params.rateLimit,
                             onLimited not called

pnpm test: 158 files, 2009 passed, no lint errors, no type errors.

Merge Danger

Door: two-way

dryRun and onLimited are off by default. Dropping rateLimitRes is a breaking change for anyone reading error.data.rateLimitRes — a major, or a minor if that's judged rare enough.

Blast Radius: small

Clients lose the limiter's raw points in the error body; retryAfter and the headers stay. Server code reading error.data.rateLimitRes reads context.params.rateLimit instead.

🤖 Generated with Claude Code