Table of Contents

Interface IProjectionStore<TProjection>

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

Defines the contract for projection storage operations.

public interface IProjectionStore<TProjection> : IServiceProvider where TProjection : class

Type Parameters

TProjection

The projection type. Must be a reference type.

Inherited Members
Extension Methods

Remarks

Projections are read-optimized views of event-sourced data. This interface provides CRUD operations plus dictionary-based querying that can be translated to any backend (SQL, NoSQL, Search engines).

Uses dictionary-based filters instead of Expression trees per Dapper constraint. Filter keys support operator suffixes for comparison operations:

  • ["Status"] = "Active" - Equality (default)
  • ["Amount:gt"] = 100 - Greater than
  • ["Tags:in"] = new[] { "A", "B" } - In collection

Tenant confinement. Isolation is declared by the resolved IProjectionTenantBoundary capability, not implied by ambient tenant context. A tenant-partitioned or tenant-routing store confines reads, writes and deletion to the selected tenant. An estate-wide store intentionally shares its physical key space; the same identifier addresses the same projection regardless of ambient tenant. Use an appropriate tenant-aware boundary before processing tenant-owned events. A store with no declared boundary does not establish tenant isolation. Query results additionally follow their filters and paging options.

Methods

CountAsync(IDictionary<string, object>?, CancellationToken)

Counts projections matching the specified filters.

Task<long> CountAsync(IDictionary<string, object>? filters, CancellationToken cancellationToken)

Parameters

filters IDictionary<string, object>

Dictionary-based filter conditions. Pass null for total count.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<long>

The count of matching projections.

DeleteAsync(string, CancellationToken)

Permanently deletes a projection key within the store's tenant boundary and physical generation.

Task DeleteAsync(string id, CancellationToken cancellationToken)

Parameters

id string

The projection identifier.

cancellationToken CancellationToken

Cancellation token.

Returns

Task

A task representing the asynchronous operation.

Remarks

This operation is idempotent. Deleting an absent key also records terminal retirement. The store atomically removes projection payload and retains minimal key/deletion metadata. Reads, queries and counts hide that metadata. Later writes cannot recreate the key; conditional writes report Vanished and unconditional writes fail explicitly. To repopulate the key, rebuild into a new physical generation. Retirement metadata must remain while the current generation can receive writes; physical removal is not a reset. This does not erase the source event history or every identifier in retained metadata. Retirement is local to the destination key. It does not cancel handlers already running, discovery of alternate projection keys, or external side effects; those must remain idempotent.

Tenant isolation follows the store's IProjectionTenantBoundary capability. A tenant-partitioned or tenant-routing store retires only the current tenant's key; the same id in another tenant remains unchanged. An estate-wide store has a shared physical key space: ambient tenant context alone does not isolate deletion. Use a tenant-aware store boundary when separate tenants may use the same projection identifier.

GetByIdAsync(string, CancellationToken)

Gets a projection by its unique identifier.

[RequiresUnreferencedCode("Implementations serialize the projection type reflectively; supply JsonSerializerOptions with a source-generated resolver for trimming and AOT.")]
[RequiresDynamicCode("Implementations serialize the projection type reflectively; supply JsonSerializerOptions with a source-generated resolver for trimming and AOT.")]
Task<TProjection?> GetByIdAsync(string id, CancellationToken cancellationToken)

Parameters

id string

The projection identifier.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<TProjection>

The projection if found; otherwise, null.

Remarks

Within a tenant-partitioned or tenant-routing store, the same id in another tenant is reported as not found. Estate-wide stores share their physical key space.

QueryAsync(IDictionary<string, object>?, QueryOptions?, CancellationToken)

Queries projections using dictionary-based filters.

[RequiresUnreferencedCode("Implementations serialize the projection type reflectively; supply JsonSerializerOptions with a source-generated resolver for trimming and AOT.")]
[RequiresDynamicCode("Implementations serialize the projection type reflectively; supply JsonSerializerOptions with a source-generated resolver for trimming and AOT.")]
Task<IReadOnlyList<TProjection>> QueryAsync(IDictionary<string, object>? filters, QueryOptions? options, CancellationToken cancellationToken)

Parameters

filters IDictionary<string, object>

Dictionary-based filter conditions. Pass null for no filtering.

options QueryOptions

Query options for pagination and sorting. Pass null for defaults.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<IReadOnlyList<TProjection>>

The matching projections.

Remarks

Filters use property names as keys with optional operator suffixes:

  • ["Status"] = "Active" - Equality (default)
  • ["Amount:gt"] = 100 - Greater than
  • ["Amount:gte"] = 100 - Greater than or equal
  • ["Amount:lt"] = 1000 - Less than
  • ["Amount:lte"] = 1000 - Less than or equal
  • ["Status:neq"] = "Deleted" - Not equals
  • ["Tags:in"] = new[] { "A", "B" } - In collection
  • ["Name:contains"] = "test" - String contains

Multiple filters are combined with AND logic. Providers translate these filters to their native query syntax (SQL WHERE, MongoDB filters, CosmosDb queries, etc.).

Tenant-partitioned and tenant-routing stores exclude other tenants' projections before applying filters and paging options. Estate-wide stores query their shared destination.

UpsertAsync(string, TProjection, CancellationToken)

Creates or updates a projection, leaving it with NO PLACEABLE POSITION.

[RequiresUnreferencedCode("Implementations serialize the projection type reflectively; supply JsonSerializerOptions with a source-generated resolver for trimming and AOT.")]
[RequiresDynamicCode("Implementations serialize the projection type reflectively; supply JsonSerializerOptions with a source-generated resolver for trimming and AOT.")]
Task UpsertAsync(string id, TProjection projection, CancellationToken cancellationToken)

Parameters

id string

The projection identifier.

projection TProjection

The projection to store.

cancellationToken CancellationToken

Cancellation token.

Returns

Task

A task representing the asynchronous operation.

Remarks

This is not a positioned write, and a positioned client must not use it. It replaces the state with a value the store cannot relate to the event stream, so on a store that records positions the row is left Unplaceable: not a fold over any prefix, and therefore something no later positioned write may advance from -- as is a row left Unnumbered, so saying it only of this one would imply the other is advanceable. What separates them is what the row ASSERTS: an unplaceable state is not a fold over any prefix, where an unnumbered one is a complete fold missing only its coordinate. That is recorded explicitly, in the same atomic action that writes the state -- never by silently dropping or resetting the position, which would make a destroyed position indistinguishable from one that was never established.

Calling this on a positioned store makes the projection unadvanceable until it is rebuilt. A positioned write refuses every row carrying no number, so the next batch is refused rather than folded, and the repair is IPositionedProjectionStore<TProjection>.RebuildAtPositionAsync after a whole-stream replay. A caller that has a complete fold but no position NUMBER wants IPositionedProjectionStore<TProjection>.UpsertUnnumberedAsync instead: that row is refused too, but it reads back as a complete fold rather than as a state related to no prefix at all, which is what a reader and an operator each need. Reaching for this method to express that makes the stronger and wrong claim.

Why the specification says this at all. It is this operation, inherited by the positioned sub-interface, that can falsify the fold invariant that sub-interface declares -- so a client holding the base interface can break the subtype's invariant from outside while staying entirely within its rights. Leaving the effect unstated is what let eight implementations agree by accident rather than by contract.