@fluixi/reactive 1.0.0-alpha.82 → 1.0.0-alpha.84

package/dist/lib/store/store.d.ts

@@ -37,10 +37,82 @@ declare class Store<T> {
     splice(path: string, start: number, deleteCount: number, ...items: any[]): any[];
     insert(path: string, index: number, value: any): void;
     removeAt(path: string, index: number): any[];
+    /**
+     * Swap a whole value, rather than merging into it.
+     *
+     * `set(partial)` merges per key, which is what you want for an object and never what
+     * you want for an array. This replaces: `replace(value)` at the root, or
+     * `replace(path, value)` further down.
+     *
+     * @example
+     * ```ts
+     * const [items, set] = createStore([1, 2, 3]);
+     * set.replace([]);            // now empty
+     * set.replace(['a', 'b']);    // now two entries
+     * ```
+     */
+    replace(pathOrValue: any, maybeValue?: any): void;
+    /**
+     * Empty an array, at the root or at a path.
+     *
+     * @example
+     * ```ts
+     * set.clear();          // the root array
+     * set.clear('todos');   // a nested one
+     * ```
+     */
+    clear(path?: string): void;
     toObservable(): Observable<T>;
     dispose(): void;
 }
+/**
+ * A fine-grained reactive store: a plain object tree that tracks reads per key.
+ *
+ * Returns the state and its setter as a tuple. The state is a proxy, so reading a
+ * property subscribes the current computation to that property alone, and a write
+ * elsewhere in the tree does not disturb it. Signals are created lazily, one per key
+ * that something actually reads, so the cost follows what the app looks at rather than
+ * the size of the state.
+ *
+ * The state is immutable from the outside by default, assigning to it does nothing, and
+ * `set` is the way in. That is what makes the tracking trustworthy, since every change
+ * goes through a path the store can see.
+ *
+ * `store()` wraps this as a single binding for the common case. Prefer it unless the
+ * state has a `set` key of its own, which the single-binding form cannot express.
+ *
+ * @example
+ * ```ts
+ * const [state, setState] = createStore({ user: { name: 'Ada' }, count: 0 });
+ *
+ * effect(() => console.log(state.user.name));   // tracks user.name only
+ * setState('count', 1);                         // the effect does not re-run
+ * setState('user.name', 'Grace');               // now it does
+ * ```
+ *
+ * @example A patch merges the keys it names; a dot path reaches through arrays:
+ * ```ts
+ * setState({ count: 5 });                       // user is untouched
+ * setState('todos.0.done', true);
+ * setState('count', (n) => n + 1);              // or derive from the current value
+ * ```
+ */
 declare function createStore<T>(initialState: T, options?: StoreOptions<T>): [Immutable<T>, Store<T>['set']];
+/**
+ * A store you assign to directly, without a setter.
+ *
+ * The same per-key tracking as `createStore`, with the immutability dropped, so
+ * `state.count = 1` is a tracked write. Reach for it when the state is local to one
+ * component and the indirection of a setter buys nothing. The cost is that a change
+ * can come from anywhere holding the object.
+ *
+ * @example
+ * ```ts
+ * const state = createMutableStore({ count: 0 });
+ * effect(() => console.log(state.count));
+ * state.count = 1;   // the effect re-runs
+ * ```
+ */
 declare function createMutableStore<T>(initialState: T, options?: Omit<StoreOptions<T>, 'immutable'>): Store<T>;
 /** A store whose state is derived from a reactive function. */
 declare function createComputedStore<T>(fn: () => T, options?: StoreOptions<T>): Store<T>;

package/dist/lib/store/store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../../src/lib/store/store.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../../src/lib/store/store.ts"],"names":[],"mappings":"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"}

package/dist/lib/store/store.js

@@ -1,9 +1,63 @@
 import { $PROXY, batch, createEffect, createMemo, createSignal, untrack, } from '@fluixi/reactive/signal';
+import { isObserved, reportReactiveDispose, reportReactiveMove, reportReactiveNode, withReactiveOrigin, } from '../signal/graph/observe.js';
 export const $RAW = Symbol('store-raw'), $NODE = Symbol('store-node'), $HAS = Symbol('store-has'), $SELF = Symbol('store-self'), $TRACK = Symbol('store-track'), $NAME = Symbol('store-name'), $STORE = Symbol('store-store');
 const NODES = new WeakMap();
 const PROXIES = new WeakMap();
