A powerful macro for defining event-sourced domains in a declarative way.

Domains in Sorcery represent your business entities and their rules. Each domain:

• Defines its state shape
• Declares what events can occur
• Specifies how events change state
• Handles commands that generate events

Domain Structure

A domain consists of:

1. State - The current data structure of your domain
2. Events - Things that have happened (facts)
3. Commands - User intentions that may generate events
4. Event Handlers - Functions that update state based on events
5. Command Handlers - Functions that validate commands and generate events

Auto-Starting

Domains are automatically started when your application boots. This ensures that:

1. All domains are ready to handle commands immediately
2. Domains listening for events from other domains don't miss any events
3. Event handlers are always active

Example

defmodule MyApp.UserDomain do
  use Sorcery.Domain

  domain do
    # Define the state shape
    state :name, default: nil
    state :email, default: nil
    state :status, default: :inactive

    # Define an event
    event :user_registered do
      field :name, type: :string
      field :email, type: :string

      # How this event changes state
      apply fn state, event ->
        %{state |
          name: event.name,
          email: event.email,
          status: :active
        }
      end
    end

    # Define a command
    command :register_user do
      field :name, type: :string
      field :email, type: :string

      # Command validation and event generation
      handle fn state, command ->
        cond do
          state.status == :active ->
            {:error, :already_registered}
          !valid_email?(command.email) ->
            {:error, :invalid_email}
          true ->
            event = %__MODULE__.Events.UserRegistered{
              name: command.name,
              email: command.email
            }
            {:ok, [event]}
        end
      end
    end
  end
end

State Definition

State fields are defined using the state/2 macro:

state :name, default: nil
state :email, default: nil
state :status, default: :inactive

Event Definition

Events are defined using the event/2 macro and must include:

• Fields that the event carries
• An apply function that updates state

event :user_registered do
  field :name, type: :string
  field :email, type: :string

  apply fn state, event ->
    %{state | name: event.name, email: event.email}
  end
end

Command Definition

Commands are defined using the command/2 macro and must include:

• Fields that the command requires
• A handle function that validates and generates events

command :register_user do
  field :name, type: :string
  field :email, type: :string

  handle fn state, command ->
    # Return {:ok, [events]} on success
    # Return {:error, reason} on failure
    {:ok, [%Events.UserRegistered{...}]}
  end
end

External Events

You can handle events from other domains using external_event/2:

external_event OtherDomain.Events.SomethingHappened do
  apply fn state, event ->
    # Update state based on external event
    state
  end
end

Best Practices

1. Keep Domains Focused: Each domain should represent a single business concept
2. Events are Facts: Name events in past tense, they represent things that happened
3. Commands May Fail: Always handle validation in command handlers
4. State is Private: Only expose state changes through commands
5. Event Handlers are Pure: They should only transform state, no side effects