Chronik v0.1.10 Chronik.Store behaviour View Source

Chronik event Store API

Link to this section Summary

Types

The options given for reading events from the stream

The version of a given event record in the Store

Callbacks

Append a list of events to the Store

This function allows the Projection module to comapre versions of EventRecords coming form the PubSub bus

Retrives the current version of the store. If there are no record returns :empty

Retrieves all events from the store starting (but not including) at version

Retrieves all events from the store for a given aggregate starting (but not including) at version

Retrives a snapshot from the Store. If there is no snapshot it returns nil

Remove all events for given aggregate

This function creates a snapshot in the store for the given aggregate. The Store only stores the last snapshot

Calls the fun function over a stream of domain events starting at version version

Calls the fun function over the aggregate’s domain event stream starting at version version

Link to this section Types

The options given for reading events from the stream

Link to this type version() View Source
version() :: term() | :empty

The version of a given event record in the Store.

A simple implementation is a integer starting from 0. The atom :empty is the initial version (without events yet).

Link to this section Functions

Link to this section Callbacks

Link to this callback append(aggregate, events, opts) View Source
append(aggregate :: Chronik.Aggregate, events :: events(), opts :: options()) ::
  {:ok, version(), event_records()} | {:error, String.t()}

Append a list of events to the Store.

  • aggregate is the agregate that generated the events.

  • events is an enumberable with the events to append.

  • options is a keyword indicating the optimistic concurrency checks to perform at the moment of writing to the stream.

Versioning

Possible values are:

  • :any: (default value) no checks are performed, the events are always written

  • :no_stream: verifies that the target stream does not exists yet

  • any other value: the event number expected to currently be at

The return values are {:ok, last_inserted_version, records} on success or {:error, message} in case of failure.

Link to this callback compare_version(version, version) View Source
compare_version(version :: version(), version :: version()) ::
  :past | :next_one | :future | :equal

This function allows the Projection module to comapre versions of EventRecords coming form the PubSub bus.

The implementation depends on the version type but a trivial implementation is to compare the integers and return the corresponding atoms.

Link to this callback current_version() View Source
current_version() :: version()

Retrives the current version of the store. If there are no record returns :empty.

Link to this callback fetch(version) View Source
fetch(version :: version()) ::
  {:ok, version(), event_records()} | {:error, String.t()}

Retrieves all events from the store starting (but not including) at version.

Possible version values are :all (default value) or a term indicating starting read position. Event at version is not included in the result.

The return values are {:ok, version, [event records]} or {:error, message} in case of failure.

If no records are found on the stream (starting at version) the function returns {:ok, version, []}.

Link to this callback fetch_by_aggregate(aggregate, version) View Source
fetch_by_aggregate(aggregate :: Chronik.Aggregate, version :: version()) ::
  {:ok, version(), event_records()} | {:error, String.t()}

Retrieves all events from the store for a given aggregate starting (but not including) at version.

Possible version values are :all (default value) or a term indicating starting read position. Event at version is not included in the result.

The return values are {:ok, version, [event records]} or {:error, message} in case of failure.

If no records are found on the stream (starting at version) the function returns {:ok, version, []}.

Link to this callback get_snapshot(aggregate) View Source
get_snapshot(aggregate :: Chronik.Aggregate) ::
  {version(), Chronik.Aggregate.state()}

Retrives a snapshot from the Store. If there is no snapshot it returns nil.

If there is a snapshot this function should return a tuple {version, state} indicating the state of the snapshot and with wich version of the aggregate was created.

Link to this callback remove_events(aggregate) View Source
remove_events(aggregate :: Chronik.Aggregate) :: :ok

Remove all events for given aggregate

Link to this callback snapshot(aggregate, state, version) View Source
snapshot(
  aggregate :: Chronik.Aggregate,
  state :: Chronik.Aggregate.state(),
  version :: version()
) :: :ok | {:error, reason() :: String.t()}

This function creates a snapshot in the store for the given aggregate. The Store only stores the last snapshot.

Link to this callback stream(fun, version) View Source
stream(fun :: (event_record(), any() -> any()), version :: version()) ::
  any()

Calls the fun function over a stream of domain events starting at version version.

Link to this callback stream_by_aggregate(aggregate, fun, version) View Source
stream_by_aggregate(
  aggregate :: Chronik.Aggregate,
  fun :: (event_record(), any() -> any()),
  version :: version()
) :: any()

Calls the fun function over the aggregate’s domain event stream starting at version version.