Interface IUnitOfWork

Namespace: Cratis.Chronicle.Transactions

Assembly: Cratis.Chronicle.dll

Represents a unit of work.

public interface IUnitOfWork : IDisposable

Inherited Members: IDisposable.Dispose()

Extension Methods: MethodCalls.CallGenericMethod<TOut, T>(T, Expression<Func<T, Func<TOut>>>, params Type[])

MethodCalls.CallGenericMethod<TOut, T, T1>(T, Expression<Func<T, Func<T1, TOut>>>, T1, params Type[])

MethodCalls.CallGenericMethod<TOut, T, T1, T2>(T, Expression<Func<T, Func<T1, T2, TOut>>>, T1, T2, params Type[])

MethodCalls.CallGenericMethod<TOut, T, T1, T2, T3>(T, Expression<Func<T, Func<T1, T2, T3, TOut>>>, T1, T2, T3, params Type[])

ConverterExtensions.ConvertTo(object, Type)

ConceptExtensions.GetConceptValue(object)

ConceptExtensions.IsConcept(object)

JsonValueExtensions.ToJsonValue(object?)

ObservableExtensions.InvokeAndWrapWithSubject<TResult>(object, Func<CancellationToken, IObservable<TResult>>)

ObservableExtensions.InvokeAndWrapWithTransformSubject<TResult, TSource>(object, Func<CancellationToken, IObservable<TSource>>, Func<TSource, TResult>)

Properties

CorrelationId

Gets the CorrelationId for the IUnitOfWork.

CorrelationId CorrelationId { get; }

Property Value

CorrelationId

EffectReceipt

Gets the winning receipt after a successful receipted commit.

EffectReceiptResult? EffectReceipt { get; }

Property Value

EffectReceiptResult

HasEnrolledDecisionReads

Gets a value indicating whether a decision read has ever been successfully enrolled in this unit of work.

bool HasEnrolledDecisionReads { get; }

Property Value

bool

Remarks

Once true, the value remains true after commit, rollback, or disposal. Custom implementations that do not override this property report false by default.

IsCompleted

Gets the value indicating whether the unit of work is completed.

bool IsCompleted { get; }

Property Value

bool

Remarks

Unit of work being completed is semantically equal to it being disposed.

IsEnforcingReadProtection

Gets whether this unit permanently uses enforced read protection and a strict lifecycle.

bool IsEnforcingReadProtection { get; }

Property Value

bool

IsSuccess

Gets a value indicating whether the IUnitOfWork was successful.

bool IsSuccess { get; }

Property Value

bool

Methods

AddDecisionRead(IDecisionRead)

Enroll a protected read as a commit dependency.

void AddDecisionRead(IDecisionRead read)

Parameters

read IDecisionRead: The protected read.

Exceptions

UnitOfWorkDecisionReadsNotSupported: This implementation does not support decision reads.

AddEnrollmentContributor(IUnitOfWorkEnrollmentContributor)

Attaches a contributor for the lifetime of an enrollment scope, such as one command invocation.

IDisposable AddEnrollmentContributor(IUnitOfWorkEnrollmentContributor contributor)

Parameters

contributor IUnitOfWorkEnrollmentContributor: The contributor to consult before enrollment.

Returns

IDisposable: A handle that removes only this registration on disposal.

Exceptions

UnitOfWorkEnrollmentContributorsNotSupported: The implementation does not support contributors.
UnitOfWorkMutatedDuringEnrollment: A contributor attempted to change registrations.

AddEvent(EventSequenceId, EventSourceId, object, Causation, EventStreamType?, EventStreamId?, EventSourceType?, ConcurrencyScope?, IEnumerable<string>?, DateTimeOffset?, Subject?)

Add an event that has occurred to the IUnitOfWork.

