[thetutlage]

📚 Description

Adds a limit:exceeded event, emitted every time a request is rejected because the key has exhausted its requests.

emitter.on('limit:exceeded', ({ key, response }) => {
  logger.warn({ key, consumed: response.consumed }, 'rate limit exceeded')
})

The event is emitted from every rejection path, exactly once per rejection:

• Limiter.consume() when the store rejects the request (covers attempt() and MultiLimiter.consume() too)
• The pre-consume checks in attempt(), penalize(), MultiLimiter.penalize() and HttpLimiter.throttle()

Methods that only update the counters (increment(), set(), block()) do not emit the event. The next rejected request does.

The payload is { key, response }. For limiters created using limiter.define(), the key is prefixed with the limiter name (e.g. login_ip_127.0.0.1), which can be used to identify the limiter.

Wiring

• The provider passes the app emitter to LimiterManager, which shares it with every Limiter and MultiLimiter it creates.
• The emitter is optional, so standalone usage is unchanged.
• The event is registered on EventsList for typed listeners.
• The event is emitted without awaiting, so listeners never delay the request.

Context

Comes out of the discussion on #19. A global event serves observability for enforced limits as well, and lets the dry run mode proposed in #20 report through the same event instead of the limitExceeded callback.

🤖 Generated with Claude Code