typescript-decompiler/docs/explanation/why-events-not-booleans.md

Why Events, Not Booleans

A policy should usually return a rich domain fact, not just true or false.

The problem with booleans

A boolean only tells you whether something was allowed. It does not tell you what happened, why it happened, or what data the rest of the system needs next.

For example, this policy is usually too thin:

const canLoadPackage = (truck: LoadingTruck, pkg: Package): boolean => {
  // ...
}

The workflow now has to reconstruct meaning from the inputs and repeat domain reasoning elsewhere.

What an event gives you

A better policy returns a success event or a failure event.

Result<PackageLoaded, LoadFailure>

That gives the workflow concrete domain facts:

• PackageLoaded says what succeeded
• LoadFailure says why the decision failed
• the event payload can carry the exact information needed for the next step

This keeps the workflow mechanical. It does not need to invent new business meaning after the decision has already been made.

Events improve reviewability

Events are also easier for humans to review than booleans. A reviewer can ask:

• Are these the right outcomes?
• Does each outcome carry the data the system needs next?
• Are we returning domain facts instead of UI phrasing or infrastructure detail?

Those are much easier questions to answer when the outputs are explicit event types.

Events are data, not instructions

An event is a fact about what happened. It is not a command to perform side effects.

• Good: PackageLoaded
• Bad: SendPackageLoadedEmail

The workflow decides what to do with the fact in context. That is where orchestration belongs.

A good rule of thumb

If a policy output would force the workflow to ask "yes, but what exactly happened?", return an event instead of a boolean.