fespalier-data
How fespalier routes load data — data.dart and its three forms (a function, a selector of a provider you already have, or a provider you write), how segments and query parameters key the provider, loa
SKILL.mdskills/fespalier-data/SKILL.md
GitHubfespalier-data
Verified against fespalier
589cf391(2026-10-08), release v0.13.0. These skills ship in the fespalier repository, and CI checks them against its code on every change. Version-sensitive claims say the release they became true in; if your app pins another fespalier, trust that release's code over this page. See Versions.
data.dart is what a route loads. Beside a page.dart it feeds that page: the
page is only built once the data has arrived, loading.dart shows meanwhile
and error.dart if it fails. Everything is Riverpod 3 underneath
(package:fespalier/fespalier.dart re-exports hooks_riverpod).
Pick a form
| You have | Write |
|---|---|
| Nothing yet; the fetch belongs to this route | Future<Product> data(Ref ref, {required int id}) => fetchProduct(id); |
| A provider already (often riverpod_generator's) | ProviderListenable<AsyncValue<Product>> data({required int id}) => productProvider(id); |
A notifier, keepAlive or retry: of your own |
final data = AsyncNotifierProvider<MyNotifier, Product>(MyNotifier.new); (type arguments spelled out) |
Do not wrap a provider you have in ref.watch(p(id).future) inside a
function-form data(): a second provider in front of the real one drops the
error the real provider holds while it retries, so error.dart cannot show during
the retry window. Use the selector. Details, errors and samples that compile:
references/data-forms.md.
Keys
The route exposes its data as XRoute.data, keyed by the segments and query
parameters data.dart uses: no keys gives a plain provider, one key a
.family<T, int> (ProductRoute.data(42)), several a record
(ItemRoute.data((shop: 'a', id: 1))). A List query parameter is keyed by a
QueryList (value equality); a catch-all by its encoded path; an enum by the
enum. A provider you write can be keyed by segments only.
A parameter of data() that is neither a segment nor an optional nullable query
parameter is an error naming it; the types must agree with every other file that
asks for the same segment.
Loading, errors and reloads
loading.dartanderror.dartare inherited by every folder below, nearest wins, and can ask for the route's segments and query parameters (error.dartalso forerror,stackTrace,retry). Without any:DefaultLoadingandDefaultError.keep_previous: true(default):loading.dartis only for the first load; a reload keeps rendering the old value or error.false: loading shows on every load.data_retry: inherit(default): generated providers set no retry of their own, so Riverpod 3's automatic retry (10 attempts with backoff) or yourProviderScope(retry:)applies; during the retry windowerror.dartstays up.none: a failure is final untilerror.dart'sretryruns it again. A selector or a provider you write ignoresdata_retry.
references/loading-error-retry.md has the mechanics and the test behaviour.
Sections
A folder with a layout.dart and no page.dart can have a data.dart: the
data of the whole section. The layout waits for it (nearest loading.dart
replaces layout and pages meanwhile), and the layout and pages below take it
by type or as a parameter called data. data() runs once however many
take it. A typed handle (TeamsTeamIdSection.watch/read/prefetch/refresh/data)
is generated for it. Two data.dart files yielding the same type for one
parameter are an error: name the parameter data (the nearest) or change a type.
See references/sections.md.
Freshness and the cache (since 0.8.1)
Opt in, per data.dart or per folder; an app that declares neither generates what 0.7.0 did.
const freshness = Freshness(staleTime: Duration(minutes: 1), refetchOnResume: true); // data.dart or route.dart
final dataCache = DataCache<Product>.json(toJson: (p) => p.toJson(), fromJson: (j) => Product.fromJson(j! as Map<String, Object?>)); // data.dart only
| Rule | What it means |
|---|---|
| Where | freshness in a data.dart (that data) or a route.dart (every function-form data() at and below; the nearest wins, a data.dart's own wins over all). dataCache in a data.dart only |
| Which forms | The function form (Future<T>, FutureOr<T> or T). A Stream, a selector and a provider form are errors; a route.dart default skips them silently |
| Stale | In memory for staleTime since it arrived. Loading and error values are never stale. Nothing polls |
| What loads a stale value | A read: a new listener (a page opening, SectionView, prefetch/preload, read), a listener coming back (page uncovered, tab shown), or a resume/reconnect signal |
| What it shows meanwhile | The stale value at once, then the new one (keep_previous decides if loading.dart shows) |
refetchOnResume / refetchOnReconnect |
Signals (appResumeSignal, reconnectSignal); threshold staleTime ?? Duration.zero. reconnectSignal never fires by itself: override it or call fire() fespalier_connectivity (0.9.0) is that signal: reconnectSignal.overrideWith(ConnectivitySignal.new) |
| A failed reload | Keeps the page on its data (keepDataOnError: true on the DataView); error.dart only when there is nothing to show, or when the error is a DataRefusal (since 0.13.1) |
An invalidation (ref.invalidate, refresh, an action's invalidates) |
Loads at once, whatever the staleTime: it is not a read |
dataCache |
Saved only if the app overrides dataCacheStorage (null by default). MemoryDataStorage for tests and the web; a Storage<String, String> on disk to survive a restart: fespalier_storage (0.9.0), PrefsDataStorage or HiveDataStorage, first frame, size budget |
Gotchas: every new reader counts (a small staleTime reloads a section each time a page below it opens);
read returns what is in memory even if stale (refresh waits for the network); keepFor is how long a
handle holds a value, not freshness; a failed user refresh() is hidden behind the old page; a cold start
always loads again; a failed load never deletes the saved value; freshness and dataCache are names fsp
now reads in a data.dart (a public variable of that name and another type is an error: rename it).
references/freshness-and-cache.md has the samples that compile, the
reconnect signal, the storage, the key format and the tests. references/reconnect-and-network.md (since 0.9.0) is fespalier_connectivity: the
reconnect signal, hasNetwork and an offline banner, connectivity versus reachability, a reachability recipe, and tests with
FakeConnectivity. references/storage-backends.md
(since 0.9.0) is fespalier_storage: choosing Prefs or Hive, the budget and eviction, versioning, corrupt entries, sign-out, the web's
quota, and a restart test that compiles.
A Rust core that says what changed (since 0.13.0). fespalier_frb: ChangeFeed(open) holds the core's change stream in
one keep-alive subscription, feed.topic<K>(matches)(key) is a provider whose value moves only on a matching event, and a
data.dart that does ref.watch(orderChanged(id)) is rebuilt exactly then: no listener, no timer, no invalidate in the code
that holds the stream. InvalidationTable is the pure form for an app that owns its subscription
(table.apply(event, container.invalidate)). It has no flutter_rust_bridge dependency (the bindings pin their own runtime):
do not add one. Starting the core is the app's, not an adapter's: Future<void> startup() => initRustCore(RustLib.init);, and
ready(container) for what must run on the container after it. Equal events are two changes (Change.seq), events fed together
are one rebuild, and since 0.21.0 an event costs a key it does not concern one matcher call and no rebuild; a debounce in the
package would be a timer, so a busy key gets ChangeBudget(tick), one move per tick of a provider the app fires. references/change-feeds.md has the samples that compile,
startup() versus ready(), the tests with FakeChangeSource, and (since 0.18.0) ChangeCodec: a core that sends raw messages (JSON or bytes, one event or a batch each) is decoded in open with raw.transform(codec), and a message or item that does not decode, or whose decoder throws UnknownChange, is skipped, counted and never numbered while the feed goes on. Since 0.21.0 it also has what a busy core costs (a reload per event, a slow data() that never settles, a burst taken one event per turn) and ChangeBudget, with a test that fires the tick by hand.
State that belongs to one page on a navigator (since 0.13.0). A data.dart is keyed by the location, so /c/1 is one
provider however often it is shown. fespalier_riverpod keys a provider by the page instance instead: PageInstance<R>
is core's pageInstanceId (the same string as RouteScope.id) plus the typed route, equal by id only, so /c/1 pushed
twice is two states while /c/1?q=2 and a remount are one. pageProvider / pageNotifierProvider are auto-dispose
families keyed by it, PageInstance.of(context, ChatRoute.of) (or usePageInstance(ChatRoute.of)) is the page's key,
PageInstance.ofScope(scope, route) the same key from an observe.dart, and holdForPage(scope, provider) (scope.hold
by another name) keeps state the page reads but does not watch, or that must outlive its widgets, until the page leaves (a
parked tab that watches keeps its state anyway; onEnter fires when the page first becomes top). The family keeps
the route it was first made with: what follows the query is data.dart's. Nothing here survives a restart.
references/page-providers.md has the samples that compile and the tests.
Typed helpers, prefetch, lookup
ProductRoute.watch(ref, id: 42); // static: AsyncValue<Product>, in build()
await ProductRoute.read(ref, id: 42); // static: Future<Product>, in callbacks
final warm = ProductRoute(id: 42).prefetch(ref); // PrefetchHandle: kept until close()
final all = ProductRoute(id: 42).preload(ref); // 0.5.0: the page's whole data, sections included
final byUri = AppRoutes.preload(ref, Uri.parse('/products/42')); // 0.5.0: the same from a location
await ProductRoute(id: 42).refresh(ref);
AppRoutes.dataAt(Uri.parse('/products/42')); // [ProductRoute.data(42)]; null if no route fits
AppRoutes.match(Uri.parse('/products/42')); // RouteMatch: info, parsed params, typed route, data
prefetchholds until youclose()the handle (0.3.0 changed this from a 30 s lapse;prefetchKeepAliveis gone).keepFor:auto-closes;Duration.zerokeeps nothing; a failed load closes its own handle.preload(0.5.0) isprefetchfor everything the page reads: the data of each section above it, then its own, behind one handle, never navigating and never running a guard.RouteLink(preload: ...)calls it for you (fespalier-routing, its links page); a link whose page still showsloading.dartafter a hover usually hasPreload.none(the default) or auri:withoutRouteLinkScope(match: AppRoutes.matchUrl).dataAtis outermost first (sections, then the route) and isnullfor an unknown location or an unparsable segment; no guard runs and no widget is built.watch/readare static because an instance member would have to name your data type in the generated file. Do not callreadfrombuild.
references/prefetch-and-lookup.md covers
these, prefetchAll, RouteMatch (fespalier hides go_router's own
RouteMatch) and Riverpod overrides.
Writes: action.dart (since 0.5.0)
action.dart is the write side of a route: Future<Refund> action(Ref ref, {required int id, required RefundInput input}), beside the page.dart (or, in a page-less
folder, beside the layout.dart of a section). Segments and query parameters bind as in
data.dart; the one other parameter is a named, required input, of any type.
final refund = RefundRoute.useAction(ref, id: id); // build(): state, isPending, hasError, call(input)
await RefundRoute.submit(ref, id: 1, input: input); // a callback or a test: the result, or it throws
- State is a generated Notifier family (
RefundRoute.action(1)):AsyncValue<T?>,AsyncData(null)when idle. It works without a widget, in aProviderContainer. - A failed write shows in
state, noterror.dart, and is never retried. The handle'scallnever throws;submitdoes. - After a success the route's own
data.dartand the sections' above it are invalidated, or whatconst invalidates = [OrderRoute, ...]lists (typed route and section names, not providers; it replaces the default set;<Object>[]for none). The action has to take the keys of what it invalidates. - Any number of actions per file, each a public function with a
Reffirst; a function not calledactionnames its helpers after itself (approve,useApprove). A sync action stays sync. - Navigation after success is the caller's; check
context.mountedafter theawait.
references/actions.md has the rules, the generated members,
what is invalidated and a test that compiles.
Forms and optimistic updates (since 0.8.1; forms are fespalier_forms since 0.11.0)
Not a file kind: form(), validate() and optimistic() are companion functions in the
action.dart of their action (approveForm, approveValidate, approveOptimistic beside
approve), and never actions themselves. form() needs the fespalier_forms package (since
0.11.0): list it under dependencies: at the same git url and ref as fespalier, or fsp
reports an error at the form(); the generated file imports it only in an app with a form.
FieldErrors, validate() and optimistic() stay in fespalier.
typedef NicknameFields = ({String nickname, bool newsletter}); // the input: a record, named fields
NicknameFields form(Profile profile) => (nickname: profile.nickname, newsletter: profile.newsletter);
FieldErrors? validate(NicknameFields input) => FieldErrors({if (input.nickname.isEmpty) 'nickname': 'Enter a nickname'});
Profile optimistic(Profile current, NicknameFields input) => Profile(input.nickname, input.newsletter);
// page (a HookConsumerWidget): final form = NicknameRoute.useForm(ref, data: profile);
The input is a record with named fields, inline or a
typedefin the sameaction.dartor, since 0.21.0, in a file of your package that it imports.useFormgivesform.fields.nickname.controller/.value/.error,onSubmit(null while the action runs),isPending,isDirty,error,reset(). It is a real hook: only in aHookConsumerWidget.data:is the data the page got.validate()runs in the form and in the action's provider, before the action: a refused input never starts the write. The action throwsFieldErrors({'field': 'message'})for what only the server knows; keys are the record's field names.optimistic()patches thedata.dartthe action invalidates whose type isT: shown from the start of the write, removed on failure, kept over the old value after a success until the data has loaded again (no frame of the old value,keep_previous: falsetoo).XRoute.data,readandrefreshstay the server's value.Fields the user has not changed follow new data; changed ones keep what was typed.
Drafts (since 0.11.0), opt-in:
useForm(ref, data: p, draft: const FormDraft(exclude: {'password'}))keeps what changed per route (written when the page is disposed and when the app goes to the background, restored when the form starts, deleted by a success orreset()) informDraftStorage(yourdataCacheStorageby default), scoped byformDraftScope;clearFormDraftsat sign-out.Leaving with unsaved changes (since 0.11.0): a
leave.dartthat isleaveIfClean(context, ref, page)asks when a form has changed, in a bottom sheet: "Keep editing", "Discard" and, for a form with adraft:, "Keep as draft". The form registers itself as the page'sLeaveSource;leavePromptis the app's question (override it on material_ui);LeavePrompts.answer(choice)is the test's.Multi-page forms (since 0.11.0): a section whose
action.darthasconst steps(step folder to the fields it asks for) is one form over several pages with one draft:SignupSection.useFlow(ref)in the layout (inside aFormFlowScope),flowOf(context)in a step,flow.next(context)checking that step's fields only,back,goTo,progress, server errors sent to the step that owns the field, aguard.dartcallingresume(ref, uri:), and oneleave.dartbeside the layout asked once when the flow is left.
references/forms.md (the package, form() and useForm, fields, submit and
errors, drafts, a sample that compiles with its test),
references/flows.md (multi-page forms) and
references/optimistic.md (validate(), FieldErrors and optimistic())
have every rule.
HTTP clients: fespalier_http and fespalier_dio (since 0.9.0, split in 0.15.0)
The core has no HTTP client. package:fespalier_dio (Dio) and, since 0.15.0, package:fespalier_http
(package:http; on 0.14.0 and earlier it was package:fespalier_dio/http.dart, removed in 0.15.0, not
deprecated: change the import to package:fespalier_http/fespalier_http.dart), repository dependencies next to
fespalier with the same url and ref, make the two clients keep three promises. They change no generated code,
file kind, key or command, and start no timer.
final cancel = ref.cancelToken(); // Dio, in a data.dart: before the first await
final client = ref.abortable(ref.watch(httpClient)); // package:http: every request of the build
await ref.read(dio).put<Object?>('/me', data: body).withFieldErrors(); // in an action.dart
WriteGuard.install(dio); // the last call on the Dio: it goes first
- A load whose page is gone stops.
ref.cancelToken(),ref.abortTrigger()andref.abortable(client)fire inref.onDispose: on dispose and before a rebuild. Ask before the firstawait: on a stalerefthe token comes back already cancelled. The request fails after its provider is gone (DioExceptionof typecancel, whoseerrorisfespalier_dio: the provider that started this request was disposed;RequestAbortedExceptionforpackage:http), so telemetry showsdisposed, never an error. - A server's validation error is the form's
FieldErrors..withFieldErrors()is an extension on the action'sFuture, not an interceptor (an interceptor can only reject with aDioException, and a form reads aFieldErrors). For 400 and 422 it reads RFC 9457 and 7807, ASP.NET Core, Laravel and Rails, Spring, JSON:API, FastAPI and Django REST framework, with the first message per field.fieldName:maps the server's names to the record's (FieldNames.camelCasechanges case only:nick_nameisnickName, notnickname). A 422 with only adetailormessageisform.error; a 400 like that is never converted (it is a bug, let it reach Sentry). Anything else rethrows the same error. - A write is never sent twice.
dio_smart_retryandRetryClientretry writes by default.WriteGuard.install(dio)puts a guard first that refuses a second send of a write (any method butGET,HEAD,OPTIONS,TRACE, unless it has anIdempotency-Keyheader orextra[WriteGuard.idempotent]) and returns the first error, except after a 401 (an auth refresh);HttpWrites.isWriteis that one rule for both clients (since 0.15.0).WriteGuard.readsOnly(evaluator)keeps the retrier from trying. Forpackage:http, putWriteGuardClient(inner)inside theRetryClientand pass itwhen: WriteGuardClient.readsOnly()andwhenError: WriteGuardClient.readErrorsOnly(rule). A retrier before the guard givesWriteNotRetried. - Keep one retry layer: Riverpod's data retry and an HTTP retrier multiply each other's attempts.
- The layers, outside in (since 0.15.0, proved by a test):
ref.abortable(...), thenSessionClient(authorizer, inner: RetryClient(WriteGuardClient(client), ...)). A retrier outside the session sends the session a streamed copy that it will not send again after a 401, so use it only for DPoP. Anyhttp.Clientfits the seam,DioHttpClient(dio)(package:fespalier_dio/client.dart) included;HttpCredentials(Authorizerimplements it) is the session for a transfer that is not anhttp.Client. Do not claimcupertino_httphonours an abort: it is unchecked. - Not in it: a retry policy of its own (a backoff needs a timer), logging, tracing (use
otel_dioorsentry_dio).
references/http.md has the samples that compile and every rule; its tests are in
fespalier-testing (its http.md), its messages in
fespalier-troubleshooting (its diagnostics-errors-and-http.md).
Offline-first and CrateStack (since 0.10.0)
package:fespalier_cratestack (a repository dependency next to fespalier, same url and ref) adds a second way to
make a read survive without a network, and a queue for writes. It changes no generated code, file kind, key or
command. It is two skills of its own: fespalier-offline (the ideas and the API) and
fespalier-cratestack (wiring a CrateStack client).
dataCacheorref.serve, never both.dataCache(since 0.8.1) saves a route's value under its key and shows it while the network is slow or away;ref.serve(key:, codec:, fetch:)saves an account's answer and returns aServed<T>that says where the value came from (networkorlocal) and when (fetchedAt), so the page can write "offline copy, as of 10:42".servekeeps its own copy, per account, in aLocalStoreor aReadCache: do not putdataCacheover it.freshnessstill decides when a read runs again;servedecides where the answer comes from.- The page type is
Served<T>, the typedata()returns, or atypedefof it in your own files (since 0.21.0) (FutureOr<Served<List<Order>>>is matched asServed<List<Order>>):fspmatches by type, through the typedefs of your files and otherwise syntactically. - Only a connection failure falls back to the device; a refusal goes to
error.dartlike any error. A single row with nothing saved isCrateStackNoLocalData; a list saysneverFetched. - A write that is the server's decision is an intent (
ref.read(intentQueue).submit(...)in anaction.dart): it returnsAcceptedorQueued, never a success the server has not given.
Models, collections, validation and results (since 0.17.0)
fespalier depends on none of freezed, dart_mappable, fast_immutable_collections, acanthis, luthor,
result_dart or fpdart, and fsp does not read them: they meet it in the value data() returns (Riverpod 3 filters
updates by ==), an extra (freezed's factory syntax is a private _Note: ExtraCodec.of), DataCache.json
(dart_mappable's toJson() is a String: pass toMap), an action's record input, validate() and the failures
data() and action() throw.
- Pick by Dart: freezed 4.0.2 needs Dart 3.13 (Flutter 3.47), freezed 3.2.5 covers Dart 3.8 and up, dart_mappable 4.10 needs 3.7; acanthis 2 needs Dart 3.13 (1.x, a different API, below it).
- A selected
Listfield notifies on every reload, equal or not; anIListfrom fast_immutable_collections 12 does not (measured, with a test that builds). validate()stays a plain function; a schema library is an adapter inside it. Unwrap a result indata()(getOrThrow(), or fpdart'sgetOrElse((l) => throw l)), soerror.dartcan switch on the sealed failure.- A model class is not a form's
input(a record is), andbuild_runnercan deletelib/app.g.dart(fespalier-troubleshooting, its flutter-pitfalls page).
references/models-and-libraries.md has the samples that compile, the
primary-constructor note and what is not built.
Seeing it in DevTools (since 0.7.0)
The fespalier tab's Data tab lists each provider fespalier makes from a data.dart: its state
(loading, data, error, stream, disposed), builds, listeners, key and value, with an Invalidate
button and, since 0.8.1, a Holders button that lists who keeps the provider (the page, a section, a
prefetch / preload handle, a RouteLink preload) and counts the other listeners. Actions lists the
runs of the action.dart functions. The generated provider body is wrapped in traceData, which returns the
function's own result (a value stays a value, a Future stays the Future), and every view watches with
watchData(ref, 'dProductsId', provider), which is ref.watch. A data.dart that returns or selects a provider is
followed since 0.8.1 as an app provider, through the state the views got; its other listeners are not
visible (fespalier-troubleshooting, its DevTools page).
Examples
Read these before inventing a pattern; each compiles and has widget tests
(the fespalier skill lists them all).
examples/features: adata.dartkeyed by a segment (catalog/$productId), ateams/$teamIdsection with itsdata.dartandaction.dart(an optimisticaddMember), forms onaction.dart, aStreaminticks/data.dart, and the cache and reconnect pair (test/offline_test.dart,test/freshness_test.dart).examples/shop:products/$id/data.dartwitherror.dartand Retry, andtest/refresh_test.dart.examples/auth: twodata.dartfiles (orders/andorders/$id/) that share one token refresh.
Common symptoms
| Symptom | Look at |
|---|---|
Page blinks to loading.dart on every reload |
keep_previous: false in pubspec.yaml (the default is true) |
A failing data.dart runs several times in a test |
Default data_retry: inherit; pumpRouter already disables retries (fespalier-testing) |
error.dart never shows during a retry |
A function-form data() wrapping .future of your provider: use a selector |
refresh/retry throws a StateError |
A selector that returns .select(...) of a provider: return the provider itself |
| A prefetched page still loads | The handle was closed, or the id/query differs from the key the page uses |
dataAt is null for a URL that works in the app |
The segment fails to parse, or the URL is outside the mount prefix |
| A page doesn't refresh after a write | The data is another route's: list it in invalidates (references/actions.md) |
| A stale value stays on screen | Nothing read it: freshness loads on a read, a resume or a reconnect, never by a timer (references/freshness-and-cache.md) |
Offline start shows error.dart |
No dataCache/dataCacheStorage, or nothing was saved yet or it passed maxAge |
| A saved value is not on the first frame (0.9.0) | open() was not awaited in startup(), a Future was passed (one loading.dart frame), or in a test no fakePrefsStore() |
refetchOnReconnect never reloads (0.9.0) |
startup() does not override reconnectSignal (ConnectivitySignal.new), or the value is younger than its staleTime, or the network went Wi-Fi to mobile (not a reconnect) |
| An offline banner stays up after the network came back (0.9.0) | A hand-written signal that never asks again on a resume (iOS drops background events): use fespalier_connectivity |
| The form forgot what I typed (0.8.1) | The data loaded again while the fields were untouched: only fields the user changed are kept |
| The page flashes the old value after a save | optimistic() patches another type than the page shows, or the data is not in invalidates |
| A request outlives its page (0.9.0) | fespalier_dio or fespalier_http: the token was asked after an await, or not given to the request (references/http.md) |
| A 422 is not under its field (0.9.0) | fespalier_dio or fespalier_http: withFieldErrors() is missing or found no field: statuses, decoder, names (references/http.md) |
A write is retried, or WriteNotRetried (0.9.0) |
WriteGuard is not first (WriteGuard.install(dio) last), or the retrier has no readsOnly (references/http.md) |
| Another account's data shows offline (0.10.0) | Impossible by design: every serve answer, intent and row is keyed by crateStackScope. A copy that did show means the scope is not the signed-in user (fespalier-offline) |
| A queued write never sends (0.10.0) | fespalier_cratestack: nothing watches autoSync, no trigger runs, or the intent is another account's (fespalier-troubleshooting, its diagnostics-cratestack.md) |
| A CrateStack read is cancelled with another page (0.10.0) | A provider is built inside ref.cancellable(...): read and watch others before it, and keep the body to the client call (fespalier-cratestack) |
An fsp error on data.dart or action.dart |
fespalier-troubleshooting |