void AddEvent(EventSequenceId eventSequenceId, EventSourceId eventSourceId, object @event, Causation causation, EventStreamType? eventStreamType = null, EventStreamId? eventStreamId = null, EventSourceType? eventSourceType = null, ConcurrencyScope? concurrencyScope = null, IEnumerable<string>? tags = null, DateTimeOffset? occurred = null, Subject? subject = null)

Parameters

eventSequenceId EventSequenceId: The EventSequenceId for the event.
eventSourceId EventSourceId: The EventSourceId for the event.
event object: The event that has occurred.
causation Causation: The Causation for the event.
eventStreamType EventStreamType: Optional EventStreamType for the event, will default to the All stream if not set.
eventStreamId EventStreamId: Optional EventStreamId for the event, will default to Default is not set.
eventSourceType EventSourceType: Optional EventSourceType for the event, will default to Default is not set.
concurrencyScope ConcurrencyScope: Optional ConcurrencyScope for the event, will default to NotSet if not set.
tags IEnumerable<string>: Optional dynamic tags to associate with the event.
occurred DateTimeOffset?: Optional timestamp for when the event occurred.
subject Subject: Optional subject identifying what the event is about.

AddEventWithNamedTags(EventSequenceId, EventSourceId, object, IEnumerable<NamedTag>, Causation, EventStreamType?, EventStreamId?, EventSourceType?, ConcurrencyScope?, IEnumerable<string>?, DateTimeOffset?, Subject?)

Add an event with structured named tags.

void AddEventWithNamedTags(EventSequenceId eventSequenceId, EventSourceId eventSourceId, object @event, IEnumerable<NamedTag> namedTags, Causation causation, EventStreamType? eventStreamType = null, EventStreamId? eventStreamId = null, EventSourceType? eventSourceType = null, ConcurrencyScope? concurrencyScope = null, IEnumerable<string>? tags = null, DateTimeOffset? occurred = null, Subject? subject = null)

Parameters

eventSequenceId EventSequenceId: The event sequence.
eventSourceId EventSourceId: The event source.
event object: The event.
namedTags IEnumerable<NamedTag>: Structured named tags.
causation Causation: The causation.
eventStreamType EventStreamType: Optional stream type.
eventStreamId EventStreamId: Optional stream id.
eventSourceType EventSourceType: Optional source type.
concurrencyScope ConcurrencyScope: Optional concurrency scope.
tags IEnumerable<string>: Optional plain tags.
occurred DateTimeOffset?: Optional occurred time.
subject Subject: Optional subject.

Exceptions

UnitOfWorkNamedTagsNotSupported: The implementation cannot carry nonempty named tags.

AddEventWithOptions(EventSequenceId, EventSourceId, object, Causation, EventEnrollmentOptions)

Enrolls an event with its scope origin. Alternate implementations retain their existing enrollment behavior.

void AddEventWithOptions(EventSequenceId eventSequenceId, EventSourceId eventSourceId, object @event, Causation causation, EventEnrollmentOptions options)

Parameters

eventSequenceId EventSequenceId: The event sequence.
eventSourceId EventSourceId: The event source.
event object: The event.
causation Causation: The causation.
options EventEnrollmentOptions: The enrollment options.

Exceptions

ConcurrencyScopeOriginNotValidForEvents: The origin is reserved for reads.

AddEvents(EventSequenceId, IEnumerable<EventForEventSourceId>, IEnumerable<KeyValuePair<EventSourceId, ConcurrencyScope>>)

Adds an ordered batch of events and independently labeled concurrency scopes to the IUnitOfWork.

void AddEvents(EventSequenceId eventSequenceId, IEnumerable<EventForEventSourceId> events, IEnumerable<KeyValuePair<EventSourceId, ConcurrencyScope>> concurrencyScopes)

Parameters

eventSequenceId EventSequenceId: The EventSequenceId for the events.
events IEnumerable<EventForEventSourceId>: The events to add, in commit order.
concurrencyScopes IEnumerable<KeyValuePair<EventSourceId, ConcurrencyScope>>: The concurrency scopes to validate with the batch.

