Skip to content

Commit 1d6c40f

Browse files
ryansolidclaude
andauthored
feat(signals): add onFlush to keep a write out of another update's hold (#4292)
* feat(signals): add onFlush to keep a write out of another update's hold `onFlush(fn)` runs `fn` once right after the pending flush, in the same microtask checkpoint and before paint, without waiting on async work. A write made there is its own update, so a component can close a menu while the consumer's `onSelect` starts async navigation. It joins a hold only when what it changes also derives from the held work, as any later write would. Dev warns (ON_FLUSH_IN_OWNED_SCOPE) when called in a component body or a computation. Separate export: tree-shakes to zero bytes when unused. The server build is a no-op. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> Claude-Session: https://claude.ai/code/session_01T8hGW34hnEajU3rg9G2cAd * size: raise the live-page caps for the 2026-10-26 bug-fix batch #4279 (+82 B minified), #4281 (+51), #4280 (+15), #4277 (+11) and #4278 (+11), net of #4261 (-39), put next over three live-page client caps. Caps at the CI measurement + 10 B; recorded minified = measured. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> Claude-Session: https://claude.ai/code/session_018LY7F9czoRqdMEvk2QwPr1 * size: re-record the base pages grown by the same batch Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> Claude-Session: https://claude.ai/code/session_018LY7F9czoRqdMEvk2QwPr1 --------- Co-authored-by: Claude <[email protected]>
1 parent ade599a commit 1d6c40f

12 files changed

Lines changed: 391 additions & 0 deletions

File tree

