Skip to main content

@livon/dlq-module

npm Package Size Security Scorecard CI

Purpose​

@livon/dlq-module listens to runtime onError events, tracks retry attempts in event context, and replays events until maxAttempts is reached.

Best for​

Use this module when you need retry control and dead-letter handling for failed runtime events.

Install​

pnpm add @livon/dlq-module

Basic usage​

import {dlqModule} from '@livon/dlq-module';

runtime(
  dlqModule({
    maxAttempts: 5,
    storeBrokenEvent: async (brokenEvent) => {
      await db.dlq.insertOne(brokenEvent);
    },
    countPendingEvents: async () => db.dlq.countPending(),
    loadReadyEvents: async () => db.dlq.loadReady(),
  }),
);

Parameters​

dlqModule({...}):

  • maxAttempts (number, required): max retry count before event is finalized as failed.
  • storeBrokenEvent ((brokenEvent) => Promise<void>, required): persists failed events (including updated context).
  • countPendingEvents (() => number | Promise<number>, required): returns pending replay count; ticker stops when <= 0.
  • loadReadyEvents (() => EventEnvelope[] | Promise<EventEnvelope[]>, required): loads events ready to replay in current tick.

Callback parameter details:

  • brokenEvent (EventEnvelope): failed event with context.dlq metadata and timestamp fields.

Context enrichment​

Module adds:

context.dlq = {
  attempts,
  maxAttempts,
  firstErrorAt,
  lastErrorAt,
  final,
};

Replay behavior​

  • status receiving events replay via emitReceive
  • status sending events replay via emitSend
  • final failures remain failed and are not replayed