liveBook · Manning

Domain event

As explained in Clean Applications with Hexagonal Architecture

An immutable representation of a significant occurrence expressed in the language of the business domain.

A publish handler can become tangled when it also updates statistics, sends notifications, and records analytics. A domain event separates the primary state change from those secondary reactions. It is an immutable, past-tense record of a significant occurrence, expressed in domain language and carrying data rather than behavior. section 4.7 section 4.7.2

Keep the responsibilities on their respective sides of the hexagon:

  • The aggregate decides what happened and queues an event when a significant state change succeeds. It does not know about dispatchers or infrastructure. section 4.7.2
  • The application handler saves the aggregate, retrieves its queued events, and publishes them through an output port. section 4.7.2
  • Listener input adapters react to published events and invoke additional use cases. Each reaction can live in a separate class. section 4.7.2 section 6.6
Figure 4.5 The domain event flow. The aggregate generates the event. The handler publishes it after the save. An input adapter listens and invokes a new use case. The event exits the hexagon through an output port and re-enters through an input adapter—maintaining the architectural boundary in both directions.

The event leaves through an output port and re-enters through a listener input adapter. section 4.7.2

Publishing an article

A successful publish changes a draft's status and records ArticlePublished with article and author identifiers and a publication time. The handler saves the article before publishing its events; listeners can then update statistics or notify subscribers. Tests check that publishing records one event, rejected transitions do not mutate state, and popping events drains the queue. section 4.7.2 section 9.2.5

Choose the event's shape for its boundary. A local event can use domain value types understood within the same bounded context. When several layers must name the contract without depending on the domain module, place it in a shared kernel and use primitive identifiers instead. An integration event is a separate, stable contract for external consumers, not simply the internal event sent farther away. section 6.5.1 section 9.2.4

Local publication is not durable by itself. Synchronous listeners sharing the transaction can cause rollback on failure, but a transaction cannot necessarily undo an external side effect. After-commit listeners avoid rolling back the primary operation, yet a process failure can still lose their work. Cross-boundary delivery needs a durable mechanism, such as an outbox; consumers must be idempotent. section 4.7.3 section 6.5.1 section 6.6

Raise events for facts other parts of the system care about, not automatically for every state change. A list preserves the order in which one aggregate collected events, but that is only an in-process ordering guarantee. Use decorators instead for technical concerns such as logging and metrics around use case execution. section 9.2.5 section 4.7.2 section 4.5.4

How Clean Applications with Hexagonal Architecture covers it

How deep it goes
Works through event generation, publication, listeners, transaction timing, and boundary contracts, while limiting aggregate-list ordering guarantees to one in-process sequence.
Examples
Uses article publication, subscriber notifications, publication statistics, analytics, and aggregate event-draining tests.
What you can do after
Apply domain events by recording them in an aggregate, publishing after persistence, and routing reactions through listeners.
How it connects
Connects aggregates, application handlers, output ports, input adapters, bounded contexts, integration events, and the outbox pattern.

Also explained in

Compare how 4 books explain domain event →

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Clean Applications with Hexagonal Architecture. The section links point to the parts of the book it draws on.