Behaviour and macros for defining event-sourced state machines.

This module provides a behaviour that can be implemented by modules to define event-sourced state machines. It also includes macros to automatically generate boilerplate code for managing state, handling events, taking snapshots, and persisting events.

Usage

To use this module, define a new module and use Hume.Projection with the desired options. Implement the required callbacks to define the initial state, event handling logic, and snapshot management.

Options

When using Hume.Projection, you can provide the following options:

• :store (required): The module implementing the event store behaviour.
• :use_ets: Use ETS for snapshot storage (default is false).
• :snapshot_every: Number of events after which to take a snapshot (default is 100).
• :snapshot_after: Time in milliseconds after which to take a snapshot (default is 30 seconds).
• :catch_up_after: Time in milliseconds after which to check for new events (default is 30 seconds).
• :strict_online: Whether to enforce strict event handling during online catch-up (default is true).

Callbacks

The following callbacks must be implemented by the module using Hume.Projection:

• init_state/1: Initializes the state of the machine.
• handle_event/2: Handles an event and updates the state.
• last_snapshot/1: Retrieves the last snapshot of the machine.
• persist_snapshot/2: Persists a snapshot of the current state.

Example

defmodule MyProjection do
  use Hume.Projection, use_ets: true, store: MyEventStore

  @impl true
  def init_state(_), do: %{}

  @impl true
  def handle_event({:add, key, value}, state),
    do: {:ok, Map.put(state || %{}, key, value)}

  @impl true
  def handle_event({:remove, key}, state),
    do: {:ok, Map.delete(state || %{}, key)}
end

Telemetry

This module emits telemetry events for various operations, including:

• [:hume, :projection, :init]
• [:hume, :projection, :catch_up, :start]
• [:hume, :projection, :catch_up, :stop]
• [:hume, :projection, :snapshot]
• [:hume, :projection, :evolve]
• [:hume, :projection, :replay]
• [:hume, :projection, :on_caught_up]

Shutdown

On :normal termination, the projection will automatically persist its current snapshot.