Table of Contents

Interface IMaterializedViewStore

Namespace
Excalibur.EventSourcing
Assembly
Excalibur.EventSourcing.Abstractions.dll

Defines the contract for materialized view persistence operations.

public interface IMaterializedViewStore

Remarks

Materialized views are read-optimized projections built from event streams. This interface provides the storage operations for view state.

For building views from events, use IMaterializedViewBuilder<TView>.

Performance Note: Methods return ValueTask<TResult> to avoid heap allocations for synchronous completions (e.g., in-memory stores, cache hits). Callers should await the result immediately and not store the ValueTask for later use.

Tenant confinement. Every operation is confined to the ambient tenant established for this store instance, and that includes the checkpoint: GetAsync<TView>(string, string, CancellationToken) reports a view stored under another tenant as not found, SaveAsync<TView>(string, string, TView, CancellationToken) can neither read nor overwrite another tenant's view under the same viewName and viewId, DeleteAsync(string, string, CancellationToken) cannot remove one, and GetPositionAsync(string, CancellationToken) and SavePositionAsync(string, long, CancellationToken) read and write a position owned by this tenant alone. The confinement applies to writes and deletes as well as reads: scoping only the read paths turns a disclosure into silent data loss rather than removing the problem. A position is the sharper case of the same rule -- a checkpoint keyed on view name alone holds one position for every tenant, so one tenant's progress advances another's and that tenant's projector skips every event in between, which is data loss that reports success.

Every implementation shipped with the framework holds that boundary, by carrying the tenant term in the statement or in the document identifier rather than filtering after the fact. The framework does not gate this contract at registration, however, so a store presenting no capability marker -- ITenantScopingCapability<TContract> for a store that reads an ambient tenant -- is not confined by the framework, only by its own statements.

Methods

DeleteAsync(string, string, CancellationToken)

Deletes a materialized view.

ValueTask DeleteAsync(string viewName, string viewId, CancellationToken cancellationToken)

Parameters

viewName string

The view name (typically the view type name).

viewId string

The view identifier.

cancellationToken CancellationToken

Cancellation token.

Returns

ValueTask

A task representing the asynchronous operation.

Remarks

Confined to the ambient tenant, like every other operation on this store: a view stored under another tenant with the same viewName and viewId is not deleted, and the call succeeds silently because that view is not visible to this caller. An implementation that omits the tenant term here deletes another tenant's view -- silent data loss rather than a disclosure, and the projector that rebuilt it will not notice.

GetAsync<TView>(string, string, CancellationToken)

Gets a materialized view by its identifier.

[RequiresUnreferencedCode("Implementations serialize the view type reflectively; supply JsonSerializerOptions with a source-generated resolver for trimming.")]
[RequiresDynamicCode("Implementations serialize the view type reflectively; supply JsonSerializerOptions with a source-generated resolver for AOT.")]
ValueTask<TView?> GetAsync<TView>(string viewName, string viewId, CancellationToken cancellationToken) where TView : class

Parameters

viewName string

The view name (typically the view type name).

viewId string

The view identifier.

cancellationToken CancellationToken

Cancellation token.

Returns

ValueTask<TView>

The view if found, or null if not found.

Type Parameters

TView

The view type.

GetPositionAsync(string, CancellationToken)

Gets the last processed position for a view.

ValueTask<long?> GetPositionAsync(string viewName, CancellationToken cancellationToken)

Parameters

viewName string

The view name for position tracking.

cancellationToken CancellationToken

Cancellation token.

Returns

ValueTask<long?>

The last processed position, or null if no position has been recorded.

Remarks

The position is used to track which events have been processed for a view, enabling catch-up subscriptions and rebuild scenarios.

ResetPositionAsync(string, CancellationToken)

Clears the recorded position for a view, so the next read reports no checkpoint at all.

ValueTask ResetPositionAsync(string viewName, CancellationToken cancellationToken)

Parameters

viewName string

The view name for position tracking.

cancellationToken CancellationToken

Cancellation token.

Returns

ValueTask

A task representing the asynchronous operation.

Remarks

Unconditional by contract. This is the operation a rebuild needs, and it is deliberately not subject to the monotonic guard that governs SavePositionAsync(string, long, CancellationToken) — a guard whose whole purpose is to refuse exactly this.

It clears rather than zeroes. GetPositionAsync(string, CancellationToken) already returns null for a view with no checkpoint, so absence is the existing representation of "start from the beginning" and needs no second encoding. Writing zero would also be indistinguishable from a view legitimately checkpointed at position zero.

It returns no outcome because it cannot refuse. Clearing an already-absent checkpoint is success, not a refusal. A store that cannot clear throws.

SaveAsync<TView>(string, string, TView, CancellationToken)

Saves a materialized view.

[RequiresUnreferencedCode("Implementations serialize the view type reflectively; supply JsonSerializerOptions with a source-generated resolver for trimming.")]
[RequiresDynamicCode("Implementations serialize the view type reflectively; supply JsonSerializerOptions with a source-generated resolver for AOT.")]
ValueTask SaveAsync<TView>(string viewName, string viewId, TView view, CancellationToken cancellationToken) where TView : class

Parameters

viewName string

The view name (typically the view type name).

viewId string

The view identifier.

view TView

The view to save.

cancellationToken CancellationToken

Cancellation token.

Returns

ValueTask

A task representing the asynchronous operation.

Type Parameters

TView

The view type.

SavePositionAsync(string, long, CancellationToken)

Advances the last processed position for a view, and reports whether the advance was taken.

ValueTask<ViewPositionSaveOutcome> SavePositionAsync(string viewName, long position, CancellationToken cancellationToken)

Parameters

viewName string

The view name for position tracking.

position long

The position to advance to.

cancellationToken CancellationToken

Cancellation token.

Returns

ValueTask<ViewPositionSaveOutcome>

Advanced when the checkpoint moved to position; RefusedAsStale when the stored checkpoint was already at or beyond it and nothing was written.

Remarks

This advance is MONOTONIC in every implementation, and the refusal is a normal outcome rather than an error. A delayed or retried write carrying an older position must not rewind the checkpoint, because the projection would then replay events it has already applied. Every store enforces that server-side.

The return value exists because the refusal used to be unobservable. This member returned ValueTask — a caller could not tell a taken advance from a refused one, and every implementation logged a successful save either way. That hid a real defect for as long as the monotonic guard existed: a caller that needed the position to go BACKWARDS was silently refused and reported success. An operation that can decline to act must say so in its signature.

To move a checkpoint backwards, use ResetPositionAsync(string, CancellationToken). Lowering a position is a different operation from advancing one, so it is a different member rather than a flag — this method cannot express it and must not be asked to.