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
TProjectionThe 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
filtersIDictionary<string, object>Dictionary-based filter conditions. Pass
nullfor no filtering.cursorstringAn opaque continuation token from a previous call's NextCursor. Pass
nullto start from the beginning.pageSizeintThe number of items per page.
cancellationTokenCancellationTokenCancellation token.
Returns
- Task<CursorPagedResult<TProjection>>
A CursorPagedResult<T> containing the page items and a continuation cursor.
Exceptions
- ArgumentOutOfRangeException
Thrown when
pageSizeis less than 1.