@solidjs/signals 2.0.0-rc.2 → 2.0.0-rc.20

package/dist/observe/core/error.js

@@ -0,0 +1,82 @@
+/**
+ * Thrown by a tracked read whose value is currently pending (an async memo /
+ * `createSignal(asyncFn)` / projection / store derivation that hasn't settled
+ * yet). Surfacing through the reactive graph is what suspends the consumer
+ * scope — the nearest enclosing `<Loading>` boundary catches the throw and
+ * renders its fallback until the source resolves.
+ *
+ * App code rarely catches this directly; `<Loading>` is the canonical
+ * handler. The error type is exposed for advanced cases — e.g. interop layers
+ * that bridge Solid's pending-throw protocol to a different async strategy,
+ * or tests that want to assert on the suspension shape.
+ *
+ * @example
+ * ```ts
+ * // Advanced: distinguish "not ready yet" from a real error in custom
+ * // boundary plumbing. App code should rely on `<Loading>` / `<Errored>`.
+ * try {
+ *   const value = readReactiveSource();
+ * } catch (err) {
+ *   if (err instanceof NotReadyError) throw err; // re-throw to suspend
+ *   reportError(err);
+ * }
+ * ```
+ */
+class NotReadyError extends Error {
+    constructor(r) {
+        // Control-flow throw: it happens on every read of a pending source, so in
+        // production skip V8's eager stack capture (proportional to stack depth —
+        // real cost under SSR) by zeroing the V8-specific stackTraceLimit around
+        // super(). Dev keeps the stack for debuggability; non-V8 engines (no
+        // stackTraceLimit) take the plain path.
+        const o = Error;
+        const t = o.stackTraceLimit;
+        if (t !== undefined) o.stackTraceLimit = 0;
+        super();
+        if (t !== undefined) o.stackTraceLimit = t;
+        this.source = r;
+    }
+}
+
+class StatusError extends Error {
+    constructor(r, o) {
+        // Best-effort message: formatting must never replace the original (#4112).
+        try {
+            var t = String(o instanceof Error ? o.message : o);
+        } catch {}
+        super(t, {
+            cause: o
+        });
+        this.source = r;
+    }
+}
+
+/** Return the user's error from an internal status wrapper. */ function unwrapStatusError(r) {
+    return r instanceof StatusError ? r.cause : r;
+}
+
+/**
+ * Rejection value of `until(fn, { timeout })` when the predicate does not turn
+ * truthy within the window. Inside an `action()`, the rejection is thrown back
+ * in at the `yield` point — catchable there, or the action fails and its
+ * optimistic state reverts.
+ */ class TimeoutError extends Error {
+    constructor(r = "Timed out waiting for condition") {
+        super(r);
+        this.name = "TimeoutError";
+    }
+}
+
+class NoOwnerError extends Error {
+    constructor() {
+        super("");
+    }
+}
+
+class ContextNotFoundError extends Error {
+    constructor() {
+        super("");
+    }
+}
+
+export { ContextNotFoundError, NoOwnerError, NotReadyError, StatusError, TimeoutError, unwrapStatusError };

package/dist/observe/core/external.js