‎.changeset/on-flush.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
---
2+
"@solidjs/signals": patch
3+
"solid-js": patch
4+
---
5+
6+
Add `onFlush(fn)`: runs `fn` once right after the pending flush, before paint, without waiting on async work. A write made there is its own update, so it is not held by async work another write in the same frame started (a menu closing while the consumer's `onSelect` navigates). Meant for event handlers and effect callbacks; dev warns (`ON_FLUSH_IN_OWNED_SCOPE`) in a component body or computation. Tree-shakes when unused.

‎documentation/solid-2.0/01-reactivity-batching-effects.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -105,6 +105,36 @@ flush(() => {
105105

106106
Use `flush(fn)` at imperative boundaries where the writes themselves should run in a synchronous flush scope. Writes inside the callback do not schedule the normal microtask flush; they are drained before `flush(fn)` returns, so you can update state and immediately read reactive values or DOM without leaving a queued flush behind. The callback's return value is preserved, and nested `flush(fn)` calls drain at each level.
107107

108+
### Keeping a write out of another update's hold: `onFlush`
109+
110+
Writes made in the same synchronous frame are applied together. When one of them starts async work (a route change, a refetch), the others are held with it until it resolves. Usually that is what you want. It is not when a component writes its own state and then calls code it doesn't control:
111+
112+
```tsx
113+
function Menu(props) {
114+
const select = (id: string) => {
115+
setOpen(false); // held if onSelect starts async work: the menu stays open
116+
props.onSelect?.(id);
117+
};
118+
// ...
119+
}
120+
```
121+
122+
`onFlush(fn)` runs `fn` once, right after the pending flush and before the browser paints, so its writes are their own update:
123+
124+
```tsx
125+
const select = (id: string) => {
126+
onFlush(() => setOpen(false)); // closes now, whatever onSelect does
127+
props.onSelect?.(id);
128+
};
129+
```
130+
131+
The write follows the normal rules from there: it commits on its own unless something it changes also derives from the held work (a memo or `createEffect` reading both), in which case it joins that hold like any later write. A render effect reading both shows the new value beside the committed one, as usual.
132+
133+
- Call it from event handlers and effect callbacks. In a component body or computation it warns in dev (`ON_FLUSH_IN_OWNED_SCOPE`); use `onSettled` there.
134+
- Its write lands after any write made inline in the same frame. Don't write the same signal both inside and outside it.
135+
- `queueMicrotask` is not a substitute: called before the frame's first write it runs before that flush, so its write joins it. `flush()` applies the write now, but also runs every pending effect early, which can make them run twice.
136+
- Unlike `onSettled`, it never waits on async work.
137+
108138
### Split tracking from effect
109139

110140
Effects have two phases: **compute** (reactive reads only; dependencies recorded) and **effect** (side effects; runs after all compute phases in the batch). This gives a clear dependency picture before any side effects run and is required for async and boundaries.

‎documentation/solid-2.0/08-dev-diagnostics.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -206,6 +206,12 @@ const handleClick = () => {
206206
};
207207
```
208208

209+
#### `ON_FLUSH_IN_OWNED_SCOPE`
210+
211+
**Message:** "onFlush called in an owned scope (a component body or a computation). It is meant for event handlers and effect callbacks; to run work after this scope's first stable render, use onSettled."
212+
213+
`onFlush` schedules one callback right after the pending flush, without waiting on async work. That is for imperative code: event handlers and effect callbacks (including `createTrackedEffect` and `onSettled` bodies). In a component body or a computation it still runs, but it is almost always the wrong tool there: setup after the first stable render belongs in `onSettled`, and a computation should not schedule side effects at all.
214+
209215
#### `PRIMITIVE_IN_FORBIDDEN_SCOPE`
210216

211217
**Message:** "Cannot create reactive primitives inside createTrackedEffect or owner-backed onSettled"
@@ -946,6 +952,7 @@ The runtime derives a request's trace itself in every tier — the W3C `tracepar
946952
| `ASYNC_OUTSIDE_LOADING_BOUNDARY` | warn | async | Async computation outside Loading boundary (non-halting; root mount is deferred) |
947953
| `CLEANUP_IN_FORBIDDEN_SCOPE` | error | lifecycle | `onCleanup` inside trackedEffect/onSettled |
948954
| `SETTLED_CLEANUP_UNOWNED` | error | lifecycle | `onSettled` returned a cleanup in an unowned (out-of-band) scope |
955+
| `ON_FLUSH_IN_OWNED_SCOPE` | warn | lifecycle | `onFlush` called in a component body or computation (meant for event handlers and effect callbacks) |
949956
| `PRIMITIVE_IN_FORBIDDEN_SCOPE` | error | lifecycle | Reactive primitive created inside trackedEffect/onSettled |
950957
| `PRIMITIVE_IN_EFFECT_CALLBACK` | error | lifecycle | Memo, effect, or root created inside an effect callback or its cleanup, where there is no ambient owner (throws) |
951958
| `ACTION_CALLED_IN_OWNED_SCOPE` | error | write | `action()` invoked from a component body or computation |

‎packages/signals/src/core/dev.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,7 @@ export type DiagnosticCode =
5454
| "NO_OWNER_CLEANUP"
5555
| "CLEANUP_IN_FORBIDDEN_SCOPE"
5656
| "SETTLED_CLEANUP_UNOWNED"
57+
| "ON_FLUSH_IN_OWNED_SCOPE"
5758
| "SETTLE_WALK_UNINITIALIZED_SOURCE"
5859
| "FLUSH_IN_EFFECT_CALLBACK"
5960
| "PRIMITIVE_IN_FORBIDDEN_SCOPE"

‎packages/signals/src/index.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -100,6 +100,7 @@ export {
100100
resolve,
101101
until,
102102
onSettled,
103+
onFlush,
103104
onCleanup
104105
} from "./signals.js";
105106
export type {

‎packages/signals/src/signals.ts‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,7 @@ import {
3636
joinFuture,
3737
passTx,
3838
resolveTx,
39+
schedule,
3940
staleReader,
4041
type Transaction
4142
} from "./core/scheduler.js";
@@ -1228,3 +1229,63 @@ export function onSettled(callback: () => void | (() => void)): void {
12281229
}
12291230
});
12301231
}
1232+
1233+
/**
1234+
* Schedules `callback` to run **once**, right after the pending flush
1235+
* finishes, in the same microtask checkpoint (before the browser paints).
1236+
* Unlike `onSettled`, it never waits on async work: if that flush is held by
1237+
* a pending transition, the callback still runs.
1238+
*
1239+
* Its main use is keeping a write out of another update's hold. Writes made
1240+
* in the same synchronous frame are applied together, so when one of them
1241+
* starts async work (a route change, a fetch), the others are held with it
1242+
* until it resolves. A write made in `onFlush` happens after that flush, so
1243+
* it is its own update: it commits on its own unless something it changes
1244+
* also derives from the held work (a memo or `createEffect` reading both),
1245+
* in which case it joins that hold as any later write would.
1246+
*
1247+
* Call it from event handlers and effect callbacks (including
1248+
* `createTrackedEffect` and `onSettled` bodies). In an owned scope such as a
1249+
* component body or a computation it warns in dev: use `onSettled` there.
1250+
*
1251+
* - A write in the callback lands after any write made inline in the same
1252+
* frame. Don't write the same signal both inside and outside it; use a
1253+
* functional setter if the order matters.
1254+
* - Several `onFlush` callbacks run in call order and batch into one flush.
1255+
* - `queueMicrotask` is not a substitute: called before the frame's first
1256+
* write, it runs before that flush and its write joins it.
1257+
*
1258+
* @example
1259+
* ```tsx
1260+
* // A menu closes now even when the consumer's onSelect starts async work.
1261+
* const select = (id: string) => {
1262+
* onFlush(() => setOpen(false));
1263+
* props.onSelect?.(id);
1264+
* };
1265+
* ```
1266+
*
1267+
* @param callback Function to run once after the pending flush
1268+
*/
1269+
export function onFlush(callback: () => void): void {
1270+
if (__DEV__) {
1271+
const owner = getOwner();
1272+
if (owner && !(owner._config & CONFIG_CHILDREN_FORBIDDEN)) {
1273+
const message =
1274+
"[ON_FLUSH_IN_OWNED_SCOPE] onFlush called in an owned scope (a component body or a computation). It is meant for event handlers and effect callbacks; to run work after this scope's first stable render, use onSettled.";
1275+
reportDiagnostic(
1276+
emitDiagnostic({
1277+
code: "ON_FLUSH_IN_OWNED_SCOPE",
1278+
kind: "lifecycle",
1279+
severity: "warn",
1280+
message,
1281+
ownerId: owner.id,
1282+
ownerName: (owner as any)._name
1283+
})
1284+
);
1285+
}
1286+
}
1287+
// The frame's flush is queued (or already draining) ahead of this
1288+
// microtask, so the callback's writes start a flush of their own.
1289+
schedule();
1290+
queueMicrotask(callback);
1291+
}

0 commit comments

Comments
 (0)