Duolith docs

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

  1. 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.
  2. The names are the brief's: resource, action, stream, pagedList, api, environment, field, form, listView, network. resource conflicts with the glossary. We propose either adding resource to the glossary as "state that loads, cached by key" or renaming it to a form of state (for example state.load(key, loader)) in Specification v0; the code change is one export.
  3. run() on an action never throws: failures land in error, because a page calls it from an event handler with no try, and an unhandled rejection would be the only symptom.
  4. A request made while offline fails at once with ApiError kind offline, and network.pretendOffline() makes the whole layer behave offline, so offline behaviour can be shown and tested without unplugging anything.
  5. 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

OptionWhy not
Return state cells and have the compiler rewrite feed.dataNeeds a compiler change for every API, and the analyzer would have to know each function
run() rejects on failureEvery handler would need catch, and forgetting it logs an error with no screen feedback
Name everything with state nowThe 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.

  • load is a property of the state function, put there by data/load.ts so state.ts does not depend on the data layer. The compiler still recognises only state(...) as a state declaration, so const feed = state.load(...) is an ordinary constant, read in markup by its fields as before.
  • The types are renamed with it: Resource is LoadedState, ResourceOptions is LoadedStateOptions and ResourceState is LoadedStatus. @duolith/testing mocks loaded state with render(path, { loads: { posts } }).
  • duolith upgrade moves existing pages with the migration resource-is-state-load (edition 0.2): it follows what the name refers to, imports state in place of resource (or uses an existing state import's name), renames the types, and reports a script that declares its own state instead of changing it. examples/upgrade shows it.