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 1b94264
Browse filesBrowse the repository at this point in the historyBrowse files
feat(signals): question-scoped pending model and the affects() primitive
isPending is re-derived from one rule (A24): a read is pending iff a value
change is in flight for it that has not yet revealed, or it carries a live
affects() mark. Same-question re-asks (refresh/poll/confirm) are silent,
new questions pend monotonically and cannot be silenced, and optimistic
writes are verdict-inert — the store-wide optimistic mask (A20/A21) is
deleted. affects(target, ...keys) is the sole declaration verb for pending
on data the graph can't see changing yet; re-exported from solid-js with a
server no-op stub.
Co-authored-by: Cursor <[email protected]>
Question-scoped pending model and the `affects()` primitive (supersedes the optimistic mask)
7
+
8
+
`isPending` is re-derived from one rule: a read is pending iff a value change is in flight for it that has not yet revealed, or it carries a live `affects()` mark.
9
+
10
+
-**Same-question re-asks are silent.**`refresh()`, polling, and confirm refetches whose tracked inputs are value-stable no longer read as pending — the fresh value reveals silently.
11
+
-**New questions pend monotonically.** An input value change in flight pends every read under the source until its answer reveals, and nothing can silence it.
12
+
-**Optimistic writes are verdict-inert.** An active override displays without decreeing settlement: it neither reads pending on its own slot (only a differing held correction re-opens the verdict) nor masks anything else. The store-wide optimistic mask (A21) and node mask (A20) are removed.
13
+
-**New `affects(target, ...keys)` primitive** (re-exported from `solid-js`). Declares that in-flight work will change the targeted data: the named slots (a store record, specific record keys, or a source accessor) read pending from the declaration until the surrounding transaction settles or reverts. `affects(x); refresh(x)` is the declared-reload idiom.
Copy file name to clipboardExpand all lines: documentation/solid-2.0/05-async-data.md
+16-12Lines changed: 16 additions & 12 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -37,7 +37,7 @@ This pushes “loading state” to UI structure (boundaries) instead of leaking
37
37
38
38
`Loading` shows fallback while the subtree needs unresolved async values.
39
39
40
-
Importantly, `Loading` is intended to cover **branch readiness**: it handles a subtree or newly mounted branch attempting to read async-derived values that are not ready yet. After that branch has produced content, subsequent revalidation/refresh should generally not “kick you back” into the fallback; use `isPending` for “background work is happening” UI.
40
+
Importantly, `Loading` is intended to cover **branch readiness**: it handles a subtree or newly mounted branch attempting to read async-derived values that are not ready yet. After that branch has produced content, subsequent revalidation/refresh should generally not “kick you back” into the fallback; use `isPending` for “a change to this data is on the way” UI.
41
41
42
42
```jsx
43
43
<Loading fallback={<Spinner />}>
@@ -65,27 +65,29 @@ By default, once a `Loading` boundary has rendered content, it keeps showing sta
65
65
66
66
This is useful for route-level or key-level transitions where you don't want to wait on all data loading before updating the UI. Show the fallback again instead.
`isPending` answers: “Does this read currently touch pending async work?”
70
+
`isPending` answers: “Is a value change in flight for this read that hasn't revealed yet?”
71
71
72
-
`isPending` performs the read you pass it and returns whether any value read by that function is currently pending. Because it is a read, its placement matters: reading async data can participate in Loading/SSR readiness, while reading upstream state only observes that state's own pending transition.
72
+
It returns `true` when a tracked input of the data has changed and the new answer hasn't landed (e.g. navigation changed an id and the refetch is still in flight), or when in-flight work has declared it will change the data (`affects`, RFC 06). A re-ask of the *same* question is silent: a bare `refresh()`, polling, or a confirming refetch after a mutation does not read as pending — the data you're showing still answers what's being asked, and the fresh value reveals silently. To make a reload read as pending, declare it: `affects(user); refresh(user)`.
73
+
74
+
`isPending` performs the read you pass it, so its placement matters: reading async data can participate in Loading/SSR readiness, while reading upstream state only observes that state's own pending transition.
<Show when={listPending()}>{/* subtle "updating…" indicator while a new query loads*/}</Show>
83
85
<List users={users()} posts={posts()} />
84
86
</Loading>
85
87
);
86
88
```
87
89
88
-
Because this pending read reaches the async values directly, it sits under the same `Loading` boundary as the data read. On first load, the boundary owns fallback UI; after the values have resolved once, the inline indicator can show stale-while-revalidating state. `isPending` may also be used outside a `Loading` boundary when the expression only reads upstream state that cannot itself be not ready.
90
+
Because this pending read reaches the async values directly, it sits under the same `Loading` boundary as the data read. On first load, the boundary owns fallback UI; after the values have resolved once, the inline indicator shows while a changed `query()` is being answered. `isPending` may also be used outside a `Loading` boundary when the expression only reads upstream state that cannot itself be not ready.
89
91
90
92
The intent is to replace `.loading`-style flags that belong to a specific primitive (`createResource`) with something that works for any expression. Since the expression is read normally, the same primitive can guard interactive controls that directly depend on async data when it is placed under the boundary that owns that read:
91
93
@@ -150,7 +152,7 @@ Wrap reads of async accessors in `Loading` to control where fallback UI appears.
150
152
151
153
#### `resource.loading` → `isPending`
152
154
153
-
In 1.x, `.loading` was a property on the resource itself. In 2.0, loading state is structural (handled by `Loading` boundaries while a branch is not ready) and expression-level for revalidation:
155
+
In 1.x, `.loading` was a property on the resource itself. In 2.0, loading state is structural (handled by `Loading` boundaries while a branch is not ready) and expression-level for in-flight changes:
Remember: `isPending(fn)` actively reads `fn`. If that read is not ready yet, it follows the same `Loading` path as reading the value directly. Put pending indicators under the boundary that should own initial fallback UI; after the value has resolved once, `isPending` is useful for inline revalidation indicators.
170
+
Here `isPending` fires while a changed `id()` is being answered. Note the split from 1.x: `.loading` was also true during a plain `refetch`, but a bare `refresh()` re-asks the same question and is *not* pending in 2.0. For a refetch that should read as pending, declare it (`affects(user); refresh(user)`); for a process affordance (“saving…”, a disabled reload button), co-write an optimistic flag in the action instead (RFC 06).
171
+
172
+
Remember: `isPending(fn)` actively reads `fn`. If that read is not ready yet, it follows the same `Loading` path as reading the value directly. Put pending indicators under the boundary that should own initial fallback UI.
169
173
170
174
#### `resource.refetch` → `refresh()`
171
175
@@ -181,7 +185,7 @@ const user = createMemo(() => fetchUser(id()));
181
185
refresh(user);
182
186
```
183
187
184
-
Like an `action(...)` result, `refresh()` is an imperative callback when you hand it to UI. Call it from event handlers, effects, or action workflows; use `Loading` / `isPending`to observe readiness.
188
+
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).
`refresh()` is not a UI state primitive. During mutations, express the expected user-visible state with `createOptimistic` / `createOptimisticStore`, then call `refresh()` to reconcile with the source of truth after the server write.
76
76
77
-
`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.
77
+
`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
+
79
+
### `affects(target, ...keys)` (declare what in-flight work will change)
80
+
81
+
`affects` declares that the surrounding work will change the targeted data. The named slots read as pending (`isPending` → `true`) from the declaration until the transaction settles or reverts. 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.
82
+
83
+
Targets mirror how you read: `affects(store)` marks a store record (root or nested — siblings are untouched), `affects(record, "key")` marks exactly the named slots, and `affects(accessor)` marks a signal/memo source.
84
+
85
+
```js
86
+
constreload=action(function* () {
87
+
affects(todos); // the whole store reads pending…
88
+
refresh(todos); // …over this otherwise-quiet re-ask
89
+
yieldapi.done();
90
+
});
91
+
92
+
constrename=action(function* (todo, text) {
93
+
setOptimisticTodos(() => { todo.text= text; });
94
+
affects(todo, "updatedAt"); // server will change this slot too
95
+
yieldapi.rename(todo.id, text);
96
+
refresh(todos);
97
+
});
98
+
```
99
+
100
+
Note the division of labor: optimistic writes show the expected value (they are verdict-inert — they neither pend their own slot nor silence anything else), `affects` marks data you know is changing but can't show yet, and process affordances (“saving…”, a disabled reload button) are co-written state — an optimistic boolean in the action that reverts on settle — not verdicts.
Copy file name to clipboardExpand all lines: documentation/solid-2.0/MIGRATION.md
+8-7Lines changed: 8 additions & 7 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -9,7 +9,7 @@ This is a short, practical guide for migrating from Solid 1.x to Solid 2.0’s A
9
9
-**Batching/reads**: setters don’t immediately change what reads return; values become visible after the microtask batch flushes (or via `flush()`).
10
10
-**Effects**: `createEffect` is split (compute → apply). Cleanup is usually “return a cleanup function”.
11
11
-**Lifecycle**: `onMount` is replaced by `onSettled` (and it can return cleanup).
12
-
-**Async UI**: use `<Loading>` for first readiness; use `isPending(() => expr)` for “refreshing…” indicators.
12
+
-**Async UI**: use `<Loading>` for first readiness; use `isPending(() => expr)` for “a change is on the way” indicators (input-driven refetches and `affects()` declarations — a bare `refresh()` is silent).
13
13
-**Lists**: `Index` is gone; use `<For keyed={false}>`. Default `For` receives raw items, while `keyed={false}` receives item accessors and a stable numeric index.
14
14
-**Stores**: prefer draft-first setters; `storePath(...)` exists as an opt-in helper for the old path-style ergonomics.
15
15
-**Plain values**: `snapshot(store)` replaces `unwrap(store)` when you need a plain non-reactive value.
@@ -320,23 +320,23 @@ The resource tuple features map to standalone APIs:
|`resource.loading`|`Loading` (initial), `isPending(() => resource())` (in-flight input change); a bare `refresh()` is silent — use `affects(resource); refresh(resource)` or a co-written optimistic flag for refetch affordances|
324
324
|`resource.error`|`Errored` boundary or effect `error` option |
325
325
|`refetch()`|`refresh(resource)`|
326
326
|`mutate()`|`createOptimisticStore` + `action` (see [RFC 06](06-actions-optimistic.md)) |
327
327
328
328
See [RFC 05 — createResource migration](05-async-data.md#createresource--async-computations--loading) for detailed before/after examples of each pattern.
329
329
330
-
### Initial loading vs revalidation: `Loading` vs `isPending`
330
+
### Initial loading vs in-flight changes: `Loading` vs `isPending`
-**`isPending(fn)`**: active pending read for the exact expression in `fn`; when that expression can be not ready, place it under the `Loading` boundary that should own initial fallback UI. It can live outside the boundary when it only reads upstream state that cannot be not ready.
333
+
-**`isPending(fn)`**: active pending read for the exact expression in `fn` — `true` while a value change is in flight for it (an input changed, or in-flight work declared it with `affects`); a bare `refresh()`/poll of the same inputs is silent. When the expression can be not ready, place it under the `Loading` boundary that should own initial fallback UI. It can live outside the boundary when it only reads upstream state that cannot be not ready.
<Show when={listPending()}>{/* subtle "updating…" indicator while a new query loads*/}</Show>
340
340
<List users={users()} posts={posts()} />
341
341
</Loading>;
342
342
```
@@ -670,9 +670,10 @@ These APIs are new additions (not renames of 1.x APIs):
670
670
-**`action(fn)`** — wraps generator/async generator mutations with transition coordination.
671
671
-**`createOptimistic` / `createOptimisticStore`** — signal/store primitives whose writes revert when a transition completes.
672
672
-**`createProjection(fn, seed)`** — derived store with reactive reconciliation.
673
-
-**`isPending(fn)`** — expression-level "stale while revalidating" check.
673
+
-**`isPending(fn)`** — expression-level "unrevealed change in flight" check.
674
674
-**`latest(fn)`** — peek at in-flight values during transitions.
675
-
-**`refresh(target)`** — explicit recomputation/invalidation of derived reads.
675
+
-**`refresh(target)`** — explicit recomputation/invalidation of derived reads (a quiet re-ask — not pending).
676
+
-**`affects(target, ...keys)`** — declare that in-flight work will change the targeted data; the named slots read pending until the transaction settles.
676
677
-**`resolve(fn)`** — returns a Promise that resolves when a reactive expression settles.
677
678
-**`Loading``on` prop** — controls when a Loading boundary re-shows fallback during revalidation.
678
679
-**`deep(store)`** — deep observation of a store (tracks all nested changes).
0 commit comments