@solidjs/signals 2.0.0-rc.7 → 2.0.0-rc.9

package/dist/observe/boundaries.js

@@ -0,0 +1,641 @@
+import { runWithOwner, signal, untrack, read, computed, spectate, setSignal, ext, recompute } from "./core/core.js";
+
+import { NotReadyError, unwrapStatusError } from "./core/error.js";
+
+import { createOwner, cleanup } from "./core/owner.js";
+
+import { Queue, transitions, wakeParked, haltReactivity, schedule } from "./core/scheduler.js";
+
+import { getContext, setContext, createContext } from "./core/context.js";
+
+import { STATUS_PENDING, STATUS_ERROR, REACTIVE_ZOMBIE, REACTIVE_DISPOSED, CONFIG_AUTO_DISPOSE } from "./core/constants.js";
+
+import { attrHooks } from "./core/attribution-hooks.js";
+
+import "./core/invariants.js";
+
+import "./core/dev.js";
+
+import "./core/verdict.js";
+
+import "./core/effect.js";
+
+import { reportClientError } from "./core/error-hooks.js";
+
+import { accessor } from "./signals.js";
+
+function boundaryComputed(t, e) {
+    const r = computed(t, {
+        lazy: true
+    });
+    ext(r).h = (t, e) => {
+        // Use passed values if provided, otherwise read from node
+        const s = t !== undefined ? t : r.S;
+        const n = e !== undefined ? e : r.o?._;
+        // Notify both status dimensions like a render effect does; the queue chain
+        // consumes this boundary's own type and forwards the remainder upward until
+        // a boundary that handles it is found.
+                r.S &= ~r.R;
+        const i = r.T.notify(r, STATUS_PENDING | STATUS_ERROR, s, n);
+        // The queue is the only propagation channel: a foreign status must not stay
+        // reader-visible on the tree, or reads re-throw it across the boundary and
+        // link unrelated ambient contexts (the #2809 nested-boundary loop). Deps are
+        // untouched, so the tree still recomputes when the foreign source settles.
+                const o = s & ~r.R & (STATUS_PENDING | STATUS_ERROR);
+        if (o) {
+            r.S &= ~o;
+            if (r.o?._ === n && !(r.S & (STATUS_PENDING | STATUS_ERROR))) if (r.o !== null) r.o._ = undefined;
+        }
+        // An ERROR the chain could not deliver to any boundary is uncaught. The
+        // scrub above already removed it from reader-visible state, so without
+        // escalation here it would vanish entirely (#2884) — halt-and-throw,
+        // exactly like an unhandled effect error.
+                if (!i && s & STATUS_ERROR) {
+            haltReactivity(unwrapStatusError(n));
+            throw n;
+        }
+    };
+    r.R = e;
+    r.C &= ~CONFIG_AUTO_DISPOSE;
+    recompute(r, true);
+    return r;
+}
+
+function createBoundChildren(t, e, r, s) {
+    const n = t.T;
+    n.addChild(t.T = r);
+    cleanup(() => n.removeChild(t.T));
+    return runWithOwner(t, () => {
+        const t = computed(e);
+        return boundaryComputed(() => flatten(read(t)), s);
+    });
+}
+
+const ON_INIT = Symbol();
+
+const RevealControllerContext = /* @__PURE__ */ createContext(null);
+
+let _revealUsed = false;
+
+const FALSE_ACCESSOR = () => false;
+
+const SEQUENTIAL_ACCESSOR = () => "sequential";
+
+function isRevealController(t) {
+    return t instanceof RevealController;
+}
+
+function isSlotReady(t) {
+    return isRevealController(t) ? t.N() : t.O.size === 0 && !t.I;
+}
+
+function isSlotMinimallyReady(t) {
+    return isRevealController(t) ? t.U() : isSlotReady(t);
+}
+
+function setSlotState(t, e, r, s) {
+    setSignal(t.v, r);
+    setSignal(t.D, s);
+    if (isRevealController(t)) {
+        if (!r && t.P === e) t.P = undefined;
+        return t.B(r, s);
+    }
+    if (!r && t.W === e && t.H) t.W = undefined;
+}
+
+class RevealController {
+    L;
+    F;
+    V=[];
+    P;
+    v=signal(false, {
+        ownedWrite: true,
+        q: true
+    });
+    D=signal(false, {
+        ownedWrite: true,
+        q: true
+    });
+    Z=true;
+    J=true;
+    K=false;
+    constructor(t, e) {
+        this.L = t;
+        this.F = e;
+    }
+    X(t) {
+        for (let e = 0; e < this.V.length; e++) {
+            const r = this.V[e];
+            if ((isRevealController(r) ? r.P : r.W) !== this) continue;
+            if (t(r) === false) return false;
+        }
+        return true;
+    }
+    N() {
+        return this.X(isSlotReady);
+    }
+    /**
+     * "Minimally ready" = this group has something visible to show under its own policy.
+     * Used by an enclosing `together` group to decide when it can release.
+     * - `together`: every direct slot is minimally ready.
+     * - `sequential`: the first owned slot is minimally ready (frontier can advance).
+     * - `natural`: any owned slot is minimally ready.
+     */    U() {
+        const t = untrack(this.L);
+        if (t === "together") return this.X(isSlotMinimallyReady);
+        if (t === "natural") {
+            let t = false;
+            let e = false;
+            this.X(r => {
+                t = true;
+                if (isSlotMinimallyReady(r)) {
+                    e = true;
+                    return false;
+                }
+            });
+            return !t || e;
+        }
+        // sequential: only the first owned slot matters.
+                let e = true;
+        this.X(t => {
+            e = isSlotMinimallyReady(t);
+            return false;
+        });
+        return e;
+    }
+    Y(t) {
+        if (this.V.includes(t)) return;
+        this.V.push(t);
+        const e = untrack(this.L);
+        setSignal(t.v, true), setSignal(t.D, e === "sequential" ? !!untrack(this.F) : false);
+        untrack(() => this.B());
+    }
+    $(t) {
+        const e = this.V.indexOf(t);
+        if (e >= 0) this.V.splice(e, 1);
+        untrack(() => this.B());
+    }
+    B(t, e) {
+        if (this.K) return;
+        this.K = true;
+        const r = this.Z;
+        const s = this.J;
+        try {
+            const r = t ?? read(this.v), s = untrack(this.L), n = s === "sequential" && !!untrack(this.F), i = e ?? n;
+            if (r) {
+                // Held by an outer group. Propagate the hold (and whatever collapsed policy
+                // the outer asked for) down the whole subtree. Inner order is ignored while
+                // held; it resumes once the outer releases us.
+                this.X(t => setSlotState(t, this, true, i));
+            } else if (s === "natural") {
+                // Each child reveals based on its own readiness. A nested controller slot
+                // is released to run its own order locally — we bypass setSlotState for it
+                // so the parent backpointer survives for upward readiness notifications.
+                this.X(t => {
+                    if (isRevealController(t)) {
+                        setSignal(t.D, false);
+                        setSignal(t.v, false);
+                        t.B(false, false);
+                    } else {
+                        setSlotState(t, this, !isSlotReady(t), false);
+                    }
+                });
+            } else if (s === "together") {
+                // Release when every direct slot is minimally ready (has something to show
+                // under its own order). A fully-ready inner together is minimally ready;
+                // sequential's first slot being ready is minimally ready; natural having any
+                // ready child is minimally ready. This lets `together` guarantee a single
+                // cohesive reveal without waiting for every grandchild.
+                const t = this.X(isSlotMinimallyReady);
+                this.X(e => setSlotState(e, this, !t, false));
+            } else {
+                let t = false;
+                this.X(e => {
+                    if (t) return setSlotState(e, this, true, n);
+                    if (isSlotReady(e)) return setSlotState(e, this, false, false);
+                    t = true;
+                    // Frontier slot. For a leaf, holding `_disabled=true` is what keeps its
+                    // fallback visible. For a composite, we instead release it so it runs
+                    // its own order locally — its leaves will each show their own fallback
+                    // until their data lands. Outer still waits on full readiness before
+                    // advancing past this slot, and we bypass setSlotState so the parent
+                    // backpointer survives for upward readiness notifications.
+                                        if (isRevealController(e)) {
+                        setSignal(e.D, false);
+                        setSignal(e.v, false);
+                        e.B(false, false);
+                    } else {
+                        setSlotState(e, this, true, false);
+                    }
+                });
+            }
+        } finally {
+            this.Z = this.N();
+            this.J = this.U();
+            this.K = false;
+        }
+        if (this.P && (r !== this.Z || s !== this.J)) this.P.B();
+    }
+}
+
+class CollectionQueue extends Queue {
+    tt;
+    O=new Set;
+    et;
+    I=true;
+    v=signal(false, {
+        ownedWrite: true,
+        q: true
+    });
+    _;
+    D=signal(false, {
+        ownedWrite: true,
+        q: true
+    });
+    W;
+    H=false;
+    rt;
+    st=ON_INIT;
+    /** The boundary's owner — where a `caught` report locates itself, set before the children are built (a creation-time throw arrives before `_tree`). */
+    nt;
+    constructor(t) {
+        super();
+        this.tt = t;
+    }
+    run(t) {
+        if (!t || read(this.v) && (!_revealUsed || read(this.D))) return;
+        return super.run(t);
+    }
+    /** The `on` key, or ON_INIT when it throws. Evaluated mid-propagation,
+     * inside the pending node's own pass: read as a spectator so the key's
+     * sources never become that node's dependencies (#3528). */    it() {
+        return spectate(() => {
+            try {
+                return this.rt();
+            } catch {
+                return ON_INIT;
+            }
+        });
+    }
+    notify(t, e, r, s) {
+        if (!(e & this.tt)) return super.notify(t, e, r, s);
+        if (this.H && this.rt) {
+            const t = this.it();
+            if (t !== this.st) {
+                this.st = t;
+                this.H = false;
+                this.O.clear();
+                // Readers forwarded while this boundary showed content are behind the
+                // fallback now: they stop blocking (`reporterBlocksSource`), and the
+                // transactions they were holding must be re-judged for it (A33, #3375).
+                // What those readers still wait on is this boundary's to wait on now:
+                // they never re-notify (status propagation dedupes on the reader's
+                // `_pendingSources`), so the reset collects it from their registrations
+                // — the one place a forwarded reader is recorded (INV-3) — or a sibling
+                // reader's flight that lands first reveals them stale (A33, #3459).
+                                for (const t of transitions) for (const [e, r] of t.ot) for (const t of r) if (this.lt(t)) {
+                    this.O.add(e);
+                    t.o?.ut?.forEach(t => this.O.add(t));
+                }
+                if (this.O.size) {
+                    setSignal(this.v, true);
+                    if (attrHooks !== null && this.tt & STATUS_PENDING) attrHooks.boundaryFallback(this, this.et, true);
+                }
+                wakeParked();
+            }
+        }
+        // Routing is dimension-independent: each boundary consumes only its own
+        // status dimension from the mask (`type &= ~collectionType` below) and
+        // forwards the remainder up the queue chain. An error inside a `Loading`
+        // needs no special rule — the ERROR dimension survives consumption here and
+        // reaches the `Errored` that catches it natively, and `flags & collectionType`
+        // keeps this boundary from collecting a node that isn't actually pending.
+        // Symmetrically, a pending inside an `Errored` forwards on the PENDING
+        // dimension, while a status already caught by an inner boundary arrives with
+        // its dimension consumed from the mask and is correctly not re-routed
+        // (the Loading > Errored > content composition escape, #2856).
+                if (this.tt & STATUS_PENDING && this.H) return super.notify(t, e, r, s);
+        if (r & this.tt) {
+            this.I = true;
+            const e = s?.source || t.o?._?.source;
+            if (e) {
+                const r = this.O.size === 0;
+                this.O.add(e);
+                // A collecting boundary waits on everything the effect is pending on,
+                // not only the source this notification carries. Status propagation
+                // dedupes on the effect's `_pendingSources`: a source it already
+                // carries (a flight that started before an `on` reset cleared the
+                // set) is never re-reported, and that source's later re-flight
+                // stays invisible — the boundary revealed when its one collected
+                // source settled while the effect was still pending (#3375).
+                                if (this.tt & STATUS_PENDING) t.o?.ut?.forEach(t => this.O.add(t));
+                if (r) {
+                    setSignal(this.v, true);
+                    if (attrHooks !== null && this.tt & STATUS_PENDING) attrHooks.boundaryFallback(this, this.et, true);
+                }
+                if (this.tt & STATUS_ERROR) {
+                    const t = unwrapStatusError(e.o?._);
+                    setSignal(this._, t);
+                    // The client error hook: this boundary renders its fallback for
+                    // it — the one road a rendered failure took that no global handler
+                    // ever saw. `source` is the computation that threw (the status
+                    // wrapper's, made at the first landing and kept downstream), so the
+                    // hook hears where it broke as well as where it was met. Once per
+                    // error object; a `reset()` re-collecting the same failure says
+                    // nothing new.
+                                        reportClientError(t, this.nt, e);
+                }
+            }
+        }
+        e &= ~this.tt;
+        return e ? super.notify(t, e, r, s) : true;
+    }
+    /** Is `reporter` live and routed to this boundary — under it, with no
+     * collecting pending-type boundary in between (`reporterBlocksSource`'s test)? */    lt(t) {
+        if (t.ft & (REACTIVE_ZOMBIE | REACTIVE_DISPOSED)) return false;
+        for (let e = t.T; e; e = e._parent) {
+            if (e === this) return true;
+            if (e.tt & STATUS_PENDING && !e.H) return false;
+        }
+        return false;
+    }
+    ct() {
+        for (const t of this.O) {
+            // A source with a live affects() mark holds display state for the
+            // mark's lifetime (the visual channel): the marked node carries no
+            // status of its own, so the count is the liveness test. The release
+            // sweep (finalizePureQueue after mark release) re-runs this check.
+            if (t.ft & REACTIVE_DISPOSED || !t.o?.t && !(t.S & this.tt) && !(this.tt & STATUS_ERROR && t.S & STATUS_PENDING)) this.O.delete(t);
+        }
+        if (!this.O.size) {
+            if (this.tt & STATUS_PENDING && this.I && !this.H && this.et) {
+                this.I = !!(this.et.S & this.tt);
+            } else {
+                this.I = false;
+            }
+            if (!this.I) {
+                setSignal(this.v, false);
+                if (attrHooks !== null && this.tt & STATUS_PENDING) attrHooks.boundaryFallback(this, this.et, false);
+                if (this.rt) {
+                    // A throw (value not yet committed) leaves _prevOn stale; the next
+                    // notify then resets.
+                    const t = this.it();
+                    if (t !== ON_INIT) this.st = t;
+                }
+            }
+        }
+        if (_revealUsed) this.W?.B();
+    }
+}
+
+function createCollectionBoundary(t, e, r, s) {
+    const n = createOwner();
+    if (_revealUsed) setContext(RevealControllerContext, null, n);
+    const i = new CollectionQueue(t);
+    i.nt = n;
+    if (t === STATUS_ERROR) i._ = signal(undefined, {
+        ownedWrite: true,
+        q: true
+    });
+    if (s) i.rt = s;
+    const o = i.et = createBoundChildren(n, e, i, t);
+    // Prime source tracking so reveal registration sees pending sources.
+        untrack(() => {
+        let e = false;
+        try {
+            read(o);
+        } catch (t) {
+            if (t instanceof NotReadyError) e = true; else throw t;
+        }
+        i.I = e || !!(o.S & t) || o.o?._ instanceof NotReadyError;
+    });
+    const l = _revealUsed && t === STATUS_PENDING ? getContext(RevealControllerContext) : null;
+    if (l) {
+        i.W = l;
+        l.Y(i);
+        cleanup(() => l.$(i));
+    }
+    return accessor(computed(() => {
+        if (!read(i.v)) {
+            const t = read(o);
+            if (!untrack(() => read(i.v))) return i.H = true, t;
+        }
+        // Collapsed reveal slots suppress their own output entirely; the
+        // renderer treats the hole as empty, so the cast never leaks to users
+        // outside a `createRevealOrder` scope.
+                if (_revealUsed && read(i.D)) return undefined;
+        return r(i);
+    }, 
+    // Boundary structure, not a user source: its value is fallback-or-content and
+    // legitimately swaps mid-hydration (reveal/resume), so it must never be frozen
+    // by snapshot capture. The tree no longer carries foreign status flags, so
+    // capture can't rely on PENDING to skip this node the way it used to.
+    {
+        q: true
+    }));
+}
+
+/**
+ * Lower-level primitive that backs the `<Loading>` flow control. Catches
+ * pending async reads inside `fn` and renders `fallback` until they settle.
+ *
+ * App code should use `<Loading fallback={...}>` instead — reach for this only
+ * when authoring custom boundary components.
+ *
+ * @param fn the tracked subtree
+ * @param fallback the fallback shown while async reads in `fn` are unresolved
+ * @param options `on` — accessor whose value scopes the boundary; when set,
+ *   transitions caused by writes to other reactive sources are *not* caught
+ *
+ * @example
+ * ```tsx
+ * // Custom boundary component built on top of the primitive.
+ * function MyLoading(props: { fallback: JSX.Element; children: JSX.Element }) {
+ *   return createLoadingBoundary(
+ *     () => props.children,
+ *     () => props.fallback
+ *   ) as unknown as JSX.Element;
+ * }
+ * ```
+ */ function createLoadingBoundary(t, e, r) {
+    return createCollectionBoundary(STATUS_PENDING, t, () => e(), r?.on);
+}
+
+/**
+ * Lower-level primitive that backs the `<Errored>` flow control. Catches
+ * thrown errors inside `fn` and invokes `fallback(error, reset)` instead.
+ * `error` is an accessor for the latest captured error; `reset()` recomputes
+ * the failing sources so the boundary can attempt to recover.
+ *
+ * App code should use `<Errored fallback={...}>` instead — reach for this only
+ * when authoring custom boundary components.
+ *
+ * @example
+ * ```tsx
+ * // Custom boundary that wraps the primitive and adds telemetry.
+ * function TracedErrored(props: { fallback: (e: () => unknown) => JSX.Element; children: JSX.Element }) {
+ *   return createErrorBoundary(
+ *     () => props.children,
+ *     (err, reset) => {
+ *       reportError(err());
+ *       return props.fallback(err);
+ *     }
+ *   ) as unknown as JSX.Element;
+ * }
+ * ```
+ */ function createErrorBoundary(t, e) {
+    return createCollectionBoundary(STATUS_ERROR, t, t => e(accessor(t._), () => {
+        for (const e of t.O) {
+            // Non-computed sources (patch-channel registrations under plain
+            // owners) are not recomputable — their reset is the record's next
+            // transition re-applying the patch (re-audit 2, P1-4).
+            if (e.ht !== undefined) recompute(e);
+        }
+        schedule();
+    }));
+}
+
+/**
+ * Coordinate the reveal timing of sibling loading boundaries.
+ *
+ * Accepts reactive accessors:
+ * - `order`: `"sequential"` (default) | `"together"` | `"natural"`.
+ *   - `"sequential"` — classic frontier reveal: siblings reveal in registration order
+ *     as each resolves; later siblings stay hidden until earlier ones complete.
+ *   - `"together"` — every direct slot stays on its fallback until the whole group
+ *     is "minimally ready" (each direct slot has produced its own first visible
+ *     content under its own order), then the whole group releases at once.
+ *   - `"natural"` — children reveal independently (as each resolves). At the top
+ *     level this is a no-op compared to not using `createRevealOrder`; the mode
+ *     exists for nesting, where the group registers as a single composite slot to
+ *     any enclosing `createRevealOrder`.
+ * - `collapsed`: only meaningful when `order === "sequential"`. When set, tail siblings
+ *   past the frontier suppress their own fallback output. Ignored under `"together"`
+ *   and `"natural"` — those orders have no frontier.
+ *
+ * Nested `createRevealOrder` groups compose: the inner controller registers as a
+ * single slot in the outer controller and is held on its fallbacks until the outer
+ * releases that slot. Once released, the inner controller runs its own order locally
+ * over anything still pending. There is no opt-out from an outer hold.
+ *
+ * "Minimally ready" is what an order considers its first visible content:
+ * - `sequential` — frontier-0 is minimally ready (leaf: on resolve; nested: via its
+ *   own minimal signal).
+ * - `together` — every direct slot is minimally ready.
+ * - `natural` — any direct slot has visible content (leaves on resolve; nested
+ *   composites via their own minimal signal).
+ *
+ * @example
+ * ```ts
+ * // Primitive form of `<Reveal>` — coordinate sibling loading boundaries
+ * // programmatically. App code uses the JSX `<Reveal>` component instead.
+ * // Both options are accessors so they can react to state changes.
+ * createRevealOrder(
+ *   () => renderSiblings(),
+ *   { order: () => mode(), collapsed: () => true }
+ * );
+ * ```
+ */ function createRevealOrder(t, e) {
+    _revealUsed = true;
+    const r = createOwner();
+    const s = getContext(RevealControllerContext);
+    const n = e?.order || SEQUENTIAL_ACCESSOR, i = e?.collapsed || FALSE_ACCESSOR;
+    const o = new RevealController(n, i);
+    setContext(RevealControllerContext, o, r);
+    return runWithOwner(r, () => {
+        const e = t();
+        computed(() => {
+            n();
+            i();
+            o.B();
+        });
+        if (s) {
+            o.P = s;
+            s.Y(o);
+            cleanup(() => s.$(o));
+        }
+        return e;
+    });
+}
+
+/**
+ * Resolves a children value to its renderable form: unwraps zero-arg functions
+ * (accessors), recursively flattens arrays, and optionally skips
+ * non-rendering values (`null`, `undefined`, `true`, `false`, `""`).
+ *
+ * Used internally by flow components and by the renderer to walk a children
+ * tree. App code rarely needs this directly — see `children()` in `solid-js`
+ * for the user-facing helper that memoizes the result.
+ *
+ * @param children value or array of values to flatten
+ * @param options
+ *   - `skipNonRendered` — drop values that won't render
+ *   - `doNotUnwrap` — leave function children as-is (caller will resolve)
+ *
+ * @example
+ * ```ts
+ * // Custom renderer walking a children tree manually. Most authors should
+ * // use `children()` from solid-js, which memoizes the resolved value.
+ * function renderChildren(value: unknown): unknown {
+ *   return flatten(value, { skipNonRendered: true });
+ * }
+ * ```
+ */ function flatten(t, e) {
+    if (typeof t === "function" && !t.length) {
+        if (e?.doNotUnwrap) return t;
+        do {
+            t = t();
+        } while (typeof t === "function" && !t.length);
+    }
+    if (e?.skipNonRendered && (t == null || t === true || t === false || t === "")) return;
+    if (Array.isArray(t)) {
+        let r = [];
+        if (flattenArray(t, r, e)) {
+            return () => {
+                let t = [];
+                flattenArray(r, t, {
+                    ...e,
+                    doNotUnwrap: false
+                });
+                return t;
+            };
+        }
+        return r;
+    }
+    return t;
+}
+
+function flattenArray(t, e = [], r) {
+    let s = null;
+    let n = false;
+    for (let i = 0; i < t.length; i++) {
+        try {
+            let s = t[i];
+            if (typeof s === "function" && !s.length) {
+                if (r?.doNotUnwrap) {
+                    e.push(s);
+                    n = true;
+                    continue;
+                }
+                do {
+                    s = s();
+                } while (typeof s === "function" && !s.length);
+            }
+            if (Array.isArray(s)) {
+                // OR, don't overwrite: an accessor already pushed under doNotUnwrap
+                // still needs the resolving wrapper even when a later sibling
+                // fragment contains no functions (#3133).
+                n = flattenArray(s, e, r) || n;
+            } else if (r?.skipNonRendered && (s == null || s === true || s === false || s === "")) {
+                // skip
+            } else e.push(s);
+        } catch (t) {
+            if (!(t instanceof NotReadyError)) throw t;
+            s = t;
+        }
+    }
+    if (s) throw s;
+    return n;
+}
+
+export { CollectionQueue, RevealController, createErrorBoundary, createLoadingBoundary, createRevealOrder, flatten };