@solidjs/signals 2.0.0-rc.13 → 2.0.0-rc.15

package/dist/observe/store/projection.js

@@ -0,0 +1,308 @@
+import { CONFIG_AUTO_DISPOSE, STATUS_PENDING, STATUS_UNINITIALIZED } from "../core/constants.js";
+
+import { computed } from "../core/core.js";
+
+import { NotReadyError } from "../core/error.js";
+
+import { handleAsync, addPendingSource, propagateStatus, forEachDependent, settlePendingSource } from "../core/async.js";
+
+import { enqueueSub } from "../core/heap.js";
+
+import { getOwner, isDisposed } from "../core/owner.js";
+
+import { question, setQuestion, schedule } from "../core/scheduler.js";
+
+import { reconcileState } from "./reconcile.js";
+
+import { wrap, nameStore, storeSetter, runDirect } from "./store.js";
+
+import { setLookup } from "./target.js";
+
+import { $TARGET, markRawIngest, setWriteOverride, isWrappable } from "./types.js";
+
+/**
+ * Store — projections (plan sec. 31, S3; INTERNALS §7/§7b).
+ *
+ * A projection is a computed store: the derive runs inside a computed — the
+ * **firewall** — whose pass writes the store through a draft; its output is
+ * adopted through the reconcile channel (replace-mode root: entity changes
+ * merge in place, the root proxy is stable for life). Children wrap into
+ * the projection's own FAMILY (writes land here, never in a source family).
+ *
+ * The firewall exists so writes from inside a computation are safe (the
+ * derive owns its leaves); the price is the ordering obligation: before any
+ * value is served through the projection, the derive is brought up to date
+ * — **without** the reader subscribing to it (that is the propagation
+ * barrier). The store's traps do that pull (`pullFamily`, store.ts): core's
+ * `read()` of the firewall with no link — freshness, the status gate
+ * (uninitialized / pending / errored) and the reader's height, by the
+ * rules a memo's read follows. No per-leaf back-pointer, nothing in core.
+ */
+/**
+ * Wrap a store proxy as a projection DRAFT: every operation carries the write
+ * override (the derive is the author — its ops must not hit the status gate,
+ * even in a continuation after an `await`/`yield` where the sync write scope
+ * has closed).
+ *
+ * FAKE TARGET, not the store proxy itself (#3060): after a proxy trap
+ * returns, the engine runs spec invariant validation against the proxy's
+ * TARGET — [[OwnPropertyKeys]] after ownKeys, [[GetOwnProperty]] after
+ * set/getOwnPropertyDescriptor/defineProperty. With the store proxy as
+ * target those checks re-enter the store's traps OUTSIDE the override
+ * bracket, so `Object.keys(state)` in a derive continuation fired the gate.
+ */ function wrapDraft(e, t, r, n, o, i) {
+    const mutate = e => {
+        if (!t()) return true;
+        setWriteOverride(true);
+        // A continuation's write is the flight's answer: it asks the flight's
+        // question (A18 provenance — a landing beneath a newer guess is held,
+        // not a correction; lanes.ts `laneWrite`).
+                const n = question;
+        if (i !== undefined) setQuestion(i());
+        try {
+            r ? r(e) : e();
+        } finally {
+            setWriteOverride(false);
+            setQuestion(n);
+        }
+        if (o) o();
+        return true;
+    };
+    const read = e => {
+        setWriteOverride(true);
+        try {
+            return e();
+        } finally {
+            setWriteOverride(false);
+        }
+    };
+    const s = {
+        get(s, c) {
+            const u = read(() => e[c]);
+            return !n && typeof u === "object" && u !== null && c !== $TARGET ? wrapDraft(u, t, r, false, o, i) : u;
+        },
+        has: (t, r) => read(() => r in e),
+        set: (t, r, n) => mutate(() => {
+            e[r] = n;
+        }),
+        deleteProperty: (t, r) => mutate(() => {
+            delete e[r];
+        }),
+        ownKeys: () => read(() => Reflect.ownKeys(e)),
+        getOwnPropertyDescriptor(t, r) {
+            const n = read(() => Reflect.getOwnPropertyDescriptor(e, r));
+            if (n) n.configurable = true;
+            return n;
+        },
+        defineProperty: (t, r, n) => mutate(() => {
+            Reflect.defineProperty(e, r, n);
+        })
+    };
+    const c = new Proxy(Array.isArray(e) ? [] : {}, s);
+    // The wrapper stands for its store proxy wherever the derive's result
+    // carries it (`wrap`, `unwrapValue`, reconcile's slot matching).
+        const u = e[$TARGET];
+    if (u !== undefined) setLookup(c, u);
+    return c;
+}
+
+function cloneState(e, t) {
+    return t ? Array.isArray(e) ? e.slice() : {
+        ...e
+    } : JSON.parse(JSON.stringify(e));
+}
+
+/** The derive's pass went pending (a new question in flight): every reader
+ * of a leaf learns it as a reader of the derive would (A9: any leaf reports
+ * the firewall's refetch) — core's own rule for a dependency going pending
+ * (`notifyStatus`): a verdict or re-derive reader re-runs, any other is
+ * pending derivatively on the derive (its readers hold; it re-runs at the
+ * landing). The leaves do not subscribe to the derive, so the family does
+ * the walk. */ function wakeFamily(e, t) {
+    const r = e.node;
+    e.woke = true;
+    forEachFamilyNode(e, e => {
+        if (e.t === null) return;
+        // The leaf carries the derive's pending as a propagated copy, as a memo
+        // between them would: a dependent recovering one branch stays pending
+        // through a leaf it still reads (core `retryReaches`), and the landing's
+        // walk retires the copy first (`settleFamily` → `settlePendingSource`).
+                addPendingSource(e, r);
+        // Its readers: core's propagation from the leaf — a verdict or re-derive
+        // reader re-runs, any other is pending derivatively on the derive and
+        // queued for the frame (held with it: the frame waits on the flight
+        // through them, `blocked`).
+                propagateStatus(e, STATUS_PENDING, t);
+    });
+}
+
+/** The derive's flight rejected: every live reader of the family
+ * re-derives (its pull throws the derive's error). */ function errorFamily(e) {
+    forEachFamilyNode(e, e => {
+        if (e.t === null) return;
+        forEachDependent(e, e => {
+            enqueueSub(e);
+        });
+    });
+    schedule();
+}
+
+/** The flight landed: the readers the wake left pending on the derive
+ * settle — core's walk, from each leaf (the leaves are not the derive's
+ * dependents, so its own settle walk does not reach them). */ function settleFamily(e) {
+    if (!e.woke) return;
+    e.woke = false;
+    const t = e.node;
+    forEachFamilyNode(e, e => {
+        if (e.t !== null) settlePendingSource(e, t);
+    });
+}
+
+function forEachFamilyNode(e, t) {
+    for (const r of e.live) {
+        const e = r.n;
+        if (e !== null) for (const r of Reflect.ownKeys(e)) t(e[r]);
+        const n = r.h;
+        if (n !== null) for (const e of Reflect.ownKeys(n)) t(n[e]);
+        if (r.k !== null) t(r.k);
+        if (r.dk !== null) t(r.dk);
+    }
+}
+
+/** The derive's pass: run `fn` against a draft of the store; commit its
+ * result (sync, or each async landing) through the reconcile channel.
+ * Draft validity is per run (R37): live from here until the NEXT run starts
+ * — a sync derive that subscribes to an external source and pushes into
+ * the draft from the callback (#3585) is the model use. */ function runProjectionComputed(e, t, r, n, o) {
+    const i = getOwner();
+    const s = e[$TARGET];
+    const c = s.fam;
+    const u = c.run = (c.run || 0) + 1;
+    let l;
+    // Open loading window (seedLoadingValue): the observable store IS commit #0
+    // for the whole first flight — the derive works a detached shadow of the
+    // seed so draft writes cannot tear through to readers (#2988). Every
+    // commit point reconciles the shadow through the normal commit path.
+        const a = i.De ? cloneState(s.v, s.s) : null;
+    // The question a write of this run answers: inside a slice, the slice's
+    // (the sync pass); in a continuation — the flight still registered — the
+    // flight's (`handleAsync` stamped it with the action that asked).
+        const asking = () => question || (i.m !== null && i.m.Te !== null ? i.m._e : 0);
+    const f = wrapDraft(e, () => c.run === u && !isDisposed(i), o, s.s, 
+    // A write after the run returned (a continuation, a callback) arms the
+    // drain itself when no landing will.
+    () => {
+        if (!(i.S & STATUS_PENDING) && !i.De) schedule();
+    }, asking);
+    // The creation run commits directly (a memo's first value is its
+    // `_value`); every later run — a re-derive in a flush, an async landing
+    // — stages and commits with the flush like a memo's recompute.
+        const d = u === 1;
+    const pass = () => storeSetter(f, o => {
+        l = t(a ?? o);
+        const commit = t => {
+            // Shadow run: commit a detached snapshot, never the shadow itself
+            // (adoption takes the value by identity — handing it the live
+            // shadow would fuse the draft to the observable store).
+            if (a && (t === undefined || t === a)) t = cloneState(a, s.s);
+            if (t !== o && t !== undefined) {
+                const write = () => {
+                    const n = question;
+                    setQuestion(asking());
+                    try {
+                        storeSetter(e, e => reconcileState(t, e, r, true), false);
+                    } finally {
+                        setQuestion(n);
+                    }
+                };
+                n ? n(write, t) : write();
+            }
+            // A landing (not the sync pass's own commit): the readers held
+            // pending on the derive settle.
+                        if (!d || !(i.S & STATUS_UNINITIALIZED)) settleFamily(c);
+        };
+        const u = handleAsync(i, l, commit, (e, t) => {
+            // The flight rejected: the leaves' readers learn it from here —
+            // they do not subscribe to the derive. Pending again (a NotReady
+            // rejection): the wake, as for the pass. Errored: every live
+            // reader re-derives and meets the error at its pull (memo parity,
+            // #2897) — and the flush that runs them advances the clock, so a
+            // later tracked re-read may retry (core `read`).
+            if (d && i.S & STATUS_UNINITIALIZED) return;
+            if (t) wakeFamily(c, e); else errorFamily(c);
+        });
+        if (!i.De) commit(u);
+    }, false);
+    try {
+        d ? runDirect(pass) : pass();
+    } catch (e) {
+        // A flight went up (NotReady out of the pass — the derive's own, with
+        // the derive as its source): the leaves' readers learn it from here —
+        // they do not subscribe to the derive.
+        // A synchronous error the same way (#3956: a rerun that finds the
+        // entry failed throws): every live reader re-derives and meets it.
+        if (!d) e instanceof NotReadyError ? wakeFamily(c, e) : errorFamily(c);
+        throw e;
+    }
+    // A pass that returned with a flight up (an iterator's sync first yield):
+    // the wake, as for the throw. Not a sync pass that superseded one — the
+    // status it reads is the dead flight's, cleared when this pass settles
+    // (#3181: a reader the settle walk had just released, re-parked for good).
+        if (i.S & STATUS_PENDING && i.m.Te !== null && !i.De && !d) wakeFamily(c, i.m?.F);
+    return i;
+}
+
+function createProjectionInternal(e, t, r) {
+    const n = r?.key === undefined ? "id" : r.key;
+    const o = {
+        map: new WeakMap,
+        node: null,
+        live: new Set,
+        shallow: !!r?.shallow,
+        // The row key, for a child paired after the adoption (store.ts
+        // `adoptChild`, #3712) as the adoption pairs them.
+        key: typeof n === "function" ? n : n === null ? null : e => isWrappable(e) ? e[n] : undefined
+    };
+    const i = wrap(t, null, null, o);
+    if (o.shallow) {
+        i[$TARGET].s = true;
+        markRawIngest(t);
+    }
+    let s;
+    if (r?.seedLoadingValue) s = {
+        loadingValue: undefined
+    };
+    if (r?.name) {
+        s = {
+            ...s,
+            name: r.name
+        };
+        nameStore(i, r.name);
+    }
+    const c = computed(() => {
+        if (!o.node) o.node = getOwner();
+        runProjectionComputed(i, e, n);
+    }, s);
+    c.i &= ~CONFIG_AUTO_DISPOSE;
+    o.node = c;
+    return {
+        store: i,
+        node: c
+    };
+}
+
+/**
+ * A derived store: `fn` runs in a computed and writes its draft; readers of
+ * the store's keys re-run only when the keys they read change (the
+ * firewall). `fn` may be async or an async iterator; the seed is a draft,
+ * never an observable value, until the first landing (A25).
+ */ function createProjection(e, t, r) {
+    return createProjectionInternal(e, t, r).store;
+}
+
+/** `createStore(fn, seed, options)`: a projection with a user setter. */ function createStoreDerived(e, t, r) {
+    const {store: n} = createProjectionInternal(e, t, r);
+    return [ n, e => storeSetter(n, e) ];
+}
+
+export { createProjection, createStoreDerived, runProjectionComputed };

