Publishing Events

Class-level publish

The most common way to publish:

Order::Placed.publish(order_id: 1, total: 99.99)              # async (default)
Order::Placed.publish(order_id: 1, total: 99.99, sync: true)   # sync

Instance-level publish

Create the event first, then publish:

event = Order::Placed.new(order_id: 1, total: 99.99)
event.publish                    # async
event.publish(sync: true)        # sync

Useful when you need the event object (e.g., for tracing).

Sync vs async

Async (default): Each handler is dispatched as an ActiveJob. Handlers run independently — one failure doesn't affect others.

Sync: Handlers called inline in the current thread. Useful for tests and when you need immediate execution.

Caused by

Link an event to its cause:

order_event = Order::Placed.new(order_id: 1, total: 99.99)
Shipment::Reserved.publish(order_id: 1, caused_by: order_event)

The child event's caused_by_id is set to the parent's id, and they share the same trace_id. See Tracing for details.

What happens on publish

1. Check suppression — skip if suppressed
2. Persist to event_store if configured (failure doesn't halt)
3. Find subscribed handlers
4. Dispatch each handler (async or sync)