Behaviour and macro for defining Chronicle reducers.

Reducers build and maintain read models by folding events into state. Each event type that the reducer handles is applied in order, progressively updating the read model from its initial state.

Defining a reducer

Use Chronicle.Reducer in a module, declare which events it handles with @handles, and implement the reduce/3 callback.

defmodule MyApp.Reducers.AccountReducer do
  use Chronicle.Reducer, model: MyApp.ReadModels.Account

  @handles MyApp.Events.AccountOpened
  @handles MyApp.Events.FundsDeposited
  @handles MyApp.Events.FundsWithdrawn

  @impl true
  def reduce(%MyApp.Events.AccountOpened{} = event, _model, _context) do
    %MyApp.ReadModels.Account{
      account_id: event.account_id,
      owner_name: event.owner_name,
      balance: event.initial_balance
    }
  end

  def reduce(%MyApp.Events.FundsDeposited{} = event, model, _context) do
    %{model | balance: model.balance + event.amount}
  end

  def reduce(%MyApp.Events.FundsWithdrawn{} = event, model, _context) do
    %{model | balance: model.balance - event.amount}
  end
end

Options for use Chronicle.Reducer

• :model — (required) the read model module this reducer produces.
• :id — a stable string identifier. Defaults to the module's full name.

Registering with Chronicle.Client

{Chronicle.Client,
  ...
  reducers: [MyApp.Reducers.AccountReducer]}

How reducers work

When Chronicle needs the current state of a read model, it:

1. Fetches the stored read model JSON (or starts with nil)
2. Fetches all new events for the relevant event source
3. Sends them to the reducer as a ReduceOperationMessage
4. The reducer applies each event via reduce/3 and returns the final state

The model is stored by Chronicle between calls, so reduce/3 only receives events that occurred since the last successful reduction.

Event context

The third argument to reduce/3 is a map with:

• :event_source_id — the event source (e.g. aggregate ID)
• :sequence_number — the event's position in the event log
• :occurred — when the event was appended (ISO 8601 string)
• :observation_state — the observation state (:initial, :replay, etc.)