Hermes PostgreSQL
    Preparing search index...

    Class AsyncOutboxConsumer<Message>Template

    Asynchronous outbox consumer for non-critical messages.

    Unlike the main outbox (WAL-based via Logical Replication), the async outbox uses polling and is suitable for:

    • Compensation commands
    • Notifications
    • Cleanup operations
    • Messages where delivery timing is flexible
    Feature Main Outbox Async Outbox
    Mechanism PostgreSQL Logical Replication Polling
    Message Loss Risk Zero (WAL-based) Low (DB-based)
    Latency Real-time streaming Poll interval
    WAL Impact Yes (retention) No
    Use Case Critical events Non-critical messages

    The async outbox is typically created via useBasicAsyncOutboxConsumerPolicy and accessed through the main outbox consumer's send() method.

    Message - The type of domain messages/events

    // Created automatically via policy
    const outbox = createOutboxConsumer({
      // ...
      asyncOutbox: useBasicAsyncOutboxConsumerPolicy()
    })

    // Critical events → main outbox (WAL-based)
    await outbox.queue(orderCreatedEvent, { tx: sql })

    // Compensations → async outbox (polling-based)
    await outbox.send(revertPaymentCommand)

    Type Parameters

    • Message extends JSONValue

    Implements

    Index

    Methods

    send start stop

    Methods

    • Sends a message or array of messages to the async outbox.

      Messages are stored in the asyncOutbox table and processed via polling. Unlike queue(), this doesn't use PostgreSQL Logical Replication.

      When to use:

      • Compensation commands
      • Non-critical notifications
      • Cleanup operations
      • Messages where delivery timing is flexible

      Parameters

      Returns Promise<void>

      If database connection is not established

      If message insertion fails

      // Send single compensation command
      await outbox.send({
        messageId: constructMessageId('RevertPayment', orderId),
        messageType: 'RevertPayment',
        message: { type: 'RevertPayment', data: { orderId } }
      })

      // Send multiple messages atomically
      await outbox.send([compensationCmd1, compensationCmd2])

      // Send within a transaction
      await sql.begin(async (sql) => {
        await updateSomething(sql)
        await outbox.send(compensationCmd, { tx: sql })
      })

    • Starts the async outbox consumer polling loop.

      Begins polling the asyncOutbox table at the configured interval for undelivered messages.

      Returns Stop

      Stop function for graceful shutdown

      If consumer is already started

      const asyncOutbox = createAsyncOutboxConsumer({
        getSql: () => sql,
        publish: async (envelope) => {
          await handleMessage(envelope)
        },
        consumerName: 'my-service'
      })

      const stop = asyncOutbox.start()

      // Later, stop gracefully
      await stop()

    Settings

    Member Visibility

    On This Page

    Key Differences from Main OutboxUsage
    Methods