HiveAtKeyValueStore class
Properties
-
atSign
→ String
-
The atSign this keystore serves. Used for the per-atSign Hive
box name and as the audit value on
AtMetaData.createdBy /
updatedBy.
final
-
availableAt
→ String
-
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 setteroverride
-
commitLog
↔ AtCommitLog?
-
The commit log for this keystore, or
null if this is an
un-synced (client-side) keystore.
getter/setter pairoverride
-
expiresAt
→ String
-
final
-
hashCode
→ int
-
The hash code for this object.
no setterinherited
-
logger
→ AtSignLogger
-
final
-
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.
getter/setter pairoverride-getter
-
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.
getter/setter pairoverride-getter
-
runtimeType
→ Type
-
A representation of the runtime type of the object.
no setterinherited
-
storagePath
↔ String
-
getter/setter pairinherited
-
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 setteroverride
-
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 setteroverride
Methods
-
clear()
→ Future<void>
-
Drop every entry from the underlying box AND from the
in-memory caches (
_expiryKeysCache). Used by
AtPersistenceBundle.clear for cheap test isolation —
production code uses close instead.
-
close()
→ Future<void>
-
inherited
-
compact(bool dryRun)
→ Stream<int>
-
Compact this keystore by delegating to the internal commit
log's HiveAtCommitLog.compact. The keystore itself doesn't
have its own compaction algorithm — the commit log is the
thing that accumulates entries faster than it can shed them.
override
-
create(String key, AtData value, {bool skipCommit = false})
→ Future<int?>
-
hive does not support directly storing emoji characters, therefore keys
are encoded in
HiveKeyStoreHelper.prepareKey using utf7 before storing.
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 key exists in HiveAtKeyValueStore. false otherwise.
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
-
getBox()
→ BoxBase
-
inherited
-
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
-
getExpiryKeysCache()
→ HashMap<String, Map<String, DateTime?>>
-
-
getKeys({String? regex})
→ Future<Stream<String>>
-
Returns list of keys from the secondary storage.
@param - regex : Optional parameter to filter keys on regular expression.
@return -
List<String> : List of keys from secondary storage.
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
-
getSize()
→ int
-
Size of this store's on-disk footprint, in KB. Sums the lengths
of every file under
storagePath whose name starts with the
box name (Hive writes <boxName>.hive and <boxName>.lock).
The previous impl summed the WHOLE storagePath directory,
which double-counts whenever multiple boxes share a directory
(which they do on the secondary).
inherited
-
getValue(dynamic key)
→ Future<AtData?>
-
inherited
-
init(String storagePath, {bool isLazy = true})
→ Future<void>
-
inherited
-
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
-
openBox(String boxName, {List<int>? hiveSecret})
→ Future<void>
-
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?>
-
hive does not support directly storing emoji characters, therefore keys
are encoded in
HiveKeyStoreHelper.prepareKey using utf7 before storing.
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?>
-
Returns an integer if the key to be deleted is present in keystore or cache.
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
-
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, AtMetaData?> 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
