Skip to content

Commit 1b94264

Browse 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]>
1 parent 4a1d997 commit 1b94264

33 files changed

Lines changed: 1734 additions & 664 deletions
Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
---
2+
"@solidjs/signals": minor
3+
"solid-js": minor
4+
---
5+
6+
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.

‎documentation/solid-2.0/05-async-data.md‎

Lines changed: 16 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,7 @@ This pushes “loading state” to UI structure (boundaries) instead of leaking
3737

3838
`Loading` shows fallback while the subtree needs unresolved async values.
3939

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.
4141

4242
```jsx
4343
<Loading fallback={<Spinner />}>
@@ -65,27 +65,29 @@ By default, once a `Loading` boundary has rendered content, it keeps showing sta
6565

6666
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.
6767

68-
### `isPending(fn)` (stale-while-revalidating queries)
68+
### `isPending(fn)` (in-flight change queries)
6969

70-
`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?”
7171

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.
7375

7476
```js
75-
const users = createMemo(() => fetchUsers());
76-
const posts = createMemo(() => fetchPosts());
77+
const users = createMemo(() => fetchUsers(query()));
78+
const posts = createMemo(() => fetchPosts(query()));
7779

7880
const listPending = () => isPending(() => users() || posts());
7981

8082
return (
8183
<Loading fallback={<Spinner />}>
82-
<Show when={listPending()}>{/* subtle "refreshing…" indicator */}</Show>
84+
<Show when={listPending()}>{/* subtle "updating…" indicator while a new query loads */}</Show>
8385
<List users={users()} posts={posts()} />
8486
</Loading>
8587
);
8688
```
8789

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.
8991

9092
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:
9193

@@ -150,7 +152,7 @@ Wrap reads of async accessors in `Loading` to control where fallback UI appears.
150152

151153
#### `resource.loading` → `isPending`
152154

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:
154156

155157
```js
156158
// 1.x
@@ -160,12 +162,14 @@ const [user] = createResource(id, fetchUser);
160162
// 2.0
161163
const user = createMemo(() => fetchUser(id()));
162164
<Loading fallback={<UserSkeleton />}>
163-
<Show when={isPending(() => user())}>Refreshing...</Show>
165+
<Show when={isPending(() => user())}>Updating...</Show>
164166
<UserDetails user={user()} />
165167
</Loading>
166168
```
167169

168-
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.
169173

170174
#### `resource.refetch` → `refresh()`
171175

@@ -181,7 +185,7 @@ const user = createMemo(() => fetchUser(id()));
181185
refresh(user);
182186
```
183187

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).
185189

186190
#### `resource.mutate` → `createOptimisticStore` / `action`
187191

‎documentation/solid-2.0/06-actions-optimistic.md‎

Lines changed: 24 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -74,7 +74,30 @@ const addTodo = action(function* (todo) {
7474

7575
`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.
7676

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+
const reload = action(function* () {
87+
affects(todos); // the whole store reads pending…
88+
refresh(todos); // …over this otherwise-quiet re-ask
89+
yield api.done();
90+
});
91+
92+
const rename = action(function* (todo, text) {
93+
setOptimisticTodos(() => { todo.text = text; });
94+
affects(todo, "updatedAt"); // server will change this slot too
95+
yield api.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.
78101

79102
### `createOptimistic` (optimistic signal)
80103

‎documentation/solid-2.0/MIGRATION.md‎

Lines changed: 8 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ This is a short, practical guide for migrating from Solid 1.x to Solid 2.0’s A
99
- **Batching/reads**: setters don’t immediately change what reads return; values become visible after the microtask batch flushes (or via `flush()`).
1010
- **Effects**: `createEffect` is split (compute → apply). Cleanup is usually “return a cleanup function”.
1111
- **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).
1313
- **Lists**: `Index` is gone; use `<For keyed={false}>`. Default `For` receives raw items, while `keyed={false}` receives item accessors and a stable numeric index.
1414
- **Stores**: prefer draft-first setters; `storePath(...)` exists as an opt-in helper for the old path-style ergonomics.
1515
- **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:
320320

321321
| 1.x resource feature | 2.0 replacement |
322322
| -------------------- | --------------------------------------------------------------------------- |
323-
| `resource.loading` | `Loading` (initial), `isPending(() => resource())` (revalidation) |
323+
| `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 |
324324
| `resource.error` | `Errored` boundary or effect `error` option |
325325
| `refetch()` | `refresh(resource)` |
326326
| `mutate()` | `createOptimisticStore` + `action` (see [RFC 06](06-actions-optimistic.md)) |
327327

328328
See [RFC 05 — createResource migration](05-async-data.md#createresource--async-computations--loading) for detailed before/after examples of each pattern.
329329

330-
### Initial loading vs revalidation: `Loading` vs `isPending`
330+
### Initial loading vs in-flight changes: `Loading` vs `isPending`
331331

332332
- **`Loading`**: initial “not ready yet” UI boundary.
333-
- **`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.
334334

335335
```jsx
336336
const listPending = () => isPending(() => users() || posts());
337337

338338
<Loading fallback={<Spinner />}>
339-
<Show when={listPending()}>{/* subtle "refreshing…" indicator */}</Show>
339+
<Show when={listPending()}>{/* subtle "updating…" indicator while a new query loads */}</Show>
340340
<List users={users()} posts={posts()} />
341341
</Loading>;
342342
```
@@ -670,9 +670,10 @@ These APIs are new additions (not renames of 1.x APIs):
670670
- **`action(fn)`** — wraps generator/async generator mutations with transition coordination.
671671
- **`createOptimistic` / `createOptimisticStore`** — signal/store primitives whose writes revert when a transition completes.
672672
- **`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.
674674
- **`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.
676677
- **`resolve(fn)`** — returns a Promise that resolves when a reactive expression settles.
677678
- **`Loading` `on` prop** — controls when a Loading boundary re-shows fallback during revalidation.
678679
- **`deep(store)`** — deep observation of a store (tracks all nested changes).

0 commit comments

Comments
 (0)