Chronicle.ReadModels (cratis_chronicle v0.2.0)

Copy Markdown View Source

Idiomatic Elixir interface for Chronicle read models.

Read models are the query side of Chronicle. They are produced by projections and reducers and can be queried in two complementary ways:

  • get/3, get_instance_by_id/3, all/2, and get_instances/2 replay the configured event sequence in the same style as the C# and TypeScript IReadModels APIs.
  • query/2 queries the materialized read-model container directly for paging and occurrence-oriented inspection.

The module also exposes helper queries for metadata and history:

Common options

Most functions accept these options:

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

Single instance lookup

{:ok, account} = Chronicle.ReadModels.get(MyApp.ReadModels.Account, "account-1")
{:ok, account} = Chronicle.ReadModels.get_instance_by_id(MyApp.ReadModels.Account, "account-1")

Use :session_id when reading from a dehydrated or session-specific projection:

{:ok, account} =
  Chronicle.ReadModels.get_instance_by_id(
    MyApp.ReadModels.Account,
    "account-1",
    session_id: "session-42"
  )

Replay all instances

{:ok, accounts} = Chronicle.ReadModels.all(MyApp.ReadModels.Account)
{:ok, accounts} = Chronicle.ReadModels.get_instances(MyApp.ReadModels.Account, event_count: 500)

Query the materialized container

{:ok, result} = Chronicle.ReadModels.query(MyApp.ReadModels.Account, page: 1, page_size: 25)

result.instances
result.total_count

Query metadata and history

{:ok, snapshots} = Chronicle.ReadModels.snapshots(MyApp.ReadModels.Account, "account-1")
{:ok, occurrences} = Chronicle.ReadModels.occurrences(MyApp.ReadModels.Account)
{:ok, definitions} = Chronicle.ReadModels.definitions()

Summary

Functions

all(model_module, opts \\ [])

Replays and returns all instances for a read model.

definitions(opts \\ [])

Returns the registered read-model definitions for the current event store.

get(model_module, key, opts \\ [])

Fetches a read model instance by key.

get_definitions(opts \\ [])

Returns the registered read-model definitions for the current event store.

get_instance_by_id(model_module, key, opts \\ [])

Fetches a read model instance by key.

get_instances(model_module, opts \\ [])

Replays and returns all instances for a read model.

get_occurrences(model_module, opts \\ [])

Returns replay occurrences for a read model.

get_snapshots_by_id(model_module, key, opts \\ [])

Returns historical snapshots for a read model instance.

occurrences(model_module, opts \\ [])

Returns replay occurrences for a read model.

query(model_module, opts \\ [])

Queries the materialized read-model container directly.

snapshots(model_module, key, opts \\ [])

Returns historical snapshots for a read model instance.

Functions

all(model_module, opts \\ [])

@spec all(
  module(),
  keyword()
) :: {:ok, [struct()]} | {:error, term()}

Replays and returns all instances for a read model.

This is the short alias for get_instances/2.

Options

  • :client — the client name (default: Chronicle.Client)
  • :namespace — overrides the client's default namespace
  • :event_sequence_id — event sequence identifier (default: "event-log")
  • :event_count — maximum number of events to process (default: unlimited)

definitions(opts \\ [])

@spec definitions(keyword()) ::
  {:ok, [Chronicle.ReadModels.Definition.t()]} | {:error, term()}

Returns the registered read-model definitions for the current event store.

This is useful for tooling, diagnostics, and documentation scenarios where you want to inspect the schema and owning observer for each read model.

Options

get(model_module, key, opts \\ [])

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

Fetches a read model instance by key.

This is the short alias for get_instance_by_id/3.

Options

  • :client — the client name (default: Chronicle.Client)
  • :namespace — overrides the client's default namespace
  • :event_sequence_id — event sequence identifier (default: "event-log")
  • :session_id — optional read-model session identifier

Returns {:ok, model_struct} on success, or {:ok, nil} if no instance was found.

get_definitions(opts \\ [])

@spec get_definitions(keyword()) ::
  {:ok, [Chronicle.ReadModels.Definition.t()]} | {:error, term()}

Returns the registered read-model definitions for the current event store.

get_instance_by_id(model_module, key, opts \\ [])

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

Fetches a read model instance by key.

Mirrors the getInstanceById() naming used by the Chronicle C# and TypeScript clients while returning idiomatic Elixir tuples.

get_instances(model_module, opts \\ [])

@spec get_instances(
  module(),
  keyword()
) :: {:ok, [struct()]} | {:error, term()}

Replays and returns all instances for a read model.

This matches the Chronicle getInstances() naming used in the C# and TypeScript clients.

get_occurrences(model_module, opts \\ [])

@spec get_occurrences(
  module(),
  keyword()
) :: {:ok, [Chronicle.ReadModels.Occurrence.t()]} | {:error, term()}

Returns replay occurrences for a read model.

get_snapshots_by_id(model_module, key, opts \\ [])

@spec get_snapshots_by_id(module(), String.t(), keyword()) ::
  {:ok, [Chronicle.ReadModels.Snapshot.t()]} | {:error, term()}

Returns historical snapshots for a read model instance.

This mirrors the getSnapshotsById() naming from the Chronicle C# and TypeScript clients.

occurrences(model_module, opts \\ [])

@spec occurrences(
  module(),
  keyword()
) :: {:ok, [Chronicle.ReadModels.Occurrence.t()]} | {:error, term()}

Returns replay occurrences for a read model.

Occurrences represent replayed or rebuilt versions of a read model and are useful when inspecting rebuilds or alternative containers.

Options

  • :client — the client name (default: Chronicle.Client)
  • :namespace — overrides the client's default namespace

query(model_module, opts \\ [])

@spec query(
  module(),
  keyword()
) :: {:ok, Chronicle.ReadModels.QueryResult.t()} | {:error, term()}

Queries the materialized read-model container directly.

This complements the replay-oriented all/2 and get_instances/2 helpers. Use it when you need paging or want to inspect a specific replay occurrence.

Options

  • :client — the client name (default: Chronicle.Client)
  • :namespace — overrides the client's default namespace
  • :occurrence — optional occurrence/container name for a replayed read model
  • :page — page number (default: 1)
  • :page_size — page size (default: 50)

snapshots(model_module, key, opts \\ [])

@spec snapshots(module(), String.t(), keyword()) ::
  {:ok, [Chronicle.ReadModels.Snapshot.t()]} | {:error, term()}

Returns historical snapshots for a read model instance.

Snapshots group the projected state together with the event batch that caused it, making this useful for troubleshooting projections and reducers.

Options

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