SqliteAtKeyValueStore class

SQLite-backed AtKeyValueStore — the main keystore (at_data table).

Mirrors the Hive keystore's semantics (metadata-builder-on-write, commit-op selection, TTL/TTB visibility, skipCommit purge) while answering expiry / availability from indexed columns rather than an in-memory cache, and lighting up the SQL-only capabilities (supportsSnapshots / supportsPathQueries / true transactions).

Implemented types

• AtKeyValueStore<String, AtData, AtMetaData?>

Constructors

SqliteAtKeyValueStore(SqliteDatabase _db, String atSign)

Properties

atSign → String

The atSign owning this store — the createdBy/updatedBy audit value the metadata builder stamps.

final

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 setter, override

commitLog ↔ AtCommitLog?

The commit log for this keystore, or null if this is an un-synced (client-side) keystore.

getter/setter pair, override

hashCode → int

The hash code for this object.

no setter, inherited

postRemoveHooks → List<Future<void> Function(String 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.

final

preRemoveHooks → List<Future<void> Function(String 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.

final

runtimeType → Type

A representation of the runtime type of the object.

no setter, inherited

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, override

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 setter, override

Methods

clear() → Future<void>

Drops all rows (keeping the connection open) for test isolation.

close() → Future<void>

No-op: the shared connection is closed by the bundle.

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(String key, AtData 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).

override

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.

override

exists(String 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.

override

get(String key) → Future<AtData?>

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.

override

getExpiredKeys() → Future<Stream<String>>

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.

override

getKeys({String? regex}) → Future<Stream<String>>

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.

override

getMany(List<String> keys) → Future<Map<String, AtData>>

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.

override

getMeta(String key) → Future<AtMetaData?>

Returns the metadata associated with key.

override

initialize() → Future<void>

Subclasses should put any necessary post-construction async initialization in this method.

override

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.

override

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.

override

noSuchMethod(Invocation invocation) → dynamic

Invoked when a nonexistent method or property is accessed.

inherited

peekExpired({DateTime? asOf, int? limit}) → Future<Stream<String>>

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.

override

peekNewlyAvailable({required DateTime since, DateTime? asOf, int? limit}) → Future<Stream<String>>

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.

override

put(String key, AtData value, {bool skipCommit = false}) → Future<int?>

Associates value with key. If a mapping already exists, the old value is replaced.

override

putAll(String key, AtData value, AtMetaData? 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.

override

putMeta(String key, AtMetaData? 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.

override

queryByPath({required KeyPattern keyPattern, required Predicate predicate, OrderByKey? orderBy, int? limit, int? skip}) → Stream<KeyEntry<String, AtData, AtMetaData?>>

Stream every (key, value, metadata) entry matching keyPattern AND predicate. The predicate is evaluated against the value's JSON-shaped fields.

override

remove(String key, {bool skipCommit = false}) → Future<int?>

Removes the mapping for key if present.

override

removeMany(List<String> 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).

override

restore(String key, AtData value) → Future<void>

Write value for key verbatim — no AtMetadataBuilder pass, no version/updatedAt mutation, no commit-log append, no change-event. The stored record is byte-for-byte what value carries (its data and its metadata).

override

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.

override

snapshot() → Future<AtKeyValueStoreSnapshot<String, AtData, AtMetaData?>>

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.

override

toString() → String

A string representation of this object.

inherited

transaction<R>(Future<R> body(KeyStoreTxn<String, AtData, 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.

override

Operators

operator ==(Object other) → bool

The equality operator.

inherited

Constants

maxKeyLength → const int

maxKeyLengthWithoutCached → const int