@@ -0,0 +1,97 @@
+import { signal, setSignal, read } from "./core.js";
+
+import { cleanup } from "./owner.js";
+
+import { setExternalHooks } from "./scheduler.js";
+
+let externalSourceConfig = null;
+
+/**
+ * Registers a factory that bridges external reactive systems (e.g. MobX, Vue refs)
+ * into Solid's tracking graph. Every computation will be wrapped so that the
+ * external library can track its own dependencies alongside Solid's.
+ *
+ * Multiple calls pipe together: each new factory wraps the previous one.
+ *
+ * @param config.factory receives `(fn, trigger)` — wrap fn execution in external tracking,
+ *   call trigger when external deps change. Return `{ track, dispose }`.
+ * @param config.untrack optional wrapper for `untrack` — disables external tracking too.
+ *
+ * @example
+ * ```ts
+ * // Bridge an external "subscribe / notify" library into Solid's graph.
+ * // `factory` wraps every Solid compute so the external library can attach
+ * // its own dependency tracker; `trigger` re-runs the compute on external
+ * // change. `untrack` mirrors Solid's `untrack()` into the external library
+ * // so that reads inside `untrack(...)` don't get tracked twice.
+ * enableExternalSource({
+ *   factory: (compute, trigger) => {
+ *     const sub = externalLib.subscribe(trigger);
+ *     return {
+ *       track: prev => externalLib.run(() => compute(prev)),
+ *       dispose: () => sub.unsubscribe()
+ *     };
+ *   },
+ *   untrack: fn => externalLib.untracked(fn)
+ * });
+ * ```
+ */
+// Wires a freshly created computed through the active external-source bridge.
+// Lives here (installed as a scheduler hook while a config is active) rather than
+// inline in core: esbuild cannot literal-track the mutable config binding the
+// way rollup does, so an inline `if (externalSourceConfig)` block ships in
+// every bundle even though only enableExternalSource() can make it reachable.
+function wireExternalSource(e) {
+    const n = signal(undefined, {
+        equals: false,
+        ownedWrite: true
+    });
+    const r = externalSourceConfig.factory(e.X, () => {
+        setSignal(n, undefined);
+    });
+    cleanup(() => r.dispose());
+    e.X = e => {
+        read(n);
+        return r.track(e);
+    };
+}
+
+function externalUntrack(e) {
+    return externalSourceConfig.untrack(e);
+}
+
+// The hooks mirror the config's liveness exactly (installed on enable,
+// removed on reset) so core's presence checks stay equivalent to the old
+// `externalSourceConfig` truthiness checks.
+function syncExternalHooks() {
+    if (externalSourceConfig) setExternalHooks(wireExternalSource, externalUntrack); else setExternalHooks(undefined, undefined);
+}
+
+function enableExternalSource(e) {
+    const {factory: n, untrack: r = e => e()} = e;
+    if (externalSourceConfig) {
+        const {factory: e, untrack: o} = externalSourceConfig;
+        externalSourceConfig = {
+            factory: (r, o) => {
+                const t = e(r, o);
+                const a = n(e => t.track(e), o);
+                return {
+                    track: e => a.track(e),
+                    dispose() {
+                        a.dispose();
+                        t.dispose();
+                    }
+                };
+            },
+            untrack: e => o(() => r(e))
+        };
+    } else {
+        externalSourceConfig = {
+            factory: n,
+            untrack: r
+        };
+    }
+    syncExternalHooks();
+}
+
+export { enableExternalSource, externalSourceConfig };

package/dist/observe/core/graph.js

