Skip to content

Add before, after and around hooks for applying events - #567

Merged
erikrozendaal merged 2 commits into
masterfrom
improvement/apply-hooks
Nov 11, 2026
Merged

erikrozendaal merged 2 commits into
masterfrom
improvement/apply-hooks

Conversation

@erikrozendaal

Copy link
Copy Markdown
Member

Summary

A condition that must hold before and after every change of an aggregate, such as no event touching a closed period, can only be checked by overriding the protected apply and repeating what it does around apply_event. The handler hooks of MessageHandler do not fit, since they also run when an aggregate is loaded, where a period closed later must not stop the events from before it.

  • before_apply, after_apply and around_apply on AggregateRoot, from the new Sequent::Core::Helpers::ApplyHooks. They take a method name or a block, which receive the event. An around hook method continues by yielding, an around hook block by calling the continuation it receives.
  • only: and except: take the same arguments as on: an event class matches that class only, is_a(SomeEvent) matches its subclasses as well, and other message matchers like has_attrs work too.
  • Live only: the hooks run in apply, not in apply_event, so loading, streaming and loading from a snapshot don't run them.
  • Order: the before hooks in the order in which they are declared, then the around hooks (the first declared one outermost), the event and the after hooks. Hooks are inherited by subclasses.
  • Failures: when a hook raises, the event is not added to the uncommitted events. An around hook that does not apply the event raises, rather than leaving an event in the uncommitted events that never reached the state.

Aggregates without hooks behave as before. An application that overrides apply itself does not run the hooks until its override does.

Tests

spec/lib/sequent/core/apply_hooks_spec.rb:

  • the order of before, around and after hooks, with methods and blocks;
  • only: and except: with classes (exact), is_a (subclasses) and has_attrs;
  • the hooks don't run when loading;
  • inherited hooks run before those of a subclass;
  • a raising hook and an around hook that does not continue leave no uncommitted event;
  • the argument checks.

@erikrozendaal
erikrozendaal requested a balanced review from Copilot November 11, 2026 13:01
@erikrozendaal
erikrozendaal marked this pull request as ready for review November 11, 2026 13:01

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

An around hook can apply an event twice while recording it once, causing live and replayed state to diverge, and subclasses miss superclass hooks registered after their own hooks.

2 open issues
What changed in this PR

Adds event-application hooks to AggregateRoot so aggregates can check conditions around live state changes without running those checks during replay.

Changes:

  • Introduces before_apply, after_apply, and around_apply, with method/block callbacks and event matcher filters.
  • Integrates hooks into live event application while leaving history loading unchanged.
  • Adds specifications and documentation for ordering, inheritance, filtering, and failure behavior.
File Description
spec/​lib/​sequent/​core/​apply_hooks_spec.rb Tests hook behavior, filtering, inheritance, and validation.
lib/​sequent/​core/​helpers/​apply_hooks.rb Implements hook registration and execution.
lib/​sequent/​core/​aggregate_root.rb Runs hooks during live event application.
docs/​docs/​concepts/​aggregate-root.md Documents hook usage and failure semantics.
CHANGELOG.md Announces the new hooks and links to documentation.

Review effort: Balanced

Comment thread lib/sequent/core/helpers/apply_hooks.rb Resolved
Comment thread lib/sequent/core/helpers/apply_hooks.rb Resolved
A condition that must hold before and after every change, such as no
event touching a closed period, could only be checked by overriding the
protected apply and repeating what it does around apply_event. The
handler hooks of MessageHandler do not fit, since they also run when an
aggregate is loaded, where a period closed later must not stop the
events from before it.

An around hook that does not apply the event fails rather than leaving
an event in the uncommitted events that never reached the state.
An around hook could call its continuation twice. apply_event then ran
twice while the event was recorded once, so the state after loading the
aggregate differed from the state it had when the event was applied.
The second application is now refused before it runs.

A subclass that declared a hook held a copy of the inherited hooks, so
a hook added to the superclass afterwards, by reopening it or including
a module, never ran for it. Each class now keeps its own hooks and
combines them with those of its superclass on lookup, cached until a
hook is added anywhere, as MessageHandler does for its handler hooks.
@erikrozendaal
erikrozendaal force-pushed the improvement/apply-hooks branch from 6be8b02 to f1d94af Compare November 11, 2026 13:48
@erikrozendaal
erikrozendaal merged commit 654b6de into master Nov 11, 2026
8 checks passed
@erikrozendaal
erikrozendaal deleted the improvement/apply-hooks branch November 11, 2026 13:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants