Class AppendResult
- Namespace
- Excalibur.EventSourcing
- Assembly
- Excalibur.EventSourcing.Abstractions.dll
Represents the result of appending events to the store.
public sealed class AppendResult
- Inheritance
-
AppendResult
- Inherited Members
Properties
ErrorMessage
Gets the error message if the operation failed.
public string? ErrorMessage { get; }
Property Value
FirstEventPosition
Gets the global stream position of the first event that was appended, or null when the store does not support a global ordering.
public long? FirstEventPosition { get; }
Property Value
- long?
The monotonic global position of the first appended event, or null when global ordering is unsupported for the originating provider.
Remarks
A store that maintains a monotonic, store-wide sequence across all streams returns a real position here. Stores that only track per-stream versions (or track no global ordering at all) return null rather than fabricating a value. The property is also null for failed appends and for successful appends that contained no events.
IsConcurrencyConflict
Gets a value indicating whether the failure was due to a concurrency conflict.
public bool IsConcurrencyConflict { get; }
Property Value
LastEventPosition
Gets the global stream position of the LAST event that was appended, or null when the store does not support a global ordering.
public long? LastEventPosition { get; }
Property Value
- long?
The monotonic global position of the last appended event, or null when global ordering is unsupported for the originating provider.
Remarks
This is the value a reader must wait for, and FirstEventPosition is not. An
append of three events reports a first position of N and a last of N+2; a read model
that has reached N may still be missing two of this caller's events, so waiting on the
first position silently fails to deliver read-your-writes.
Each provider reports this itself rather than letting a caller derive it. Deriving
first + count - 1 assumes one append's positions are contiguous, which is a property of a
provider's allocation strategy, not of this contract — PostgreSQL's store reserves a contiguous
block under a counter-row lock held to COMMIT and documents that it must never become a sequence,
but nothing obliges another provider to do the same. A derivation in shared code would be correct
today and silently wrong the first time a provider allocates differently.
Null under exactly the same conditions as FirstEventPosition: a provider without a store-wide sequence, a failed append, or a successful append that carried no events.
NextExpectedVersion
Gets the version the aggregate's stream is at after this append — the value a subsequent append must pass as its expected version — or null when this result cannot state one.
public long? NextExpectedVersion { get; }
Property Value
Remarks
Versions are zero-based, so appending N events to a new stream reports N-1 here: this
is the version of the last event written, not the version the next event will receive. An append
that carried no events reports back the version it was given.
A failed append reports null rather than a number, because it has no version to
report and -1 is not free to borrow as a sentinel: under this interface's version base
-1 is the ordinary value meaning this stream does not exist. Reporting it after a
failure would hand a caller a number asserting the opposite of the truth, which they could pass
straight back as an expected version and create a stream that already holds events.
A concurrency conflict is the one failure that can state a version, and it states one only
when it measured one: where the store read the stream's actual version in order to detect the
conflict it reports that measured value here — including a genuine -1 when the conflict is
that the stream does not exist at all. Where the store detected the conflict by another route and
the version read did not succeed, it reports null.
Every value this property carries is one the store measured. It is never the caller's own
expected version echoed back, never a bound, and never derived from anything but a read. That is
what makes the two meanings of -1 separable: a -1 here is always "the stream
measurably does not exist", and "not measured" is null instead. A caller may pass
a measured version into a subsequent operation after applying its concurrency policy. For
Unknown, reconcile the original operation before rebasing or
regenerating events; a null version is not permission to retry as a new operation.
Outcome
Gets what the append actually did.
public AppendOutcome Outcome { get; }
Property Value
- AppendOutcome
The single outcome that holds for this result.
Remarks
Success and IsConcurrencyConflict are derived from this. Existing success handling remains compatible, but false does not prove rejection: callers must handle Unknown before retrying. Read this when the difference between an append written by this call and one recognised as already durable matters — see AlreadyCommitted.
Success
Gets a value indicating whether the append operation succeeded.
public bool Success { get; }
Property Value
Remarks
True for Committed and for AlreadyCommitted alike: in both the events the caller asked to append are durable. False does not prove rollback: Unknown may represent a committed append.
Methods
CreateAlreadyCommitted(long, long?, long?)
Creates a successful append result for events that were already durably present, which the store recognised as its own by identity rather than writing again.
public static AppendResult CreateAlreadyCommitted(long nextExpectedVersion, long? firstEventPosition, long? lastEventPosition)
Parameters
nextExpectedVersionlongThe version the recognised events reached.
firstEventPositionlong?The global stream position of the first recognised event, or null when the store does not support a global ordering or cannot state one.
lastEventPositionlong?The global stream position of the last recognised event, or null when the store does not support a global ordering or cannot state one.
Returns
- AppendResult
A successful append result carrying AlreadyCommitted.
Remarks
Every store that answers a committed-append identity probe reports through here rather than through CreateSuccess(long, long?, long?). The two are indistinguishable to a caller reading only Success, and that is deliberate — the distinction is for the caller that needs it.
CreateConcurrencyConflict(long, long?)
Creates a failed append result due to version mismatch.
public static AppendResult CreateConcurrencyConflict(long expectedVersion, long? actualVersion)
Parameters
expectedVersionlongThe version the append required the stream to be at.
actualVersionlong?The stream's current version as the store read it, or null when the store detected the conflict without being able to read one.
Returns
- AppendResult
A failed append result indicating concurrency conflict.
Remarks
actualVersion takes only what a read returned. Pass the read's own result
straight through — never expectedVersion, never a bound, never a value derived
from anything but a read. The parameter is long? precisely so that a store which did
not measure has no way to type a number here: the violation is inexpressible rather than
merely discouraged.
Echoing the caller's own expectedVersion back is the specific error this
signature exists to prevent, and it is not merely unmeasured but known-false: the state that reaches
an unmeasured conflict is one where a stream-key unique violation was raised, which proves another
writer holds the row at expectedVersion + 1. That makes expectedVersion
the one value the stream provably is not, and it would additionally render
ErrorMessage as "expected version N but current version is N" — a conflict asserting
that nothing moved.
When actualVersion is null the message states that the version
could not be determined rather than naming one, so the string a consumer reads never claims a
measurement that was not taken.
CreateFailure(string)
Creates a failed append result with custom error.
public static AppendResult CreateFailure(string errorMessage)
Parameters
errorMessagestringThe error message.
Returns
- AppendResult
A failed append result, reporting no version.
Remarks
Nothing was appended, so the result states no version: NextExpectedVersion is null. Use CreateConcurrencyConflict(long, long?) for the one failure that has a version to report.
CreateSuccess(long, long?, long?)
Creates a successful append result for events this call wrote.
public static AppendResult CreateSuccess(long nextExpectedVersion, long? firstEventPosition, long? lastEventPosition)
Parameters
nextExpectedVersionlongThe next expected version.
firstEventPositionlong?The global stream position of the first appended event, or null when the store does not support a global ordering.
lastEventPositionlong?The global stream position of the last appended event -- the value a reader waits for to observe this whole append -- or null when the store does not support a global ordering.
Returns
- AppendResult
A successful append result.
CreateUnknown(string)
Reports that the provider cannot determine whether the atomic append committed.
public static AppendResult CreateUnknown(string errorMessage)
Parameters
errorMessagestringThe diagnostic reason the outcome could not be established.
Returns
- AppendResult
An unknown outcome, with no asserted version or global position.
Remarks
Preserve the original operation identity and payloads for reconciliation. A negative read alone cannot prove abortion while the original operation retains authority to commit.