QueryCache class final

The query cache: the entity store, the tag graph and a transport, wired.

Running a query issues the request, normalizes the response into the store, hands the registry the skeleton's dependencies, and returns the rehydrated value. The cached thing is a skeleton of references, and reads of it are memoized by the store, so a value keeps its identity for as long as the entities under it do not move.

One request per query, not one per subscriber; and a response that predates a write never settles the query it was for.

Constructors

QueryCache({required Transport transport, required EntitySchema entities, Scheduler? scheduler, CommitScheduler? commitScheduler, int limit = 128, void onError(Object error, String context)?, int frameRestarts = 3, Clock clock = realClock, Duration? staleTime, List<SyncSource> syncSources = const [], StorageAdapter? storage})
Creates a cache.

Properties

clock → Clock
The injected clock. Read only on a settle and when a finite staleTime is in play.
final
commits → Stream<void>
Fires after every store commit. Persistence listens here. Asynchronous, so a burst of commits costs listeners nothing until they run.
no setter
commitScheduler → CommitScheduler
When stream commits run. Read by plan 01b's StreamBinder.
final
entities → EntitySchema
The generated entities table this cache normalizes against.
final
generation → int
Which life of the cache this is. clear, and so every setPrincipal that changes the principal, starts a new one. A writer that captured it before an await or a batching delay and sees it differ afterwards holds data that belonged to what was dropped, and must not commit it.
no setter
hashCode → int
The hash code for this object.
no setterinherited
idle → Future<void>
Completes once every queued principal transition has finished: the old sources stopped, the old session closed and, for a principal, the next session opened and its sources started. A transition queued while waiting is waited for too. Never fails.
no setter
invalidator ↔ Invalidator
The batched invalidator.
latefinal
isDisposed → bool
Whether dispose has run. A disposed cache refuses new work.
no setter
live ↔ LiveBinding?
The stream runtime, when one was attached. Null for a REST-only app.
getter/setter pair
observer ↔ CacheObserver?
Where the cache reports what it did. Null in production.
getter/setter pair
overlays ↔ OverlayStack
Pending optimistic changes, layered over the store.
latefinal
principal → String?
Who the cached data belongs to.
no setter
principalChanges → Stream<String?>
Every identity change, after the cache has been emptied. Synchronous.
no setter
queries → Iterable<CachedQuery>
Every query that settled successfully, as dehydrate reads them.
no setter
registry → QueryRegistry
The mounted-query registry and tag index.
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
session → StorageSession?
The open storage session for the current principal. Null without storage, without a principal, or while a switch is in progress.
no setter
sessionChanges → Stream<StorageSession?>
A session each time one opens, and null each time one closes.
no setter
size → int
How many queries are tracked, watched or merely remembered.
no setter
store → EntityStore
The normalized entity store.
final

Methods

clear() → void
Drops every entity, every skeleton and every registry entry. Watched queries are reset in place and refetched.
collect() → int
Drops every entity no cached query and no pending overlay can reach. Returns how many records were dropped.
dispose() → Future<void>
Abandons every request in flight, closes every watch stream, stops every sync source, closes the session, and closes the principalChanges, commits and sessionChanges streams. The cache is unusable after.
drop(OperationMeta meta, TagContext args) → bool
Forgets one query, or resets and refetches it when somebody is watching. Returns false when nothing was tracking it.
dropKey(String cacheKey) → bool
drop by cache key. The TypeScript drop(key).
effectiveStaleTime(OperationMeta meta, TagContext args) → Duration?
The staleTime governing this query now: the strictest live subscriber's, else the operation's, else the cache default. Null when no record exists or nothing bounds it.
fetch(OperationMeta meta, TagContext args, {RequestOptions options = const RequestOptions()}) → Future<Object?>
Runs this query or joins the request already running for it. Serves the cached value without a request when the query has settled, nothing has invalidated it and it has not aged past its staleTime.
getState(OperationMeta meta, TagContext args) → QueryState<Object?>
This query's current state, opening its record if it is new. Stable across reads while nothing changes.
invalidate(Iterable<String> tags) → void
Invalidates already-resolved tags, as a stream frame or a manual refresh would.
invalidateQuery(OperationMeta meta, TagContext args) → void
Marks one query stale: its in-flight answer is discarded and, when it is watched, it refetches in the next batch.
key(OperationMeta meta, TagContext args) → String
The cache key this operation and these arguments resolve to.
mutate(OperationMeta meta, TagContext args, {MutateOptions options = const MutateOptions()}) → Future<Object?>
Runs a mutation, commits what it returned, and invalidates what it declared. The response is normalized first, so placement callbacks and refetched queries see the mutated entity.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
notifyChanged() → void
Something wrote to the store behind this cache's back: re-read every tracked query and notify the ones whose value moved. The seam the stream layer commits through.
owns(String typename) → bool
Whether a registered sync source owns typename.
peek(OperationMeta meta, TagContext args) → QueryState<Object?>?
This query's state without opening a record or moving the LRU order. Null means nothing is cached.
refetch(OperationMeta meta, TagContext args, {RequestOptions options = const RequestOptions()}) → Future<Object?>
Runs this query again whatever the cache holds.
report(Object error, String context) → void
Reports a failure through the cache's own error channel.
restore(RestoreInput input) → void
Settles a query from a skeleton, with no request behind it: the seam hydrate writes through. Merges rather than replaces, so restoring the same payload twice moves no version and changes no identity.
revalidate({bool onlyStale = true}) → int
Refetches every watched, settled query that is not already in flight, and returns how many it started. With onlyStale true (the default) only queries that aged past their staleTime are refetched. Driven by the freshness installers.
setPrincipal(String? principal) → void
Declares who the cached data belongs to, dropping everything on a change. Watched queries are re-mounted and refetched; their in-flight requests are abandoned. Every running sync source's context is fenced before anything is dropped; the sources themselves stop in the background, and idle completes once they have.
settledTimeOf(OperationMeta meta, TagContext args) → int?
When this query last settled, on clock, or null if it never has.
subscribe(OperationMeta meta, TagContext args, void listener(), {Duration? staleTime}) → void Function()
Watches a query, fetching it if there is nothing to show yet. The low level primitive watch is built on; the returned function unsubscribes.
toString() → String
A string representation of this object.
inherited
tracked() → Iterable<TrackedRecord>
Every query this cache is tracking, for an inspector. No copy, no open.
watch(OperationMeta meta, TagContext args, {bool live = false, Duration? staleTime}) → Stream<QueryState<Object?>>
Watches a query as a stream of states.
watchLive(OperationMeta meta, TagContext args) → void Function()
Subscribes this query to the channels its entities are pushed on and returns the release: the whole of what live: true does. With no stream runtime attached it reports through onError (context live) and returns a no-op, exactly as TypeScript does.
watchPrincipal(void listener(String? principal)) → void Function()
Calls listener on every identity change, after the cache has been emptied. A throwing listener is reported with the context principal.
watchPrincipalChanging(void listener(String? principal)) → void Function()
Calls listener on every identity change, synchronously, before the cache is emptied: after principal already returns the next principal, and before the clear notifies any watcher and before any watchPrincipal listener or principalChanges event. An adapter uses it to stop showing the previous principal's data before anything can observe the change.

Operators

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