eventstore v0.6.0 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)

Summary

Functions

append_to_stream(stream_uuid, expected_version, events)

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

read_all_streams_forward(start_event_id \\ 0, count \\ 1000)

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

read_snapshot(source_uuid)

Read a snapshot, if available, for a given source

read_stream_forward(stream_uuid, start_version \\ 0, count \\ 1000)

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

record_snapshot(snapshot)

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

subscribe_to_all_streams(subscription_name, subscriber)

Subscriber will be notified of every event persisted to any stream

subscribe_to_stream(stream_uuid, subscription_name, subscriber)

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

unsubscribe_from_all_streams(subscription_name)

Unsubscribe an existing subscriber from all event notifications

unsubscribe_from_stream(stream_uuid, subscription_name)

Unsubscribe an existing subscriber from event notifications

Functions

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.

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.

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.

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.

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

subscribe_to_all_streams(subscription_name, subscriber)

subscribe_to_all_streams(String.t, pid) ::
  {: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, subscription} notification messages.

Returns {:ok, subscription} when subscription succeeds.

subscribe_to_stream(stream_uuid, subscription_name, subscriber)

subscribe_to_stream(String.t, String.t, pid) ::
  {: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, subscription} notification messages.

Returns {:ok, subscription} when subscription succeeds.

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.

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.