Command routing macro to allow configuration of each command to its command handler.

Example

Define a router module which uses Commanded.Commands.Router and configures available commands to dispatch:

defmodule BankRouter do
  use Commanded.Commands.Router

  dispatch OpenAccount,
    to: OpenAccountHandler,
    aggregate: BankAccount,
    identity: :account_number
end

The to option determines which module receives the command being dispatched. This command handler module must implement a handle/2 function. It receives the aggregate's state and the command to execute. Usually the command handler module will forward the command to the aggregate.

Once configured, you can either dispatch a command using the module by and specify the application:

command = %OpenAccount{account_number: "ACC123", initial_balance: 1_000}

:ok = BankRouter.dispatch(command, application: BankApp)

Or, more simply you should include the router module in your application:

defmodule BankApp do
  use Commanded.Application, otp_app: :my_app

  router MyApp.Router
end

Then dispatch commands using the app:

command = %OpenAccount{account_number: "ACC123", initial_balance: 1_000}

:ok = BankApp.dispatch(command)

Dispatch command directly to an aggregate

You can route a command directly to an aggregate, without requiring an intermediate command handler.

Example

defmodule BankRouter do
  use Commanded.Commands.Router

  dispatch OpenAccount, to: BankAccount, identity: :account_number
end

The aggregate must implement an execute/2 function that receives the aggregate's state and the command being executed.

Define aggregate identity

You can define the identity field for an aggregate once using the identify macro. The configured identity will be used for all commands registered to the aggregate, unless overridden by a command registration.

Example

defmodule BankRouter do
  use Commanded.Commands.Router

  identify BankAccount,
    by: :account_number,
    prefix: "bank-account-"

  dispatch OpenAccount, to: BankAccount
end

An optional identity prefix can be used to distinguish between different aggregates that would otherwise share the same identity. As an example you might have a User and a UserPreferences aggregate that you wish to share the same identity. In this scenario you should specify a prefix for each aggregate (e.g. "user-" and "user-preference-").

The prefix is used as the stream identity when appending and reading the aggregate's events: "". It can be a string or a zero arity function returning a string.

Consistency

You can choose the consistency guarantee when dispatching a command. The available options are:

• :eventual (default) - don't block command dispatch while waiting for event handlers

  :ok = BankApp.dispatch(command) :ok = BankApp.dispatch(command, consistency: :eventual)

• :strong - block command dispatch until all strongly consistent event handlers and process managers have successfully processed all events created by the command.

  Use this when you have event handlers that update read models you need to query immediately after dispatching the command.

  :ok = BankApp.dispatch(command, consistency: :strong)

• Provide an explicit list of event handler and process manager modules (or their configured names), containing only those handlers you'd like to wait for. No other handlers will be awaited on, regardless of their own configured consistency setting.

  :ok = BankApp.dispatch(command, consistency: [ExampleHandler, AnotherHandler])
  :ok = BankApp.dispatch(command, consistency: ["ExampleHandler", "AnotherHandler"])

  Note you cannot opt-in to strong consistency for a handler that has been configured as eventually consistent.

Aggregate version

You can optionally choose to include the aggregate's version as part of the dispatch result by setting include_aggregate_version true.

{:ok, aggregate_version} = BankApp.dispatch(command, include_aggregate_version: true)

This is useful when you need to wait for an event handler (e.g. a read model projection) to be up-to-date before continuing or querying its data.

Execution results

You can also choose to include the execution result as part of the dispatch result by setting include_execution_result true.

{:ok, execution_result} = BankApp.dispatch(command, include_execution_result: true)

Or by setting include_execution_result in your application config file:

# config/config.exs
config :commanded, include_execution_result: true

Use this if you need to get information from the events produced by the aggregate but you don't want to wait for the events to be projected.

Metadata

You can associate metadata with all events created by the command.

Supply a map containing key/value pairs comprising the metadata:

:ok = BankApp.dispatch(command, metadata: %{"ip_address" => "127.0.0.1"})