package/dist/observe/store/reconcile.js

@@ -0,0 +1,259 @@
+import { isEqual } from "../core/core.js";
+
+import { isOwned, $OWNER, storeLookup, lookupTarget } from "./target.js";
+
+import { userWriting, unwrapValue, adoptPB, sameKey, materializePB, notifyFold, sameRow, targetsEqual, bumpDeep, notifyKeyValue, notifyKeyDiff, notifyFoldTail, hasAccessorFlag } from "./store.js";
+
+import { optHooks } from "./hooks.js";
+
+import { $TARGET, markRawIngest, isWrappable, rawValuesUsed, isRawValue } from "./types.js";
+
+/**
+ * Store — reconcile: the immutable-diff adoption channel (INTERNALS §3).
+ *
+ * Reconcile never merge-writes into backing objects: it adopts `incoming`
+ * as the backing at every proxied level (an internal pointer swap at the
+ * fold — no clones, no user-object mutation), value-notifies only where
+ * nodes exist, and descends into a changed child pair only where a target
+ * with nodes or the sticky descendants flag exists below (§6d: diff the
+ * listened path, not every cell). Reference-equal unowned pairs skip
+ * outright (an owned backing is setter-diverged and must diff).
+ *
+ * Keyed arrays: the aligned prefix is walked positionally; from the first
+ * misalignment rows match by key (surviving rows keep their proxy
+ * identity), unkeyed items fall back to position.
+ */ function reconcileState(e, n, t, o = false) {
+    if (n == null) throw new Error("");
+    const f = n?.[$TARGET];
+    if (f === undefined || f.px !== n) throw new Error("");
+    const l = t === null ? null : typeof t === "string" ? e => e?.[t] : t;
+    // A user's reconcile on an optimistic family (S4): not an adoption of
+    // truth but an optimistic edit — the keyed diff is written into the draft
+    // (a matched row keeps its proxy, its changed leaves become its guesses),
+    // and the setter's exit turns the draft into guesses like any.
+        if (userWriting() && f.fam?.opt === true) {
+        optHooks.reconcile(n, unwrapValue(e), l);
+        return;
+    }
+    // Replace-mode root handed another store's proxy: chain to it (§7b).
+        if (o && e !== n && e?.[$TARGET] !== undefined) {
+        const n = f.pb ?? f.v;
+        if (n === e) return;
+ // already chained to this store
+                adoptPB(f, e);
+        return;
+    }
+    const i = unwrapValue(e);
+    if (l) {
+        const e = f.pb ?? f.v;
+        const n = l(e);
+        if (n !== undefined && !sameKey(l(i), n)) {
+            if (!o) throw new Error("");
+            // A different entity at the root: the old backing is disowned (wraps
+            // fresh if re-handed) and the new one adopted whole.
+                        const e = f.pb ?? f.v;
+            if (isOwned(e)) delete e[$OWNER]; else (f.fam?.map ?? storeLookup).delete(e);
+            adoptPB(f, i);
+            return;
+        }
+    }
+    applyAdopt(f, i, l, o);
+}
+
+/** Adopt `incoming` at `t` and notify its nodes — one leaf write per
+ * changed observed key, the structural nodes once — descending into
+ * changed child pairs that are proxied below. */ function applyAdopt(e, n, t, o = false) {
+    // The diff base is the view the nodes were last told (#3296). A nested
+    // overlay draft (`Object.create(v)`, #3044) reads a key the draft deleted
+    // as present through its prototype; materialized first — `adoptPB` does
+    // so anyway, after the base was taken — so a deletion the draft made is
+    // a deletion here (#3743: the presence and value diffs both read `old`).
+    const f = e.ovl ? materializePB(e) : e.pb ?? e.v;
+    if (n === f && !isOwned(f)) return;
+    const l = e.fam;
+    // Q-D: a landing on an optimistic family is reconciled against the VIEW
+    // — key matching from the arrangement the guesses made (R28), so a row
+    // the guess added keeps its proxy when the server returns it.
+        const i = l?.opt === true ? optHooks.view(e, f) : f;
+    const s = Array.isArray(n);
+    const u = e.s === true;
+    const r = f;
+    adoptPB(e, n, false);
+    if (u) markRawIngest(n);
+    if (Array.isArray(i) !== s) {
+        notifyFold(e, r, n);
+        return;
+    }
+    if (s) {
+        const f = i;
+        const s = n;
+        const a = e.n;
+        let c = 0;
+        if (t && !u) {
+            const i = f.length;
+            const u = s.length;
+            let d = false;
+            let p = 0;
+            // Aligned prefix: same row (by reference or key) at the same index.
+                        for (const y = Math.min(i, u); p < y; p++) {
+                const i = s[p];
+                const u = f[p];
+                if (u !== i && !sameRow(u, i, t)) break;
+ // misaligned: fall to the keyed remainder below
+                                if ((u !== i || i !== null && typeof i === "object" && isOwned(i)) && i !== null && typeof i === "object") descend(unwrapValue(u), i, t, l, o);
+                if (e.dk !== null && !d && !(i !== null && typeof i === "object" ? targetsEqual(u, i) : isEqual(u, i))) {
+                    bumpDeep(e);
+                    d = true;
+                }
+                if (a !== null) {
+                    const e = a[p];
+                    if (e !== undefined) {
+                        c++;
+                        notifyKeyValue(e, p, r[p], i, r, n);
+                    }
+                }
+            }
+            if (e.dk !== null && !d && p < s.length) bumpDeep(e);
+            const y = p;
+ // misalignment point (== nlen on aligned ticks)
+                        let w = null;
+            for (;p < s.length; p++) {
+                const e = s[p];
+                if (e !== null && typeof e === "object") {
+                    const n = t(e);
+                    let i;
+                    if (n !== undefined) {
+                        if (w === null) {
+                            w = new Map;
+                            for (let e = y; e < f.length; e++) {
+                                const n = unwrapValue(f[e]);
+                                if (n !== null && typeof n === "object") {
+                                    const o = t(n);
+                                    if (o === undefined) continue;
+                                    const f = w.get(o);
+                                    if (f === undefined) w.set(o, e); else if (Array.isArray(f)) f.push(e); else w.set(o, [ f, e ]);
+                                }
+                            }
+                        }
+                        const e = w.get(n);
+                        if (e === undefined) i = undefined; else if (Array.isArray(e)) {
+                            i = unwrapValue(f[e.shift()]);
+                            if (e.length === 1) w.set(n, e[0]);
+                        } else {
+                            i = unwrapValue(f[e]);
+                            w.delete(n);
+                        }
+                    } else {
+                        i = unwrapValue(f[p]);
+ // keyless item: positional fallback
+                                        }
+                    descend(i, e, t, l, o);
+                }
+                if (a !== null) {
+                    const e = a[p];
+                    if (e !== undefined) {
+                        c++;
+                        notifyKeyDiff(e, p, r, n, false);
+                    }
+                }
+            }
+        } else {
+            const i = Math.min(f.length, s.length);
+            const d = s.length;
+            let p = false;
+            for (let y = 0; y < d; y++) {
+                const d = s[y];
+                if (!u && y < i && d !== null && typeof d === "object") descend(unwrapValue(f[y]), d, t, l, o);
+                if (e.dk !== null && !p && !(d !== null && typeof d === "object" ? targetsEqual(f[y], d) : isEqual(f[y], d))) {
+                    bumpDeep(e);
+                    p = true;
+                }
+                if (a !== null) {
+                    const e = a[y];
+                    if (e !== undefined) {
+                        c++;
+                        notifyKeyDiff(e, y, r, n, false);
+                    }
+                }
+            }
+        }
+        // Indices past the new length (and `length` itself) still have nodes.
+                if (a !== null && c < e.nc) {
+            for (const e of Reflect.ownKeys(a)) {
+                const t = typeof e === "string" ? +e : NaN;
+                if (!(t >= 0 && t < s.length)) notifyKeyDiff(a[e], e, r, n, false);
+            }
+        }
+        notifyFoldTail(e, r, n);
+        return;
+    }
+    const a = e.n;
+    let c = 0;
+    let d = false;
+    for (const f in n) {
+        const s = n[f];
+        const p = r[f];
+        const y = s !== null && typeof s === "object";
+        if (p === s && (!y || !isOwned(s)) && (a === null || a[f] === undefined || !hasAccessorFlag(a[f]))) {
+            if (a !== null && a[f] !== undefined) c++;
+            continue;
+        }
+        if (y && !u) descend(unwrapValue(i[f]), s, t, l, o);
+        if (e.dk !== null && !d && !(y ? targetsEqual(p, s) : isEqual(p, s))) {
+            bumpDeep(e);
+            d = true;
+        }
+        if (a !== null) {
+            const e = a[f];
+            if (e !== undefined) {
+                c++;
+                notifyKeyValue(e, f, p, s, r, n);
+            }
+        }
+    }
+    const p = Object.getOwnPropertySymbols(n);
+    for (let e = 0; e < p.length; e++) {
+        const f = p[e];
+        if (f === $OWNER) continue;
+        const i = n[f];
+        if (!u && i !== null && typeof i === "object") descend(unwrapValue(r[f]), i, t, l, o);
+        if (a !== null) {
+            const e = a[f];
+            if (e !== undefined) {
+                c++;
+                notifyKeyValue(e, f, r[f], i, r, n);
+            }
+        }
+    }
+    // Keys the incoming object no longer has still have nodes.
+        if (a !== null && c < e.nc) {
+        for (const e of Reflect.ownKeys(a)) {
+            if (!hasOwnP.call(n, e)) notifyKeyDiff(a[e], e, r, n, false);
+        }
+    }
+    notifyFoldTail(e, r, n);
+}
+
+const hasOwnP = Object.prototype.hasOwnProperty;
+
+/** Descend into a changed child pair — only where something is proxied
+ * below (§6d), never into a raw-marked leaf, never across array/object or a
+ * key mismatch (that is a replacement, handled by the parent's slot). */ function descend(e, n, t, o, f = false) {
+    if (e === null || typeof e !== "object" || n === null || typeof n !== "object") return;
+    const l = lookupTarget(e, o);
+    if (l === undefined) return;
+ // nothing proxied below this pair
+        if (!isWrappable(n)) return;
+    if (rawValuesUsed && isRawValue(n)) return;
+    n = unwrapValue(n);
+    if (Array.isArray(e) !== Array.isArray(n)) return;
+    if (t) {
+        const o = t(e);
+        const f = t(n);
+        if (o !== undefined && f !== undefined && !sameKey(o, f)) return;
+    }
+    if (!f && t !== null && !l.d) return;
+    applyAdopt(l, n, t, f);
+}
+
+export { reconcileState };