Table of Contents

Class FirestoreCdcPosition

Namespace
Excalibur.Cdc.Firestore
Assembly
Excalibur.Cdc.Firestore.dll

Represents a position in Firestore CDC using synthetic position tracking.

public sealed class FirestoreCdcPosition : ChangePosition, IEquatable<ChangePosition>, IEquatable<FirestoreCdcPosition>
Inheritance
FirestoreCdcPosition
Implements
Inherited Members

Remarks

Firestore does not have native CDC cursors like other providers. Position is tracked using a combination of document UpdateTime and DocumentId for deterministic ordering.

Documents are ordered by UpdateTime first, then by DocumentId for documents with the same UpdateTime. This ensures consistent ordering across restarts.

Properties

CollectionPath

Gets the collection path being watched.

public string CollectionPath { get; }

Property Value

string

IsBeginning

Gets a value indicating whether this position represents the beginning of the stream.

public bool IsBeginning { get; }

Property Value

bool

IsValid

Gets a value indicating whether this position is valid for resuming.

public override bool IsValid { get; }

Property Value

bool

LastDocumentId

Gets the last processed document ID.

public string? LastDocumentId { get; }

Property Value

string

Remarks

Used as a secondary ordering key for documents with the same UpdateTime. This ensures deterministic ordering when multiple documents have identical timestamps.

Timestamp

Gets the timestamp when this position was recorded (for diagnostics).

public override DateTimeOffset? Timestamp { get; }

Property Value

DateTimeOffset?

UpdateTime

Gets the last processed document update time.

public DateTimeOffset? UpdateTime { get; }

Property Value

DateTimeOffset?

Remarks

Used as the primary ordering key for position tracking. Documents with UpdateTime greater than this value are unprocessed.

Methods

Beginning(string)

Creates a position representing the beginning of the stream.

public static FirestoreCdcPosition Beginning(string collectionPath)

Parameters

collectionPath string

The collection path.

Returns

FirestoreCdcPosition

A position that will read from the beginning.

Equals(FirestoreCdcPosition?)

Indicates whether the current object is equal to another object of the same type.

public bool Equals(FirestoreCdcPosition? other)

Parameters

other FirestoreCdcPosition

An object to compare with this object.

Returns

bool

true if the current object is equal to the other parameter; otherwise, false.

Equals(ChangePosition?)

Indicates whether the current object is equal to another object of the same type.

public override bool Equals(ChangePosition? other)

Parameters

other ChangePosition

An object to compare with this object.

Returns

bool

true if the current object is equal to the other parameter; otherwise, false.

Equals(object?)

Determines whether the specified object is equal to the current object.

public override bool Equals(object? obj)

Parameters

obj object

The object to compare with the current object.

Returns

bool

true if the specified object is equal to the current object; otherwise, false.

FromBase64(string)

Deserializes a position from a base64 string.

public static FirestoreCdcPosition FromBase64(string base64)

Parameters

base64 string

The base64-encoded string.

Returns

FirestoreCdcPosition

The deserialized position.

Exceptions

FormatException

Thrown if the string format is invalid.

FromBytes(byte[])

Deserializes a position from a byte array.

public static FirestoreCdcPosition FromBytes(byte[] bytes)

Parameters

bytes byte[]

The byte array.

Returns

FirestoreCdcPosition

The deserialized position.

Exceptions

FormatException

Thrown if the byte array format is invalid.

FromUpdateTime(string, DateTimeOffset, string?)

Creates a position from specific update time and document ID.

public static FirestoreCdcPosition FromUpdateTime(string collectionPath, DateTimeOffset updateTime, string? lastDocumentId)

Parameters

collectionPath string

The collection path.

updateTime DateTimeOffset

The last processed document update time.

lastDocumentId string

The last processed document ID.

Returns

FirestoreCdcPosition

A position that will resume from the specified location.

GetHashCode()

Serves as the default hash function.

public override int GetHashCode()

Returns

int

A hash code for the current object.

IsAfterPosition(DateTimeOffset, string)

Determines if a document should be processed based on this position.

public bool IsAfterPosition(DateTimeOffset docUpdateTime, string docId)

Parameters

docUpdateTime DateTimeOffset

The document's update time.

docId string

The document ID.

Returns

bool

true if the document is after this position; otherwise, false.

Now(string)

Creates a position representing the current time (latest).

public static FirestoreCdcPosition Now(string collectionPath)

Parameters

collectionPath string

The collection path.

Returns

FirestoreCdcPosition

A position that will read from now.

ToBase64()

Serializes this position to a base64 string for storage.

public string ToBase64()

Returns

string

A base64-encoded string representation.

ToBytes()

Serializes this position to a byte array for storage.

public byte[] ToBytes()

Returns

byte[]

A byte array representation of this position.

Remarks

This method is used for interoperability with the core CdcPositionResetEventArgs which uses byte arrays for position storage.

ToString()

Returns a string that represents the current object.

public override string ToString()

Returns

string

A string that represents the current object.

ToToken()

Converts this position to a string token suitable for storage and resumption.

public override string ToToken()

Returns

string

A string representation of this position that can be persisted and later used to resume CDC processing from this point.

Remarks

The token format is provider-specific but must be round-trippable through the corresponding Parse method on the derived type.

TryFromBase64(string?, out FirestoreCdcPosition?)

Attempts to deserialize a position from a base64 string.

public static bool TryFromBase64(string? base64, out FirestoreCdcPosition? position)

Parameters

base64 string

The base64-encoded string.

position FirestoreCdcPosition

The deserialized position if successful.

Returns

bool

true if parsing succeeded; otherwise, false.

WithCollectionPath(string)

Creates a copy with a different collection path.

public FirestoreCdcPosition WithCollectionPath(string collectionPath)

Parameters

collectionPath string

The new collection path.

Returns

FirestoreCdcPosition

A new position with the updated collection path.

WithDocument(DateTimeOffset, string)

Updates the position with a new document.

public FirestoreCdcPosition WithDocument(DateTimeOffset updateTime, string documentId)

Parameters

updateTime DateTimeOffset

The document update time.

documentId string

The document ID.

Returns

FirestoreCdcPosition

A new position with the updated values.