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

package/dist/observe/core/dev.js

@@ -0,0 +1,232 @@
+import { withOrigin, withInteraction, setAttributionHooks, attrHooks } from "./attribution-hooks.js";
+
+import { context } from "./core.js";
+
+/** First warning when a change reaches (or a pass tracks) this many edges. */ const GRAPH_SIZE_WARN_AT = 2e3;
+
+/** Re-warn once the count has grown by this much since the last warning. */ const GRAPH_SIZE_WARN_EVERY = 500;
+
+const diagnosticListeners = new Set;
+
+const diagnosticCaptures = new Set;
+
+let diagnosticSequence = 0;
+
+const diagnostics = {
+    subscribe(e) {
+        diagnosticListeners.add(e);
+        return () => diagnosticListeners.delete(e);
+    },
+    emit(e, t = null) {
+        return emitDiagnostic(e, t);
+    },
+    capture() {
+        const e = [];
+        diagnosticCaptures.add(e);
+        return {
+            get events() {
+                return e;
+            },
+            clear() {
+                e.length = 0;
+            },
+            stop() {
+                diagnosticCaptures.delete(e);
+                return [ ...e ];
+            }
+        };
+    }
+};
+
+const attributionSlot = {
+    install: setAttributionHooks,
+    get installed() {
+        return attrHooks;
+    },
+    withInteraction: withInteraction,
+    withOrigin: withOrigin
+};
+
+const OBSERVE = {
+    diagnostics: diagnostics,
+    attribution: attributionSlot,
+    subjectOf(e) {
+        return eventSubjects.get(e);
+    },
+    exclude(e) {
+        excludedOwners.add(e);
+        hasExclusions = true;
+    },
+    isExcluded: isExcluded
+};
+
+// --- Excluded owners ---------------------------------------------------------------
+
+// An observer that lives inside the observed app (an adapter's panel,
+// devtools) marks its root; both channels check the subject's owner chain —
+// the same walk `ownerPath` already makes — and stay silent under it. The
+// flag short-circuits the walk for the common case of no exclusions.
+const excludedOwners = new WeakSet;
+
+let hasExclusions = false;
+
+/** Events built for an excluded subject: never delivered, never reported. */ const suppressedEvents = new WeakSet;
+
+function isExcluded(e) {
+    if (!hasExclusions || !e) return false;
+    let t = "Nt" in e ? e : e.an ?? null;
+    for (;t !== null; t = t.Nt) if (excludedOwners.has(t)) return true;
+    return false;
+}
+
+/** For engines that cache the verdict per node: is anything excluded at all? */ function anyExcluded() {
+    return hasExclusions;
+}
+
+/** Was `entry` built for an excluded subject? Once-per-key reporters must not spend their slot on it. */ function isSuppressed(e) {
+    return suppressedEvents.has(e);
+}
+
+const DEV = undefined;
+
+/**
+ * Root-first names of the owners enclosing `subject` (inclusive when the
+ * subject is itself a named owner). Signals hop to their registering owner
+ * (`_owner`, set by registerGraph). Unnamed owners are skipped so the path
+ * reads as the component tree plus the scope: `<App> › <TodoRow> › effect`.
+ */ function ownerPath(e) {
+    if (!e) return undefined;
+    let t = "Nt" in e ? e : e.an ?? null;
+    const n = [];
+    for (;t !== null; t = t.Nt) {
+        const e = t._name;
+        if (typeof e === "string" && e.length) n.push(e);
+    }
+    return n.length ? n.reverse() : undefined;
+}
+
+/**
+ * Records a diagnostic on the structured channel (listeners, captures) and
+ * returns the entry. `subject` locates it: the current reactive `context` by
+ * default (right for the synchronous rule checks — they fire inside the
+ * scope that misbehaved); pass the node for scheduler-time findings whose
+ * ambient context is the flush, or `null` for events that have no location
+ * by nature. An `ownerPath` already on the event wins over the subject walk
+ * (hosts whose owners are not signals' owners compute their own). Console
+ * output is a separate, dev-tier step — see `reportDiagnostic`.
+ */ function emitDiagnostic(e, t = context) {
+    const n = {
+        sequence: ++diagnosticSequence,
+        ...e
+    };
+    // The observer's own subtree: build the entry (the caller may throw its
+    // message) but tell nobody.
+        if (isExcluded(t)) {
+        suppressedEvents.add(n);
+        return n;
+    }
+    if (n.ownerPath === undefined) {
+        const e = ownerPath(t);
+        if (e) n.ownerPath = e;
+    }
+    if (t) eventSubjects.set(n, t);
+    for (const e of diagnosticListeners) e(n);
+    for (const e of diagnosticCaptures) e.push(n);
+    return n;
+}
+
+/**
+ * The subject each emitted event was about, for the console step: events are
+ * serializable records and cannot carry the node, but the console can show
+ * what the node knows — a rendering runtime may stamp a binding effect with
+ * the DOM element it writes (`_devElement`), and a live element reference
+ * beside the message is the most addressable pointer a console can print.
+ */ const eventSubjects = new WeakMap;
+
+/**
+ * The console face of a diagnostic — ONE entry per finding: the message, the
+ * owner path (`in <App> › <TodoRow> › effect`) so a human can locate it, the
+ * once-per-code footer as trailing lines, and — when the subject is a
+ * binding effect the rendering runtime tagged — the element it writes, as a
+ * second console argument (hover highlights it, click jumps to Elements).
+ * Severity picks the console method. Call sites report the entry
+ * `emitDiagnostic` returned so the structured and console channels never
+ * disagree. Dev-tier: in an observe build this is a no-op, so wiring paths
+ * that both emit and report (graph-size warnings) reach the channel only —
+ * production observability never writes to the console.
+ */ function reportDiagnostic(e) {
+    return;
+}
+
+/**
+ * Observe-tier: stamp a signal with its creating owner so `ownerPath` can
+ * locate signal subjects. The per-owner `_signals` list and the devtools
+ * `onGraph` hook are dev-tier — the observe build pays one property write.
+ */ function registerGraph(e, t) {
+    e.an = t;
+}
+
+/**
+ * Graph-size warnings are once per node, re-warning only when the count has
+ * grown by GRAPH_SIZE_WARN_EVERY since the last one — off-node, so the
+ * pathological handful of nodes that ever reach the threshold are the only
+ * ones that cost anything, and no node carries a bookkeeping field for it.
+ */ const graphSizeWarnedAt = new WeakMap;
+
+function shouldWarnGraphSize(e, t) {
+    const n = graphSizeWarnedAt.get(e);
+    if (n !== undefined && t < n + GRAPH_SIZE_WARN_EVERY) return false;
+    graphSizeWarnedAt.set(e, t);
+    return true;
+}
+
+/**
+ * Observe-tier: a committed change on `node` is about to re-run `count`
+ * subscribers (the notify walk in `insertSubs` counted them as it went —
+ * fan-out costs exactly one local increment in a loop that already visits
+ * every edge, and nothing at link time). Fires from GRAPH_SIZE_WARN_AT up,
+ * on the write rather than the link: a fan-out that is never written costs
+ * nothing, and one that is re-runs every subscriber this flush. Always-on
+ * wherever the channel exists — unlike the opt-in attribution engine, a
+ * graph-size pathology should surface without asking.
+ */ function noteFanOut(e, t) {
+    if (!shouldWarnGraphSize(e, t)) return;
+    const n = e._name;
+    const i = `[HUGE_FAN_OUT] ${n ? `Signal "${n}"` : "A signal"} changed with ${t} subscribers — ` + `every one re-runs this flush. If many independent computations read the same value ` + `(for example every row of a list comparing against one selected id), prefer a per-key ` + `store or projection so only the items whose result flipped update.`;
+    reportDiagnostic(emitDiagnostic({
+        code: "HUGE_FAN_OUT",
+        kind: "graph",
+        severity: "warn",
+        message: i,
+        nodeName: n,
+        ownerId: e.id,
+        ownerName: n,
+        data: {
+            count: t
+        }
+    }, e));
+}
+
+/**
+ * Observe-tier: a recompute pass of `node` tracked `count` distinct sources
+ * (its trimmed dep list, walked once at the end of the pass — see recompute;
+ * no per-link work, no pass bracket). Fires from GRAPH_SIZE_WARN_AT up.
+ */ function noteFanIn(e, t) {
+    if (!shouldWarnGraphSize(e, t)) return;
+    const n = e._name;
+    const i = `[HUGE_FAN_IN] ${n ? `Computation "${n}"` : "A computation"} tracked ${t} sources. ` + `It will re-run when any of them change. Narrow the read or split the derivation so each ` + `computation tracks only what it needs.`;
+    reportDiagnostic(emitDiagnostic({
+        code: "HUGE_FAN_IN",
+        kind: "graph",
+        severity: "warn",
+        message: i,
+        nodeName: n,
+        ownerId: e.id,
+        ownerName: n,
+        data: {
+            count: t
+        }
+    }, e));
+}
+
+export { DEV, GRAPH_SIZE_WARN_AT, GRAPH_SIZE_WARN_EVERY, OBSERVE, anyExcluded, emitDiagnostic, isExcluded, isSuppressed, noteFanIn, noteFanOut, ownerPath, registerGraph, reportDiagnostic };

