0020. The data layer is objects with reactive properties, named as in the brief
- Status: Accepted (Mik, 17 Nov 2026)
- Date: 2026-11-14
- Decided by: Mik
- Planning item: D23
Context
The WP8 brief asks for resource, action, stream, pagedList, api and environment, plus validation and list helpers. Pages compile so that only variables declared with state(...) are rewritten to .value access (0012); anything else is an ordinary object. The glossary (spec/glossary.yaml) lists resource as a word to avoid: its state is "a reactive value, which may hold a value or load one".
Decision
- Each function returns a plain object whose properties are getters over state cells:
feed.data,feed.loading,like.pending,updates.latest. Reading one inside a binding subscribes that binding, so no compiler support is needed and nothing re-renders except what reads the property. Settable properties (field.value,listView.query) are setters, so markup assigns them like variables. - The names are the brief's:
resource,action,stream,pagedList,api,environment,field,form,listView,network.resourceconflicts with the glossary. We propose either adding resource to the glossary as "state that loads, cached by key" or renaming it to a form ofstate(for examplestate.load(key, loader)) in Specification v0; the code change is one export. run()on an action never throws: failures land inerror, because a page calls it from an event handler with notry, and an unhandled rejection would be the only symptom.- A request made while offline fails at once with
ApiErrorkindoffline, andnetwork.pretendOffline()makes the whole layer behave offline, so offline behaviour can be shown and tested without unplugging anything. - Until conditionals exist, docs and examples show a part of a screen only sometimes with a list of zero or one item:
<list each={feed.error ? [feed.errorMessage] : []} as="message">.
Alternatives considered
| Option | Why not |
|---|---|
Return state cells and have the compiler rewrite feed.data | Needs a compiler change for every API, and the analyzer would have to know each function |
run() rejects on failure | Every handler would need catch, and forgetting it logs an error with no screen feedback |
Name everything with state now | The brief and the plan use these names; the rename is cheap once Specification v0 decides |
Consequences
The data APIs work in today's pages with no compiler change. The glossary question must be settled before the names are marked stable. Pages written against these names will follow whatever rename is chosen.
What Mik decided (17 Nov 2026)
Mik chose the rename: state that loads is **state.load(key, loader, options)**, and resource is no longer a name in @duolith/client. The glossary gains loaded state (state that loads, cached by key), with resource among its words to avoid; state keeps resource on its own list.
loadis a property of thestatefunction, put there bydata/load.tssostate.tsdoes not depend on the data layer. The compiler still recognises onlystate(...)as a state declaration, soconst feed = state.load(...)is an ordinary constant, read in markup by its fields as before.- The types are renamed with it:
ResourceisLoadedState,ResourceOptionsisLoadedStateOptionsandResourceStateisLoadedStatus.@duolith/testingmocks loaded state withrender(path, { loads: { posts } }). duolith upgrademoves existing pages with the migrationresource-is-state-load(edition 0.2): it follows what the name refers to, importsstatein place ofresource(or uses an existingstateimport's name), renames the types, and reports a script that declares its ownstateinstead of changing it.examples/upgradeshows it.