Chronicle.EventSequences.EventLog (cratis_chronicle v0.2.0)

Appends and queries events in a Chronicle event log.

The event log is the primary EventSequence in Chronicle. Use append/3 to record domain events for a given event source (such as an aggregate root).

Usage

:ok = Chronicle.EventSequences.EventLog.append("account-1", %MyApp.Events.AccountOpened{
  account_id: "account-1",
  owner_name: "Alice",
  initial_balance: 500
})

To append to a specific client:

:ok = Chronicle.EventSequences.EventLog.append("account-1", event, client: :my_chronicle)

Multiple events

events = [
  %MyApp.Events.AccountOpened{account_id: "1", owner_name: "Alice"},
  %MyApp.Events.FundsDeposited{account_id: "1", amount: 500}
]
:ok = Chronicle.EventSequences.EventLog.append_many("account-1", events)

Transactions

When a Chronicle.Transactions.UnitOfWork is active, append operations are buffered locally and only sent to Chronicle when the unit of work is committed.

Summary

Functions

append(event_source_id, event, opts \\ [])

Appends a single event to the event log for the given event source.

append_many(event_source_id, events, opts \\ [])

Appends multiple events to the event log for the given event source.

get_for_event_source(event_source_id, opts \\ [])

Returns events for the given event source ID from the event log.

get_tail_sequence_number(event_source_id \\ nil, opts \\ [])

Returns the tail sequence number for an event sequence.

has_events_for?(event_source_id, opts \\ [])

Checks whether an event sequence has events for an event source id.

Functions

append(event_source_id, event, opts \\ [])

@spec append(String.t(), struct(), keyword()) :: :ok | {:error, term()}

Appends a single event to the event log for the given event source.

Options

:client — the client name (default: Chronicle.Client)
:namespace — overrides the client's default namespace
:event_sequence_id — event sequence id (default: "event-log")
:event_source_type — the event source type (default: "Default")
:event_stream_type — the event stream type (default: "All")
:event_stream_id — the event stream ID (default: "Default")
:tags — list of tag strings
:subject — the identity subject string
:correlation_id — correlation id override (Chronicle.Correlation.CorrelationId or string)
:identity — identity override (Chronicle.Identity)
:causation — causation chain override (list of Chronicle.Auditing.CausationEntry)
:concurrency_scope — Chronicle.Events.ConcurrencyScope or keyword options with :sequence_number, :event_source_id, :event_stream_type, :event_stream_id, :event_source_type, and :event_types

Returns :ok on success or {:error, reason} on failure.

append_many(event_source_id, events, opts \\ [])

@spec append_many(String.t(), [struct()], keyword()) :: :ok | {:error, term()}

Appends multiple events to the event log for the given event source.

All events are appended atomically. Each event must be a struct that use Chronicle.Events.EventType.

Options

Same as append/3, including :event_sequence_id and :concurrency_scope.

get_for_event_source(event_source_id, opts \\ [])

@spec get_for_event_source(
  String.t(),
  keyword()
) :: {:ok, list()} | {:error, term()}

Returns events for the given event source ID from the event log.

Options

:client — the client name (default: Chronicle.Client)
:namespace — overrides the client's default namespace
:event_sequence_id — event sequence id (default: "event-log")
:event_types — list of event type modules to filter by (default: all)

Returns {:ok, [appended_event]} or {:error, reason}.

get_tail_sequence_number(event_source_id \\ nil, opts \\ [])

@spec get_tail_sequence_number(
  String.t() | nil,
  keyword()
) :: {:ok, non_neg_integer()} | {:error, term()}

Returns the tail sequence number for an event sequence.

Options

:client — the client name (default: Chronicle.Client)
:namespace — overrides the client's default namespace
:event_sequence_id — event sequence id (default: "event-log")

has_events_for?(event_source_id, opts \\ [])

@spec has_events_for?(
  String.t(),
  keyword()
) :: {:ok, boolean()} | {:error, term()}

Checks whether an event sequence has events for an event source id.

Options

:client — the client name (default: Chronicle.Client)
:namespace — overrides the client's default namespace
:event_sequence_id — event sequence id (default: "event-log")