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

Use the event store configured for a Decree application: the `Decree.Store` module named by
`event_store: [event_store: MyApp.EventStore]` in its config, called with the store process's
`name:`. The framework's `Decree.EventStore.EventData`, `RecordedEvent` and `SnapshotData` are
mapped to the store's structs and back here.

### Telemetry Events

Adds telemetry events for the following functions. Events are emitted in the form

`[:decree, :event_store, event]` with their spannable postfixes (`start`, `stop`, `exception`)

  * ack_event/3
  * append_to_stream/4
  * append_to_streams/3
  * delete_snapshot/2
  * delete_subscription/3
  * prune_snapshots/3
  * read_query/3
  * read_snapshot/3
  * read_tags/3
  * record_snapshot/2
  * stream_forward/2
  * stream_forward/3
  * stream_forward/4
  * subscribe/2
  * subscribe_to/5
  * subscribe_to/6
  * unsubscribe/2

`read_query/3`'s span never fires `exception`, and a failure stops it with `error`: its doc
says why.

# `application`

```elixir
@type application() :: Decree.Application.t()
```

# `config`

```elixir
@type config() :: Keyword.t()
```

# `error`

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

# `expected_version`

```elixir
@type expected_version() ::
  :any_version | :no_stream | :stream_exists | non_neg_integer()
```

# `source_uuid`

```elixir
@type source_uuid() :: String.t()
```

# `start_from`

```elixir
@type start_from() :: :origin | :current | integer()
```

# `stream_uuid`

```elixir
@type stream_uuid() :: String.t()
```

# `subscriber`

```elixir
@type subscriber() :: pid()
```

# `subscription`

```elixir
@type subscription() :: any()
```

# `subscription_name`

```elixir
@type subscription_name() :: String.t()
```

# `ack_event`

Acknowledge receipt and successful processing of the given event received from
a subscription to an event stream. If the event is part of a batch, every event that
precedes it in the batch is acknowledged as well.

# `append_to_stream`

Append one or more events to a stream atomically.

The store's answers come back unchanged (see `c:Decree.Store.append_to_stream/4`).
`{:error, :wrong_expected_version}` makes an aggregate rebuild its state and retry the
command while it has attempts left. A failure of the append statement other than its domain
answers is `{:error, %Decree.Store.AppendError{}}`, classified `:unavailable`, `:retryable`
or `:rejected`, and the aggregate returns it as the command's error. After an
`:unavailable` one the aggregate stops, so the next command rebuilds its state from the
stream (see `Decree.Store.AppendError`).

With `returning: :append_result` in `opts`, success answers
`{:ok, %Decree.Store.AppendResult{}}` instead of `:ok`.

# `append_to_streams`

Append events to several streams atomically, in one statement.

`appends` is a list of `{stream_uuid, expected_version, events}`, one per stream. The
options and answers are those of `c:Decree.Store.append_to_streams/2`: with `condition:` an
event past its `after` matching its `items` answers `{:error, :append_condition_failed}`, and
with `returning: :append_result` success answers `{:ok, %Decree.Store.AppendResult{}}`.

# `append_without_span`

Appends one or more events to a stream atomically, as `append_to_stream/5` does, with no
telemetry event.

It answers what `append_to_stream/5` answers, and a raise, an exit or a throw reaches the
caller as it would there.

# `conditional_targets`

The targets the application's running event store's `conditional_appends` declares, or `[]`
if it declares none.

It answers from the config the store parsed as it started, so it agrees with what the store
refuses. An application with a rule route or a windowed aggregate calls this as it starts,
right after its store has, and an application with neither never calls it. See "Two
declarations" in `Decree.Decision.Rule`.

# `deletable_stream_prefixes`

The stream prefixes the application's event store declares as deletable.

A store without `enable_hard_deletes` answers `[]`, whatever it declares: no delete can reach
a stream there.

# `delete_snapshot`

Delete a previously recorded snapshot for a given source, at every snapshot version.

# `delete_subscription`

Delete an existing subscription.

## Example

    :ok = Decree.EventStore.delete_subscription(MyApp, :all, "Example")

# `prune_snapshots`

Delete the snapshots of a source type whose snapshot version is below the given one.
See `Decree.Aggregate.prune_snapshots/2`.

# `read_query`

Reads the events matching a query across every stream, in one statement, each upcast as
`stream_forward/4` upcasts it.

See `c:Decree.Store.read_query/2` for the items, options and answers. The result's
events are `Decree.EventStore.RecordedEvent`s.

Its span covers the store's answer, and the upcast runs after it stops. A raise, an exit or
a throw from either, the store's deserializing and the mapping included, reaches
the caller as it was raised, and no telemetry event holds it. The span never fires its
exception event. A failure inside it stops it with `error` in the stop metadata, the kind
alone: `:error`, `:exit` or `:throw`. A read that answered stops with no `error`.

# `read_snapshot`

Read a snapshot, if available, for a given source at a snapshot version.

A source has one row per snapshot version, so code at another version never reads or
overwrites this one's. A nil `snapshot_version` is refused with
`{:error, :invalid_snapshot_version}`.

# `read_stream_head`

Reads the last event of the given stream, upcast as `stream_forward/4` upcasts.

Answers `{:ok, recorded_event}`, or `{:error, :stream_not_found}` for a stream that never
existed and for one hard-deleted, which nothing tells apart, or `{:error, reason}` for a read
that failed. A failed read is never `:stream_not_found`.

Its cost does not grow with the stream.

# `read_tags`

Reads the tags of the events at the given `$all` positions, in one statement.

Answers as `c:Decree.Store.read_tags/2` does: a position with no row is absent, and so are
tags of a kind the store declares deletable and every tag of an event of a type it declares.

# `record_snapshot`

Record a snapshot of the data and metadata for a given source

# `stream_forward`

Streams events from the given stream, in the order in which they were originally written.

# `subscribe`

Create a transient subscription to a single event stream.

The event store will publish any events appended to the given stream to the
`subscriber` process as an `{:events, events}` message.

The subscriber does not need to acknowledge receipt of the events.

# `subscribe_to`

Create a persistent subscription to an event stream.

To subscribe to all events appended to any stream use `:all` as the stream
when subscribing.

The event store will remember the subscribers last acknowledged event.
Restarting the named subscription will resume from the next event following
the last seen.

Once subscribed, the subscriber process should be sent a
`{:subscribed, subscription}` message to allow it to defer initialisation
until the subscription has started.

The subscriber process will be sent all events persisted to the stream. It
will receive a `{:events, events}` message for each batch of events persisted
for a single aggregate.

The subscriber must ack each received, and successfully processed event, using
`Decree.EventStore.ack_event/3`.

## Examples

Subscribe to all streams:

    {:ok, subscription} =
      Decree.EventStore.subscribe_to(MyApp, :all, "Example", self(), :current)

Subscribe to a single stream:

    {:ok, subscription} =
      Decree.EventStore.subscribe_to(MyApp, "stream1", "Example", self(), :origin)

# `unsubscribe`

Unsubscribe an existing subscriber from event notifications.

This will not delete the subscription.

## Example

    :ok = Decree.EventStore.unsubscribe(MyApp, subscription)

---

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