Remarks

Both inputs are materialized before this method returns. Consecutive single-event enrollments retain their legacy source-grouped order. Each call to this method forms a globally ordered segment between those legacy segments, and commit flattens every segment into one append operation. A concurrency-scope key can be an independent label when its scope does not narrow by event-source ID. For event-target labels, a missing or NotSet scope retains the configured strategy. An independent non-target label must use a concrete exact scope or None.

Exceptions

ConcurrencyScopeLabelMustBeSpecified: Thrown when an event target or scope label is unspecified, blank, or whitespace.
ConcurrencyScopeEventSourceIdDoesNotMatchLabel: Thrown when a scope narrows by an event source different from its label.
DuplicateConcurrencyScopeForEventSourceId: Thrown when more than one scope has the same label in one enrollment.
ConflictingConcurrencyScopesForLabel: Thrown when a label already has a different explicit scope in this unit of work.
IndependentConcurrencyScopeMustBeExplicit: Thrown when an independent non-target label does not have a concrete exact scope or None.
UnitOfWorkCannotSpanEventSequences: Thrown when this unit of work is already bound to another event sequence.
UnitOfWorkBatchEnrollmentNotSupported: Thrown when an alternate unit-of-work implementation does not support ordered batch enrollment.

AddEvents(EventSequenceId, IEnumerable<EventForEventSourceId>, IEnumerable<KeyValuePair<EventSourceId, ConcurrencyScope>>, ConcurrencyScopeOrigin)

Enrolls an ordered batch with the origin of its supplied scopes.

void AddEvents(EventSequenceId eventSequenceId, IEnumerable<EventForEventSourceId> events, IEnumerable<KeyValuePair<EventSourceId, ConcurrencyScope>> concurrencyScopes, ConcurrencyScopeOrigin origin)

Parameters

eventSequenceId EventSequenceId: The event sequence.
events IEnumerable<EventForEventSourceId>: The ordered events.
concurrencyScopes IEnumerable<KeyValuePair<EventSourceId, ConcurrencyScope>>: The supplied scopes.
origin ConcurrencyScopeOrigin: The scope contribution.

Exceptions

ConcurrencyScopeOriginNotValidForEvents: The origin is reserved for reads.

AllowReads(ReadAllowance, string)

Allows explicit reads without permitting immediate appends or removing existing dependencies.

IDisposable AllowReads(ReadAllowance allowance, string reason)

Parameters

allowance ReadAllowance: Advisory reads or reads contributed before exposure.
reason string: The explicit reason for the region.

Returns

IDisposable: The flow-local read region.

Exceptions

UnitOfWorkReadProtectionNotSupported: The implementation cannot support allowances.

Commit()

Commit the IUnitOfWork.

Task Commit()

Returns

Task: Awaitable task.

EnforceReadProtection()

Begins invocation read protection before any event or read dependency is enrolled. Only the first caller receives the owning lifetime; subsequent leases cannot end enforcement.

ReadProtectionFrame EnforceReadProtection()

Returns

ReadProtectionFrame: The invocation frame, disposed by the owning command pipeline in a finally block.

Exceptions

UnitOfWorkReadProtectionNotSupported: The implementation cannot enforce read protection.

EnrolContributedRead(ContributedRead)

Atomically validates target, staged overlap and distinct contributions before enrolling a read.

void EnrolContributedRead(ContributedRead contribution)

Parameters

contribution ContributedRead: The stream or aggregate dependency.

Exceptions

UnitOfWorkReadProtectionNotSupported: The implementation cannot enroll contributions.

GetAppendConditions()

Gets the append conditions captured by the trusted commit.

IReadOnlyList<AppendCondition> GetAppendConditions()

Returns

IReadOnlyList<AppendCondition>: The immutable append-condition descriptions.

