eventstore v0.10.1 EventStore

EventStore client API to read & write events to a logical event stream and subscribe to event notifications

Example usage

# ensure the event store application has been started
Application.ensure_all_started(:eventstore)

# append events to a stream
:ok = EventStore.append_to_stream(stream_uuid, expected_version, events)

# read all events from a stream, starting at the beginning
{:ok, recorded_events} = EventStore.read_stream_forward(stream_uuid)

Link to this section Summary

Functions

Acknowledge receipt of the given events received from a single stream, or all streams, subscription

Append one or more events to a stream atomically. Returns :ok on success

Get the event store configuration for the environment

Get the serializer configured for the environment

Delete a previously recorded snapshop for a given source

Reads the requested number of events from all streams, in the order in which they were originally written

Read a snapshot, if available, for a given source

Reads the requested number of events from the given stream, in the order in which they were originally written

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

Streams events from all streams, in the order in which they were originally written

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

Subscriber will be notified of every event persisted to any stream

Subscriber will be notified of each batch of events persisted to a single stream

Unsubscribe an existing subscriber from all event notifications

Unsubscribe an existing subscriber from event notifications

Link to this section Types

Link to this type start_from()
start_from() :: :origin | :current | integer

Link to this section Functions

Link to this function ack(subscription, events)
ack(pid, EventStore.RecordedEvent.t | [EventStore.RecordedEvent.t] | non_neg_integer) ::
  :ok |
  {:error, reason :: term}

Acknowledge receipt of the given events received from a single stream, or all streams, subscription.

Link to this function append_to_stream(stream_uuid, expected_version, events)
append_to_stream(String.t, non_neg_integer, [EventStore.EventData.t]) ::
  :ok |
  {:error, reason :: term}

Append one or more events to a stream atomically. Returns :ok on success.

  • stream_uuid is used to uniquely identify a stream.

  • expected_version is used for optimistic concurrency. Specify 0 for the creation of a new stream. An {:error, wrong_expected_version} response will be returned if the stream already exists. Any positive number will be used to ensure you can only append to the stream if it is at exactly that version.

  • events is a list of %EventStore.EventData{} structs.

Link to this function configuration()

Get the event store configuration for the environment

Link to this function configured_serializer()

Get the serializer configured for the environment

Link to this function delete_snapshot(source_uuid)
delete_snapshot(String.t) :: :ok | {:error, reason :: term}

Delete a previously recorded snapshop for a given source

Returns :ok on success, or when the snapshot does not exist

Link to this function read_all_streams_forward(start_event_id \\ 0, count \\ 1000)
read_all_streams_forward(non_neg_integer, non_neg_integer) ::
  {:ok, [EventStore.RecordedEvent.t]} |
  {:error, reason :: term}

Reads the requested number of events from all streams, in the order in which they were originally written.

  • start_event_id optionally, the id of the first event to read. Defaults to the beginning of the stream if not set.

  • count optionally, the maximum number of events to read. If not set it will be limited to returning 1,000 events from all streams.

Link to this function read_snapshot(source_uuid)
read_snapshot(String.t) ::
  {:ok, EventStore.Snapshots.SnapshotData.t} |
  {:error, :snapshot_not_found}

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

Returns {:ok, %EventStore.Snapshots.SnapshotData{}} on success, or {:error, :snapshot_not_found} when unavailable.

Link to this function read_stream_forward(stream_uuid, start_version \\ 0, count \\ 1000)
read_stream_forward(String.t, non_neg_integer, non_neg_integer) ::
  {:ok, [EventStore.RecordedEvent.t]} |
  {:error, reason :: term}

Reads the requested number of events from the given stream, in the order in which they were originally written.

  • stream_uuid is used to uniquely identify a stream.

  • start_version optionally, the version number of the first event to read. Defaults to the beginning of the stream if not set.

  • count optionally, the maximum number of events to read. If not set it will be limited to returning 1,000 events from the stream.

Link to this function record_snapshot(snapshot)
record_snapshot(EventStore.Snapshots.SnapshotData.t) ::
  :ok |
  {:error, reason :: term}

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

Returns :ok on success

Link to this function stream_all_forward(start_event_id \\ 0, read_batch_size \\ 1000)
stream_all_forward(non_neg_integer, non_neg_integer) :: Enumerable.t

Streams events from all streams, in the order in which they were originally written.

  • start_event_id optionally, the id of the first event to read. Defaults to the beginning of the stream if not set.

  • read_batch_size optionally, the number of events to read at a time from storage. Defaults to reading 1,000 events per batch.

Link to this function stream_forward(stream_uuid, start_version \\ 0, read_batch_size \\ 1000)
stream_forward(String.t, non_neg_integer, non_neg_integer) ::
  Enumerable.t |
  {:error, reason :: term}

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

  • start_version optionally, the version number of the first event to read. Defaults to the beginning of the stream if not set.

  • read_batch_size optionally, the number of events to read at a time from storage. Defaults to reading 1,000 events per batch.

Link to this function subscribe_to_all_streams(subscription_name, subscriber, opts \\ [])
subscribe_to_all_streams(String.t, pid, keyword) ::
  {:ok, subscription :: pid} |
  {:error, :subscription_already_exists} |
  {:error, reason :: term}

Subscriber will be notified of every event persisted to any stream.

  • subscription_name is used to uniquely identify the subscription.

  • subscriber is a process that will be sent {:events, events} notification messages.

  • opts is an optional map providing additional subscription configuration:

    • start_from is a pointer to the first event to receive. It must be one of:
      • :origin for all events from the start of the stream (default).
      • :current for any new events appended to the stream after the subscription has been created.
      • any positive integer for an event id to receive events after that exact event.
    • mapper to define a function to map each recorded event before sending to the subscriber.

Returns {:ok, subscription} when subscription succeeds.

Link to this function subscribe_to_stream(stream_uuid, subscription_name, subscriber, opts \\ [])
subscribe_to_stream(String.t, String.t, pid, keyword) ::
  {:ok, subscription :: pid} |
  {:error, :subscription_already_exists} |
  {:error, reason :: term}

Subscriber will be notified of each batch of events persisted to a single stream.

  • stream_uuid is the stream to subscribe to. Use the $all identifier to subscribe to events from all streams.

  • subscription_name is used to uniquely identify the subscription.

  • subscriber is a process that will be sent {:events, events} notification messages.

  • opts is an optional map providing additional subscription configuration:

    • start_from is a pointer to the first event to receive. It must be one of:
      • :origin for all events from the start of the stream (default).
      • :current for any new events appended to the stream after the subscription has been created.
      • any positive integer for a stream version to receive events after.
    • mapper to define a function to map each recorded event before sending to the subscriber.

Returns {:ok, subscription} when subscription succeeds.

Link to this function unsubscribe_from_all_streams(subscription_name)
unsubscribe_from_all_streams(String.t) :: :ok

Unsubscribe an existing subscriber from all event notifications.

  • subscription_name is used to identify the existing subscription to remove.

Returns :ok on success.

Link to this function unsubscribe_from_stream(stream_uuid, subscription_name)
unsubscribe_from_stream(String.t, String.t) :: :ok

Unsubscribe an existing subscriber from event notifications.

  • stream_uuid is the stream to unsubscribe from.

  • subscription_name is used to identify the existing subscription to remove.

Returns :ok on success.