foldkit-remote 0.8.0 → 0.9.0

package/README.md

@@ -283,14 +283,15 @@ what it needs, and something else decides whether to ask.
 ### 4. Let the active screen drive the fetching
 
 ```ts
+import { Option } from 'effect'
 import * as Subscription from 'foldkit/subscription'
 
 const subscriptions = Subscription.make<Model, Message, RemoteClient>()(() =>
   foldData.subscriptions({
     project: Surface.at(ProjectPage, model =>
       model.route._tag === 'project'
-        ? { projectId: model.route.projectId }
-        : undefined,
+        ? Option.some({ projectId: model.route.projectId })
+        : Option.none(),
     ),
   }),
 )
@@ -301,6 +302,21 @@ page, Remote sees its requirements, diffs them against the cache, and fetches
 only what is missing. When the page is inactive, it creates no read work. This
 is the one step that causes I/O, and it does so only while the screen is on.
 
+A read that is not a Surface's, such as the record a detail pane shows, is made
+active with `Data.active`: its function of the Model returns the read, or none
+while there is nothing to read.
+
+```ts
+const detail = Data.active('ProjectDetail', model =>
+  Option.map(model.openProjectId, id => Data.get(Project.select({ name: true }), id)),
+)
+foldData.subscriptions({ detail })
+```
+
+It belongs to the domain's application and sends no Messages. A domain bound
+to a raw optic (`ModelRef.fromOptic`) names no application, so `Data.active`
+throws for one rather than guess.
+
 ### 5. Provide a client
 
 The Subscription needs a `RemoteClient`. Before there is a server, a backend
@@ -381,7 +397,7 @@ function update(model: Model, message: Message): Update.Return<Model, Message, R
 ```
 
 The rest of this guide uses the fold. With the spread, read `Data.subscriptions`
-for `foldData.subscriptions` and `Data.fetch` for `foldData.fetch`.
+for `foldData.subscriptions` and `Data.mutate` for `foldData.mutate`.
 
 ### One value with `foldkit-bundle`: `Data.wiring`
 
@@ -395,7 +411,9 @@ const Page = Bundle.parent({ Model, Message })
 const wiring = Page.assemble(
   Data.wiring({
     project: Surface.at(ProjectPage, model =>
-      model.route._tag === 'project' ? { projectId: model.route.projectId } : undefined,
+      model.route._tag === 'project'
+        ? Option.some({ projectId: model.route.projectId })
+        : Option.none(),
     ),
   }),
 )
@@ -730,10 +748,42 @@ What Remote should do when the Model already contains the selected fields is a
 
 A refreshing policy emits `RefreshStarted` before the read, so the Projection
 becomes `Refreshing` without discarding the old value. Planning accepts `now`
-(default `Date.now`) as an input, so tests can control time.
+as an input, so tests can control time. It defaults to `Date.now`, read at each
+use, so fake timers (`vi.useFakeTimers`) move it; Effect's `TestClock` does not,
+because a plan runs outside Effect, so a test that drives `TestClock` passes
+`now`. A mutation's answer is dated the same way, by `Data.mutate`'s `now`
+option.
+
+A policy belongs to one `subscriptions` call, and covers every read in it. Reads
+under different policies take a call each:
+
+```ts
+const projectPage = Surface.at(ProjectPage, model =>
+  model.route._tag === 'project' ? Option.some({ projectId: model.route.projectId }) : Option.none(),
+)
+const owner = Data.active('Owner', () => Option.some(Data.get(UserSummary, 'u1')))
+
+const pageEntries = Data.subscriptions({ page: projectPage })
+// Retention is the domain's: one `retain` roots every read, so the second
+// call's is left out rather than spread over the first's.
+const { retain: _domainRetain, ...ownerEntries } = Data.subscriptions(
+  { owner },
+  { policy: RemotePolicy.staleWhileRevalidate({ maxAge: 5_000 }) },
+)
+
+const subscriptions = Subscription.make<Model, Message, RemoteClient>()(() => ({
+  ...pageEntries,
+  ...ownerEntries,
+}))
+```
+
+Retention stays the domain's: a call's `retain` entry roots every read any call
+of the domain names, so neither call collects what the other reads. Keeping one
+`retain` entry is all it takes; it waits for its own call's `grace`.
 
-**Time reaches Remote only as a Message.** The plan is a function of the Model
-and `now`, and it runs when the Model changes; a page that sits still past its
+**Time reaches Remote only as a Message.** The plan is a function of the Remote
+model, what is asked, and `now`, and it runs again only when one of those
+changes; a page that sits still past its
 `maxAge` would otherwise never be looked at again. So a read entry under
 `staleWhileRevalidate` knows when the earliest value it holds ages out, sleeps
 until then under the Effect clock, and emits `RefreshStarted` for what is due.
