AtKeyValueStore<K, V, T> class abstract interface

The at_server-flavour key-value store. Extends KeyValueStore with the sync-coupled surface that only makes sense for a keystore that participates in atSign-to-atSign sync:

  • a (possibly-null) commitLog that records every mutation
  • the putMeta / putAll / getMeta metadata triplet that at_secondary_server uses on the update / lookup paths
  • the structured-key scanKeys surface — KeyPattern filters by atKey shape (sharedBy / sharedWith / namespace / idPrefix), so it lives on the atKey-aware tier rather than the generic KeyValueStore
  • the queryByPath / supportsPathQueries predicate-query pair that lights up on a future SQL backend

The commit log is nullable: server-side bundles always have one (writes append to it for sync); client-side bundles may not (clients track sync via a different mechanism). The server's bootstrap is responsible for the single non-null assertion and binding the result to a non-nullable local — downstream consumers don't re-check.

Compaction lives on the resources that actually get compacted (AtCommitLog, AtAccessLog, AtNotificationKeystore); the keystore itself is not compactable in the cron-driven sense.

Implemented types
Implementers

Properties

changes → Stream<KeyStoreChange>
Broadcast stream of KeyStoreChange events — one per successful mutation that affects the key set or stored value. Late subscribers do not receive earlier events.
no setterinherited
commitLog ↔ AtCommitLog?
The commit log for this keystore, or null if this is an un-synced (client-side) keystore.
getter/setter pair
hashCode → int
The hash code for this object.
no setterinherited
postRemoveHooks → List<Future<void> Function(K key, {required bool skipCommit})>
Hooks invoked synchronously after a single-key remove. Each hook is awaited in order. Hook exceptions are propagated to the caller after the remove has already happened.
no setterinherited
preRemoveHooks → List<Future<void> Function(K key, {required bool skipCommit})>
Hooks invoked synchronously before a single-key remove. Each hook is awaited in order; if a hook throws, the remove is aborted and the exception propagates.
no setterinherited
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
supportsPathQueries → bool
true when this keystore can push value-field predicates down to its native query plan (queryByPath is then a real indexed query). false when queryByPath is unsupported and consumers must fall back to a scanKeys + in-memory filter.
no setter
supportsSnapshots → bool
true when this keystore can produce real isolated snapshots (snapshot returns a handle whose reads observe the keystore's state at snapshot-creation time, ignoring concurrent writes). false when the handle delegates to live state (Hive backends).
no setterinherited

Methods

compact(bool dryRun) → Stream<Object>
Compact the keystore. The Hive impl delegates to its internal commit log's compaction; a client-side bundle (no commit log) is a no-op and yields nothing.
override
create(K key, V value, {bool skipCommit = false}) → Future<int?>
If no mapping exists for key, associates it with value and returns the commit-log sequence number; otherwise behaviour is implementation-defined (typically throws).
inherited
deleteExpiredKeys() → Future<bool>
Removes all expired keys. Deletes are local-only — they are NOT appended to the commit log, so an expiry sweep never advances the local commitId and never propagates to other secondaries via sync. Expiry is treated as backend maintenance, not a sync-worthy mutation; clients drop expired keys independently using their own TTL bookkeeping.
inherited
exists(K key) → Future<bool>
Returns true if the keystore currently contains key, else false. The backend-agnostic existence check — the same call site works against every backend.
inherited
get(K key) → Future<V?>
Retrieves the value mapped to key, or null if no mapping exists. Implementations may also throw a backend-specific not-found exception (e.g. KeyNotFoundException) instead of returning null — consult the concrete impl.
inherited
getExpiredKeys() → Future<Stream<K>>
Streams all keys that have expired. The returned Future completes once the backend has accepted the request (surfacing any setup failure eagerly); the Stream then yields the keys.
inherited
getKeys({String? regex}) → Future<Stream<K>>
Streams the keys, optionally filtered by regex. The returned Future completes once the backend has accepted the request — setup failures (store not open, invalid regex) reject the Future eagerly rather than surfacing mid-stream; the Stream then yields the matching keys.
inherited
getMany(List<K> keys) → Future<Map<K, V>>
Bulk fetch — returns the values for every key in keys that is currently present. Keys that are absent are NOT included in the returned map.
inherited
getMeta(K key) → Future<T>
Returns the metadata associated with key.
initialize() → Future<void>
Subclasses should put any necessary post-construction async initialization in this method.
inherited
nextAvailableAt({DateTime? asOf}) → Future<DateTime?>
Smallest non-null availableAt among entries that have not yet become available (availableAt > asOf, asOf defaulting to now), or null if there are none. Drives a TTB-sweep wake-up timer.
nextExpiresAt() → Future<DateTime?>
Smallest non-null expiry instant across all entries, or null if no entry has one set. Drives expiry-cron wake-up: a caller can sleep until the returned time, then call peekExpired or deleteExpiredKeys to drain.
inherited
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
peekExpired({DateTime? asOf, int? limit}) → Future<Stream<K>>
Up to limit keys whose expiry instant is at-or-before asOf (default: now), in ascending-expiry order. limit: 1 answers "which key is next to expire". limit: null means no limit — the same set as getExpiredKeys, but with guaranteed ascending-expiry ordering. Ties (same expiry instant) are yielded in implementation-defined order.
inherited
peekNewlyAvailable({required DateTime since, DateTime? asOf, int? limit}) → Future<Stream<K>>
Up to limit keys whose availableAt is in (since, asOf] — keys that crossed the born threshold since the caller's last sweep watermark. Ascending-availableAt order; asOf defaults to now.
put(K key, V value, {bool skipCommit = false}) → Future<int?>
Associates value with key. If a mapping already exists, the old value is replaced.
inherited
putAll(K key, V value, T metadata) → Future<int?>
Writes value and metadata for key atomically. Returns the commit-log sequence number assigned to this write, or null if no sequence number was produced.
putMeta(K key, T metadata) → Future<int?>
Updates the metadata for key without touching its value. Returns the commit-log sequence number assigned to this write, or null if no sequence number was produced.
queryByPath({required KeyPattern keyPattern, required Predicate predicate, OrderByKey? orderBy, int? limit, int? skip}) → Stream<KeyEntry<K, V, T>>
Stream every (key, value, metadata) entry matching keyPattern AND predicate. The predicate is evaluated against the value's JSON-shaped fields.
remove(K key, {bool skipCommit = false}) → Future<int?>
Removes the mapping for key if present.
inherited
removeMany(List<K> keys, {bool skipCommit = false}) → Future<int>
Bulk delete — removes every key in keys. Returns the count of keys actually removed (race-tolerant: input keys may already have been deleted).
inherited
scanKeys(KeyPattern pattern, {bool includeExpired = false, OrderByKey? orderBy, int? limit, int? skip}) → Future<Stream<String>>
Stream the keystore keys that match pattern. Backend- portable successor to KeyValueStore.getKeys for callers that want structured filtering rather than building regular expressions.
snapshot() → Future<AtKeyValueStoreSnapshot<K, V, T>>
Take a snapshot of the keystore's current state. Overrides KeyValueStore.snapshot with the atKey-aware snapshot type that surfaces AtKeyValueStoreSnapshot.scanKeys.
override
stats() → Future<KeyStoreStats>
Diagnostic snapshot of the keystore's state — total counts, TTL/TTB key counts, approximate size, oldest/newest timestamps. Intended for operator dashboards, not for runtime decisions on a hot path.
inherited
toString() → String
A string representation of this object.
inherited
transaction<R>(Future<R> body(KeyStoreTxn<K, V, dynamic> txn)) → Future<R>
Run body as a transaction. Mutations performed via the supplied handle are buffered in memory and applied in body order on successful completion; if the body throws, the buffer is dropped and the exception propagates.
inherited

Operators

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