package/dist/observe/core/effect.js

@@ -0,0 +1,179 @@
+import { REACTIVE_DISPOSED, LANE_RUN, STATUS_ERROR, EFFECT_USER, CONFIG_AUTO_DISPOSE, CONFIG_CHILDREN_FORBIDDEN, EFFECT_TRACKED, EFFECT_RENDER, STATUS_PENDING } from "./constants.js";
+
+import { setEffectStatusNotify, ext, createEffectNode, recompute, computed, staleValues } from "./core.js";
+
+import { attrHooks } from "./attribution-hooks.js";
+
+import { unwrapStatusError, StatusError } from "./error.js";
+
+import { enqueueSub } from "./heap.js";
+
+import { GlobalQueue, currentTransition, activeTransition, haltReactivity, schedule } from "./scheduler.js";
+
+/**
+ * Effects are the leaf nodes of our reactive graph. When their sources change, they are
+ * automatically added to the queue of effects to re-execute, which will cause them to fetch their
+ * sources and recompute
+ */ function effect(t, e, E, r) {
+    const n = !!r?.user;
+    const f = createEffectNode(t, e, E, n ? EFFECT_USER : EFFECT_RENDER, r);
+    recompute(f, true);
+    !r?.defer && (f.Re === EFFECT_USER || r?.schedule ? f.C.enqueue(f.Re, runEffect.bind(null, f)) : runEffect(f, LANE_RUN));
+}
+
+function notifyEffectStatus(t, e) {
+    // Use passed values if provided, otherwise read from node
+    const E = t !== undefined ? t : this.S;
+    const r = e !== undefined ? e : this.o?._;
+    if (E & STATUS_ERROR) {
+        this.C.notify(this, STATUS_PENDING, 0);
+        if (this.Re === EFFECT_USER) {
+            // The error handler is the error arm of the effect phase (#2840 ruling):
+            // queue it like the effect function. It runs in the same imperative,
+            // writable scope, throws escalate the same way, and a held transition
+            // (or optimistic lane) defers it exactly as it defers the success arm.
+            // No payload is queued — the node already carries `_statusFlags`/`_error`,
+            // and the runner dispatches on them, so a recovery before the effect
+            // phase takes the success arm instead. Blocked forwards (explicit
+            // `status` arg without node-state writes) don't queue: the status
+            // re-propagates unblocked at commit.
+            if (this.S & STATUS_ERROR) {
+                this._t = true;
+                this.C.enqueue(this.Re, this.kt ??= runEffect.bind(null, this));
+            }
+            return;
+        }
+        if (!this.C.notify(this, STATUS_ERROR, STATUS_ERROR)) {
+            haltReactivity(unwrapStatusError(r));
+            throw r;
+        }
+    } else if (this.Re === EFFECT_RENDER) {
+        this.C.notify(this, STATUS_PENDING | STATUS_ERROR, E, r);
+    }
+}
+
+function runEffect(t, e) {
+    if (!t._t || t.it & REACTIVE_DISPOSED) return;
+    // Ownership (#3319): a value computed under a transaction is applied by that
+    // transaction's commit. The ordinary effect phase runs with a transaction
+    // active only when the flush's finalize ENTERED one (every other path parks
+    // or settles first): leave a run owned by a still-held transaction queued —
+    // `_modified` stays set — and the next gate stashes it with the owner.
+    // Mainline-owned runs (null) apply now. Lanes are exempt by design (they
+    // apply their own effects ahead of their transaction — the optimistic view)
+    // and mark their runs with LANE_RUN.
+    
+    // Lane exemption has one exception (#3331): a lane runner for an effect that
+    // no longer rides a lane — its optimistic source was superseded, so the lane
+    // has no optimistic view left to apply, and the value this effect now
+    // carries (or will, once its plain recompute lands) belongs to the still-held
+    // transaction. Hand the run to the regular queue, where the transaction's
+    // gate stashes it with the owner. Lane-less runners with no live owner
+    // (reverts, wake-only lanes) apply now.
+        if (t.Vt !== null && !currentTransition(t.Vt).Ut && (e & LANE_RUN ? !t.o?.Te : activeTransition !== null)) {
+        t.C.enqueue(t.Re, t.kt);
+        return;
+    }
+    // Error arm (#2840), user effects only: a compute-phase error that is still
+    // the node's settled state at effect time runs the bundle's error handler in
+    // this same imperative, writable scope. Unwrap the StatusError used for
+    // source tracking — user code gets the error it threw, as boundaries do. No
+    // handler: log and keep the system alive (the run was skipped). A handler
+    // (or logging) consumes the error; a handler throw falls to the shared
+    // catch below and escalates boundary-or-halt like any effect-phase throw.
+    // Render effects bypass: their errors route to boundaries synchronously in
+    // notifyEffectStatus, and a runner queued by an earlier valueChanged in the
+    // same flush must not be hijacked by a later-arriving error status.
+        if (t.S & STATUS_ERROR && t.Re === EFFECT_USER) {
+        const e = unwrapStatusError(t.o?._);
+        t.Bt = t.ge;
+        t._t = false;
+        try {
+            t.Jt ? t.Jt(e, () => {
+                const e = t.Xt;
+                t.Xt = undefined;
+                e?.();
+            }) : console.error(e);
+        } catch (e) {
+            if (!t.C.notify(t, STATUS_ERROR, STATUS_ERROR)) {
+                haltReactivity(e);
+                throw e;
+            }
+        }
+        return;
+    }
+    const E = t.Xt;
+    t.Xt = undefined;
+    try {
+        E?.();
+        const e = t.zt(t.ge, t.Bt);
+        if (false && e !== undefined && typeof e !== "function") ;
+        // The final cleanup is invoked by disposeChildren at true disposal.
+                t.Xt = e;
+    } catch (e) {
+        ext(t)._ = new StatusError(t, e);
+        t.S |= STATUS_ERROR;
+        if (!t.C.notify(t, STATUS_ERROR, STATUS_ERROR)) {
+            haltReactivity(e);
+            throw e;
+        }
+    } finally {
+        t.Bt = t.ge;
+        t._t = false;
+    }
+    // Outside the try (see the rule in attribution-hooks.ts). Reached whether or
+    // not the callback threw — a throw that escapes the catch above halts.
+        if (attrHooks !== null) attrHooks.effectRunEnd(t);
+}
+
+GlobalQueue.bt = runEffect;
+
+/**
+ * Internal tracked effect - bypasses heap, goes directly to effect queue.
+ * Runs as a leaf owner: child primitives and onCleanup are forbidden (false throws).
+ * Uses stale reads.
+ */ function trackedEffect(t, e) {
+    const run = () => {
+        // `_modified` is NOT redundant with the heap: the heap dedups within a
+        // pass, but a held transition's passes each enqueue `_run` into the same
+        // user queue, and this gate is what collapses them into one run at commit.
+        if (!E._t || E.it & REACTIVE_DISPOSED) return;
+        try {
+            E._t = false;
+            recompute(E);
+        } finally {}
+    };
+    const E = computed(() => {
+        const e = E.Xt;
+        E.Xt = undefined;
+        e?.();
+        const r = staleValues(t);
+        E.Xt = r;
+    }, {
+        ...e,
+        lazy: true
+    });
+    E.Xt = undefined;
+    E.T = E.T & ~CONFIG_AUTO_DISPOSE | CONFIG_CHILDREN_FORBIDDEN;
+    E._t = true;
+    E.Re = EFFECT_TRACKED;
+    // Observe-tier label: the computed literal defaulted its `_name` slot to
+    // "computed"; relabel by kind (a store into the slot, not a new field).
+        if (e?.name === undefined) E._name = "trackedEffect";
+    // Status dispatch rides the SHARED notifier (statusNotifierOf keys off
+    // _type): its error arm is behavior-identical to the closure that used to
+    // live here, without the per-node NodeExtension allocation.
+        E.ct = run;
+    // The first run rides the heap like every wake (GlobalQueue._update), so a
+    // tracked effect created inside a render-effect callback runs after that
+    // pass's staged writes commit, not before.
+        enqueueSub(E);
+    schedule();
+}
+
+// Install the shared effect status notifier (statusNotifierOf serves it to
+// every effect node) — module-scope: any bundle that creates effects
+// evaluates this module.
+setEffectStatusNotify(notifyEffectStatus);
+
+export { effect, trackedEffect };

package/dist/observe/core/error.js

@@ -0,0 +1,80 @@
+/**
+ * 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 {
+    source;
+    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 {
+    source;
+    constructor(r, o) {
+        super(o instanceof Error ? o.message : String(o), {
+            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,98 @@
+import { signal, setSignal, read } from "./core.js";
+
+import { cleanup } from "./owner.js";
+
+import { GlobalQueue } 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 on GlobalQueue 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.ot, () => {
+        setSignal(n, undefined);
+    });
+    cleanup(() => r.dispose());
+    e.ot = 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 null checks stay equivalent to the old
+// `externalSourceConfig` truthiness checks.
+function syncExternalHooks() {
+    GlobalQueue.un = externalSourceConfig ? wireExternalSource : null;
+    GlobalQueue.cn = externalSourceConfig ? externalUntrack : null;
+}
+
+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 };