commanded_messaging v0.2.1 CommandedMessaging View Source

Commanded Messaging

Common macros for messaging in a Commanded application

Commands

The Commanded.Command macro creates an Ecto embedded_schema so you can take advantage of the well known Ecto.Changeset API.

defmodule BasicCreateAccount do
  use Commanded.Command,
    username: :string,
    email: :string,
    age: :integer
end

iex> BasicCreateAccount.new()
#Ecto.Changeset<action: nil, changes: %{}, errors: [], data: #BasicCreateAccount<>, valid?: true>

Validation

defmodule CreateAccount do
  use Commanded.Command,
    username: :string,
    email: :string,
    age: :integer

  def handle_validate(command) do
    command
    |> validate_required([:username, :email, :age])
    |> validate_format(:email, ~r/@/)
    |> validate_number(:age, greater_than: 12)
  end
end

iex> CreateAccount.new()
#Ecto.Changeset<action: nil, changes: %{}, errors: [username: {"can't be blank", [validation: :required]}, email: {"can't be blank", [validation: :required]}, age: {"can't be blank", [validation: :required]}], data: #CreateAccount<>, valid?: false>

iex> CreateAccount.new(username: "chris", email: "chris@example.com", age: 5)
#Ecto.Changeset<action: nil, changes: %{age: 5, email: "chris@example.com", username: "chris"}, errors: [age: {"must be greater than %{number}", [validation: :number, kind: :greater_than, number: 12]}], data: #CreateAccount<>, valid?: false>

To create the actual command struct, use Ecto.Changeset.apply_changes/1

iex> command = CreateAccount.new(username: "chris", email: "chris@example.com", age: 5)
iex> Ecto.Changeset.apply_changes(command)
%CreateAccount{age: 5, email: "chris@example.com", username: "chris"}

Note that apply_changes will not validate values.

Events

Most events mirror the commands that produce them. So we make it easy to reduce the boilerplate in creating them with the Commanded.Event macro.

defmodule BasicAccountCreated do
  use Commanded.Event,
    from: CreateAccount
end

iex> command = CreateAccount.new(username: "chris", email: "chris@example.com", age: 5)
iex> cmd = Ecto.Changeset.apply_changes(command)
iex> BasicAccountCreated.new(cmd)
%BasicAccountCreated{
  age: 5,
  email: "chris@example.com",
  username: "chris",
  version: 1
}

Extra Keys

There are times when we need keys defined on an event that aren't part of the originating command. We can add these very easily.

defmodule AccountCreatedWithExtraKeys do
  use Commanded.Event,
    from: CreateAccount,
    with: [:date]
end

iex> command = CreateAccount.new(username: "chris", email: "chris@example.com", age: 5)
iex> cmd = Ecto.Changeset.apply_changes(command)
iex> AccountCreatedWithExtraKeys.new(cmd, date: ~D[2019-07-25])
%AccountCreatedWithExtraKeys{
  age: 5,
  date: ~D[2019-07-25],
  email: "chris@example.com",
  username: "chris",
  version: 1
}

Excluding Keys

And you may also want to drop some keys from your command.

defmodule AccountCreatedWithDroppedKeys do
  use Commanded.Event,
    from: CreateAccount,
    with: [:date],
    drop: [:email]
end

iex> command = CreateAccount.new(username: "chris", email: "chris@example.com", age: 5)
iex> cmd = Ecto.Changeset.apply_changes(command)
iex> AccountCreatedWithDroppedKeys.new(cmd)
%AccountCreatedWithDroppedKeys{
  age: 5,
  date: nil,
  username: "chris",
  version: 1
}

Versioning

You may have noticed that we provide a default version of 1.

You can change the version of an event at anytime.

After doing so, you should define an upcast instance that knows how to transform older events into the latest version.

# This is for demonstration purposes only. You don't need to create a new event to version one.
defmodule AccountCreatedVersioned do
  use Commanded.Event,
    version: 2,
    from: CreateAccount,
    with: [:date, :sex],
    drop: [:email],

  defimpl Commanded.Event.Upcaster, for: AccountCreatedWithDroppedKeys do
    def upcast(%{version: 1} = event, _metadata) do
      AccountCreatedVersioned.new(event, sex: "maybe", version: 2)
    end

    def upcast(event, _metadata), do: event
  end
end

iex> command = CreateAccount.new(username: "chris", email: "chris@example.com", age: 5)
iex> cmd = Ecto.Changeset.apply_changes(command)
iex> event = AccountCreatedWithDroppedKeys.new(cmd)
iex> Commanded.Event.Upcaster.upcast(event, %{})
%AccountCreatedVersioned{age: 5, date: nil, sex: "maybe", username: "chris", version: 2}

Note that you won't normally call upcast manually. Commanded will take care of that for you.

Command Dispatch Validation

The Commanded.CommandDispatchValidation macro will inject the validate_and_dispatch function into your Commanded.Application.