View Source 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:

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 into strong consistency for individual event handlers and command dispatch as required.

quick-overview

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})