devtools library
The forge devtools: why the cache did what it did.
configureClient attaches these automatically in debug and profile
builds; import this library to register a cache built with the
QueryCache constructor, to hand the panel an OutboxInspector, or to
call the inspector from your own code.
configureClient, registerForgeServiceExtensions, unregisterForgeDevtools
and forgeDevtoolsFor check the constant kForgeDevtools and do nothing
when it is false, so a release build attaches nothing and the compiler
drops the code only they reach. The rest of this library (attach,
Devtools, ControlledTransport and the other types) is not gated: an app
that calls it directly keeps what it calls in a release build too, so guard
those calls with kForgeDevtools yourself.
Classes
- ActionLog
- The panel did something.
- CacheSnapshot
- Counters, queries and the tag graph in one read.
- CauseSummary
- What raised a set of tags, reduced to what an explanation needs.
- ControlledTransport
- Wraps a transport with switchable offline, slow and fail-next conditions.
- Devtools
- The inspector over one cache.
- DevtoolsActions
- Panel actions over one cache.
- DevtoolsInspectable
- Something the devtools extension (plan 06) can describe in a panel. The Grove sync source (plan 05) implements it with its replica clock, peers and pending counts per entity.
- EntityFilter
-
How
entitiesis narrowed and paged. The default is everything. - EntitySnapshot
- One entity record as the store holds it.
- ErrorLog
- A request failed. The message only.
- Explanation
- The answer to one of the two questions.
- FetchLog
- A request went out for a query.
- FrameCapture
- One decoded frame, captured with a bounded copy of its payload.
- FrameOptions
- Turns frame capture on. Presence is the switch; limit defaults to 200.
- FramesLog
- A batch of frames committed. A cause.
- InvalidatedLog
- A mounted query was reached by these tags.
- InvalidationPreview
- What an operation would invalidate, asked without running it.
- LogEntry
-
One recorded event.
seqis monotonic for the life of the devtools andsessioncounts identity changes. - MissCause
-
What a caller may hand
whyNotRefetchedas the thing that should have hit. - MissReport
- The answer to "why did this query not refetch".
- MutationLog
- A mutation settled, with the tags it raised. A cause.
- NearMiss
- One place the two tag sets nearly meet, and what to do about it.
- OperationCause
- An operation, resolved exactly as the invalidator would resolve it.
- OutboxInspector
-
What the devtools Outbox panel (plan 06) drives. The offline package's
OfflineClient(plan 04) implements it; declared here so it can before the devtools package exists. - OutboxLog
- A queued write moved. New in Dart.
- OverlaySnapshot
- One pending optimistic write, as a shape. Never carries what it writes.
- ParsedTag
- A tag pulled apart. A tag is just a string, so nothing here validates.
- PlacedLog
- A placement callback answered instead of a refetch.
- PrincipalLog
- The identity changed and the cache was dropped.
- QueryDetail
- One query joined across the registry and its tracked record.
- QuerySnapshot
- One query the registry remembers, mounted or not.
- RecordSnapshot
- One tracked record's cheap fields. Sized by nothing a response controls.
- RefetchReport
- The answer to "why did this query refetch".
- RequestLog
-
The request ring. Hand observer to
RestTransport, or letregisterForgeServiceExtensionswire it through the debug slot. - RequestRetry
- One retry that was taken.
- RequestSnapshot
- What one request did, reduced to what is free to keep.
- Revalidation
- The revalidation toggles. The application registers how to start each source it uses; the panel toggles them and never installs one itself.
- SettleLog
- A response settled into a query.
- StoreSnapshot
- The counters that say whether anything is leaking.
- SyncLog
- A sync source reported a status change. New in Dart.
- TagHit
- One resolved tag and the mounted queries it would reach.
- TagsCause
- Tags already resolved: a recorded cause or a hand-written hypothesis.
- TagSnapshot
- One tag and who is on either side of it.
Enums
- ActionKind
- What a panel action did. The names are the TS wire names.
- FetchReason
- Why a request went out.
- MissOutcome
- What happened to a query when a cause went past it.
- NearMissRelation
- How an invalidated tag and a carried tag are related without matching.
- NetworkMode
- The network the panel imposes.
- OutboxPhase
- What happened to a queued write.
- RequestOutcome
- Where a request is.
- RevalidationSource
- The three sources of a refetch nobody asked for.
Constants
- kForgeDevtools → const bool
- Whether the forge devtools are compiled into this build.
Functions
-
argsKey(
Object? args, {int limit = 200}) → String - A truncated argument key, so one enormous body cannot fill the ring.
-
attach(
QueryCache cache, {int limit = 500, Clock clock = realClock, int argsLimit = 200, FrameOptions? frames, RequestLog? requests, ControlledTransport? controls, Revalidation? revalidation, OutboxInspector? outbox}) → Devtools -
Starts observing
cache. Chains to an observer already in the slot and gives the slot back on Devtools.dispose if it is still ours. -
forgeDevtoolsFor(
QueryCache cache) → Devtools? -
The devtools attached to
cache, or null when none is (always null in a release build). Use it to reach the simulatorconfigureClientinstalled, for example to feedwithSimulatedConnectivity. -
nearMisses(
List< String> invalidated, List<String> carried, [int limit = 8]) → List<NearMiss> -
Every near miss between what a cause raised and what a query carries,
most suspicious first, capped at
limit. -
parseTag(
String tag) → ParsedTag - Splits a tag into typename, identity and collection-ness.
-
registerForgeServiceExtensions(
QueryCache cache, {RestTransport? transport, ControlledTransport? controls, Map< String, OperationMeta> operations = const {}, OutboxInspector? outbox, Revalidation? revalidation}) → Devtools? -
Attaches the devtools to
cacheand exposes it to Flutter DevTools. -
unregisterForgeDevtools(
QueryCache cache) → void -
Detaches the devtools from
cache, restoring its observer. -
withSimulatedConnectivity(
ConnectivitySignal real, ControlledTransport controls) → ConnectivitySignal -
A connectivity signal that is offline when either
realorcontrolsis. Feed this to anything that takes aConnectivitySignal(an outbox,revalidateOnReconnect) so the panel's offline switch behaves like a lost network.
Typedefs
- StartRevalidation = void Function() Function()
-
Starts one revalidation source and returns how to stop it: the shape
revalidateOnFocus,revalidateOnReconnectandpollalready have.
Exceptions / Errors
- SimulatedOffline
- Thrown by ControlledTransport while offline. The request was never sent.