You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 748db2f
Browse filesBrowse the repository at this point in the historyBrowse files
`refresh(target)` now returns a promise for the target's next QUIESCENT state — the re-ask (and anything that supersedes it) has settled. Accessor targets resolve with the settled value; store targets resolve with the store node passed (nested targets re-ask the whole family but resolve with the node the caller was looking at). A failed re-ask rejects, so `yield refresh(x)` in an action throws back at the yield point and reverts like any failed step; an ignored promise never surfaces an unhandled rejection, keeping fire-and-forget refresh unchanged. Semantics are quiescence, not flight identity: a superseding refresh folds every waiter onto whatever finally lands. Inside actions, truth landing into the held transaction is staged; the promise settles then (matching `resolve()`/`until()` delivery) and delivers the staged value — never the caller's optimistic override. The re-ask stays verdict-quiet (`isPending` unchanged).
7
+
8
+
Implementation is pay-for-use and shares `resolve()`/`until()`'s effect machinery: the waiter is a microtask-delivered, direct-commit, authoritative-read effect over the marked node, deferred one microtask so same-tick refreshes still coalesce into a single re-ask. One new reader bit (`CONFIG_FRESH_READ`) makes the waiter's read pull a still-dirty source through recompute inline — it then parks on the re-ask's pending window (woken by the settle walk, which runs on every landing including equal-value ones) or serves the sync answer, instead of misreading the pre-re-ask value as settled. `updateIfNecessary` now also refuses disposed nodes outright (#2983's bug class), and a disposed or non-derived target resolves immediately with its last value.
Warn in dev when a scripted server function call is answered with 304 Not Modified (#3101). The scripted transport sends no conditional headers, so a hand-rolled 304 resolves the call to `undefined` rather than "unchanged" — the warning points at GET-declared reads with ETag/Cache-Control, where the browser owns the conditional exchange and replays its cached answer.
Fix a type error in refresh()'s quiescence waiter that broke declaration emit (`pnpm types`): the waiter captured inside the effect's own compute is the effect node, so it is typed `Computed` rather than `Owner`, matching what `dispose()` takes. Type-only; no runtime change.
Fix derived optimistic stores permanently corrupting committed state when the source's draft writes ran while a caller's optimistic override was active (#3108). The source is the truth author: its draft reads — sync body and post-`await`/`yield` continuations alike — now serve the authoritative view instead of composing the caller's tentative overlay. Before, a generator continuation's `store.push` read `length` through an action's optimistic row and landed truth at the wrong index, committing `[null, row]`. Values, array length, membership, keys, and descriptors all leave the authoritative view together, gated on the same authoritative-write posture `ensurePB` already used to seed authoritative drafts from committed truth. User setter drafts are unchanged and keep composing on the optimistic view (#2951). Not an `until()` bug, despite the report's shape — the corruption reproduced with a plain yielded promise.
Key server-function ids on identity instead of position (#3109). Production ids were `<xxhash32(path)>-<ordinal>`, so appending a server function to a file renumbered the others and every client holding the old numbering silently dispatched to different code with a 200. Ids are now `<name>-<xxhash32(root-relative path)>`, with a trailing ordinal only when the same descriptive name recurs within one file — appends, deletes, reorders, and body edits no longer move any address, and a removed or renamed function becomes a clean 404 instead of a wrong call. Development and production now share the exact same id format.
Label the unknown-id 404 so version skew is recoverable (#3110). A call whose well-formed address is not registered in the answering deployment — a tab holding the previous build's ids across a deploy, or a genuinely removed function — now answers with an `X-Server-Function-Unknown` header, and the client stamps `unknownFunction: true` (plus a directed message) on the rejection. Integrations can act on it — typically by reloading the document onto the current build — instead of surfacing a generic failed call. A 404 for a path the address scheme gives no meaning to stays unlabelled.
Carry masked redirects in a dedicated header and retire the RC transition shims. Scripted callers now receive redirects as `X-Server-Function-Redirect: <status> <url>` with the target resolved server-side against the request URL (#3102) — `Location` never rides a masked 200, so an authored `Location` on a forwarding status (a 201's created-at) stays data, and integrations compare origins on a real URL instead of guessing navigation strategy from the author's spelling (#3107). `decodeRedirectHeaderValue` is exported for readers. Removed the transitional instance-header scripted fallback at the bare address and its forced no-store (#3094): the answer shape is now a function of the URL alone, with the data address as the only scripted path.
Single-flight always folds the keyed envelope — the raw legacy payload shape is gone with the other RC shims. The unnamed registration's slice rides under its reserved id "true" like any named source, so `{ value, data }` has one shape, not two; the client always delivers `data[source]` to each consumer. The unrecognized-opt-in courtesy (arbitrary truthy header values reaching the unnamed hook) is also removed: only exact source ids run collection.
Copy file name to clipboardExpand all lines: documentation/solid-2.0/05-async-data.md
+13Lines changed: 13 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -242,6 +242,19 @@ refresh(user);
242
242
243
243
Like an `action(...)` result, `refresh()` is an imperative callback when you hand it to UI. Call it from event handlers, effects, or action workflows. A bare `refresh()` is a quiet re-ask — the fresh value reveals silently and `isPending` stays `false`; pair it with `affects()` when the reload should read as pending (RFC 06).
244
244
245
+
`refresh()` also returns a promise for the target's **next quiescent state** — the re-ask (and anything that supersedes it) has settled. Accessor targets resolve with the settled value; store targets resolve with the store node you passed, so reads through it after the `await` are fresh:
246
+
247
+
```js
248
+
constfresh=awaitrefresh(user);
249
+
// or, for a store/projection:
250
+
awaitrefresh(todos);
251
+
navigate(`/todos/${todos.at(-1).id}`);
252
+
```
253
+
254
+
The promise is safe to ignore — fire-and-forget `refresh()` is unchanged, and a failed refetch never surfaces an unhandled rejection from an ignored promise. The semantics are quiescence, not flight identity: if a second refresh (or any invalidation) supersedes this one mid-flight, the promise waits for — and delivers — whatever finally lands. A failed re-ask rejects with the error. Awaiting does not change the quiet-re-ask contract: `isPending` still stays `false` for a bare refresh.
255
+
256
+
Refresh granularity is the granularity of the *derive function*: refreshing a nested store node re-asks the whole family projection (there is no per-path refetch to re-run), though the promise still resolves with the node you passed. Inside actions, `yieldrefresh(x)` is the mutate-then-refetch sequencing primitive — see RFC 06.
In 1.x, `mutate` replaced the resource value wholesale. This had several problems: no granular updates (the entire list re-rendered), no reconciliation (identity lost on every mutation), and no protection against race conditions (concurrent mutations could clobber each other):
`refresh()` is also an action: call it from event handlers, effects, or other actions rather than from pure computations. It starts invalidation work; it does not carry user-visible optimistic state by itself. Because it re-asks the *same* question (no input changed), a bare `refresh()` is quiet: the fresh value reveals silently and `isPending` stays `false`. When the reload should read as pending, declare it with `affects()`.
78
78
79
+
#### Awaitable `refresh()`
80
+
81
+
`refresh()` returns a promise for the target's **next quiescent state**: the re-ask — and anything that supersedes it — has settled. Fire-and-forget callers can keep ignoring it (an ignored promise never surfaces an unhandled rejection); awaiting it turns refresh into a sequencing point:
82
+
83
+
```js
84
+
constsubmit=action(asyncfunction* (order) {
85
+
setOptimisticOrder(order);
86
+
yieldapi.placeOrder(order);
87
+
// Wait for the refetch to actually land, then act on fresh server state.
88
+
constinv=yieldrefresh(inventory);
89
+
if (inv[order.sku] < threshold) yieldapi.flagRestock(order.sku);
90
+
});
91
+
```
92
+
93
+
The contract:
94
+
95
+
-**Value delivery.** Accessor targets resolve with the settled value. Store targets resolve with the store node you passed — stores are identity-stable containers, so the await is the ordering and any read through the node afterwards is fresh. Refreshing a nested store node re-asks the whole family (refresh granularity is the derive function's granularity) but resolves with the node the caller was looking at.
96
+
-**Quiescence, not flight identity.** If a second refresh — or any invalidation — supersedes this one mid-flight, the promise waits for whatever finally lands and delivers that. A superseded flight that never settles on its own means nothing; the superseding answer contains or replaces it.
97
+
-**Failures propagate.** A failed re-ask rejects the promise. Inside an action, `yield refresh(x)` throws back at the yield point, so the failure joins the action's normal story: catch it to compensate, or let it revert the optimistic state with the failed action.
98
+
-**Staged delivery inside actions.** Truth landing into the open transaction stages (it cannot commit while the action holds); the promise still settles then, delivering the staged value — matching `resolve()`/`until()` delivery. The caller's own optimistic override is never the delivered value.
99
+
-**Still quiet.** Awaiting does not create a pending window; pair with `affects()` as before when the reload should read as pending.
100
+
101
+
This is the mutate-then-refetch sequencing primitive: the confirmation is simply "the refetch I issued has settled", with no condition to express and no version fields to invent. When the confirmation instead arrives on a live channel the mutation didn't ask — sockets, subscriptions — reach for `until()` below.
102
+
79
103
### `affects(target, key?)` (declare what in-flight work will change)
80
104
81
105
`affects` declares that the surrounding work will change the targeted data. The marked data — and anything derived from it — reads as pending (`isPending` → `true`) from the declaration until the transaction settles or reverts, exactly as if a real fetch for it were in flight; the values themselves stay readable throughout. It is additive only: a declaration can turn pending *on* for data the graph can't see changing yet; nothing turns pending *off* while a real change is in flight — pairing `affects(x)` with `refresh(x)` keeps the whole window pending even though the bare refresh alone would be quiet.
The flows above assume the mutation's own response confirms the write: await it, `refresh()`, done. Actions that feed **live sources** — sockets, subscriptions, live queries — have no such ack: the transport call returns immediately (or is fire-and-forget), and the authoritative update arrives later on the data channel. Without a hold, the action settles at the transport ack, the optimistic state reverts, and the confirmed data flickers in a beat later.
156
+
The flows above assume the mutation's own response confirms the write: await it, `yield refresh()`, done — the refetch's settle point is the confirmation. Actions that feed **live sources** — sockets, subscriptions, live queries — have no such ack: the transport call returns immediately (or is fire-and-forget), and the authoritative update arrives later on the data channel. Without a hold, the action settles at the transport ack, the optimistic state reverts, and the confirmed data flickers in a beat later.
133
157
134
158
`until(fn, options?)` is that hold. It returns a promise that resolves the first time the reactive predicate `fn` settles **truthy**, with that (narrowed) value. Falsy results and pending async reads both mean "not yet" — the subscription stays live and re-evaluates as sources change. Yield it from an action to hold the transaction — and every optimistic override riding it — open until the world confirms:
135
159
@@ -159,7 +183,7 @@ Practical guidance:
159
183
-**Scope `affects()` narrowly** during long holds — mark the row, not the store, or every pending-driven affordance reads busy for the whole confirmation window.
160
184
-**Any arrival path confirms.** Live-channel landings, other transactions' commits (they land beneath the hold), and refetches the action itself issued (they land *staged into* the hold, and the predicate reads staged data) all satisfy the predicate the moment they carry the confirming truth.
161
185
162
-
Where `resolve(fn)` answers "what is this value" (first settled value, whatever it is), `until(fn)` answers "when does the world confirm this condition" (first *truthy* settle). They share delivery machinery; the one read-semantics difference is deliberate: `resolve` reads your own transaction's view, overrides included — it is reporting your state. `until` reads the authoritative view, overrides carved out — it is waiting on the world, and your own optimism must not be able to answer for it. Both see transition-staged data; neither can deadlock on a value the surrounding action holds.
186
+
Where `resolve(fn)` answers "what is this value" (first settled value, whatever it is), `until(fn)` answers "when does the world confirm this condition" (first *truthy* settle), and an awaited `refresh(x)` answers "when has this re-ask settled" (no condition at all — the settle point of a refetch you issued). They share delivery machinery; the read-semantics differences are deliberate: `resolve` reads your own transaction's view, overrides included — it is reporting your state. `until` reads the authoritative view, overrides carved out — it is waiting on the world, and your own optimism must not be able to answer for it. `refresh` delivers the landed (staged-or-committed) value, never the caller's override. All see transition-staged data; none can deadlock on a value the surrounding action holds. Most mutate-then-refetch flows want `yield refresh(...)`; only confirmations arriving on a channel the mutation didn't ask genuinely need `until`.
0 commit comments