@fluixi/reactive 1.0.0-alpha.83 → 1.0.0-alpha.85

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

@@ -66,7 +66,7 @@ function nodesOf(target) {
     let ns = NODES.get(target);
     if (!ns)
         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
+    // 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)
@@ -109,7 +109,7 @@ function trackKeys(target) {
     const ns = nodesOf(target);
     // 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.
+    // 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
@@ -317,12 +317,43 @@ 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
  *   set(partialObject)            per-key merge
  *   set([[path, valOrFn], ...])   batch of path updates
- *   set(path, ['seg', ...], val)  path plus extra segments
+ *   set(path, ...steps, val)      a step per argument: key, index, [indices],
+ *                                 { from, to, by }, a predicate, or '*'
  *   set(path, val | updater)      the common form (dotted, [n], [*])
  */
 function applySet(root, args) {
@@ -334,10 +365,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' &&
@@ -346,12 +389,98 @@ function applySet(root, args) {
         mergeInto(root, first);
         return;
     }
-    if (Array.isArray(args[1]) && args.length >= 3) {
-        applyPath(root, `${first}.${args[1].join('.')}`, args[2]);
+    // Three or more arguments: every one but the last selects a step, the last is the
+    // value. This used to read `args[1]` as the value and ignore the rest, so
+    // `set('items', 0, 'done', true)` wrote the number 0 over `items`, accepted by the
+    // typings, and silent.
+    if (args.length >= 3) {
+        setDeep(root, args.slice(0, -1), args[args.length - 1]);
         return;
     }
     applyPath(root, String(first), args[1]);
 }
+/**
+ * Which keys a selector names at this level.
+ *
+ * The typings offer four shapes for the steps between a path and a value, and each one
+ * resolves here rather than at a call site:
+ *   'name' | 2        a single key, dotted paths expanded by the caller
+ *   [0, 2]            several indices of an array
+ *   { from, to, by }  a range of indices
+ *   (item, i) => bool a predicate over an array
+ *   '*'               every key
+ */
+function selectKeys(current, selector) {
+    if (typeof selector === 'function') {
+        if (!Array.isArray(current))
+            return [];
+        const keys = [];
+        for (let i = 0; i < current.length; i++)
+            if (selector(current[i], i))
+                keys.push(i);
+        return keys;
+    }
+    if (Array.isArray(selector)) {
+        // Against an array these are indices. Against anything else there is nothing to
+        // index, so they are path segments: the form this function used to be given.
+        return Array.isArray(current) ? selector.map(Number) : selector.map(String);
+    }
+    if (selector &&
+        typeof selector === 'object' &&
+        ('from' in selector || 'to' in selector || 'by' in selector)) {
+        if (!Array.isArray(current))
+            return [];
+        const by = selector.by ?? 1;
+        const from = selector.from ?? 0;
+        const to = selector.to ?? current.length - 1;
+        const keys = [];
+        for (let i = from; i <= to; i += by)
+            if (i >= 0 && i < current.length)
+                keys.push(i);
+        return keys;
+    }
+    if (selector === '*') {
+        return Array.isArray(current)
+            ? current.map((_, i) => i)
+            : Object.keys(current ?? {});
+    }
+    return [selector];
+}
+/**
+ * Walk the selectors, writing the value at every leaf they reach.
+ *
+ * A string step is expanded first, so `set('a.b', 'c', v)` and `set('a', 'b', 'c', v)`
+ * land in the same place. Missing containers are created on the way down, as an array
+ * when the next step looks like an index.
+ */
+function setDeep(current, selectors, value) {
+    if (current == null)
+        return;
+    // Expand a dotted or bracketed string into its own steps before selecting.
+    const [head, ...rest] = selectors;
+    if (typeof head === 'string') {
+        const parts = parsePath(head);
+        if (parts.length > 1) {
+            setDeep(current, [...parts, ...rest], value);
+            return;
+        }
+    }
+    const keys = selectKeys(current, head);
+    if (rest.length === 0) {
+        for (const key of keys)
+            writeKey(current, key, nextValue(value, current[key]));
+        return;
+    }
+    for (const key of keys) {
+        let next = current[key];
+        if (next == null || typeof next !== 'object') {
+            const lookahead = rest[0];
+            next = typeof lookahead === 'number' || /^\d+$/.test(String(lookahead)) ? [] : {};
+            writeKey(current, key, next);
+        }
+        setDeep(next, rest, value);
+    }
+}
 function clone(value) {
     if (value == null || typeof value !== 'object')
         return value;
@@ -485,6 +614,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();
@@ -506,6 +687,8 @@ const SETTER_METHODS = [
     'splice',
     'insert',
     'removeAt',
+    'replace',
+    'clear',
     'unwrap',
     'toObservable',
 ];
@@ -515,11 +698,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 });
 }