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
storeIProjectionStore<TProjection>The projection store.
propertyNamestringThe property name to extract distinct values from.
filtersIDictionary<string, object>Optional dictionary-based filter conditions to scope the distinct values. Pass
nullfor no filtering.cancellationTokenCancellationTokenCancellation token.
Returns
- Task<IReadOnlyList<object>>
A read-only list of distinct values for the specified property.
Type Parameters
TProjectionThe 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
storeIProjectionStore<TProjection>The projection store.
idstringThe projection identifier to check.
cancellationTokenCancellationTokenCancellation token.
Returns
Type Parameters
TProjectionThe 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
storeIProjectionStore<TProjection>The projection store.
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> when the store supports cursor pagination; otherwise null.
Type Parameters
TProjectionThe 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
pageSizeis 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
storeIProjectionStore<TProjection>The projection store.
filtersIDictionary<string, object>Dictionary-based filter conditions. Pass
nullfor no filtering.pageNumberintThe 1-based page number to retrieve.
pageSizeintThe number of items per page.
optionsQueryOptionsQuery options for sorting. Pass
nullfor default ordering.cancellationTokenCancellationTokenCancellation token.
Returns
- Task<PagedResult<TProjection>>
A PagedResult<T> containing the page items and pagination metadata.
Type Parameters
TProjectionThe 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
pageNumberorpageSizeis less than 1.