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

package/dist/prod/affects.js

@@ -0,0 +1,222 @@
+import { forEachDependent, notifyStatus, addPendingSource, setPendingError, settlePendingSource } from "./core/async.js";
+
+import { $REFRESH, STATUS_PENDING } from "./core/constants.js";
+
+import { NotReadyError } from "./core/error.js";
+
+import "./core/core.js";
+
+import { globalQueue, schedule, GlobalQueue, shiftAffectsMarks } from "./core/scheduler.js";
+
+import "./core/verdict.js";
+
+import "./core/effect.js";
+
+import "./core/invariants.js";
+
+import { $TARGET, getStoreAffectsNodes } from "./store/store.js";
+
+/**
+ * The pending-source identity of a live `affects()` mark on `node` (lazy,
+ * one per node, shared by overlapping registrations via the refcount).
+ *
+ * A mark rides the SAME status rails as real in-flight async — downstream
+ * subscribers hold the sentinel in `_pendingSources` — but under its own
+ * identity so the two channels can't clear each other:
+ * - `_reask` is permanently `false`: a mark is by definition a declared
+ *   value change, so `quietPending` never silences a window it participates
+ *   in — even when the mark rides over an otherwise-quiet `refresh()`
+ *   re-ask of the same node (the whole point of declaring one).
+ * - A landing on the marked node settles only the node's OWN source entry;
+ *   the sentinel entry survives until the mark's transaction releases it.
+ * - The sentinel itself never carries `STATUS_PENDING`, so
+ *   `transitionComplete` never counts a mark as a blocker of its own
+ *   transaction (release happens AT settle — self-blocking would deadlock),
+ *   and reads of the marked node never throw (marks are value-transparent
+ *   at the source; pendingness is what propagates).
+ */ function getAffectsSentinel(e) {
+    return e.t ??= {
+        o: undefined,
+        // Brand + backref: lets the scheduler's settlement checks recognize
+        // mark-sourced pending (which must never block its own transaction —
+        // release happens AT settle).
+        l: e,
+        u: 0,
+        i: 0,
+        A: false,
+        k: undefined,
+        p: null,
+        S: null
+    };
+}
+
+/**
+ * Push a live mark's pendingness downstream from the marked node through the
+ * normal status rails. Runs on every registration (dedup in `notifyStatus`
+ * stops re-descent at already-covered subscribers). Subscribers that
+ * recompute mid-window shed this via `clearStatus` and re-acquire it through
+ * the read path (`applyAffectsReads` for direct readers of the marked node,
+ * `collectMarkSources` transitively) — the mark analogue of real async's
+ * re-throw-on-read. Subscribers are deliberately NOT queued as pending nodes
+ * (#2893): they hold no value needing a transition-scheduled commit, and
+ * queueing would stamp the marking action's transaction onto them — from then
+ * on ANY write dirtying one of them (including writes to unmarked signals
+ * that merely share a downstream memo) would be captured and frozen until the
+ * action settles.
+ */ function propagateAffectsMark(e) {
+    if (!e.p && !e.G) return;
+    const t = getAffectsSentinel(e);
+    const r = new NotReadyError(t);
+    forEachDependent(e, e => {
+        if (e.m !== t && !e.M?.has(t)) {
+            notifyStatus(e, STATUS_PENDING, r);
+        }
+    });
+}
+
+/**
+ * Re-establish mark pendingness on a computed that read marked sources
+ * during its recompute (`clearStatus` at the top of the commit path wiped
+ * any sentinel entries it held). Called by `recompute` after the commit —
+ * not before, because setting `_error` earlier would make the commit path
+ * treat the node as errored and skip the value write.
+ */ function applyAffectsReads(e, t) {
+    let r = false;
+    for (let f = 0; f < t.length; f++) {
+        const o = t[f];
+        if (!o.P) continue;
+        const s = getAffectsSentinel(o);
+        if (addPendingSource(e, s)) {
+            e.i |= STATUS_PENDING;
+            setPendingError(e, s);
+            r = true;
+        }
+    }
+    if (r && GlobalQueue._ !== null) GlobalQueue._(e);
+}
+
+/**
+ * The counting half of a mark, shared by direct registration and store-scope
+ * inheritance (a node created inside a live keyless mark's identity scope):
+ * bumps the refcount and pokes the node's verdict companions so an
+ * already-materialized `false` flips reactively.
+ */ function markAffects(e) {
+    e.P = (e.P || 0) + 1;
+    shiftAffectsMarks(1);
+    // Companions only exist once the verdict layer (isPending/latest) loaded;
+    // without them there is no materialized verdict to flip.
+        if (e.P === 1 && GlobalQueue._ !== null) GlobalQueue._(e);
+}
+
+/**
+ * Registers one `affects()` mark on a node: counts it, records the
+ * registration with the current transaction (after initTransition the queue's
+ * array aliases the active transition's, mirroring `_optimisticNodes`), and
+ * propagates STATUS_PENDING downstream on the status rails so everything
+ * DERIVED from the marked data reads pending too. Propagation runs on every
+ * registration (not just the first): subscribers gained since an earlier
+ * overlapping registration get covered, and dedup stops re-descent early.
+ */ function registerAffectsMark(e) {
+    markAffects(e);
+    globalQueue.N.push(e);
+    propagateAffectsMark(e);
+    schedule();
+}
+
+/**
+ * Releases one registration. When the node's last mark drops, settles the
+ * mark's sentinel out of every downstream `_pendingSources` (waking blocked
+ * nodes and re-deriving verdicts along the walk). Companion writes go through
+ * the settlement snap (committed, not transition-scoped) so releasing a mark
+ * can't open a fresh override window that would itself need settlement.
+ */ function releaseAffectsMark(e) {
+    shiftAffectsMarks(-1);
+    e.P--;
+    if (!e.P) {
+        const t = e.t;
+        if (t) settlePendingSource(e, t, true);
+        GlobalQueue.R !== null && GlobalQueue.R(e);
+        GlobalQueue.T?.(e);
+    }
+}
+
+/**
+ * Releases one batch of affects marks (a settling transaction's, or the
+ * ambient batch at a plain flush end).
+ */ function releaseAffectsMarks(e) {
+    for (let t = 0; t < e.length; t++) releaseAffectsMark(e[t]);
+    e.length = 0;
+}
+
+/**
+ * True when a node's pending status comes ONLY from affects() sentinels. A
+ * mark is a promise of change, not an absence of value: reads of mark-pended
+ * derived nodes stay value-transparent (verdicts report pending; the read
+ * path must not suspend). Any real async source among the pending sources
+ * keeps normal suspension semantics. Core's read path reaches this through
+ * `GlobalQueue._onlyMarkPending`, gated on the `activeAffectsMarks` counter.
+ */ function onlyMarkPending(e) {
+    const t = e.M;
+    if (t) {
+        for (const e of t) if (!e.l) return false;
+        return true;
+    }
+    return !!e.m?.l;
+}
+
+/**
+ * Collect the still-live marked nodes behind a pended owner's sentinel
+ * sources into a recompute's `affectsReads`. This is the transitive half of
+ * read-path re-establishment (#2893): real async re-establishes at every
+ * derivation level because its re-throw on read re-registers the source, but
+ * mark-pended reads are value-transparent — without this, pendingness dies on
+ * the first mid-window recompute past depth one, and the isPending() probe
+ * itself (whose prepare step recomputes retryable NotReady holders) strips
+ * the very status it reports on. Reached through
+ * `GlobalQueue._collectMarkSources`, gated on `activeAffectsMarks`.
+ */ function collectMarkSources(e, t) {
+    const r = e.m;
+    if (r) {
+        const e = r.l;
+        if (e && e.P) t.push(e);
+    } else if (e.M) {
+        for (const r of e.M) {
+            const e = r.l;
+            if (e && e.P) t.push(e);
+        }
+    }
+}
+
+// Late installation (same pattern as `GlobalQueue._update`): the mark engine
+// lives with the feature so graphs that never declare a mark never ship it.
+// Each call site is gated by state only this module creates (`markedReads`
+// collection under `activeAffectsMarks`, a non-empty `_affectsNodes` batch,
+// a live scope in the store's `affectsScopes`), so the hooks are installed
+// before the first time any of them can fire.
+GlobalQueue.j = applyAffectsReads;
+
+GlobalQueue.h = releaseAffectsMarks;
+
+GlobalQueue.D = markAffects;
+
+GlobalQueue.F = releaseAffectsMark;
+
+GlobalQueue.$ = onlyMarkPending;
+
+GlobalQueue.I = collectMarkSources;
+
+function affects(e, t) {
+    const r = e?.[$TARGET];
+    if (r) {
+        const e = getStoreAffectsNodes(r, t);
+        for (let t = 0; t < e.length; t++) registerAffectsMark(e[t]);
+        return;
+    }
+    const f = e?.[$REFRESH];
+    if (f) {
+        registerAffectsMark(f);
+        return;
+    }
+}
+
+export { affects };