@@ -0,0 +1,162 @@
+import { NewSet, REACTIVE_RECOMPUTING_DEPS, CONFIG_AUTO_DISPOSE, STATUS_PENDING, REACTIVE_DISPOSED, REACTIVE_ZOMBIE, CONFIG_SLOT_NODE } from "./constants.js";
+
+import { deleteFromHeap } from "./heap.js";
+
+import { disposeChildren, runCleanup } from "./owner.js";
+
+import { bumpNotifyEpoch, dirtyQueue } from "./scheduler.js";
+
+/** The store's shared slot-node release handler (store/store.ts installs it
+ * once) — a live binding read directly by the sweep site: no wrapper frame,
+ * no null check (a CONFIG_SLOT_NODE node existing implies the store module
+ * loaded and registered it). */ let slotUnobservedHook;
+
+function setSlotUnobserved(e) {
+    slotUnobservedHook = e;
+}
+
+// https://github.com/stackblitz/alien-signals/blob/v2.0.3/src/system.ts#L100
+function unlinkSubs(e) {
+    const n = e.S;
+    const l = e.G;
+    const o = e.t;
+    const s = e.en;
+    if (o !== null) o.en = s; else n.Ot = s;
+    if (s !== null) s.t = o; else {
+        n.o = o;
+        if (o === null) {
+            // Store slot nodes dispatch to the ONE shared hook — no per-node
+            // unobserved closure, no NodeExtension to hold it.
+            // A user hook that throws is collected like a cleanup (owner.ts): the
+            // unlink and the teardown around it carry on.
+            if (n.l & CONFIG_SLOT_NODE) slotUnobservedHook(n); else if (n.T?.Gt) runCleanup(n.T.Gt);
+            // No more subscribers; only tear down if CONFIG_AUTO_DISPOSE is set.
+            // A pending node is exempt: its in-flight async work is an observer —
+            // tearing down would orphan the work and re-execute it on the next
+            // read. The settle path runs this same last-one-out check when that
+            // observer releases (the untracked-read dormancy sweep guards on
+            // pending identically).
+            // During a pass's teardown of its unfinished frame, the release waits
+            // for the pass to end (`deferredReleases`, #4142).
+                        const e = n;
+            e.X && e.l & CONFIG_AUTO_DISPOSE && !(e.R & REACTIVE_ZOMBIE) && !(e.m & STATUS_PENDING) && (deferredReleases ? deferredReleases.push(e) : unobserved(e));
+        }
+    }
+    return l;
+}
+
+function trimStaleDeps(e) {
+    const n = e._;
+    let l = n !== null ? n.G : e.C;
+    if (l !== null) {
+        do {
+            l = unlinkSubs(l);
+        } while (l !== null);
+        if (n !== null) n.G = null; else e.C = null;
+    }
+}
+
+// Shared by unobserved() and the disposeChildren child loop. The truthy guard
+// (not `!== null`) matters: plain Owners in a child chain have no _deps field,
+// and skipping early also avoids adding one (hidden-class churn) via the
+// null-out below.
+function clearDeps(e) {
+    let n = e.C;
+    if (!n) return;
+    do {
+        n = unlinkSubs(n);
+    } while (n !== null);
+    e.C = null;
+    e._ = null;
+}
+
+/**
+ * Last-one-out releases held back while a pass tears down the frame of an
+ * earlier pass that never committed (#4142). The pass is about to rebuild
+ * the same children, which read the same lazy nodes again. Released on the
+ * spot, a lazy async memo whose only reader was the old frame's child memo
+ * was torn down, re-ran on the new child's read, went pending, and the cycle
+ * repeated forever. `recompute` collects them around that teardown and
+ * releases what is still unobserved when the pass ends.
+ */ let deferredReleases = null;
+
+const deferReleases = e => deferredReleases = e;
+
+function unobserved(e) {
+    deleteFromHeap(e, dirtyQueue);
+    clearDeps(e);
+    disposeChildren(e, true);
+}
+
+/**
+ * Deferred dormancy for never-observed auto-dispose computeds (#3078).
+ *
+ * An untracked top-level read of a subscriber-less observation-lifecycle memo
+ * used to call unobserved() inline at the end of read(). That kept the leak
+ * closed (the compute links the memo into its deps' sub lists — without a
+ * teardown point a never-observed memo is retained by its sources forever;
+ * upstream alien-signals has exactly this retention), but it made reads
+ * destructive: each read disposed the node, the next read revived it with a
+ * full recompute in whatever ambient transition/lane context happened to be
+ * current, so consecutive reads could return different answers with no write
+ * in between.
+ *
+ * Instead, reads queue the node here and the scheduler sweeps at the top of
+ * the next flush (before runHeap, so a same-tick dirtying is reclaimed
+ * instead of recomputed). Reads become idempotent within a tick (the node
+ * stays alive and serves its cache, uniform with observed memos) while
+ * reclamation still happens within one microtask — the enqueue site arms
+ * schedule(), so a flush is guaranteed even when no other work is queued.
+ */ const dormantNodes = new NewSet;
+
+function sweepDormant() {
+    if (dormantNodes.size === 0) return;
+    for (const e of dormantNodes) {
+        // Re-validate at sweep time: the node may have gained a subscriber (its
+        // lifecycle is the unlinkSubs cascade now), gone pending (in-flight async
+        // is an observer; the settle path re-runs last-one-out), lost its
+        // AUTO_DISPOSE bit (owner teardown strips it, #3024), or already been
+        // torn down.
+        if (!e.o && e.l & CONFIG_AUTO_DISPOSE && !(e.m & STATUS_PENDING) && !(e.R & (REACTIVE_DISPOSED | REACTIVE_ZOMBIE))) {
+            unobserved(e);
+        }
+    }
+    dormantNodes.clear();
+}
+
+// https://github.com/stackblitz/alien-signals/blob/v2.0.3/src/system.ts#L52
+function link(e, n) {
+    const l = n._;
+    if (l !== null && l.S === e) return;
+    let o = null;
+    const s = n.R & REACTIVE_RECOMPUTING_DEPS;
+    if (s) {
+        o = l !== null ? l.G : n.C;
+        if (o !== null && o.S === e) {
+            o.de = n.Ne;
+            n._ = o;
+            return;
+        }
+    }
+    // A link stamped with the current pass generation was created or reused
+    // in-order during this recompute, i.e. it already sits in the validated
+    // [deps.._depsTail] prefix — the O(1) equivalent of scanning the dep list
+    // (the old alien-signals `isValidLink` walk, O(n²) when a computation
+    // re-reads earlier deps non-consecutively, e.g. store leaf reads).
+        const r = e.Ot;
+    if (r !== null && r.u === n && (!s || r.de === n.Ne)) return;
+    const t = n._ = e.Ot = {
+        S: e,
+        u: n,
+        G: o,
+        en: r,
+        t: null,
+        de: n.Ne
+    };
+    if (l !== null) l.G = t; else n.C = t;
+    if (r !== null) r.t = t; else e.o = t;
+    // New subscriber edge: staged-rewrite skips (§12d) must not miss it.
+        bumpNotifyEpoch();
+}
+
+export { clearDeps, deferReleases, deferredReleases, dormantNodes, link, setSlotUnobserved, slotUnobservedHook, sweepDormant, trimStaleDeps, unlinkSubs, unobserved };

