Using Commanded

Commanded provides the building blocks for you to create your own Elixir applications following the CQRS/ES pattern.

A separate guide is provided for each of the components you can build:

  • Application.
  • Aggregates.
  • Commands, registration and dispatch.
  • Events and handlers.
  • Process managers.

Commanded uses strong consistency for command dispatch (write model) and eventual consistency, by default, for the read model. Receiving an :ok reply from dispatch indicates the command was successfully handled and any created domain events fully persisted to your chosen event store. You may opt-in to strong consistency for individual event handlers and command dispatch as required.

Quick overview

Here's an example bank account opening feature built using Commanded to demonstrate its usage.

  1. Define an OpenBankAccount command:

     defmodule OpenBankAccount do
       defstruct [:account_number, :initial_balance]
     end
  2. Define a corresponding BankAccountOpened domain event:

     defmodule BankAccountOpened do
       @derive Jason.Encoder
       defstruct [:account_number, :initial_balance]
     end
  3. Build a BankAccount aggregate to handle the command, protect its business invariants, and return a domain event when successfully handled:

     defmodule BankAccount do
       defstruct [:account_number, :balance]
       # Public command API
       def execute(%BankAccount{account_number: nil}, %OpenBankAccount{account_number: account_number, initial_balance: initial_balance})
         when initial_balance > 0
       do
         %BankAccountOpened{account_number: account_number, initial_balance: initial_balance}
       end
       # Ensure initial balance is never zero or negative
       def execute(%BankAccount{}, %OpenBankAccount{initial_balance: initial_balance})
         when initial_balance <= 0
       do
         {:error, :initial_balance_must_be_above_zero}
       end
       # Ensure account has not already been opened
       def execute(%BankAccount{}, %OpenBankAccount{}) do
         {:error, :account_already_opened}
       end
       # State mutators
       def apply(%BankAccount{} = account, %BankAccountOpened{} = event) do
         %BankAccountOpened{account_number: account_number, initial_balance: initial_balance} = event
         %BankAccount{account |
           account_number: account_number,
           balance: initial_balance
         }
       end
     end
  4. Define a router module to route the open account command to the bank account aggregate:

     defmodule BankRouter do
       use Commanded.Commands.Router
       dispatch OpenBankAccount, to: BankAccount, identity: :account_number
     end
  5. Define an application to host the aggregate and supporting processes:

     defmodule BankApp do
       use Commanded.Application,
         otp_app: :bank,
         event_store: [adapter: Commanded.EventStore.Adapters.InMemory]
       router BankRouter
     end

    This application is configured to use in-memory event store included with Commanded for testing.

  6. Create an event handler module that updates a bank account balance:

     defmodule AccountBalanceHandler do
       use Commanded.Event.Handler,
         application: BankApp,
         name: __MODULE__
       def init do
         with {:ok, _pid} <- Agent.start_link(fn -> 0 end, name: __MODULE__) do
           :ok
         end
       end
       def handle(%BankAccountOpened{initial_balance: initial_balance}, _metadata) do
         Agent.update(__MODULE__, fn _ -> initial_balance end)
       end
       def current_balance do
         Agent.get(__MODULE__, fn balance -> balance end)
       end
     end
  7. Start the application and event handler processes:

     {:ok, _pid} = BankApp.start_link()
     {:ok, _pid} = AccountBalanceHandler.start_link()

    In a real application you would use a supervisor to start these processes.

Finally, we can dispatch a command to open a new bank account:

:ok = BankApp.dispatch(%OpenBankAccount{account_number: "ACC123456", initial_balance: 1_000})