Domain Events

## What a domain event is A domain event is a small, **immutable** object that captures a fact: something significant has already happened inside the domain model, and the rest of the system may care about it. Structurally it usually carries three things: 1. a **name** that identifies what happened; 2. an **occurred-at timestamp**; 3. just enough **data** (typically the aggregate's identifier plus a handful of relevant fields) for a listener to know what to do next. It does not carry behavior or ask for anything to be validated — by the time it exists, validation is over. ## Why the tense: a request versus a fact The past-tense naming convention exists to keep two very different kinds of objects from being confused with each other: commands and events. | | Command | Domain event | |---|---|---| | Example | `ShipOrder`, `CancelSubscription` | `OrderShipped`, `SubscriptionCancelled` | | What it is | a request — it names an intention, is phrased as an imperative | a report of something that has already been committed to the aggregate's state and passed all invariants | | Can it be rejected | it can be rejected (the order might already be shipped, the subscription might already be cancelled) | it cannot be un-happened, and nothing downstream gets a vote on whether it should have occurred | The model already decided that when the aggregate accepted the command. Naming disciplines this distinction into the code itself: **any type ending in an imperative verb is a request, anything phrased as a completed action is a fact.** This matters because command and event types frequently coexist in the same module (an application service handling `ShipOrder`, an aggregate raising `OrderShipped` in response), and without the naming convention it becomes easy to accidentally treat a fact as if it were still negotiable, or to dispatch a request to something expecting a completed fact. ## Why model events explicitly at all The main reason to model events explicitly at all, rather than just calling further methods directly from inside the aggregate, is **decoupling and expressiveness**. If `OrderAggregate.ship()` directly called `inventoryService.releaseHold()` and `notificationService.sendShippedEmail()`, the aggregate would need compile-time knowledge of every downstream concern that cares about shipping, and testing it would require mocking all of them. By instead raising an `OrderShipped` event and letting something else subscribe to it, the aggregate stays focused purely on its own invariants, and new listeners can be added without touching the aggregate's code. This is the **open/closed principle** applied to business behavior: the shipping outcome becomes a stable extension point. ## The trade-off The trade-off is **ceremony and indirection**. Every event needs: - its own type; - a place where it's raised; - one or more listeners. That is more moving parts than a plain method call for something simple like a `total` recalculation. Chasing "what happens when an order ships" now means jumping from the aggregate to wherever listeners are registered, rather than reading top to bottom in one method. Overusing events for trivial internal bookkeeping the aggregate could just do inline is a real failure mode: it turns straightforward control flow into a scavenger hunt and makes debugging harder, without buying any real decoupling benefit because nothing external actually needs to react. ## The naming-drift failure mode A second failure mode is **naming drift**: teams that reuse a single generic event like `OrderUpdated` for every kind of change lose the very benefit past-tense, fact-based naming was meant to provide. A listener subscribed to `OrderUpdated` has to inspect the payload or a `changeType` field to figure out what actually happened, pushing the responsibility of interpreting intent out of the type system and into runtime logic — effectively turning a strongly-typed fact back into an untyped notification. The naming convention only pays off if events are also granular and intent-revealing, not just tense-correct. ## A worked example A concrete example: in an e-commerce system, an `Order` aggregate exposes a `ship(trackingNumber)` method. Internally it: 1. checks invariants (order must be Paid, items in stock); 2. transitions its own status to Shipped; 3. and only then constructs and records an `OrderShipped(orderId, trackingNumber, shippedAt)` event. Nothing calls "ShipOrder" as an event — that would be the command that triggered the method, likely from an application service handling an HTTP request or scheduled job. Once `OrderShipped` exists, in-process listeners inside the same bounded context can react — for example, decrementing a fulfillment metrics counter — without the `Order` aggregate needing to know those listeners exist. The event is the seam between "what happened to the order" and "what the rest of the model does about it".