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 1d6c40f
Browse filesBrowse the repository at this point in the historyBrowse files
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.
Copy file name to clipboardExpand all lines: documentation/solid-2.0/01-reactivity-batching-effects.md
+30Lines changed: 30 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -105,6 +105,36 @@ flush(() => {
105
105
106
106
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.
107
107
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
+
108
138
### Split tracking from effect
109
139
110
140
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.
Copy file name to clipboardExpand all lines: documentation/solid-2.0/08-dev-diagnostics.md
+7Lines changed: 7 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -206,6 +206,12 @@ const handleClick = () => {
206
206
};
207
207
```
208
208
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
+
209
215
#### `PRIMITIVE_IN_FORBIDDEN_SCOPE`
210
216
211
217
**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
946
952
|`ASYNC_OUTSIDE_LOADING_BOUNDARY`| warn | async | Async computation outside Loading boundary (non-halting; root mount is deferred) |
|`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) |
951
958
|`ACTION_CALLED_IN_OWNED_SCOPE`| error | write |`action()` invoked from a component body or computation |
"[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: (ownerasany)._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.
0 commit comments