# `Decree.Command`
[🔗](https://github.com/sparkle-space/decree/blob/v0.1.0/lib/decree/command.ex#L1)

A command whose `command_id` its requester mints.

Every command a router dispatches carries a `command_id`: a lowercase canonical UUID that
whoever asks for the command (a LiveView, a seed, an event handler, an external agent)
mints once and sends with it. A dispatch refuses a command without one, before the
identity is extracted and before any aggregate or decision runs:

  - `{:error, :command_id_required}` - the field is missing, nil, or a binary that is empty
    or only whitespace.
  - `{:error, :invalid_command_id}` - anything else that is not a canonical UUID: an
    uppercase or padded UUID, a UUID without dashes, the raw 16-byte form, an integer, an
    atom.

Nothing repairs a `command_id`: no path generates, fills, trims or downcases one, and the
`command_uuid` a dispatch mints is a different value that never stands in for it. The
refusal is the default middleware `Decree.Middleware.CommandId`, which runs after every
middleware a router registers.

## Declaring a command

    defmodule OpenAccount do
      use Decree.Command

      defstruct [:account_id, :command_id, :initial_balance]
    end

`use Decree.Command` marks the module and checks, once the module has compiled, that it
defines a struct with a `:command_id` field: a module that does not fails to compile. It
does not define the struct, or give the field a default: a default would be one id for
every command of the module.

A router refuses a command that is not a `Decree.Command` when it compiles only when it
asks to, with `use Decree.Commands.Router, require_decree_command: true`. The default is
off for now. The dispatch refusal does not depend on it: a plain struct with a canonical
`command_id` dispatches.

## Checking before dispatch

A facade whose side effect precedes dispatch asks `check_id/1`, which is the rule the
dispatch applies, so it answers the same refusal first.

# `check_id`

```elixir
@spec check_id(term()) :: :ok | {:error, :command_id_required | :invalid_command_id}
```

Whether a `command_id` is one a dispatch takes: `:ok` for a lowercase canonical UUID, and
otherwise the refusal the dispatch answers.

nil, and a binary that is empty or only whitespace, are `:command_id_required`. Any other
binary that is not a canonical UUID (`Decree.UUID.canonical?/1`), and anything that is not
a binary, is `:invalid_command_id`. The value is never repaired.

    :ok = Decree.Command.check_id("6f9619ff-8b86-d011-b42d-00c04fc964ff")
    {:error, :invalid_command_id} = Decree.Command.check_id("6F9619FF-8B86-D011-B42D-00C04FC964FF")
    {:error, :command_id_required} = Decree.Command.check_id(nil)

# `command?`

```elixir
@spec command?(struct() | module() | term()) :: boolean()
```

Whether a command struct, or a command module, uses `Decree.Command`.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
