@fluixi/reactive 1.0.0-alpha.83 → 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

@@ -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,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
@@ -334,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' &&
@@ -485,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();
@@ -506,6 +600,8 @@ const SETTER_METHODS = [
     'splice',
     'insert',
     'removeAt',
+    'replace',
+    'clear',
     'unwrap',
     'toObservable',
 ];
@@ -515,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 });
 }