package/dist/observe/core/heap.js

@@ -0,0 +1,124 @@
+import "./core.js";
+
+import { REACTIVE_IN_HEAP, REACTIVE_RECOMPUTING_DEPS, REACTIVE_CHECK, REACTIVE_DIRTY, REACTIVE_IN_HEAP_HEIGHT } from "./constants.js";
+
+import { dirtyQueue } from "./scheduler.js";
+
+/**
+ * Schedule one subscriber to re-run on the next flush: inserted into the
+ * dirty heap with the `_min` cursor pulled down. Tracked effects ride the
+ * heap too — the heap visit is their (empty) compute phase, which hands the
+ * callback to the user queue once the pass has committed (see
+ * GlobalQueue._update, #3291).
+ */ function enqueueSub(e) {
+    if (dirtyQueue.Et > e.lt) dirtyQueue.Et = e.lt;
+    insertIntoHeap(e, dirtyQueue);
+}
+
+function actualInsertIntoHeap(e, t) {
+    const E = (e._parent?.Pt ? e._parent.Ht?.lt : e._parent?.lt) ?? -1;
+    if (E >= e.lt) e.lt = E + 1;
+    const n = e.lt;
+    const I = t.jt[n];
+    if (I === undefined) t.jt[n] = e; else {
+        const t = I.Ct;
+        t.Rt = e;
+        e.Ct = t;
+        I.Ct = e;
+    }
+    if (n > t.yt) t.yt = n;
+}
+
+function insertIntoHeap(e, t) {
+    let E = e.R;
+    // RECOMPUTING refusals are not always losses: a genuinely missed wake (a
+    // write to a link this pass already validated) is latched link-side in
+    // insertSubs as REACTIVE_MISSED_WAKE for recompute's tail (#3037).
+        if (E & (REACTIVE_IN_HEAP | REACTIVE_RECOMPUTING_DEPS)) return;
+    if (E & REACTIVE_CHECK) {
+        e.R = E & -4 | REACTIVE_DIRTY | REACTIVE_IN_HEAP;
+    } else {
+        e.R = E | REACTIVE_IN_HEAP;
+        // An unmarked node entering an already-marked heap is marked on the
+        // spot, keeping the markHeap memo valid. `_marked` is only reset by
+        // runHeap, so a write between two mid-tick pulls (read-time markHeap +
+        // updateIfNecessary) would otherwise leave this node unmarked and every
+        // downstream pull stale until the next flush (#2922: the second
+        // `latest()` returned the first write's value). Invalidating the memo
+        // instead re-walked the WHOLE heap on the next pull — with N effects
+        // parked in the heap for a synchronous mount (each row writing a ref
+        // signal its effect subscribes to), mounting N rows was O(N²) (#3350).
+        // markNode's own guard skips an already-DIRTY node.
+                if (t.p) markNode(e);
+    }
+    if (!(E & REACTIVE_IN_HEAP_HEIGHT)) actualInsertIntoHeap(e, t);
+}
+
+function insertIntoHeapHeight(e, t) {
+    let E = e.R;
+    if (E & (REACTIVE_IN_HEAP | REACTIVE_RECOMPUTING_DEPS | REACTIVE_IN_HEAP_HEIGHT)) return;
+    e.R = E | REACTIVE_IN_HEAP_HEIGHT;
+    actualInsertIntoHeap(e, t);
+}
+
+function deleteFromHeap(e, t) {
+    const E = e.R;
+    if (!(E & (REACTIVE_IN_HEAP | REACTIVE_IN_HEAP_HEIGHT))) return;
+    e.R = E & -25;
+    const n = e.lt;
+    if (e.Ct === e) t.jt[n] = undefined; else {
+        const E = e.Rt;
+        const I = t.jt[n];
+        const i = E ?? I;
+        if (e === I) t.jt[n] = E; else e.Ct.Rt = E;
+        i.Ct = e.Ct;
+    }
+    e.Ct = e;
+    e.Rt = undefined;
+}
+
+function markHeap(e) {
+    if (e.p) return;
+    e.p = true;
+    for (let t = 0; t <= e.yt; t++) {
+        for (let E = e.jt[t]; E !== undefined; E = E.Rt) {
+            if (E.R & REACTIVE_IN_HEAP) markNode(E);
+        }
+    }
+}
+
+function markNode(e, t = REACTIVE_DIRTY) {
+    const E = e.R;
+    if ((E & (REACTIVE_CHECK | REACTIVE_DIRTY)) >= t) return;
+    e.R = E & -4 | t;
+    for (let t = e.o; t !== null; t = t.t) {
+        markNode(t.u, REACTIVE_CHECK);
+    }
+}
+
+function runHeap(e, t) {
+    e.p = false;
+    for (e.Et = 0; e.Et <= e.yt; e.Et++) {
+        let E = e.jt[e.Et];
+        while (E !== undefined) {
+            if (E.R & REACTIVE_IN_HEAP) t(E); else adjustHeight(E, e);
+            E = e.jt[e.Et];
+        }
+    }
+    e.yt = 0;
+}
+
+function adjustHeight(e, t) {
+    deleteFromHeap(e, t);
+    let E = e.lt;
+    for (let t = e.C; t; t = t.G) {
+        const e = t.S;
+        if (e.X && e.lt >= E) E = e.lt + 1;
+    }
+    if (e.lt !== E) {
+        e.lt = E;
+        for (let E = e.o; E !== null; E = E.t) insertIntoHeapHeight(E.u, t);
+    }
+}
+
+export { deleteFromHeap, enqueueSub, insertIntoHeap, insertIntoHeapHeight, markHeap, markNode, runHeap };

