Table of Contents

Interface ICursorProjectionStore<TProjection>

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

Extends IProjectionStore<TProjection> with cursor-based (keyset) pagination support.

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

Type Parameters

TProjection

The projection type. Must be a reference type.

Inherited Members
Extension Methods

Remarks

This is an ISP sub-interface following the IBufferDistributedCache precedent. Consumers reach it through QueryCursorAsync<TProjection>(IProjectionStore<TProjection>, IDictionary<string, object>?, string?, int, CancellationToken), which returns null when the store does not support cursor pagination:

var result = await store.QueryCursorAsync(filters, null, 20, ct);
if (result is not null)
{
    // Use result.NextCursor for subsequent pages
}

Do not test the store's type to detect this capability. A store is commonly reached through a decorator -- tenant scoping, encryption -- whose own interface list is fixed when it is compiled, so the test reports the decorator and not the store beneath it. Ask the store for the capability instead (GetService(Type)), which the extension method above already does.

Cursor-based pagination provides stable results under concurrent writes and better performance on large datasets compared to offset-based pagination. The cursor is an opaque string produced by CursorEncoder — consumers must not parse it.

Provider-specific implementations encode cursor values appropriate to their backend (e.g., Elasticsearch search_after, SQL Server keyset queries, DynamoDB ExclusiveStartKey).

Methods

QueryCursorAsync(IDictionary<string, object>?, string?, int, CancellationToken)

Queries projections with cursor-based pagination, returning a page of results along with a continuation token for the next page.

[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<CursorPagedResult<TProjection>> QueryCursorAsync(IDictionary<string, object>? filters, string? cursor, int pageSize, CancellationToken cancellationToken)

Parameters

filters IDictionary<string, object>

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

cursor string

An opaque continuation token from a previous call's NextCursor. Pass null to start from the beginning.

pageSize int

The number of items per page.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<CursorPagedResult<TProjection>>

A CursorPagedResult<T> containing the page items and a continuation cursor.

Exceptions

ArgumentOutOfRangeException

Thrown when pageSize is less than 1.