@solidjs/signals 2.0.0-beta.8 → 2.0.0-rc.0

package/dist/prod/store/optimistic.js

@@ -0,0 +1,217 @@
+import { STATUS_PENDING, CONFIG_AUTO_DISPOSE, NOT_PENDING } from "../core/constants.js";
+
+import { computed } from "../core/core.js";
+
+import { GlobalQueue, schedule, currentTransition, insertSubs, setProjectionWriteActive, projectionWriteActive } from "../core/scheduler.js";
+
+import "../core/invariants.js";
+
+import "../core/verdict.js";
+
+import "../core/effect.js";
+
+import { installOptimisticEngine } from "../core/optimistic.js";
+
+import { runProjectionComputed } from "./projection.js";
+
+import { $TARGET, STORE_FIREWALL, storeSetter, STORE_OPTIMISTIC_OVERRIDE, STORE_NODE, STORE_OPTIMISTIC_OWNERS, getOverlayLayer, STORE_VALUE, $DELETED, isWrappable, wrap, visibleNodeValue, $TRACK, notifySelf, STORE_WRAP, createStoreProxy, storeTraps, STORE_LOOKUP, STORE_SHALLOW, markRawIngest, STORE_OPTIMISTIC } from "./store.js";
+
+function createOptimisticStore(e, t, i) {
+    // Register clear function with scheduler; store nodes marked
+    // STORE_OPTIMISTIC take the engine's write path, so install it before any
+    // node can be created.
+    installOptimisticEngine();
+    if (!GlobalQueue.Dt) {
+        GlobalQueue.Dt = clearOptimisticStores;
+        // Store half of the engine's override blockage (#2951): signal-form
+        // createOptimistic carries the pending async and the override on ONE node,
+        // so transitionBlocked sees both; a derived optimistic STORE splits them —
+        // the layer sits on store targets while the in-flight truth lives on the
+        // firewall computed. Without this, the transition adopting a bare store
+        // write settled in the same flush that started the refetch and its settle
+        // consumed the layer mid-flight (follow-up writes then drafted from base,
+        // clobbering instead of composing). Optimistic state clears when truth
+        // lands or its transaction ends — never mid-refetch. Wrapped here (engine
+        // is already installed above) so store-free apps never carry the check.
+                const e = GlobalQueue.Tn;
+        GlobalQueue.Tn = t => {
+            for (const e of t.cn) {
+                if ((e[$TARGET]?.[STORE_FIREWALL]?.S ?? 0) & STATUS_PENDING) return true;
+            }
+            return e(t);
+        };
+    }
+    const r = typeof e === "function";
+    // Plain form: the second slot carries options.
+        if (!r && i === undefined) i = t;
+    const o = r ? t : e;
+    const n = r ? e : undefined;
+    // Create optimistic projection store
+        const {store: c} = createOptimisticProjectionInternal(n, o, i);
+    return [ c, e => storeSetter(c, e) ];
+}
+
+// Clear the optimistic overrides of a settling batch of stores and notify
+// signals. Owns the whole batch (iterate + clear + reschedule) so the
+// scheduler's flush tail carries only a size-guarded hook call. The
+// completing transition scopes each clear to its own layer keys (#2899).
+function clearOptimisticStores(e, t) {
+    for (const i of e) {
+        const e = i[$TARGET];
+        if (e?.[STORE_OPTIMISTIC_OVERRIDE]) clearOptimisticOverride(e, t);
+    }
+    e.clear();
+    schedule();
+}
+
+/**
+ * Consume optimistic layer entries and reset their backing nodes to base.
+ * With `completing` (settle path, #2899) only entries the settling
+ * transaction owns are consumed — the layer is store-wide but concurrent
+ * actions revert independently, so keys stamped by a still-in-flight
+ * transition survive (node-level overrides already have this granularity via
+ * _optimisticNodes; this is the layer's half). `null` consumes ambient
+ * (transaction-less) entries at plain flush end. Omitted (projection landing:
+ * fresh authoritative data) consumes everything — the correction supersedes
+ * every tentative layer.
+ */ function clearOptimisticOverride(e, t) {
+    const i = e[STORE_OPTIMISTIC_OVERRIDE];
+    if (!i) return;
+    const r = e[STORE_NODE];
+    const o = e[STORE_OPTIMISTIC_OWNERS];
+    const n = t !== undefined;
+    let c = false;
+    let s = false;
+    // Use projectionWriteActive to bypass optimistic signal behavior (no lane creation)
+    // This ensures reversion effects go to regular queues, not lane queues
+        const O = projectionWriteActive;
+    setProjectionWriteActive(true);
+    try {
+        for (const O of Reflect.ownKeys(i)) {
+            if (n) {
+                let e = o?.[O] ?? null;
+                // Resolve merge chains (entangled actions settle as one); path-compress
+                // so later keys skip the walk. A dead owner (`_done === true`) settled
+                // through some other path — never strand its entry. A null owner is an
+                // ambient write: its batch belongs to whichever transaction adopted it
+                // (initTransition mid-batch) or to the plain flush, so it clears on
+                // whichever clear call reaches this store first.
+                                if (e) {
+                    if (typeof e.fn === "object") e = o[O] = currentTransition(e);
+                    if (e !== t && e.fn !== true) {
+                        s = true;
+                        continue;
+                    }
+                }
+            }
+            delete i[O];
+            if (o) delete o[O];
+            c = true;
+            const T = r?.[O];
+            if (T) {
+                // Clear lane association so effects go to regular queue
+                T.Ke = undefined;
+                // Re-read from base — this key left the optimistic layer above, so the
+                // overlay resolves to STORE_OVERRIDE or STORE_VALUE.
+                                const t = getOverlayLayer(e, O);
+                const i = t ? t[O] : e[STORE_VALUE][O];
+                const r = i === $DELETED ? undefined : i;
+                const o = isWrappable(r) ? wrap(r, e) : r;
+                const n = visibleNodeValue(T);
+                T._e = NOT_PENDING;
+                T.sn = null;
+                T.De = NOT_PENDING;
+                T.Ue = o;
+                if (!T.be || !T.be(n, o)) {
+                    insertSubs(T, true);
+                    schedule();
+                }
+            }
+        }
+        if (!s) {
+            // Assignment, not delete: StoreNode targets share one pre-initialized
+            // hidden class (see createStoreProxy) and a delete would demote it.
+            e[STORE_OPTIMISTIC_OVERRIDE] = undefined;
+            e[STORE_OPTIMISTIC_OWNERS] = undefined;
+        }
+        // Notify $TRACK
+                if (c && r?.[$TRACK]) {
+            r[$TRACK].Ke = undefined;
+            notifySelf(e);
+        }
+    } finally {
+        setProjectionWriteActive(O);
+    }
+}
+
+function createOptimisticProjectionInternal(e, t, i) {
+    let r;
+    const o = new WeakMap;
+    const n = !!i?.shallow;
+    const wrapper = e => {
+        e[STORE_WRAP] = wrapProjection;
+        e[STORE_LOOKUP] = o;
+        if (n) {
+            e[STORE_SHALLOW] = true;
+            markRawIngest(e[STORE_VALUE]);
+        }
+        e[STORE_OPTIMISTIC] = true;
+ // Mark as optimistic store
+                Object.defineProperty(e, STORE_FIREWALL, {
+            get() {
+                return r;
+            },
+            configurable: true
+        });
+    };
+    const wrapProjection = e => {
+        if (o.has(e)) return o.get(e);
+        if (e[$TARGET]?.[STORE_WRAP] === wrapProjection) return e;
+        const t = createStoreProxy(e, storeTraps, wrapper);
+        o.set(e, t);
+        return t;
+    };
+    const c = wrapProjection(t);
+    // If there's a projection function, create a computed to drive it
+        if (e) {
+        // All writes inside firewall recompute must go to STORE_OVERRIDE (base), not
+        // STORE_OPTIMISTIC_OVERRIDE. The outer wrap covers the sync body (including
+        // `fn(draft)` and the initial commit); `wrapCommit` re-applies the flag for
+        // async yields because they fire outside any enclosing try/finally. It also
+        // consumes stale optimistic overlays once fresh projected data lands.
+        const clearProjectionOverride = () => {
+            const e = c[$TARGET];
+            if (e?.[STORE_OPTIMISTIC_OVERRIDE]) clearOptimisticOverride(e);
+        };
+        const wrapCommit = e => {
+            const t = projectionWriteActive;
+            setProjectionWriteActive(true);
+            try {
+                e();
+                clearProjectionOverride();
+            } finally {
+                setProjectionWriteActive(t);
+            }
+        };
+        // seedLoadingValue: born-committed firewall, same as createProjection.
+                let t;
+        if (i?.seedLoadingValue) t = {
+            loadingValue: undefined
+        };
+        r = computed(() => {
+            setProjectionWriteActive(true);
+            try {
+                runProjectionComputed(c, e, i?.key === undefined ? "id" : i.key, wrapCommit, clearProjectionOverride);
+            } finally {
+                setProjectionWriteActive(false);
+            }
+        }, t);
+        r.T &= ~CONFIG_AUTO_DISPOSE;
+    }
+    return {
+        store: c,
+        node: r
+    };
+}
+
+export { createOptimisticStore };