GetAppendErrors()

Get any errors that have occurred while attempting to commit in the IUnitOfWork.

IEnumerable<AppendError> GetAppendErrors()

Returns

IEnumerable<AppendError>: A collection of AppendError.

GetConcurrencyViolations()

Gets any concurrency violations thar occurred in the IUnitOfWork.

IEnumerable<ConcurrencyViolation> GetConcurrencyViolations()

Returns

IEnumerable<ConcurrencyViolation>: A collection of ConcurrencyViolation.

GetConstraintViolations()

Gets any constraint violations that occurred in the IUnitOfWork.

IEnumerable<ConstraintViolation> GetConstraintViolations()

Returns

IEnumerable<ConstraintViolation>: A collection of ConstraintViolation.

GetDecisionConflicts()

Gets the decision conflicts that refused the commit.

IEnumerable<DecisionConflict> GetDecisionConflicts()

Returns

IEnumerable<DecisionConflict>: Decision conflicts, if any, with the first conflicting event when the kernel reported it.

GetEvents()

Get the events that have occurred in the IUnitOfWork.

IEnumerable<object> GetEvents()

Returns

IEnumerable<object>: A collection of events.

OnCompleted(Action<IUnitOfWork>)

Set callback to be called when completed.

void OnCompleted(Action<IUnitOfWork> callback)

Parameters

callback Action<IUnitOfWork>: The callback to call.

RefuseImmediateAppends()

Refuses immediate appends in this asynchronous flow without changing read admission. The first caller owns completion only if no completion owner or enforced read protection already exists. Otherwise the frame is refusal-only and completion stays with the existing owner. Later acquisitions cannot complete the unit or end refusal.

ImmediateAppendRefusal RefuseImmediateAppends()

Returns

ImmediateAppendRefusal: The refusal lifetime, or a borrowed frame for a nested acquisition. Commit through the existing owner when present.

Exceptions

UnitOfWorkImmediateAppendRefusalNotSupported: The implementation cannot enforce append admission.
ImmediateAppendRefusalRequiresOwner: Another unit owns the active refusal.

Rollback()

Rollback the IUnitOfWork.

Task Rollback()

Returns

Task: Awaitable task.

SuspendReadRegions()

Suspends the read regions this asynchronous flow inherited, without ending read protection.

IDisposable SuspendReadRegions()

Returns

IDisposable: The suspension, disposed by the host when the nested invocation ends.

Remarks

A read region flows with the asynchronous context, so a region opened by an outer invocation also covers a nested invocation it runs. A host that runs nested invocations under the same read protection suspends the inherited regions at the start of the nested one: reads are then refused as if no region were open, while regions opened inside the suspension apply as usual. Disposing the returned scope restores the inherited regions. Suspensions nest.

Exceptions

UnitOfWorkReadProtectionNotSupported: The implementation cannot support read regions.

TryGetLastCommittedEventSequenceNumber(out EventSequenceNumber?)

Try to get the EventSequenceNumber of the last committed event.

bool TryGetLastCommittedEventSequenceNumber(out EventSequenceNumber? eventSequenceNumber)

Parameters

eventSequenceNumber EventSequenceNumber: The outputted EventSequenceNumber of the last committed event.

Returns

bool: True if events were committed, false if not.

UseEffectReceipt(EffectKey, JsonNode?)

Enrolls one effect key in this unit's atomic commit. Re-enrolling the same key replaces its response until completion begins.

void UseEffectReceipt(EffectKey key, JsonNode? response = null)

Parameters

key EffectKey: The occurrence effect key.
response JsonNode: Optional plaintext JSON response without personal data.

Exceptions

EffectReceiptsNotSupported: Atomic receipt support is absent or unknown.
EffectReceiptResponseTooLarge: The response exceeds 64 KiB of UTF-8 JSON.
UnitOfWorkEffectReceiptAlreadySet: Another key is already enrolled.