Collection<T> class

A typed, queryable set of documents backed by a per-collection CrdtTable.

Documents are identified by the string returned from Codec.idOf. Each document is split into one or more independently timestamped CRDT records by a MergeStrategy; how concurrent edits to the same document merge depends on that strategy (whole-document, per-field, or deep). Edits to different documents always both survive.

Document existence is tracked separately from its fields by a single last-write-wins record (the "existence register"), keyed by the bare document id. This makes deletion atomic at the document level regardless of the merge strategy: a delete and a concurrent field edit are reconciled on that one register (latest wins), so a document can never come back missing some of its fields. The field records of a deleted document are intentionally left untouched, which guarantees that a revived document still carries its full field set; they are harmless until overwritten or compacted.

Document ids and field paths must not contain the ASCII Unit Separator (\x1F, U+001F), which is reserved as the id/field separator. This is enforced: put, increment, and delete throw ArgumentError on an offending id or path instead of writing a record key that would collide with another document's.

The initial load is asynchronous. put, delete, get, all, where, and query await it before returning meaningful results.

Properties

hashCode → int
The hash code for this object.
no setterinherited
length → int
The number of live documents in this collection.
no setter
ready → Future<void>
A future that completes when the initial storage load finishes.
no setter
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited

Methods

all({int? limit, int? offset}) → Future<List<T>>
All live (non-deleted) documents in unspecified order.
compact({required Duration horizon}) → Future<int>
Permanently removes tombstoned records (deleted documents and removed fields) whose HLC wall-clock is older than horizon. Returns the number of records physically reclaimed.
delete(String documentId) → Future<void>
Deletes the document identified by documentId by tombstoning its existence register.
dispose() → Future<void>
Closes any open watch streams and releases resources. Called by Database.close and Database.leave. Safe to call more than once.
get(String documentId) → Future<T?>
Returns the document identified by documentId, or null if absent or deleted.
getChangeset({String? sinceHlc, String? untilHlc}) → Future<CrdtChangeset>
Returns records modified after sinceHlc (or all records when null) in CrdtChangeset format ready for wire serialisation.
increment(String documentId, String fieldPath, {num by = 1}) → Future<void>
Adds by (which may be negative) to the PnCounter field at fieldPath of the document identified by documentId.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
put(T value) → Future<void>
Persists value, using Codec.idOf as the document key.
query() → CollectionQuery<T>
Starts a typed query over this collection.
rekeyEngine(List<int> newKey) → Future<void>
Re-encrypts the backing engine at rest under newKey (a no-op for the in-memory engine). Called by Database when the group key rotates. Awaits the initial load so the engine exists first.
toString() → String
A string representation of this object.
inherited
watch() → Stream<List<T>>
Returns a stream that emits the current document list once the initial storage load completes, then on every subsequent change.
where(bool test(T), {int? limit, int? offset}) → Future<Iterable<T>>
All live documents that satisfy test.

Operators

operator ==(Object other) → bool
The equality operator.
inherited