@@ -758,6 +808,24 @@ const loaded = await Effect.runPromise(
 Remote Messages reduced into it. It never changes the semantics of the
 Projection itself.
 
+A render that fetches nothing (SSR, a prerender) needs everything a page's
+active Surfaces read, and one read can decide what another asks for: a page's
+Blocks are known once its document is. `Data.satisfy` prefetches every active
+Surface, cache-first, pass after pass until a pass plans nothing:
+
+```ts
+const ready = await Effect.runPromise(
+  Data.satisfy(model, actives).pipe(Effect.provide(clientLayer)),
+)
+```
+
+`actives` is the record `Data.wiring` takes. The passes are bounded (8 by
+default, `{ passes }` to change it); a Surface still reading after the last
+fails the Effect with `RemoteUnsatisfied`, which names it, rather than
+rendering it loading. A read the server leaves unanswered settles as missing,
+so it ends the loop; what runs out the passes is a chain whose every read
+reveals one more.
+
 ### Refreshing from `update`
 
 To revalidate what a screen already declares — a refresh button, a focus
@@ -779,9 +847,9 @@ since stale data is planned again under every policy, so the page is requested
 once. The Projection must be observed, as it is while it is on screen; for data
 nothing observes, use `Data.prefetch` with `RemotePolicy.networkOnly`.
 
-- A refreshed connection's first page replaces its loaded pages, so items the
-  server removed or reordered follow it; later pages are fetched again with
-  `Data.next`.
+- A refreshed connection is asked for again as one page the size of the widest
+  window reading it (including what "load more" grew), which replaces what it
+  held, so items the server removed or reordered follow it.
 - A read already in flight restarts instead of landing after the refresh.
 - Refreshing what is already refreshing, or nothing, returns the same Model.
 
@@ -888,11 +956,10 @@ const projects = Data.query(
 )
 
 projects.read(model)
-// RemoteData<Page<ProjectSummary>>
+// RemoteData<Page<ProjectSummary>>: at most 25 items
 
-Data.next(model, projects)      // QueryRef | undefined
-Data.previous(model, projects)  // QueryRef | undefined
-Data.fetch(ref)                 // Command whose Message merges the page
+Data.more(model, projects)
+// Option<Model>: "load more", the window grown to 50; none when all are shown
 ```
 
 The connection stores entity references and explicit boundaries rather than one
@@ -901,13 +968,32 @@ Remote represents an honest gap instead of pretending the visible rows are
 adjacent.
 
 A query Projection is `Initial` until the page **and every selected field of its
-visible items** are present. Once a page lands, those items become ordinary
-entity requirements and can be fulfilled in the same planning loop.
-
-Two Projections of the same connection plan one query and select the union of
-their required fields. `Data.next` / `Data.previous` preserve the page size and
-use the loaded boundaries; `hasNext` / `hasPrevious` come from those boundaries,
-not from guessing based on row counts.
+visible items** are present. The `select` travels with the query: the server
+returns the selected fields of the page's items with the edges, and one
+`ConnectionMerged` merges the page and writes them, so a fresh list usually
+lands `Ready` in one response. What the server leaves out (withheld fields,
+nested targets it does not expand) becomes ordinary entity requirements and
+is fetched next, as before; a server that predates payloads sends edges only
+and the list reads the old two-round-trip way.
+
+**A read shows at most its window.** Remote keeps one connection per query and
+input, whatever window asks for it, so a picker's `first: 50` and a card's
+`first: 3` of the same query share the rows, and each read is cut to its own
+window: `first` from the start, `last` from the end. `hasNext` / `hasPrevious`
+are true when the read cut rows or the connection's boundary says there are
+more; they are never guessed from a row count.
+
+Two Projections of the same connection plan one query, for the wider window,
+and select the union of their fields. When a connection holds fewer rows than a
+window asks for, the read entry asks only for the rows it lacks, after the
+loaded end (or before the loaded start).
+
+**"Load more" grows the window.** `Data.more(model, projection)` is the Model
+with that read's window one page larger, called from `update`; the read entry
+then fetches what the connection lacks. It is kept in Remote's store, under the
+query, input and window first asked for, so a list holds no state of its own,
+and it is forgotten when retention drops the connection. Another window of the
+same query does not grow with it.
 
 ### Filtering a loaded list without asking the server
 
@@ -1206,6 +1292,11 @@ const back = Data.lift(previewed, 'post-preview')
   returns the same Model.
 - An overlay's id is apart from every request's, so a mutation that settles does
   not take a preview with it.
+- A preview of an entity the server has not seen, such as an unsaved post, has
+  only the fields the overlay holds. A Selection that reads more reads
+  `Failed`, with an `Overlaid` error naming what is missing, since nothing will
+  fetch it. Overlay every field the Selection reads, or preview through a
+  smaller Selection.
 
 ### Reading past what is only pending
 
@@ -1276,8 +1367,9 @@ failure Message rather than mutating anything out of band.
 Remote is a cache, so it should be allowed to forget facts no active feature
 needs.
 
-`Data.subscriptions` derives retention roots from the active Surfaces. A root
-keeps:
+`Data.subscriptions` derives retention roots from the active Surfaces of every
+call on the domain, so a call's `retain` entry never collects what another call
+reads; `connections` given to any call are kept the same way. A root keeps:
 
 - the entities and fields its Projection requires;
 - referenced targets reached by nested selections;
@@ -1428,11 +1520,17 @@ into private state:
 ```ts
 Data.inspect(model)            // serializable cache/domain summary
 Data.plan(model, projection)   // the entity plan a read would execute
+Data.meta(model, projection)   // when what is shown was received, stale/loading
 Data.explain(model, query)     // what one query read is, and currently is
 Remote.planQueries(...)        // missing/stale query work
 Remote.inspectEntity(...)      // one normalized entity
 ```
 
+`Data.meta` is for views, not debugging: `updatedAt` is the newest server
+write among what the projection shows (`undefined` when nothing shown was
+received), with `stale` and `loading` beside it, so "updated 5s ago" reads
+the Model like any other render.
+
 These are pure and useful in tests, tooling, and debugging. For a read that
 stays `Initial`, `Data.why` and `Data.plan` are the tools; see
 [Why is it still `Initial`?](#why-is-it-still-initial).
@@ -1539,8 +1637,16 @@ requirements for the concrete target.
 options.
 
 `Remote.storeOf` is the visible store after pending optimistic layers. Reads are
-memoized per visible store (and connection where applicable), so equal reads of
-one Model state assemble/decode once and return one value.
+memoized per visible store (and, for a list, its connection and overlays), so
+equal reads of one Model state assemble/decode once and return one value.
+
+Across Model states, an entity's or row's decoded value stays the same object
+while its entity's fields are equal: a refetch or live patch that brought equal
+data hands the view the value it already rendered, so a keyed row's lazy view
+does not re-run. A write to any field of the entity, even one the row does not
+select, or a pending optimistic patch on it while other writes land, gives the
+row a new value. When the store changed, the `RemoteData` around a value and a
+page's `items` array are new.
 
 `Remote.prefetch(bound, model, projection, options?)` runs the same plans
 imperatively and reduces their results into a new Model.
@@ -1549,7 +1655,10 @@ imperatively and reduces their results into a new Model.
 
 `updateRemote(remote, message)` is the pure reducer over Remote facts;
 `Data.update` applies it to a bound Remote state and `Data.reduce` applies it to
-the application Model.
+the application Model. The common Messages that change nothing (a duplicate live
+event, a repeated `ReadStarted`, an empty `Hydrated`, a retention pass that
+collects nothing) return the Model they were given, so Foldkit neither renders
+nor recomputes Subscription dependencies.
 
 Its Messages cover reads and refreshes, mutations, live events/gaps, query
 connections, retention, and hydration. `Remote.messages` is the case record for
@@ -1574,21 +1683,30 @@ Remote.retain(projections, toMessage?, { connections?, grace? })
   active roots -> RetentionChanged
 ```
 
-The observe entry's dependencies are the current plan and the Model's refresh
-generation (`{ requirements, queries, refresh }`), so `Data.refresh` restarts
+The observe entry's dependencies are the current plan, the Model's refresh
+generation, and when a held value next ages out
+(`{ requirements, queries, refresh, expires }`), so `Data.refresh` restarts
 it. If entity requirements and queries are both empty, it performs no I/O. A
 refreshing read emits `RefreshStarted` first, then a result Message.
 
-Every emitted Message changes the Model, so Foldkit recomputes Subscription
+A Message that changes the Model makes Foldkit recompute Subscription
 dependencies. For example, after a query page lands, the next computation sees
 the page's entity ids and plans any selected fields those entities still lack.
 An interrupted identical read is joined by the client coalescer instead of
 needlessly restarted.
 
+The live entry's dependencies are what the Surface reads live, the refresh
+floor, and the stream's cursor. The stream stays open as events advance the
+cursor; the cursor is only where a stream restarted for another reason resumes.
+
 Retention uses the Projection requirements/connections as roots and eventually
 emits `RetentionChanged`; the reducer's pure `gc` keeps everything reachable
 from those roots plus pending work and collects the rest.
 
+The entries `Data.subscriptions` returns carry these dependencies in their
+types: `ReadDependencies` for `<key>.read`, `LiveDependencies` for
+`<key>.live`, and `RetentionRoots` for `retain`.
+
 ### Connections by hand
 
 A connection stores entity references in segments with explicit boundaries, so
@@ -1617,7 +1735,7 @@ them.
 
 ### Mutations by hand
 
-`Remote.mutateInto(bound, model, mutation, input, requestId, { optimistic })` is
+`Remote.mutateInto(bound, model, mutation, input, requestId, { optimistic, now })` is
 the one-step imperative start/run/settle form for SSR and tests.
 
 `Remote.mutate(mutation, input, requestId)` is the transport call itself. It
@@ -1625,7 +1743,10 @@ decodes the typed `Output` and returns normalized entity patches and confirmed
 connection changes for a caller to reduce through `updateRemote`.
 
 `MutationSucceeded` reconciles at most once per `requestId`; an unknown or
-already-applied settlement is a no-op.
+already-applied settlement is a no-op. It carries `now`, the clock reading of
+the answer, which dates the entities it writes as a read's `now` does, so a
+freshness policy ages them from then. `Data.mutate` and `Remote.mutateInto`
+stamp it from their `now` option, `Date.now` by default.
 
 ### The transport seam