Table of Contents

Class ProjectionStoreExtensions

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

Extension methods for IProjectionStore<TProjection> providing common query operations with provider-optimized escape hatches.

public static class ProjectionStoreExtensions
Inheritance
ProjectionStoreExtensions
Inherited Members

Methods

DistinctValuesAsync<TProjection>(IProjectionStore<TProjection>, string, IDictionary<string, object>?, CancellationToken)

Gets the distinct values of a specified property across all projections matching the given filters. Useful for populating filter dropdown options.

[RequiresUnreferencedCode("Fallback uses reflection to extract property values. Implement IDistinctValuesProjectionStore<T> for AOT-safe usage.")]
[RequiresDynamicCode("Implementations serialize the projection type reflectively; supply JsonSerializerOptions with a source-generated resolver for trimming and AOT.")]
public static Task<IReadOnlyList<object>> DistinctValuesAsync<TProjection>(this IProjectionStore<TProjection> store, string propertyName, IDictionary<string, object>? filters, CancellationToken cancellationToken) where TProjection : class

Parameters

store IProjectionStore<TProjection>

The projection store.

propertyName string

The property name to extract distinct values from.

filters IDictionary<string, object>

Optional dictionary-based filter conditions to scope the distinct values. Pass null for no filtering.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<IReadOnlyList<object>>

A read-only list of distinct values for the specified property.

Type Parameters

TProjection

The projection type.

Remarks

If the store implements IDistinctValuesProjectionStore<TProjection>, the provider-optimized path is used (e.g., SELECT DISTINCT in SQL, aggregation pipeline in MongoDB). Otherwise, falls back to QueryAsync(IDictionary<string, object>?, QueryOptions?, CancellationToken) and extracts distinct values via reflection.

The fallback path loads all matching projections into memory and is not suitable for large datasets. It requests the observed count in one query and refuses a truncated response. Provider result-window limits and errors propagate. Count and query are separate observations, not a concurrent snapshot. Providers should implement the escape hatch for production use.

ExistsAsync<TProjection>(IProjectionStore<TProjection>, string, CancellationToken)

Checks whether a projection with the specified identifier exists.

[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.")]
public static Task<bool> ExistsAsync<TProjection>(this IProjectionStore<TProjection> store, string id, CancellationToken cancellationToken) where TProjection : class

Parameters

store IProjectionStore<TProjection>

The projection store.

id string

The projection identifier to check.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<bool>

true if a projection with the specified id exists; otherwise, false.

Type Parameters

TProjection

The projection type.

Remarks

If the store implements IExistsProjectionStore<TProjection>, the provider-optimized path is used (e.g., SELECT TOP 1 1 in SQL, HEAD request in CosmosDB). Otherwise, falls back to GetByIdAsync(string, CancellationToken) with a null check.

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

Queries projections with cursor-based pagination.

[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.")]
public static Task<CursorPagedResult<TProjection>?> QueryCursorAsync<TProjection>(this IProjectionStore<TProjection> store, IDictionary<string, object>? filters, string? cursor, int pageSize, CancellationToken cancellationToken) where TProjection : class

Parameters

store IProjectionStore<TProjection>

The projection store.

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> when the store supports cursor pagination; otherwise null.

Type Parameters

TProjection

The projection type.

Remarks

Cursor pagination has no correct in-memory fallback: the cursor is an opaque provider token, and synthesising one would produce a token the provider cannot honour. This method therefore reports the absence of the capability as null rather than inventing a page, so a caller can choose offset pagination instead.

Prefer this over testing the store's type, for the reason given on QueryPagedAsync<TProjection>(IProjectionStore<TProjection>, IDictionary<string, object>?, int, int, QueryOptions?, CancellationToken): a decorator does not implement the capability interface even when the store it wraps does.

Exceptions

ArgumentOutOfRangeException

Thrown when pageSize is less than 1.

QueryPagedAsync<TProjection>(IProjectionStore<TProjection>, IDictionary<string, object>?, int, int, QueryOptions?, CancellationToken)

Queries projections with offset-based pagination.

[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.")]
public static Task<PagedResult<TProjection>> QueryPagedAsync<TProjection>(this IProjectionStore<TProjection> store, IDictionary<string, object>? filters, int pageNumber, int pageSize, QueryOptions? options, CancellationToken cancellationToken) where TProjection : class

Parameters

store IProjectionStore<TProjection>

The projection store.

filters IDictionary<string, object>

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

pageNumber int

The 1-based page number to retrieve.

pageSize int

The number of items per page.

options QueryOptions

Query options for sorting. Pass null for default ordering.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<PagedResult<TProjection>>

A PagedResult<T> containing the page items and pagination metadata.

Type Parameters

TProjection

The projection type.

Remarks

Uses the provider's native pagination when the store offers IPageableProjectionStore<TProjection>; otherwise counts matching rows and requests a bounded page through QueryAsync(IDictionary<string, object>?, QueryOptions?, CancellationToken). Count and page are separate observations, not a snapshot across concurrent writes.

Prefer this over testing the store's type. A store reached through a decorator -- tenant scoping, encryption -- does not itself implement the capability interface even when the store beneath it does, so a type test silently selects the fallback. This method asks the store for the capability instead, which a decorator answers on behalf of the store it wraps.

Exceptions

ArgumentOutOfRangeException

Thrown when pageNumber or pageSize is less than 1.