Core Building Blocks
Subscription
Asynchronously react to business events
A subscription is a fire-and-forget handler that listens to events and reacts without blocking the emitter. Use subscriptions for cross-service communication, event-driven workflows, async side effects, or any flow where the caller does not need an immediate response.
Subscriptions live inside services alongside commands and streams. The service builder collects subscription definitions, and the event bridge routes matching events to the right handler.
Fire-and-forget event listeners
Subscriptions do not return a response to the caller. They either acknowledge the event (ack), schedule a retry, send it to a dead-letter queue, or drop it. If you need request/response, use a command instead.
In this section
What is a Subscription?
Understand the subscription lifecycle, explicit outcomes, filtering, and bridge advice.
The Subscription Builder
Define typed event subscriptions, filters, before guards, and explicit handler outcomes.
Testing
Test handlers in isolation with mocks or validate bridge routing with runtime harnesses.
Quick reference
Subscription lifecycle
flowchart LR
A[Event Received] --> B[Filter Match?]
B -->|No| C[Event Ignored]
B -->|Yes| D[Before Guards]
D --> E[Subscription Function]
E --> F[Return Outcome]
F -->|ack| G[Message Acknowledged]
F -->|retry| H[Retry Later]
F -->|deadLetter| I[Dead Letter Queue]
F -->|drop| J[Event Dropped]
F -->|stop-consumer| K[Consumer Stopped]Key principles
- Subscriptions are fire-and-forget — they do not return a response to the caller.
- Handler functions must return an explicit outcome:
{ status: 'ack' | 'retry' | 'deadLetter' | 'drop' | 'stop-consumer' }. - Use
async function, not arrow functions, to preservethiscontext. - Before guards run in parallel — any guard that throws cancels the handler.
- After guards are handled by the Service runtime — you define them on the builder but the service orchestrates them.
- Filter which events to process with
subscribeToEvent(),filterSentFrom(),filterReceivedBy(), etc. - Bridge advice (
adviceDurable,adviceAutoacknowledgeMessage, etc.) hints at infrastructure behavior but the bridge decides.