-function createDataNode(initial) {
-    const [get, set] = createSignal(initial);
+const OWNERS = new WeakMap();
+/** Every tracked object back to the state it belongs to, for deciding what is still in use. */
+const ROOTS = new WeakMap();
+/**
+ * Say goodbye to the signals of an object a write replaced.
+ *
+ * `set('items', [...items, one])` drops the old array but keeps the objects in it, so what
+ * is still reachable from the state keeps its nodes and only the rest is let go. Without
+ * this a watcher accumulates a card per key of every array a list ever had.
+ *
+ * Only when something is watching: this walks the state, and nothing else needs it.
+ */
+function forgetReplaced(dead, state) {
+    if (!isTrackable(dead) || !isObserved())
+        return;
+    const alive = new Set();
+    const keep = (value) => {
+        if (!isTrackable(value) || alive.has(value))
+            return;
+        alive.add(value);
+        for (const child of Object.values(value))
+            keep(child);
+    };
+    keep(ROOTS.get(state) ?? state);
+    const seen = new Set();
+    const drop = (value) => {
+        if (!isTrackable(value))
+            return;
+        const target = value;
+        if (alive.has(target) || seen.has(target))
+            return;
+        seen.add(target);
+        const ns = NODES.get(target);
+        if (ns) {
+            for (const node of ns.keys.values())
+                reportReactiveDispose(node);
+            if (ns.all)
+                reportReactiveDispose(ns.all);
+            NODES.delete(target);
+            OWNERS.delete(target);
+            PROXIES.delete(target);
+        }
+        for (const child of Object.values(target))
+            drop(child);
+    };
+    drop(dead);
+}
+const pathOf = (base, key, array) => array ? `${base}[${String(key)}]` : `${base}.${String(key)}`;
+function createDataNode(initial, ns, key) {
+    // A key signal is made the first time something reads it, which can be anywhere. Named and
+    // attributed to the object it belongs to, so a graph shows it under that object at the
+    // line the store was declared rather than wherever it was first read.
+    const owner = ns?.owner;
+    const label = owner && key !== undefined ? pathOf(owner.name, key, ns?.array) : undefined;
+    const [get, set] = withReactiveOrigin(owner?.store, () => createSignal(initial, label ? { name: label } : undefined));
     const node = get;
     node.$ = set;
     return node;
@@ -11,18 +65,52 @@ function createDataNode(initial) {
 function nodesOf(target) {
     let ns = NODES.get(target);
     if (!ns)
-        NODES.set(target, (ns = { keys: new Map() }));
+        NODES.set(target, (ns = { keys: new Map(), owner: OWNERS.get(target), array: Array.isArray(target) }));
+    // An object can be reached before the store has claimed it, a write touches it, or it is
+    // read through something other than its parent's proxy. Caching "no owner" there would
+    // leave every key signal it ever makes unnamed and unattached.
+    else if (!ns.owner)
+        ns.owner = OWNERS.get(target);
     return ns;
 }
 function keyNode(ns, key, seed) {
     let node = ns.keys.get(key);
     if (!node)
-        ns.keys.set(key, (node = createDataNode(seed)));
+        ns.keys.set(key, (node = createDataNode(seed, ns, key)));
     return node;
 }
+/**
+ * Say where an object now sits in the state.
+ *
+ * A write that replaces a container leaves the objects inside it where they were, holding
+ * the same signals, under a new key signal. Re-claiming moves those signals across so they
+ * stay attached to the object they describe instead of to the node that used to hold it.
+ */
+function claim(target, holder, name, parent) {
+    const was = OWNERS.get(target);
+    if (was && was.store === holder && was.name === name)
+        return;
+    const owner = { store: holder, name };
+    OWNERS.set(target, owner);
+    ROOTS.set(target, ROOTS.get(parent) ?? parent);
+    // It may already have a node store, from an earlier read or an earlier position.
+    const ns = NODES.get(target);
+    if (!ns)
+        return;
+    ns.owner = owner;
+    if (!isObserved())
+        return;
+    for (const [key, node] of ns.keys)
+        reportReactiveMove(node, holder, pathOf(name, key, ns.array));
+    if (ns.all)
+        reportReactiveMove(ns.all, holder, pathOf(name, '*', ns.array));
+}
 function trackKeys(target) {
     const ns = nodesOf(target);
-    (ns.all || (ns.all = createDataNode()))();
+    // Which keys exist, as opposed to what any one of them holds. It has no value of its own,
+    // so a graph would otherwise show an unexplained empty node the first time a list is
+    // iterated, which is exactly when one appears.
+    (ns.all || (ns.all = createDataNode(undefined, ns, '*')))();
 }
 // The signal setter reads a function argument as an updater, so a function value
 // has to be handed over wrapped.
@@ -73,8 +161,16 @@ const handler = {
         const desc = Object.getOwnPropertyDescriptor(target, key);
         if (desc && desc.get)
             return desc.get.call(receiver);
-        const current = keyNode(nodesOf(target), key, value)();
-        return isTrackable(current) ? box(current) : current;
+        const ns = nodesOf(target);
+        const holder = keyNode(ns, key, value);
+        const current = holder();
+        if (!isTrackable(current))
+            return current;
+        // A nested object hangs off the signal that holds it, not off the store, so a cart with
+        // three items reads as three objects rather than as a dozen loose keys.
+        if (ns.owner)
+            claim(current, holder, pathOf(ns.owner.name, key, ns.array), target);
+        return box(current);
     },
     set() {
         // The proxy is read-only; writes come in through the setter.
@@ -107,7 +203,38 @@ const handler = {
 // writes
 // Writes one key on a raw node and pokes what changed: the key's own signal, the
 // array length signal when the length moved, and the iteration signal.
-function writeKey(state, key, value) {
+/**
+ * The raw form of a value on its way into the state.
+ *
+ * `set({ items: [...cart.items, one] })` spreads proxies back in, and a store that holds its
+ * own proxies tracks each of them twice: a second node store per object, a proxy wrapping a
+ * proxy, and a graph with two signals for every key.
+ */
+function rawValue(value, seen = new Set()) {
+    if (value == null || typeof value !== 'object')
+        return value;
+    const raw = value[$RAW] ?? value;
+    if (seen.has(raw) || !isTrackable(raw))
+        return raw;
+    seen.add(raw);
+    let changed = false;
+    const swap = (v) => {
+        const next = rawValue(v, seen);
+        if (next !== v)
+            changed = true;
+        return next;
+    };
+    if (Array.isArray(raw)) {
+        const out = raw.map(swap);
+        return changed ? out : raw;
+    }
+    const out = {};
+    for (const k of Object.keys(raw))
+        out[k] = swap(raw[k]);
+    return changed ? out : raw;
+}
+function writeKey(state, key, rawInput) {
+    const value = rawValue(rawInput);
     const prev = state[key];
     if (prev === value && (value !== undefined || key in state))
         return;
@@ -121,6 +248,7 @@ function writeKey(state, key, value) {
     const node = ns.keys.get(key);
     if (node)
         pokeNode(node, value);
+    forgetReplaced(prev, state);
     if (isArray && state.length !== len) {
         const lengthNode = ns.keys.get('length');
         if (lengthNode)
@@ -189,6 +317,36 @@ function applyAt(current, segs, value) {
 function applyPath(root, path, value) {
     applyAt(root, parsePath(path), value);
 }
+/**
+ * Whether a lone array argument is a batch of `[path, value]` pairs.
+ *
+ * The batch form and a replacement array are the same shape at the call site, so the
+ * entries decide. Every one has to be a pair with a string path; anything else is a
+ * value. An empty array is not a batch, which is what made `set([])` on an array root
+ * do nothing at all.
+ */
+function isPathBatch(value) {
+    return (Array.isArray(value) &&
+        value.length > 0 &&
+        value.every((e) => Array.isArray(e) && e.length >= 2 && typeof e[0] === 'string'));
+}
+/**
+ * Replace an array's contents in place, keeping its identity.
+ *
+ * The tail is written away before the length moves, so an index that had a signal is
+ * told it is gone. Assigning `length` alone truncates without notifying anyone, which
+ * leaves a stale read behind on every removed index.
+ */
+function replaceArray(target, next) {
+    // Keys are strings everywhere else, because every other path reaches writeKey through
+    // parsePath. A numeric key here would miss the node the proxy registered under '2'.
+    for (let i = target.length - 1; i >= next.length; i--)
+        writeKey(target, String(i), undefined);
+    if (target.length !== next.length)
+        writeKey(target, 'length', next.length);
+    for (let i = 0; i < next.length; i++)
+        writeKey(target, String(i), next[i]);
+}
 /**
  * Runs the setter overloads against the raw root:
  *   set(state => newState)        whole-state updater, merged back
@@ -206,10 +364,22 @@ function applySet(root, args) {
         return;
     }
     if (Array.isArray(first) && args.length === 1) {
-        for (const entry of first)
-            if (Array.isArray(entry))
+        if (isPathBatch(first)) {
+            for (const entry of first)
                 applyPath(root, entry[0], entry[1]);
-        return;
+            return;
+        }
+        // Not a batch, so it is a value. Against an array root that is a replacement.
+        if (Array.isArray(root)) {
+            replaceArray(root, first);
+            return;
+        }
+        // An empty array asks for no updates, which is harmless either way.
+        if (first.length === 0)
+            return;
+        throw new TypeError('[fluixi] set() was given an array that is neither a batch of [path, value] ' +
+            'pairs nor a replacement for an array root. Name the path you meant, as in ' +
+            "set('items', [...]).");
     }
     if (first &&
         typeof first === 'object' &&
@@ -254,6 +424,18 @@ class Store {
         this.options = options;
         this.root = initialState;
         this.set = ((...args) => batch(() => applySet(this.root, args)));
+        if (initialState && typeof initialState === 'object') {
+            OWNERS.set(initialState, { store: this, name: options.name ?? 'store' });
+            ROOTS.set(initialState, initialState);
+        }
+        // One node for the store itself, so the line that declared it is in the graph even
+        // though its key signals are not made until something reads them.
+        reportReactiveNode({
+            kind: 'store',
+            node: this,
+            handle: () => this.root,
+            name: options.name,
+        });
     }
     get state() {
         return box(this.root);
@@ -345,6 +527,58 @@ class Store {
         this.set(path, arr);
         return removed;
     }
+    /**
+     * Swap a whole value, rather than merging into it.
+     *
+     * `set(partial)` merges per key, which is what you want for an object and never what
+     * you want for an array. This replaces: `replace(value)` at the root, or
+     * `replace(path, value)` further down.
+     *
+     * @example
+     * ```ts
+     * const [items, set] = createStore([1, 2, 3]);
+     * set.replace([]);            // now empty
+     * set.replace(['a', 'b']);    // now two entries
+     * ```
+     */
+    replace(pathOrValue, maybeValue) {
+        if (arguments.length >= 2) {
+            const target = rawAt(this.root, String(pathOrValue));
+            const next = maybeValue;
+            if (Array.isArray(target) && Array.isArray(next)) {
+                replaceArray(target, next);
+                return;
+            }
+            this.set(pathOrValue, next);
+            return;
+        }
+        const root = this.root;
+        if (Array.isArray(root) && Array.isArray(pathOrValue)) {
+            replaceArray(root, pathOrValue);
+            return;
+        }
+        this.set(pathOrValue);
+    }
+    /**
+     * Empty an array, at the root or at a path.
+     *
+     * @example
+     * ```ts
+     * set.clear();          // the root array
+     * set.clear('todos');   // a nested one
+     * ```
+     */
+    clear(path) {
+        const target = path === undefined ? this.root : rawAt(this.root, path);
+        if (Array.isArray(target)) {
+            replaceArray(target, []);
+            return;
+        }
+        if (target && typeof target === 'object') {
+            for (const key of Object.keys(target))
+                writeKey(target, key, undefined);
+        }
+    }
     toObservable() {
         const [get] = createSignal(this.state);
         return get.toObservable();
@@ -366,6 +600,8 @@ const SETTER_METHODS = [
     'splice',
     'insert',
     'removeAt',
+    'replace',
+    'clear',
     'unwrap',
     'toObservable',
 ];
@@ -375,11 +611,58 @@ function attachStoreMethods(target, store) {
     target.$ = store.reactive.bind(store);
 }
 // public api
+/**
+ * A fine-grained reactive store: a plain object tree that tracks reads per key.
+ *
+ * Returns the state and its setter as a tuple. The state is a proxy, so reading a
+ * property subscribes the current computation to that property alone, and a write
+ * elsewhere in the tree does not disturb it. Signals are created lazily, one per key
+ * that something actually reads, so the cost follows what the app looks at rather than
+ * the size of the state.
+ *
+ * The state is immutable from the outside by default, assigning to it does nothing, and
+ * `set` is the way in. That is what makes the tracking trustworthy, since every change
+ * goes through a path the store can see.
+ *
+ * `store()` wraps this as a single binding for the common case. Prefer it unless the
+ * state has a `set` key of its own, which the single-binding form cannot express.
+ *
+ * @example
+ * ```ts
+ * const [state, setState] = createStore({ user: { name: 'Ada' }, count: 0 });
+ *
+ * effect(() => console.log(state.user.name));   // tracks user.name only
+ * setState('count', 1);                         // the effect does not re-run
+ * setState('user.name', 'Grace');               // now it does
+ * ```
+ *
+ * @example A patch merges the keys it names; a dot path reaches through arrays:
+ * ```ts
+ * setState({ count: 5 });                       // user is untouched
+ * setState('todos.0.done', true);
+ * setState('count', (n) => n + 1);              // or derive from the current value
+ * ```
+ */
 function createStore(initialState, options = { immutable: true }) {
     const store = new Store(initialState, options);
     attachStoreMethods(store.set, store);
     return [store.proxy, store.set];
 }
+/**
+ * A store you assign to directly, without a setter.
+ *
+ * The same per-key tracking as `createStore`, with the immutability dropped, so
+ * `state.count = 1` is a tracked write. Reach for it when the state is local to one
+ * component and the indirection of a setter buys nothing. The cost is that a change
+ * can come from anywhere holding the object.
+ *
+ * @example
+ * ```ts
+ * const state = createMutableStore({ count: 0 });
+ * effect(() => console.log(state.count));
+ * state.count = 1;   // the effect re-runs
+ * ```
+ */
 function createMutableStore(initialState, options = {}) {
     return new Store(initialState, { ...options, immutable: false });
 }