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

Protocol to allow an event to be transformed before being passed to a
consumer.

You can use an upcaster to change the shape of an event (e.g. add a new field
with a default, rename a field) or rename an event.

Upcaster will run for new events and for historical events.

Because the upcaster changes any historical event to the latest version,
consumers (aggregates and event handlers) only need to support the latest
version.

## Example

    defimpl Decree.Event.Upcaster, for: AnEvent do
      def upcast(%AnEvent{} = event, _metadata) do
        %AnEvent{name: name} = event

        %AnEvent{event | first_name: name}
      end
    end

## Metadata

The `upcast/2` function receives the domain event and a map of metadata
associated with that event. The metadata is provided during command dispatch.

In addition to the metadata key/values you provide, the following system
values will be included in the metadata:

  - `application` - the `Decree.Application` used to read the event.
  - `event_id` - a globally unique UUID to identify the event.
  - `event_number` - a globally unique, monotonically incrementing integer
    used to order the event amongst all events.
  - `stream_id` - the stream identity for the event.
  - `stream_version` - the version of the stream for the event.
  - `causation_id` - an optional UUID identifier used to identify which
    command caused the event.
  - `correlation_id` - an optional UUID identifier used to correlate related
    commands/events.
  - `created_at` - the datetime, in UTC, indicating when the event was
    created.

These key/value metadata pairs will use atom keys to differentiate them from
the user provided metadata which uses string keys.

# `t`

```elixir
@type t() :: term()
```

All the types that implement this protocol.

# `upcast`

```elixir
@spec upcast(event :: struct(), metadata :: map()) :: struct()
```

---

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