@quanticjs/events-redis

Redis Streams transport for QuanticJS domain events: RedisStreamPublisher (XADD) and the abstract RedisStreamConsumer (XREADGROUP consumer groups).

⚠️ Reliability notice — The Redis Streams transport provides weaker delivery guarantees than the Kafka transport. Use it for non-critical eventing only unless you enable and tune: minIdleTimeMs/reclaimIntervalMs (orphan reclaim), maxDeliveries (poison-message DLQ), and leave maxStreamLength unset (no trimming). Streams have no replication-acknowledged durability equivalent to Kafka acks=-1.

Minimum supported Redis: 6.2 (XAUTOCLAIM). On older Redis, orphaned-entry reclaim is disabled with an error log and only the startup PEL drain runs.

Usage

QuanticEventsRedisModule.forRoot({
  consumer: {
    minIdleTimeMs: 60_000,     // entries idle longer are reclaimable from dead consumers
    reclaimIntervalMs: 30_000, // XAUTOCLAIM loop period
    maxDeliveries: 5,          // delivery-count cap before dead-lettering
    readBatchSize: 10,
    blockMs: 5_000,
  },
  publisher: {
    // maxStreamLength: 100_000, // OFF by default — see "Stream retention" below
  },
})

Consumer options can also be passed per consumer through the RedisStreamConsumer constructor's second argument (these defaults apply when omitted).

Reliability behavior

• Orphan reclaim — a periodic XAUTOCLAIM loop claims entries idle ≥ minIdleTimeMs from any consumer in the group (including dead pods) and reprocesses them. Set minIdleTimeMs above your worst-case handler time, otherwise an entry still being processed can be claimed and processed twice (inherent to streams; the inbox primitive dedups command effects if used).
• Poison messages / DLQ — an entry whose delivery count exceeds maxDeliveries is appended to <streamKey>:dlq (full original fields plus originalId, stream, group, deliveryCount, deadLetteredAt — replayable) and then XACKed. The DLQ write happens before the ack, so a failed DLQ write loses nothing. DLQ streams are never trimmed by this package; monitor and drain them operationally.
• Startup PEL drain — on boot the consumer drains its entire pending-entries list in batches before live tailing begins.
• Ordinary failures — a failed entry is left un-acked in the PEL; the reclaim loop retries it after minIdleTimeMs until maxDeliveries routes it to the DLQ.

Stream retention

RedisStreamPublisher performs no trimming by default — streams grow unbounded. Pick one:

• Set publisher.maxStreamLength consciously, sized to worst-case consumer backlog. Trimming is approximate (MAXLEN ~) and silently drops unconsumed entries once the cap is passed.
• Leave it unset and run an operational retention job (periodic XTRIM after checking consumer-group lag).