package/dist/prod/store/projection.js

@@ -0,0 +1,231 @@
+import { computed } from "../core/core.js";
+
+import { getOwner } from "../core/owner.js";
+
+import { setProjectionWriteActive } from "../core/scheduler.js";
+
+import { handleAsync } from "../core/async.js";
+
+import "../core/verdict.js";
+
+import "../core/effect.js";
+
+import { CONFIG_AUTO_DISPOSE } from "../core/constants.js";
+
+import { reconcileState } from "./reconcile.js";
+
+import { $TARGET, STORE_VALUE, storeSetter, STORE_WRAP, createStoreProxy, storeTraps, setWriteOverride, STORE_LOOKUP, STORE_SHALLOW, markRawIngest, STORE_FIREWALL } from "./store.js";
+
+function createProjectionInternal(e, t, r) {
+    let o;
+    const n = new WeakMap;
+    // A shallow projection's children are raw and never wrapped, so the
+    // wrapper only ever runs for the root — flagging unconditionally is safe.
+        const i = !!r?.shallow;
+    const wrapper = e => {
+        e[STORE_WRAP] = wrapProjection;
+        e[STORE_LOOKUP] = n;
+        if (i) {
+            e[STORE_SHALLOW] = true;
+            markRawIngest(e[STORE_VALUE]);
+        }
+        Object.defineProperty(e, STORE_FIREWALL, {
+            get() {
+                return o;
+            },
+            configurable: true
+        });
+    };
+    const wrapProjection = e => {
+        if (n.has(e)) return n.get(e);
+        if (e[$TARGET]?.[STORE_WRAP] === wrapProjection) return e;
+        const t = createStoreProxy(e, storeTraps, wrapper);
+        n.set(e, t);
+        return t;
+    };
+    const c = wrapProjection(t);
+    // seedLoadingValue: the firewall is born committed (the seed is commit #0);
+    // the internal handleAsync serves it during the derive's first flight. The
+    // node's own value channel is void, so the loading value itself is
+    // `undefined` — presence of the key is what flips the mode.
+        let s;
+    if (r?.seedLoadingValue) s = {
+        loadingValue: undefined
+    };
+    o = computed(() => {
+        if (!o) o = getOwner();
+        runProjectionComputed(c, e, r?.key === undefined ? "id" : r.key);
+    }, s);
+    o.T &= ~CONFIG_AUTO_DISPOSE;
+    return {
+        store: c,
+        node: o
+    };
+}
+
+/**
+ * Creates a derived (projected) store. Like `createMemo` but for stores: the
+ * derive function receives a mutable draft and either mutates it in place
+ * (canonical) or returns a new value. Either way the result is reconciled
+ * against the previous draft by `options.key` (default `"id"`), so surviving
+ * items keep their proxy identity — only added/removed items are
+ * created/disposed.
+ *
+ * If the derive returns a different entity than the one currently held (the
+ * `/users/1` → `/users/2` shape), the store swaps to it rather than merging,
+ * and nothing below it is treated as surviving.
+ *
+ * Returns the projected store directly (no setter — reads only).
+ *
+ * Use this when you want the structural-sharing / per-property tracking
+ * behaviour of a store on top of a derived computation. For simple read-only
+ * derivations, `createMemo` is lighter.
+ *
+ * @param fn receives the current draft; mutate it in place or return new
+ *   data. Return is convenient for filter/derive shapes where mutation is
+ *   awkward.
+ * @param seed the backing store value to wrap and reconcile into
+ * @param options `ProjectionOptions` — `name`, `key`. `key` defaults to
+ *   `"id"`; specify it only when your data uses a different identity field
+ *   (e.g. `{ key: "uuid" }` or `{ key: u => u.slug }`), or `null` to merge
+ *   positionally with no keyed pass.
+ *
+ * @example
+ * ```ts
+ * // Mutation form — update individual fields on the draft.
+ * const summary = createProjection<{ total: number; active: number }>(
+ *   draft => {
+ *     draft.total = users().length;
+ *     draft.active = users().filter(u => u.active).length;
+ *   },
+ *   { total: 0, active: 0 }
+ * );
+ *
+ * // Return form — produce a derived collection. Reconciled by `id` so each
+ * // surviving user keeps the same store identity across recomputes.
+ * const activeUsers = createProjection<User[]>(
+ *   () => allUsers().filter(u => u.active),
+ *   []
+ * );
+ * ```
+ *
+ * @see {@link https://github.com/solidjs/x-reactivity#createprojection}
+ */ function createProjection(e, t, r) {
+    return createProjectionInternal(e, t, r).store;
+}
+
+/**
+ * Shared projection computed body used by both `createProjection` and the derived
+ * form of `createOptimisticStore`. Encapsulates the write-trap draft, `storeSetter`
+ * wrapping, the `handleAsync` subscription with a setter callback, and the commit
+ * path (which must always go through `storeSetter` so the `writeOnly` guard is
+ * engaged during `reconcile`'s property reads).
+ *
+ * `wrapCommit` is invoked for every commit (sync return and each async yield) and
+ * lets callers layer extra context around the write — e.g. the optimistic store
+ * re-enters `setProjectionWriteActive` so reconciles target `STORE_OVERRIDE`
+ * instead of `STORE_OPTIMISTIC_OVERRIDE` even when an async yield fires outside
+ * the outer `setProjectionWriteActive` scope.
+ */ function runProjectionComputed(e, t, r, o, n) {
+    const i = getOwner();
+    let c = false;
+    let s;
+    // Open loading window (seedLoadingValue): the observable store IS commit #0
+    // for the whole first flight, so the derive works a detached shadow of the
+    // seed — draft writes (pre-await, or between yields) land on the shadow and
+    // cannot tear through to readers (#2988; store reads resolve from the live
+    // backing, and the born-committed firewall removed the status gate that hid
+    // windowless drafts). Every commit point — sync return, each yield, the
+    // async landing — reconciles the shadow through the normal commit path, so
+    // a fully-sync derive still lands immediately (commit #0 superseded before
+    // any observer runs, same as a sync answer superseding loadingValue). The
+    // JSON round-trip matches the server's frozen-seed copy (seedLock): a
+    // loading-window seed is renderable data by contract. Optimistic note:
+    // onDraftWrite (override clearing) shifts from write-time to commit-time
+    // for the shadow run — an invisible draft write must not clobber a visible
+    // optimistic override mid-window.
+        const u = i.Ee ? JSON.parse(JSON.stringify(e[$TARGET][STORE_VALUE])) : null;
+    const a = new Proxy(e, createWriteTraps(() => !c || i.Te === s, n));
+    storeSetter(a, n => {
+        s = t(u ?? n);
+        c = true;
+        const commit = t => {
+            // Shadow run: a void/self return is the mutation form — the shadow
+            // carries the writes and is what commits. Commit a detached snapshot,
+            // never the shadow itself: reconcile adopts a new root value by
+            // identity, and handing it the live shadow would fuse the draft to the
+            // observable store — later shadow writes would mutate the backing
+            // silently and the next yield would diff the shadow against itself.
+            if (u && (t === undefined || t === u)) t = JSON.parse(JSON.stringify(u));
+            if (t === n || t === undefined) return;
+            const write = () => storeSetter(e, e => reconcileState(t, e, r, true));
+            o ? o(write) : write();
+        };
+        const a = handleAsync(i, s, commit);
+        // A still-open window after handleAsync means the return was the
+        // commit-#0 fall-through, not a landing — real landings arrive through
+        // the setter. A closed one is a genuine sync landing (windowless nodes
+        // were never open); commit it.
+                if (!i.Ee) commit(a);
+    });
+    return i;
+}
+
+function createWriteTraps(e, t) {
+    const r = {
+        get(e, t) {
+            let o;
+            setWriteOverride(true);
+            setProjectionWriteActive(true);
+            try {
+                o = e[t];
+            } finally {
+                setWriteOverride(false);
+                setProjectionWriteActive(false);
+            }
+            if (t === $TARGET) return o;
+            return typeof o === "object" && o !== null ? new Proxy(o, r) : o;
+        },
+        has(e, t) {
+            let r;
+            setWriteOverride(true);
+            setProjectionWriteActive(true);
+            try {
+                r = t in e;
+            } finally {
+                setWriteOverride(false);
+                setProjectionWriteActive(false);
+            }
+            return r;
+        },
+        set(r, o, n) {
+            if (e && !e()) return true;
+            setWriteOverride(true);
+            setProjectionWriteActive(true);
+            try {
+                r[o] = n;
+                t?.();
+            } finally {
+                setWriteOverride(false);
+                setProjectionWriteActive(false);
+            }
+            return true;
+        },
+        deleteProperty(r, o) {
+            if (e && !e()) return true;
+            setWriteOverride(true);
+            setProjectionWriteActive(true);
+            try {
+                delete r[o];
+                t?.();
+            } finally {
+                setWriteOverride(false);
+                setProjectionWriteActive(false);
+            }
+            return true;
+        }
+    };
+    return r;
+}
+
+export { createProjection, createProjectionInternal, createWriteTraps, runProjectionComputed };