Interface IEventStore
- Namespace
- Excalibur.EventSourcing
- Assembly
- Excalibur.EventSourcing.Abstractions.dll
Defines the contract for event store operations supporting event sourcing patterns.
public interface IEventStore : IServiceProvider
- Inherited Members
Remarks
This interface provides the core operations for event-sourced aggregates:
- Loading events for aggregate hydration
- Appending events with optimistic concurrency control
- For reliable event publishing, use the transactional outbox pattern
For snapshot operations, use ISnapshotStore.
Tenant confinement. Every operation is confined to the ambient tenant established for this
store instance: a confined read returns none of another tenant's rows and every one of the caller's
own, and a confined append can neither be observed by, nor collide with, another tenant's stream.
Which mechanism a given provider uses to hold that boundary is declared by its capability marker —
ITenantScopingCapability<TContract> for a store that reads an ambient tenant,
ITenantPartitionedCapability<TContract> for one that carries the tenant on the row and
re-establishes it on read — and the package's own ARCHITECTURE.md states the falsifiable
guarantee and how it is verified. A store presenting neither marker is not confined by the framework.
Performance Note: Methods return ValueTask<TResult> to avoid heap allocations for synchronous completions (e.g., in-memory stores, cache hits). Callers should await the result immediately and not store the ValueTask for later use.
Methods
AppendAsync(string, string, IEnumerable<IDomainEvent>, long, CancellationToken)
Appends events to the store with optimistic concurrency control.
ValueTask<AppendResult> AppendAsync(string aggregateId, string aggregateType, IEnumerable<IDomainEvent> events, long expectedVersion, CancellationToken cancellationToken)
Parameters
aggregateIdstringThe aggregate identifier. Must not be null, empty, or white space.
aggregateTypestringThe aggregate type name. Must not be null, empty, or white space.
eventsIEnumerable<IDomainEvent>The events to append. Must not be null.
expectedVersionlongThe version the stream is expected to currently be at, or
-1when the stream does not yet exist. See the version base stated in the remarks below.cancellationTokenCancellationTokenCancellation token.
Returns
- ValueTask<AppendResult>
The result of the append operation, carrying the stream's version after the append in NextExpectedVersion.
Remarks
Version base. Stream versions are zero-based and contiguous. The first event appended to a
new stream is version 0, and each subsequent event takes the next integer. A stream that
does not yet exist has no current version, which expectedVersion expresses as
-1. Appending N events to a new stream therefore leaves it at version N-1:
that is the value NextExpectedVersion reports, and the value the next
append must pass as expectedVersion — it is the version the stream is now at,
not the version the next event will receive. Appending no events leaves the version unchanged and
reports back the version it was given.
An identifier that is null, empty, or white space is a usage error, never a legitimate stream: accepting one would fabricate a stream key and write events where no reader will ever look. Every implementation therefore rejects such an argument by throwing, rather than reporting a failed AppendResult — a returned result models a domain or infrastructure outcome, not a caller defect. Implementations validate their arguments before any I/O or concurrency check is attempted.
Outcome or defect. The line between a returned AppendResult and a thrown exception is whether the identical call could ever succeed without a change to the calling program. A version clash could, once the caller reloads, so it is reported as a result carrying IsConcurrencyConflict; an infrastructure fault may be reported as Failed only when non-commit is established. A lost commit acknowledgement with inconclusive recovery is Unknown, even if a later read sees a different stream version or no matching rows. Retry classification does not establish commit certainty. An event type the configured resolver does not declare could not — no retry, reload or reconfiguration reaches it — so it throws, as do a blank identifier, a batch above the provider's atomic limit, and cancellation. Every implementation of this interface answers the same way; a caller may rely on that rather than on which provider is configured.
Cancellation propagates. A cancelled append raises OperationCanceledException rather than reporting a failed result: reporting it as a store failure would invite a caller to retry inside a scope that has already been cancelled. Cancellation after dispatch does not prove rollback. Reconcile outside the cancelled operation using the original tenant, stream, event identities, payloads and expected version; do not regenerate events or rebase the append merely because its acknowledgement was not received.
Confined to the ambient tenant established for this store instance: the appended events join only
this tenant's stream for aggregateId, and the optimistic-concurrency check
against expectedVersion is evaluated within that same partition — another
tenant holding a stream under the same aggregateId can neither cause nor observe
a conflict here.
Exceptions
- ArgumentException
aggregateIdoraggregateTypeis empty or white space.- ArgumentNullException
aggregateId,aggregateType, oreventsis null.- EventBatchTooLargeException
eventscontains more events than the underlying store can append atomically. The exception carries the offending count and the limit, so a caller may split the batch and retry.- EventTypeNotDeclaredException
An event's runtime type is not declared by the type-info resolver the host configured, so it cannot be serialized. Nothing is appended. The identical call cannot succeed until the type is declared, which is why this is thrown rather than reported as a failed AppendResult.
LoadAsync(string, string, long, CancellationToken)
Loads events for an aggregate from a specific version.
ValueTask<IReadOnlyList<StoredEvent>> LoadAsync(string aggregateId, string aggregateType, long fromVersion, CancellationToken cancellationToken)
Parameters
aggregateIdstringThe aggregate identifier. Must not be null, empty, or white space.
aggregateTypestringThe aggregate type name. Must not be null, empty, or white space.
fromVersionlongThe version to start loading from, exclusive: the result begins at the next version after this one. Versions are zero-based, so
-1loads the whole stream. See the version base stated on AppendAsync(string, string, IEnumerable<IDomainEvent>, long, CancellationToken).cancellationTokenCancellationTokenCancellation token.
Returns
- ValueTask<IReadOnlyList<StoredEvent>>
The events for the aggregate from the specified version in order.
Remarks
Confined identically to the zero-argument overload above: none of another tenant's events for
this aggregateId, and every one of the caller's own from
fromVersion onward.
Exceptions
- ArgumentException
aggregateIdoraggregateTypeis empty or white space.- ArgumentNullException
aggregateIdoraggregateTypeis null.
LoadAsync(string, string, CancellationToken)
Loads all events for an aggregate.
ValueTask<IReadOnlyList<StoredEvent>> LoadAsync(string aggregateId, string aggregateType, CancellationToken cancellationToken)
Parameters
aggregateIdstringThe aggregate identifier. Must not be null, empty, or white space.
aggregateTypestringThe aggregate type name. Must not be null, empty, or white space.
cancellationTokenCancellationTokenCancellation token.
Returns
- ValueTask<IReadOnlyList<StoredEvent>>
The events for the aggregate in version order.
Remarks
Confined to the ambient tenant established for this store instance: returns none of another
tenant's events for this aggregateId, and every one of the caller's own — a
store that returns fewer than the caller's own full history satisfies neither this contract nor
the aggregate that must replay from it.
Exceptions
- ArgumentException
aggregateIdoraggregateTypeis empty or white space.- ArgumentNullException
aggregateIdoraggregateTypeis null.