@kuindji/reactive 1.1.0 → 1.3.0

package/dist/store.js

@@ -10,20 +10,90 @@ export function createStore(initialData = {}) {
     const pipe = createEventBus();
     const control = createEventBus();
     let effectKeys = [];
+    // Computed keys are read-only via the public `set` and recompute via the
+    // `effect` control event. `computingKeys` is a per-key re-entrancy guard so
+    // a cyclic computed throws instead of looping forever.
+    const computedKeys = new Set();
+    const computingKeys = new Set();
+    // Re-seed closures keyed in registration order so reset() can recompute each
+    // computed value from the (now cleared) deps. Without this, reset() clears
+    // `data` but leaves computed keys stale/undefined while still marked
+    // read-only, so they no longer equal fn(deps).
+    const computedReseeders = new Map();
+    // The effect listener installed for each computed key, so re-registering the
+    // same key detaches the previous recompute closure instead of leaving it
+    // attached (which would run a stale fn on every dependency change).
+    const computedEffectListeners = new Map();
+    // Multi-key object sets write every base value first with effect emission
+    // deferred (`deferEffects`), then replay effects once so computed values
+    // recompute from the final state instead of once per intermediate write.
+    // `computedBatch`, when active, records the dependency values each computed
+    // last recomputed from in this batch. A computed is skipped only when its
+    // deps are unchanged since then — so a redundant dep change is a no-op, but
+    // a dependent in a computed chain still recomputes once its upstream
+    // computed updates (rather than settling on a stale early value).
+    let deferEffects = false;
+    let computedBatch = null;
+    const arraysShallowEqual = (a, b) => {
+        if (a.length !== b.length) {
+            return false;
+        }
+        for (let i = 0; i < a.length; i++) {
+            if (a[i] !== b[i]) {
+                return false;
+            }
+        }
+        return true;
+    };
+    let destroyed = false;
+    // Timers scheduled by asyncSet, tracked so destroy() can cancel them.
+    // Otherwise a pending callback fires after teardown and throws "Store is
+    // destroyed" from inside the timer.
+    const pendingTimers = new Set();
+    const assertAlive = () => {
+        if (destroyed) {
+            throw new Error("Store is destroyed");
+        }
+    };
+    const dedupe = (keys) => Array.from(new Set(keys));
+    // A public set() can trigger a computed cascade. Routing it through batch()
+    // makes that cascade glitch-free (one coalesced onChange per affected key).
+    // Only do so at the top level: if already batching or intercepting, the
+    // surrounding operation coalesces; with no effect listener there is no
+    // cascade to coalesce.
+    const canCoalesceCascade = () => {
+        var _a;
+        return !batching
+            && !changes.isIntercepting()
+            && !control.isIntercepting()
+            && !!((_a = control.get(EffectEventName)) === null || _a === void 0 ? void 0 : _a.hasListener());
+    };
     const effectInterceptor = (name, args) => {
         if (name === ChangeEventName) {
             effectKeys.push(...args[0]);
             return false;
         }
+        // While the multi-key loop writes base values, swallow effect emissions;
+        // they are replayed once afterwards against the final state.
+        if (name === EffectEventName && deferEffects) {
+            return false;
+        }
         return true;
     };
-    const _set = (name, value, triggerChange = true) => {
+    const _set = (name, value, triggerChange = true, runBeforeChange = true) => {
         var _a, _b, _c, _d, _e;
         const prev = data.get(name);
         if (prev !== value) {
-            const beforeChangeResults = control.all(BeforeChangeEventName, name, value);
-            if (beforeChangeResults.some((result) => result === false)) {
-                return;
+            // A computed recompute skips the beforeChange veto (runBeforeChange
+            // false): the initial computed seed() bypasses beforeChange for the
+            // same reason, so allowing a veto here would leave the derived value
+            // stale and no longer equal to fn(deps) — internally inconsistent
+            // with the seeded value. beforeChange still gates ordinary sets.
+            if (runBeforeChange) {
+                const beforeChangeResults = control.all(BeforeChangeEventName, name, value);
+                if (beforeChangeResults.some((result) => result === false)) {
+                    return;
+                }
             }
             const pipeArgs = [value];
             let newValue;
@@ -98,12 +168,16 @@ export function createStore(initialData = {}) {
                         effectKeys = [];
                         return true;
                     }
+                    // Clear before propagating: an unhandled throw here would
+                    // otherwise leave the cascade's collected keys dirty for the
+                    // next _set, which would report them as spuriously changed.
+                    effectKeys = [];
                     throw error;
                 }
             }
             if (triggerChange) {
                 try {
-                    control.trigger(ChangeEventName, [name, ...effectKeys]);
+                    control.trigger(ChangeEventName, dedupe([name, ...effectKeys]));
                     if (!control.isIntercepting()) {
                         effectKeys = [];
                     }
@@ -121,6 +195,9 @@ export function createStore(initialData = {}) {
                         effectKeys = [];
                         return true;
                     }
+                    // Clear before propagating (see the effect-trigger catch
+                    // above): a leaked effectKeys would taint the next _set.
+                    effectKeys = [];
                     throw error;
                 }
             }
@@ -129,7 +206,28 @@ export function createStore(initialData = {}) {
         return false;
     };
     function asyncSet(name, value) {
-        setTimeout(() => {
+        // Validate computed keys synchronously, mirroring set(). Deferring the
+        // check to the timer callback would turn a misuse into an uncaught
+        // exception escaping the timer (crashing Node / surfacing as an uncaught
+        // browser error) instead of a catchable throw at the call site.
+        if (typeof name === "string") {
+            if (computedKeys.has(name)) {
+                throw new Error(`Cannot set computed property "${name}"`);
+            }
+        }
+        else if (typeof name === "object" && name !== null) {
+            for (const k of Object.keys(name)) {
+                if (computedKeys.has(k)) {
+                    throw new Error(`Cannot set computed property "${k}"`);
+                }
+            }
+        }
+        const timer = setTimeout(() => {
+            pendingTimers.delete(timer);
+            // The store may have been destroyed between scheduling and firing.
+            if (destroyed) {
+                return;
+            }
             if (typeof name === "string") {
                 set(name, value);
             }
@@ -137,65 +235,235 @@ export function createStore(initialData = {}) {
                 set(name);
             }
         }, 0);
+        pendingTimers.add(timer);
     }
-    function set(name, value) {
+    // Coalesce a change log per key and replay it as one onChange each, keeping
+    // the first entry's pre-cascade `prev` and the last entry's settled `value`
+    // and dropping keys whose net value is unchanged. Store-change errors route
+    // to the error event; an unhandled one propagates unless the surrounding
+    // callback already failed (`hasCallbackError`), in which case it is swallowed
+    // so the original callback error is the one that ultimately surfaces. Shared
+    // by batch() and the single-set cascade wrapper so both coalesce identically.
+    const replayCoalescedLog = (log, hasCallbackError) => {
+        var _a;
+        const coalesced = new Map();
+        for (const [propName, value, prev] of log) {
+            const existing = coalesced.get(propName);
+            if (existing) {
+                existing.value = value;
+            }
+            else {
+                coalesced.set(propName, { value, prev });
+            }
+        }
+        for (const [propName, { value, prev }] of coalesced) {
+            if (value === prev) {
+                continue;
+            }
+            const changeArgs = [
+                value,
+                prev,
+            ];
+            try {
+                changes.trigger(propName, ...changeArgs);
+            }
+            catch (error) {
+                control.trigger(ErrorEventName, {
+                    error: error instanceof Error
+                        ? error
+                        : new Error(String(error)),
+                    args: changeArgs,
+                    type: "store-change",
+                    name: propName,
+                });
+                if ((_a = control.get(ErrorEventName)) === null || _a === void 0 ? void 0 : _a.hasListener()) {
+                    continue;
+                }
+                if (hasCallbackError) {
+                    continue;
+                }
+                throw error;
+            }
+        }
+    };
+    // Replay a coalesced cascade log and, if the driving callback failed, rethrow
+    // its error last (after every surviving onChange has fired).
+    const replayCoalescedChanges = (log, hasCallbackError, callbackError) => {
+        replayCoalescedLog(log, hasCallbackError);
+        if (hasCallbackError) {
+            throw callbackError;
+        }
+    };
+    // Run `fn` with onChange emissions intercepted and coalesced. The control
+    // change-key collection (effectKeys / effectInterceptor ordering) inside
+    // `fn` is untouched, so only the per-key onChange stream is deduped.
+    const withChangeCoalescing = (fn, liveKey) => {
+        const log = [];
+        let liveDelivered = false;
+        const logger = function (propName, args) {
+            // Deliver the directly-set key's onChange live (it fires inside _set
+            // before the effect cascade) so plain onChange listeners still run
+            // ahead of effect listeners; only the cascade's emissions are
+            // coalesced. Returning a non-false value lets the interceptor pass
+            // the event through to its listeners.
+            if (!liveDelivered && liveKey !== undefined && propName === liveKey) {
+                liveDelivered = true;
+                return true;
+            }
+            log.push([propName, args[0], args[1]]);
+            return false;
+        };
+        changes.intercept(logger);
+        let callbackError;
+        let hasCallbackError = false;
+        try {
+            fn();
+        }
+        catch (error) {
+            callbackError = error;
+            hasCallbackError = true;
+        }
+        finally {
+            changes.stopIntercepting();
+        }
+        replayCoalescedChanges(log, hasCallbackError, callbackError);
+    };
+    // The write path shared by set() and its coalescing wrapper. Computed-key
+    // validation happens in set() before this runs.
+    const applySet = (name, value) => {
         var _a, _b;
         if (typeof name === "string") {
             _set(name, value);
+            return;
         }
-        else if (typeof name === "object") {
-            const changedKeys = [];
-            const isIntercepting = control.isIntercepting();
-            const hasEffectListener = (_a = control.get(EffectEventName)) === null || _a === void 0 ? void 0 : _a.hasListener();
-            const shouldInterceptEffects = hasEffectListener && !isIntercepting;
-            let controlError = null;
+        const changedKeys = [];
+        const isIntercepting = control.isIntercepting();
+        const hasEffectListener = (_a = control.get(EffectEventName)) === null || _a === void 0 ? void 0 : _a.hasListener();
+        const shouldInterceptEffects = hasEffectListener && !isIntercepting;
+        let controlError = null;
+        if (shouldInterceptEffects) {
+            control.intercept(effectInterceptor);
+            computedBatch = new Map();
+        }
+        let allChangedKeys = [];
+        try {
+            // Phase 1: write every base value with effect emission deferred,
+            // so computed values do not recompute against a half-updated
+            // state mid-loop.
             if (shouldInterceptEffects) {
-                control.intercept(effectInterceptor);
+                deferEffects = true;
             }
-            try {
-                Object.entries(name).forEach(([k, v]) => {
-                    if (_set(k, v, false)) {
-                        changedKeys.push(k);
-                    }
-                });
-                const allChangedKeys = [
-                    ...changedKeys,
-                    ...effectKeys,
-                ];
-                if (allChangedKeys.length > 0) {
+            const entries = Object.entries(name);
+            entries.forEach(([k, v]) => {
+                if (_set(k, v, false)) {
+                    changedKeys.push(k);
+                }
+            });
+            // Phase 2: with all base values final, replay the effect once per
+            // changed key. `computedBatch` skips a computed whose dependency
+            // values are unchanged since its last recompute, while still
+            // letting chained computeds re-settle when an upstream updates.
+            if (shouldInterceptEffects) {
+                deferEffects = false;
+                changedKeys.forEach((k) => {
+                    var _a;
+                    // Mirror _set's effect error contract: a throwing effect
+                    // listener routes to the error event (and is swallowed if
+                    // a handler exists) rather than aborting the whole set.
                     try {
-                        control.trigger(ChangeEventName, allChangedKeys);
+                        control.trigger(EffectEventName, k, data.get(k));
                     }
                     catch (error) {
-                        controlError = error instanceof Error
-                            ? error
-                            : new Error(String(error));
+                        control.trigger(ErrorEventName, {
+                            error: error instanceof Error
+                                ? error
+                                : new Error(String(error)),
+                            args: [k],
+                            type: "store-control",
+                            name: k,
+                        });
+                        if (!((_a = control.get(ErrorEventName)) === null || _a === void 0 ? void 0 : _a.hasListener())) {
+                            throw error;
+                        }
                     }
-                }
+                });
             }
-            finally {
-                if (shouldInterceptEffects) {
-                    effectKeys = [];
-                    control.stopIntercepting();
-                }
+            allChangedKeys = dedupe([
+                ...changedKeys,
+                ...effectKeys,
+            ]);
+        }
+        finally {
+            if (shouldInterceptEffects) {
+                effectKeys = [];
+                deferEffects = false;
+                computedBatch = null;
+                control.stopIntercepting();
             }
-            if (controlError) {
-                control.trigger(ErrorEventName, {
-                    error: controlError,
-                    args: [name],
-                    type: "store-control",
-                });
-                if ((_b = control.get(ErrorEventName)) === null || _b === void 0 ? void 0 : _b.hasListener()) {
-                    return;
+        }
+        // Fire the outer change AFTER intercepting stops; otherwise the
+        // effectInterceptor (active during the loop to fold computed/effect
+        // writes into effectKeys) would swallow this trigger too.
+        if (allChangedKeys.length > 0) {
+            try {
+                control.trigger(ChangeEventName, allChangedKeys);
+            }
+            catch (error) {
+                controlError = error instanceof Error
+                    ? error
+                    : new Error(String(error));
+            }
+        }
+        if (controlError) {
+            control.trigger(ErrorEventName, {
+                error: controlError,
+                args: [name],
+                type: "store-control",
+            });
+            if ((_b = control.get(ErrorEventName)) === null || _b === void 0 ? void 0 : _b.hasListener()) {
+                return;
+            }
+            throw controlError;
+        }
+    };
+    function set(name, value) {
+        assertAlive();
+        if (typeof name === "string") {
+            if (computedKeys.has(name)) {
+                throw new Error(`Cannot set computed property "${name}"`);
+            }
+        }
+        else if (typeof name === "object") {
+            // Validate all keys before any write so a computed key in the patch
+            // throws without partially applying the others.
+            for (const k of Object.keys(name)) {
+                if (computedKeys.has(k)) {
+                    throw new Error(`Cannot set computed property "${k}"`);
                 }
-                throw controlError;
             }
         }
         else {
             throw new Error(`Invalid key: ${String(name)}`);
         }
+        // A cascade-triggering set coalesces its onChange emissions: a computed
+        // touched several times during the cascade (e.g. a diamond sink
+        // recomputed once per upstream) fires onChange once with its settled
+        // value and the real pre-set prev, instead of leaking an internally
+        // inconsistent intermediate (b_new + c_old) with a wrong prev. The
+        // control change-key collection is left untouched, so change-key
+        // ordering is unaffected.
+        if (canCoalesceCascade()) {
+            // For a single-key set, deliver that key's onChange live (before the
+            // effect cascade) and coalesce only the downstream computed-key
+            // emissions. A multi-key (object) set is an explicit batch, so all
+            // of its onChange emissions remain coalesced.
+            withChangeCoalescing(() => applySet(name, value), typeof name === "string" ? name : undefined);
+            return;
+        }
+        applySet(name, value);
     }
     const get = (key) => {
+        assertAlive();
         if (typeof key === "string") {
             const value = data.get(key);
             return value;
@@ -223,7 +491,7 @@ export function createStore(initialData = {}) {
     };
     let batching = false;
     const batch = (fn) => {
-        var _a, _b;
+        var _a;
         if (batching) {
             throw new Error("Nested batch() calls are not supported");
         }
@@ -257,45 +525,30 @@ export function createStore(initialData = {}) {
             changes.stopIntercepting();
             batching = false;
         }
-        for (const [propName, value, prev] of log) {
-            const changeArgs = [
-                value,
-                prev,
-            ];
+        // Coalesce the log per key before replaying: a key written multiple
+        // times in the batch (e.g. a computed recomputing once per base-key
+        // write) must fire onChange once with its final value, not once per
+        // intermediate value. Drop keys whose net value is unchanged from before
+        // the batch. The callback error (if any) is deferred and rethrown at the
+        // end so the partial-write control change event below still fires.
+        replayCoalescedLog(log, hasCallbackError);
+        // Dedupe so the control change event lists each key once, matching the
+        // non-batch path (which dedupes via `dedupe([name, ...effectKeys])`).
+        // A computed touched by several base-key writes would otherwise repeat.
+        const dedupedChangedKeys = dedupe(allChangedKeys);
+        if (dedupedChangedKeys.length > 0) {
             try {
-                changes.trigger(propName, ...changeArgs);
+                control.trigger(ChangeEventName, dedupedChangedKeys);
             }
             catch (error) {
                 control.trigger(ErrorEventName, {
                     error: error instanceof Error
                         ? error
                         : new Error(String(error)),
-                    args: changeArgs,
-                    type: "store-change",
-                    name: propName,
-                });
-                if ((_a = control.get(ErrorEventName)) === null || _a === void 0 ? void 0 : _a.hasListener()) {
-                    continue;
-                }
-                if (hasCallbackError) {
-                    continue;
-                }
-                throw error;
-            }
-        }
-        if (allChangedKeys.length > 0) {
-            try {
-                control.trigger(ChangeEventName, allChangedKeys);
-            }
-            catch (error) {
-                control.trigger(ErrorEventName, {
-                    error: error instanceof Error
-                        ? error
-                        : new Error(String(error)),
-                    args: [allChangedKeys],
+                    args: [dedupedChangedKeys],
                     type: "store-control",
                 });
-                if ((_b = control.get(ErrorEventName)) === null || _b === void 0 ? void 0 : _b.hasListener()) {
+                if ((_a = control.get(ErrorEventName)) === null || _a === void 0 ? void 0 : _a.hasListener()) {
                     if (hasCallbackError) {
                         throw callbackError;
                     }
@@ -313,16 +566,125 @@ export function createStore(initialData = {}) {
     };
     const reset = () => {
         data.clear();
+        // Recompute computed keys from the cleared deps (registration order, so a
+        // base computed re-seeds before a dependent in a chain) and re-seed them
+        // silently, keeping each consistent with fn(deps) instead of stale.
+        computedReseeders.forEach((reseed) => {
+            reseed();
+        });
         control.trigger(ResetEventName);
     };
+    // One-call teardown: destroy the underlying change/pipe/control buses and
+    // drop all data. Post-destroy set/get throw rather than silently no-op.
+    const destroy = () => {
+        pendingTimers.forEach((timer) => clearTimeout(timer));
+        pendingTimers.clear();
+        changes.destroy();
+        pipe.destroy();
+        control.destroy();
+        data.clear();
+        computedKeys.clear();
+        computingKeys.clear();
+        computedReseeders.clear();
+        computedEffectListeners.clear();
+        effectKeys = [];
+        destroyed = true;
+    };
+    const isDestroyed = () => destroyed;
+    // Registers `key` as a derived value recomputed from `deps`. Built as sugar
+    // over the `effect` control event: recompute writes via the internal `_set`
+    // (triggerChange = true) so the change folds into the same outer `change`
+    // batch via `effectKeys`. Computed keys flow transparently through
+    // get/getData/onChange/useStoreState/useStoreSelector.
+    //
+    // Recompute is registration-order, not topologically sorted, so a dependent
+    // (chain or diamond) may recompute from a stale upstream first. The internal
+    // intermediate recompute is invisible to consumers: set() coalesces the
+    // onChange stream for a cascade, so each computed fires onChange once with
+    // its settled value and the real pre-set prev (`computedBatch` also dedupes
+    // redundant recomputes within a multi-key set). The final get()/onChange
+    // value is always correct.
+    const computed = (key, deps, fn) => {
+        // Bail before running user code or seeding data: on a destroyed store
+        // the control bus throws only when the recompute listener is attached,
+        // by which point fn() has already run and the initial value has been
+        // written, repopulating cleared state that getData() would then expose.
+        assertAlive();
+        const readDeps = () => deps.map((d) => data.get(d));
+        // Compute the initial value BEFORE committing any registration state.
+        // If `fn` throws here, nothing has been mutated, so the key does not
+        // become a permanently read-only computed with no listener installed.
+        const initialValue = fn(...readDeps());
+        // Seed silently (no change emitted at setup time) but through pipe, so
+        // the value read right after computed()/reset() matches what every
+        // later _set-driven recompute produces; otherwise a piped key silently
+        // changes shape on the first dependency change. beforeChange is skipped
+        // on purpose: a silent seed has no change to veto, and a computed key
+        // must always hold a value.
+        const seed = (raw) => {
+            const pipeArgs = [raw];
+            const piped = pipe.pipe(key, ...pipeArgs);
+            data.set(key, piped !== undefined ? piped : raw);
+        };
+        seed(initialValue);
+        computedKeys.add(key);
+        // reset() re-runs this to recompute the value from the cleared deps. It
+        // seeds `data` silently (no change emitted), matching this setup path.
+        computedReseeders.set(key, () => {
+            seed(fn(...readDeps()));
+        });
+        // Detach a prior recompute closure for this key (re-registration)
+        // before installing the new one, so the old fn does not keep running on
+        // every dependency change.
+        const prevEffect = computedEffectListeners.get(key);
+        if (prevEffect) {
+            control.removeListener(EffectEventName, prevEffect);
+        }
+        const effectListener = (changedName) => {
+            if (deps.indexOf(changedName) === -1) {
+                return;
+            }
+            const depValues = readDeps();
+            // Within a single multi-key set, skip the recompute only when this
+            // computed's dependency values are unchanged since its last
+            // recompute in the batch. That dedupes redundant dep changes while
+            // still re-settling a chain when an upstream computed updates.
+            if (computedBatch) {
+                const lastDepValues = computedBatch.get(key);
+                if (lastDepValues
+                    && arraysShallowEqual(lastDepValues, depValues)) {
+                    return;
+                }
+                computedBatch.set(key, depValues);
+            }
+            if (computingKeys.has(key)) {
+                throw new Error(`Cyclic computed dependency detected at "${key}"`);
+            }
+            computingKeys.add(key);
+            try {
+                // runBeforeChange=false: a computed key is derived and must
+                // always hold fn(deps); a beforeChange veto here would strand a
+                // stale value (see _set and the seed() rationale).
+                _set(key, fn(...depValues), true, false);
+            }
+            finally {
+                computingKeys.delete(key);
+            }
+        };
+        control.addListener(EffectEventName, effectListener);
+        computedEffectListeners.set(key, effectListener);
+    };
     const api = {
         set,
         get,
         getData,
         batch,
         asyncSet,
+        computed,
         isEmpty,
         reset,
+        destroy,
+        isDestroyed,
         onChange: changes.addListener,
         removeOnChange: changes.removeListener,
         updateOnChangeOptions: changes.updateListenerOptions,

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@kuindji/reactive",
-    "version": "1.1.0",
+    "version": "1.3.0",
     "author": "Ivan Kuindzhi",
     "type": "module",
     "repository": {