@solidjs/signals 2.0.0-beta.17 → 2.0.0-beta.19

package/dist/prod/boundaries.js

@@ -0,0 +1,568 @@
+import { runWithOwner, signal, untrack, read, computed, setSignal, recompute } from "./core/core.js";
+
+import { NotReadyError, unwrapStatusError } from "./core/error.js";
+
+import { createOwner, cleanup } from "./core/owner.js";
+
+import { Queue, haltReactivity, schedule } from "./core/scheduler.js";
+
+import { getContext, setContext, createContext } from "./core/context.js";
+
+import { STATUS_PENDING, STATUS_ERROR, REACTIVE_DISPOSED, CONFIG_AUTO_DISPOSE } from "./core/constants.js";
+
+import "./core/invariants.js";
+
+import "./core/verdict.js";
+
+import "./core/effect.js";
+
+import { accessor } from "./signals.js";
+
+function boundaryComputed(e, t) {
+    const r = computed(e, {
+        lazy: true
+    });
+    r.C = (e, t) => {
+        // Use passed values if provided, otherwise read from node
+        const n = e !== undefined ? e : r.i;
+        const s = t !== undefined ? t : r.k;
+        // 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.i &= ~r.O;
+        const i = r.v.notify(r, STATUS_PENDING | STATUS_ERROR, n, s);
+        // 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 = n & ~r.O & (STATUS_PENDING | STATUS_ERROR);
+        if (o) {
+            r.i &= ~o;
+            if (r.k === s && !(r.i & (STATUS_PENDING | STATUS_ERROR))) r.k = 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 && n & STATUS_ERROR) {
+            haltReactivity(unwrapStatusError(s));
+            throw s;
+        }
+    };
+    r.O = t;
+    r.U &= ~CONFIG_AUTO_DISPOSE;
+    recompute(r, true);
+    return r;
+}
+
+function createBoundChildren(e, t, r, n) {
+    const s = e.v;
+    s.addChild(e.v = r);
+    cleanup(() => s.removeChild(e.v));
+    return runWithOwner(e, () => {
+        const e = computed(t);
+        return boundaryComputed(() => flatten(read(e)), n);
+    });
+}
+
+const ON_INIT = Symbol();
+
+const RevealControllerContext = /* @__PURE__ */ createContext(null);
+
+let _revealUsed = false;
+
+const FALSE_ACCESSOR = () => false;
+
+const SEQUENTIAL_ACCESSOR = () => "sequential";
+
+function isRevealController(e) {
+    return e instanceof RevealController;
+}
+
+function isSlotReady(e) {
+    return isRevealController(e) ? e.B() : e.W.size === 0 && !e.L;
+}
+
+function isSlotMinimallyReady(e) {
+    return isRevealController(e) ? e.q() : isSlotReady(e);
+}
+
+function setSlotState(e, t, r, n) {
+    setSignal(e.V, r);
+    setSignal(e.H, n);
+    if (isRevealController(e)) {
+        if (!r && e.J === t) e.J = undefined;
+        return e.K(r, n);
+    }
+    if (!r && e.X === t && e.Y) e.X = undefined;
+}
+
+class RevealController {
+    Z;
+    ee;
+    te=[];
+    J;
+    V=signal(false, {
+        ownedWrite: true,
+        re: true
+    });
+    H=signal(false, {
+        ownedWrite: true,
+        re: true
+    });
+    ne=true;
+    se=true;
+    ie=false;
+    constructor(e, t) {
+        this.Z = e;
+        this.ee = t;
+    }
+    oe(e) {
+        for (let t = 0; t < this.te.length; t++) {
+            const r = this.te[t];
+            if ((isRevealController(r) ? r.J : r.X) !== this) continue;
+            if (e(r) === false) return false;
+        }
+        return true;
+    }
+    B() {
+        return this.oe(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.
+     */    q() {
+        const e = untrack(this.Z);
+        if (e === "together") return this.oe(isSlotMinimallyReady);
+        if (e === "natural") {
+            let e = false;
+            let t = false;
+            this.oe(r => {
+                e = true;
+                if (isSlotMinimallyReady(r)) {
+                    t = true;
+                    return false;
+                }
+            });
+            return !e || t;
+        }
+        // sequential: only the first owned slot matters.
+                let t = true;
+        this.oe(e => {
+            t = isSlotMinimallyReady(e);
+            return false;
+        });
+        return t;
+    }
+    le(e) {
+        if (this.te.includes(e)) return;
+        this.te.push(e);
+        const t = untrack(this.Z);
+        setSignal(e.V, true), setSignal(e.H, t === "sequential" ? !!untrack(this.ee) : false);
+        untrack(() => this.K());
+    }
+    ae(e) {
+        const t = this.te.indexOf(e);
+        if (t >= 0) this.te.splice(t, 1);
+        untrack(() => this.K());
+    }
+    K(e, t) {
+        if (this.ie) return;
+        this.ie = true;
+        const r = this.ne;
+        const n = this.se;
+        try {
+            const r = e ?? read(this.V), n = untrack(this.Z), s = n === "sequential" && !!untrack(this.ee), i = t ?? s;
+            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.oe(e => setSlotState(e, this, true, i));
+            } else if (n === "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.oe(e => {
+                    if (isRevealController(e)) {
+                        setSignal(e.H, false);
+                        setSignal(e.V, false);
+                        e.K(false, false);
+                    } else {
+                        setSlotState(e, this, !isSlotReady(e), false);
+                    }
+                });
+            } else if (n === "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 e = this.oe(isSlotMinimallyReady);
+                this.oe(t => setSlotState(t, this, !e, false));
+            } else {
+                let e = false;
+                this.oe(t => {
+                    if (e) return setSlotState(t, this, true, s);
+                    if (isSlotReady(t)) return setSlotState(t, this, false, false);
+                    e = 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(t)) {
+                        setSignal(t.H, false);
+                        setSignal(t.V, false);
+                        t.K(false, false);
+                    } else {
+                        setSlotState(t, this, true, false);
+                    }
+                });
+            }
+        } finally {
+            this.ne = this.B();
+            this.se = this.q();
+            this.ie = false;
+        }
+        if (this.J && (r !== this.ne || n !== this.se)) this.J.K();
+    }
+}
+
+class CollectionQueue extends Queue {
+    ue;
+    W=new Set;
+    ce;
+    L=true;
+    V=signal(false, {
+        ownedWrite: true,
+        re: true
+    });
+    k;
+    H=signal(false, {
+        ownedWrite: true,
+        re: true
+    });
+    X;
+    Y=false;
+    fe;
+    he=ON_INIT;
+    constructor(e) {
+        super();
+        this.ue = e;
+    }
+    run(e) {
+        if (!e || read(this.V) && (!_revealUsed || read(this.H))) return;
+        return super.run(e);
+    }
+    notify(e, t, r, n) {
+        if (!(t & this.ue)) return super.notify(e, t, r, n);
+        if (this.Y && this.fe) {
+            const e = untrack(() => {
+                try {
+                    return this.fe();
+                } catch {
+                    return ON_INIT;
+                }
+            });
+            if (e !== this.he) {
+                this.he = e;
+                this.Y = false;
+                this.W.clear();
+            }
+        }
+        // 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.ue & STATUS_PENDING && this.Y) return super.notify(e, t, r, n);
+        if (r & this.ue) {
+            this.L = true;
+            const t = n?.source || e.k?.source;
+            if (t) {
+                const e = this.W.size === 0;
+                this.W.add(t);
+                if (e) setSignal(this.V, true);
+                if (this.ue & STATUS_ERROR) {
+                    setSignal(this.k, unwrapStatusError(t.k));
+                }
+            }
+        }
+        t &= ~this.ue;
+        return t ? super.notify(e, t, r, n) : true;
+    }
+    Se() {
+        for (const e of this.W) {
+            if (e.u & REACTIVE_DISPOSED || !(e.i & this.ue) && !(this.ue & STATUS_ERROR && e.i & STATUS_PENDING)) this.W.delete(e);
+        }
+        if (!this.W.size) {
+            if (this.ue & STATUS_PENDING && this.L && !this.Y && this.ce) {
+                this.L = !!(this.ce.i & this.ue);
+            } else {
+                this.L = false;
+            }
+            if (!this.L) {
+                setSignal(this.V, false);
+                if (this.fe) {
+                    try {
+                        this.he = untrack(() => this.fe());
+                    } catch {
+                        /* value not yet committed — _prevOn stays stale, next notify will reset */}
+                }
+            }
+        }
+        if (_revealUsed) this.X?.K();
+    }
+}
+
+function createCollectionBoundary(e, t, r, n) {
+    const s = createOwner();
+    if (_revealUsed) setContext(RevealControllerContext, null, s);
+    const i = new CollectionQueue(e);
+    if (e === STATUS_ERROR) i.k = signal(undefined, {
+        ownedWrite: true,
+        re: true
+    });
+    if (n) i.fe = n;
+    const o = i.ce = createBoundChildren(s, t, i, e);
+    // Prime source tracking so reveal registration sees pending sources.
+        untrack(() => {
+        let t = false;
+        try {
+            read(o);
+        } catch (e) {
+            if (e instanceof NotReadyError) t = true; else throw e;
+        }
+        i.L = t || !!(o.i & e) || o.k instanceof NotReadyError;
+    });
+    const l = _revealUsed && e === STATUS_PENDING ? getContext(RevealControllerContext) : null;
+    if (l) {
+        i.X = l;
+        l.le(i);
+        cleanup(() => l.ae(i));
+    }
+    return accessor(computed(() => {
+        if (!read(i.V)) {
+            const e = read(o);
+            if (!untrack(() => read(i.V))) return i.Y = true, e;
+        }
+        // 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.H)) 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.
+    {
+        re: 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(e, t, r) {
+    return createCollectionBoundary(STATUS_PENDING, e, () => t(), 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(e, t) {
+    return createCollectionBoundary(STATUS_ERROR, e, e => t(accessor(e.k), () => {
+        for (const t of e.W) recompute(t);
+        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(e, t) {
+    _revealUsed = true;
+    const r = createOwner();
+    const n = getContext(RevealControllerContext);
+    const s = t?.order || SEQUENTIAL_ACCESSOR, i = t?.collapsed || FALSE_ACCESSOR;
+    const o = new RevealController(s, i);
+    setContext(RevealControllerContext, o, r);
+    return runWithOwner(r, () => {
+        const t = e();
+        computed(() => {
+            s();
+            i();
+            o.K();
+        });
+        if (n) {
+            o.J = n;
+            n.le(o);
+            cleanup(() => n.ae(o));
+        }
+        return t;
+    });
+}
+
+/**
+ * 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(e, t) {
+    if (typeof e === "function" && !e.length) {
+        if (t?.doNotUnwrap) return e;
+        do {
+            e = e();
+        } while (typeof e === "function" && !e.length);
+    }
+    if (t?.skipNonRendered && (e == null || e === true || e === false || e === "")) return;
+    if (Array.isArray(e)) {
+        let r = [];
+        if (flattenArray(e, r, t)) {
+            return () => {
+                let e = [];
+                flattenArray(r, e, {
+                    ...t,
+                    doNotUnwrap: false
+                });
+                return e;
+            };
+        }
+        return r;
+    }
+    return e;
+}
+
+function flattenArray(e, t = [], r) {
+    let n = null;
+    let s = false;
+    for (let i = 0; i < e.length; i++) {
+        try {
+            let n = e[i];
+            if (typeof n === "function" && !n.length) {
+                if (r?.doNotUnwrap) {
+                    t.push(n);
+                    s = true;
+                    continue;
+                }
+                do {
+                    n = n();
+                } while (typeof n === "function" && !n.length);
+            }
+            if (Array.isArray(n)) {
+                s = flattenArray(n, t, r);
+            } else if (r?.skipNonRendered && (n == null || n === true || n === false || n === "")) {
+                // skip
+            } else t.push(n);
+        } catch (e) {
+            if (!(e instanceof NotReadyError)) throw e;
+            n = e;
+        }
+    }
+    if (n) throw n;
+    return s;
+}
+
+export { CollectionQueue, RevealController, createErrorBoundary, createLoadingBoundary, createRevealOrder, flatten };

package/dist/prod/core/action.js

@@ -0,0 +1,83 @@
+import { globalQueue, activeTransition, currentTransition, setActiveTransition, schedule, flush } from "./scheduler.js";
+
+import { isThenable } from "./async.js";
+
+import "./core.js";
+
+function restoreTransition(e, n) {
+    globalQueue.initTransition(e);
+    const t = n();
+    flush();
+    return t;
+}
+
+/**
+ * Wraps a generator function so each invocation runs as a single transaction
+ * (a "transition") that batches every signal/store write between yields. The
+ * surrounding UI sees one atomic update per yielded step; nothing is committed
+ * until the action either completes or the next `yield` resolves.
+ *
+ * Yield promises (or any awaitable) inside the generator — the action waits
+ * for each before continuing, but the writes you made beforehand are already
+ * visible (or held by `<Loading>` if optimistic). Yield bare values for
+ * synchronous batched steps.
+ *
+ * Each call returns a `Promise` that resolves with the generator's return
+ * value, or rejects if it throws. Pair with `createOptimistic` /
+ * `createOptimisticStore` to apply tentative writes that auto-revert if the
+ * action fails.
+ *
+ * @example
+ * ```ts
+ * const [todos, setTodos] = createOptimisticStore<Todo[]>([]);
+ *
+ * const addTodo = action(function* (text: string) {
+ *   const tempId = crypto.randomUUID();
+ *   setTodos(t => { t.push({ id: tempId, text, pending: true }); }); // optimistic
+ *   const saved = yield api.createTodo(text); // network round-trip
+ *   setTodos(t => {
+ *     const i = t.findIndex(x => x.id === tempId);
+ *     if (i >= 0) t[i] = saved;
+ *   });
+ *   return saved;
+ * });
+ *
+ * await addTodo("buy milk");
+ * ```
+ */ function action(e) {
+    return (...n) => new Promise((t, r) => {
+        const i = e(...n);
+        globalQueue.initTransition();
+        let o = activeTransition;
+        o.Te.push(i);
+        const done = (e, n, s = false) => {
+            o = currentTransition(o);
+            const u = o.Te.indexOf(i);
+            if (u >= 0) o.Te.splice(u, 1);
+            setActiveTransition(o);
+            schedule();
+            s ? r(n) : t(e);
+        };
+        const step = (e, n) => {
+            let t;
+            try {
+                t = n ? i.throw(e) : i.next(e);
+            } catch (e) {
+                return done(undefined, e, true);
+            }
+            // A rejected iterator result (async generators) means the error already
+            // escaped the generator body — it is completed, and throwing back in
+            // would just reject again forever. Settle instead.
+                        if (isThenable(t)) return void t.then(run, e => done(undefined, e, true));
+            run(t);
+        };
+        const run = e => {
+            if (e.done) return done(e.value);
+            if (isThenable(e.value)) return void e.value.then(e => restoreTransition(o, () => step(e)), e => restoreTransition(o, () => step(e, true)));
+            restoreTransition(o, () => step(e.value));
+        };
+        step();
+    });
+}
+
+export { action };