@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)

@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

• :client — the client name (default: Chronicle.Client)

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

Explicitly cleans up a materialized read-model session.

Sessions are created implicitly when reading with a :session_id (see get_instance_by_id/3); call this once a session's caller is done with it to release the resources Chronicle held for it, rather than waiting for it to expire on its own.

Options

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

@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.

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

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

@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.

@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.

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

Returns replay occurrences for a read model.

@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.

@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

@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)

@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")

@spec unwatch(pid()) :: :ok

Stops a subscription started by watch/2.

@spec watch(
  module(),
  keyword()
) :: {:ok, pid()} | {:error, term()}

Watches a read model for live changes.

Mirrors the C# and TypeScript clients' Watch<TReadModel>(), which returns an IObservable/async-iterable of live changesets. Elixir has no equivalent built-in, so this follows the same message-based subscription idiom as Chronicle.Connections.Lifecycle.subscribe/1: the calling process receives a {:chronicle_read_model_changed, model_module, %Chronicle.ReadModels.Changeset{}} message for every change (added/modified/removed, for any instance of the read model), until unwatch/1 is called.

On a stream failure, the calling process receives {:chronicle_read_model_watch_error, model_module, reason} and the watch ends; call watch/2 again to resume.

Returns {:ok, watcher}, where watcher identifies the background watch process — pass it to unwatch/1 to stop.

Options

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