Emitting an event

An action announces an event with emit, a statement written like reject (Raising a failure). The event reaches its subscribers only once the action's writes have committed.

domains/planning/actions/complete_todo.jadpo:

// domains/planning/actions/complete_todo.jadpoaction complete_todo(todo_id: Todo.id) fails TodoNotFound -> Todo {    var todo: Todo = attempt mark_complete(todo_id)    emit TodoCompleted {        todo_id: todo.id        completed_at: clock.now    }    return todo}

Saved with the action, delivered after it

The event is saved in the same database transaction as the action's writes, and delivered only after that transaction commits. If the action fails or rolls back, the event is thrown away and no subscriber ever sees it. This is known as a transactional outbox: the outbox is the table where events wait to be delivered.

Who can emit

Only actions emit, and they emit only events. A function, a query, a test, a fixture or a seed can't (event.emit_invalid). Routes, schedules and subscribers emit by calling an action.

No attempt, and nothing back

emit needs no attempt. It can't fail with a domain failure, and a storage problem is a fault that fails the whole action (Faults).

emit returns nothing. The caller can't wait for, or read, what subscribers do. A route that needs the finished result waits with settle: (Waiting for follow-on work).

Where the event is kept

The event goes in the outbox of the store the action's transaction is in, written as the action commits, with a delivery record for each subscriber, pending and due at once. An action that began no transaction keeps them in the store it writes or, if it writes none, in the one events: { store: } names, beginning its transaction there for them.

An action that emits but writes no store, itself or through what it calls, needs application { events: { store: main } }. Without it, it is event.store_required, even when it reads a store.

An event nothing subscribes to is still written. Its row keeps its type's key, its payload as the contract's JSON, when it was emitted, the emitting action's traceparent, the encoding its payload was written in, and how deep in a chain of events it is. A route whose action emits but writes no store keeps its Idempotency-Keys beside its events (Idempotent writes).

Limits

More than 1,000 events in one action, or an event whose JSON is over 64 KB, is a defect as it is emitted, and the action rolls back.