Defines the behaviour an event handler must implement.

Provides a convenience macro that implements the behaviour, allowing you to handle only the events you are interested in processing.

You should start your event handlers using a Supervisor to ensure they are restarted on error.

Event handler name

The name you specify is used when subscribing to the event store. Therefore you should not change the name once the handler has been deployed. A new subscription will be created when you change the name, and you event handler will receive already handled events.

Subscription options

You can choose to start the event handler’s event store subscription from :origin, :current position, or an exact event number using the start_from option. The default is to use the origin so your handler will receive all events.

Use the :current position when you don’t want newly created event handlers to go through all previous events. An example would be adding an event handler to send transactional emails to an already deployed system containing many historical events.

Example

Set the start_from option (:origin, :current, or an explicit event number) when using Commanded.Event.Handler:

defmodule AccountBalanceHandler do
  use Commanded.Event.Handler, name: "AccountBalanceHandler", start_from: :origin

  # ...
end

You can optionally override :start_from by passing it as option when starting your handler:

{:ok, _handler} = AccountBalanceHandler.start_link(start_from: :current)