package/dist/observe/core/identities.js

@@ -0,0 +1,62 @@
+import { CONFIG_TRANSPARENT } from "./constants.js";
+
+import "./dev.js";
+
+import { getOwner } from "./owner.js";
+
+// Deferred hydration, dependency edges: plain-signal identities.
+// While on (`setSignalIdentities`; the server-components client turns it on
+// before hydrating), a plain signal created under an id-bearing owner is
+// named `<owner id>~<n>`, n counting the plain signals (and plain store
+// roots: `createStore` over an object, store/edges.ts) created under that
+// owner in its current pass (transparent owners defer to the nearest
+// id-bearing one, as child ids do). The server names the same signal the
+// same way and restarts the count on every re-run, so an edge it shipped (a
+// slot fill read it) matches the client node; the write hook receives the
+// node and looks its name up (`signalName`). The count restarts when the owner's pass
+// generation (`_depGen`, bumped by every recompute) moves on. Only the
+// frames client imports this module, so nothing here ships without it.
+// Names live in a side table, not on the node: frames reads them across the
+// package boundary, where a mangled field would not survive.
+let counts = null;
+
+const names = new WeakMap;
+
+/** @internal The identity of a plain signal named while identities were on. */ function signalName(n) {
+    return n === undefined ? undefined : names.get(n);
+}
+
+function identify(n) {
+    let e = getOwner();
+    if (!e) return;
+    while (e.l & CONFIG_TRANSPARENT && e._parent) e = e._parent;
+    if (e.id == null) return;
+    const t = e.Ne;
+    let i = counts.get(e);
+    if (i === undefined || i[0] !== t) counts.set(e, i = [ t, 0 ]);
+    const s = e.id + "~" + i[1]++;
+    // A store root named twice (one object made into two stores, or a store
+    // handed to `createStore`) is one target under two server names: its
+    // writes cannot be attributed (an empty name).
+        names.set(n, names.has(n) ? "" : s);
+}
+
+/** @internal Name plain signals from now on (`on`), or stop. */ function setSignalIdentities(n) {
+    counts = n ? counts || new WeakMap : null;
+    signalHook = n ? identify : null;
+}
+
+/**
+ * @internal Called with every plain signal `createSignal` makes, and every
+ * plain store root `createStore` makes, while set (the namer above). Never
+ * set unless `setSignalIdentities` is imported, so a bundle without it keeps
+ * only a null check.
+ */ let signalHook = null;
+
+/**
+ * @internal Dev only: `watch` is called with every node read while set (the
+ * dev hook `onRead`) — the frames client's identity-drift check watches the
+ * named signals a deferred occurrence reads as it mounts. A no-op in prod.
+ */ function setReadWatch(n) {}
+
+export { setReadWatch, setSignalIdentities, signalHook, signalName };

package/dist/observe/core/invariants.js

@@ -0,0 +1,12 @@
+import "./dev.js";
+
+/**
+ * Quiescence checks. Run only when the system is fully drained: nothing
+ * scheduled, no active/stashed transitions, no live lanes. At that point no
+ * transition-scoped state may survive, and the lazily-created companions must
+ * agree with a fresh computation of their owner's state.
+ */ function devCheckQuiescent(e) {
+    return;
+}
+
+export { devCheckQuiescent };