watch-state 3.5.0-alpha.3 → 3.5.0

package/Cache/Cache.d.ts

@@ -1,16 +1,6 @@
-import { Observable } from '../Observable';
-import { type Observer, type Watcher } from '../types';
-export declare class Cache<V = unknown> extends Observable<V> implements Observer {
-    invalid: boolean;
-    updated: boolean;
-    destroyed: boolean;
-    isCache: boolean;
-    destructors: Set<Function>;
-    childWatchers: Set<Observer>;
-    readonly watcher: Watcher<V>;
-    constructor(watcher: Watcher<V>, freeParent?: boolean, fireImmediately?: boolean);
-    update(): void;
-    forceUpdate(): void;
-    get value(): V;
-    destroy(): void;
+import { Compute } from '../Compute';
+/**
+ * @deprecated Use `Compute`
+ */
+export declare class Cache<V = unknown> extends Compute<V> {
 }

package/Cache/Cache.es6.js

@@ -1,72 +1,10 @@
-import { scope } from '../constants.es6.js';
-import '../helpers/index.es6.js';
-import '../Observable/index.es6.js';
-import '../Watch/index.es6.js';
-import { Observable } from '../Observable/Observable.es6.js';
-import { invalidateCache } from '../helpers/invalidateCache/invalidateCache.es6.js';
-import { Watch } from '../Watch/Watch.es6.js';
-import { watchWithScope } from '../helpers/watchWithScope/watchWithScope.es6.js';
-import { queueWatchers } from '../helpers/queueWatchers/queueWatchers.es6.js';
-import { destroyWatchers } from '../helpers/destroyWatchers/destroyWatchers.es6.js';
+import '../Compute/index.es6.js';
+import { Compute } from '../Compute/Compute.es6.js';
 
-class Cache extends Observable {
-    constructor(watcher, freeParent, fireImmediately) {
-        super();
-        this.invalid = true;
-        this.updated = false;
-        this.destroyed = false;
-        this.isCache = true;
-        // Observer
-        this.destructors = new Set();
-        this.childWatchers = new Set();
-        this.watcher = watcher;
-        if (!freeParent) {
-            const { activeWatcher } = scope;
-            if (activeWatcher) {
-                activeWatcher.childWatchers.add(this);
-                activeWatcher.destructors.add(() => {
-                    activeWatcher.childWatchers.delete(this);
-                });
-            }
-        }
-        if (fireImmediately) {
-            this.forceUpdate();
-        }
-    }
-    update() {
-        invalidateCache(this);
-        const parents = [...this.observers];
-        let parent;
-        while ((parent = parents.pop())) {
-            if (parent instanceof Watch) {
-                return this.forceUpdate();
-            }
-            if (parent instanceof Cache) {
-                parents.push(...parent.observers);
-            }
-        }
-    }
-    forceUpdate() {
-        if (!this.destroyed) {
-            this.invalid = false;
-            watchWithScope(this, () => {
-                const newValue = this.watcher(this.updated ? this.updated = true : false);
-                if (newValue !== this.rawValue) {
-                    this.rawValue = newValue;
-                    queueWatchers(this.observers);
-                }
-            });
-        }
-    }
-    get value() {
-        if (this.invalid) {
-            this.forceUpdate();
-        }
-        return this.destroyed ? this.rawValue : super.value;
-    }
-    destroy() {
-        destroyWatchers(this);
-    }
+/**
+ * @deprecated Use `Compute`
+ */
+class Cache extends Compute {
 }
 
 export { Cache };

package/Cache/Cache.js

@@ -2,75 +2,13 @@
 
 Object.defineProperty(exports, '__esModule', { value: true });
 
-var constants = require('../constants.js');
-require('../helpers/index.js');
-require('../Observable/index.js');
-require('../Watch/index.js');
-var Observable = require('../Observable/Observable.js');
-var invalidateCache = require('../helpers/invalidateCache/invalidateCache.js');
-var Watch = require('../Watch/Watch.js');
-var watchWithScope = require('../helpers/watchWithScope/watchWithScope.js');
-var queueWatchers = require('../helpers/queueWatchers/queueWatchers.js');
-var destroyWatchers = require('../helpers/destroyWatchers/destroyWatchers.js');
+require('../Compute/index.js');
+var Compute = require('../Compute/Compute.js');
 
-class Cache extends Observable.Observable {
-    constructor(watcher, freeParent, fireImmediately) {
-        super();
-        this.invalid = true;
-        this.updated = false;
-        this.destroyed = false;
-        this.isCache = true;
-        // Observer
-        this.destructors = new Set();
-        this.childWatchers = new Set();
-        this.watcher = watcher;
-        if (!freeParent) {
-            const { activeWatcher } = constants.scope;
-            if (activeWatcher) {
-                activeWatcher.childWatchers.add(this);
-                activeWatcher.destructors.add(() => {
-                    activeWatcher.childWatchers.delete(this);
-                });
-            }
-        }
-        if (fireImmediately) {
-            this.forceUpdate();
-        }
-    }
-    update() {
-        invalidateCache.invalidateCache(this);
-        const parents = [...this.observers];
-        let parent;
-        while ((parent = parents.pop())) {
-            if (parent instanceof Watch.Watch) {
-                return this.forceUpdate();
-            }
-            if (parent instanceof Cache) {
-                parents.push(...parent.observers);
-            }
-        }
-    }
-    forceUpdate() {
-        if (!this.destroyed) {
-            this.invalid = false;
-            watchWithScope.watchWithScope(this, () => {
-                const newValue = this.watcher(this.updated ? this.updated = true : false);
-                if (newValue !== this.rawValue) {
-                    this.rawValue = newValue;
-                    queueWatchers.queueWatchers(this.observers);
-                }
-            });
-        }
-    }
-    get value() {
-        if (this.invalid) {
-            this.forceUpdate();
-        }
-        return this.destroyed ? this.rawValue : super.value;
-    }
-    destroy() {
-        destroyWatchers.destroyWatchers(this);
-    }
+/**
+ * @deprecated Use `Compute`
+ */
+class Cache extends Compute.Compute {
 }
 
 exports.Cache = Cache;

package/Cache/Cache.test.d.ts

@@ -0,0 +1 @@
+export {};

package/Compute/Compute.d.ts

@@ -0,0 +1,82 @@
+import { Observable } from '../Observable';
+import type { Destructor, Observer, Watcher } from '../types';
+export declare function forceQueueWatchers(): void;
+export declare function queueWatchers(observers: Set<Observer>): void;
+export declare function invalidateCompute(observer: Observer): void;
+/**
+ * Cached reactive computation with memoization.
+ * Recalculates value only when dependencies change and when it is actively consumed
+ * by a Watcher or another Compute that is itself consumed by a Watcher.
+ *
+ * This ensures that computations are only evaluated when their output is actually needed,
+ * enabling efficient lazy evaluation and automatic subscription management.
+ *
+ * @class Compute
+ * @extends Observable<V>
+ * @implements {Observer}
+ * @template V - computed value type
+ *
+ * @example
+ * const fullName = new State('Mighty Mike')
+ * const name = new Compute(() => fullName.value.split(' ')[1])
+ *
+ * // Only when accessed inside an `Observer`, `Compute` becomes active:
+ *
+ * const nameWatcher = new Watch(() => console.log(name.value))
+ * // Triggers computation and subscribes to `name`
+ *
+ * // This does NOT trigger recomputation:
+ * console.log(name.value)
+ *
+ * // If used inside another `Compute` that is watched, it triggers:
+ * const greeting = new Compute(() => `${name.value} How are you?`)
+ *
+ * const greetingWatcher new Watch(() => console.log(greeting.value))
+ * // Triggers greeting
+ *
+ * fullName.value = 'Mighty Michael'
+ * // Triggers full chain: fullName → name → greeting → greetingWatcher
+ *
+ * fullName.value = 'Deight Michael'
+ * // Triggers part of chain: fullName → name
+ */
+export declare class Compute<V = unknown> extends Observable<V> implements Observer {
+    /** Indicates if computed value is stale and needs recalculation. */
+    invalid: boolean;
+    /** Tracks if the computation has run at least once. */
+    updated: boolean;
+    /**
+     * Indicates if observer has been destroyed.
+     * Prevents accidental use after cleanup.
+     */
+    destroyed: boolean;
+    /** @deprecated Use `observer instanceof Compute` */
+    isCache: boolean;
+    /** Cleanup functions to run on destroy (e.g., unsubscribes). */
+    readonly destructors: Set<Destructor>;
+    /** Child watchers created within this watcher's scope */
+    readonly childrenObservers: Set<Observer>;
+    /** @deprecated Use `childrenObservers` */
+    get childWatchers(): Set<Observer>;
+    readonly watcher: Watcher<V>;
+    constructor(watcher: Watcher<V>, freeParent?: boolean, fireImmediately?: boolean);
+    /** Mark computation as invalid and trigger propagation to parent observers. */
+    update(): void;
+    forceUpdate(): void;
+    /**
+     * Current value with automatic subscription.
+     *
+     * Accessing `value` inside an `Observer` automatically subscribes the watcher.
+     *
+     * @example
+     * const count = new State(0)
+     * const text = new Compute(() => `Count: ${count.value}`)
+     *
+     * new Watch(() => console.log(text.value)) // Count: 0
+     *
+     * count.value++ // Count: 1
+     */
+    get value(): V;
+    /** Stop observation and remove all dependencies. */
+    destroy(): void;
+}

package/Compute/Compute.es6.js

@@ -0,0 +1,184 @@
+import { scope } from '../constants.es6.js';
+import '../helpers/bindObserver/index.es6.js';
+import '../helpers/clearWatcher/index.es6.js';
+import '../helpers/destroyWatchers/index.es6.js';
+import '../helpers/watchWithScope/index.es6.js';
+import '../Observable/index.es6.js';
+import '../utils/shiftSet/index.es6.js';
+import { shiftSet } from '../utils/shiftSet/shiftSet.es6.js';
+import { clearWatcher } from '../helpers/clearWatcher/clearWatcher.es6.js';
+import { Observable } from '../Observable/Observable.es6.js';
+import { bindObserver } from '../helpers/bindObserver/bindObserver.es6.js';
+import { watchWithScope } from '../helpers/watchWithScope/watchWithScope.es6.js';
+import { destroyWatchers } from '../helpers/destroyWatchers/destroyWatchers.es6.js';
+
+/* queue */
+let currentCompute;
+let currentObserver;
+let forcedQueue;
+const computeStack = new Set();
+const observersStack = new Set();
+function forceQueueWatchers() {
+    if (forcedQueue)
+        return;
+    forcedQueue = true;
+    while ((currentCompute = shiftSet(computeStack)) || (currentObserver = shiftSet(observersStack))) {
+        if (currentCompute) {
+            currentCompute.invalid = true;
+            continue;
+        }
+        clearWatcher(currentObserver);
+        currentObserver.update();
+    }
+    forcedQueue = false;
+}
+function queueWatchers(observers) {
+    const useLoop = !scope.eventDeep && !observersStack.size && !computeStack.size;
+    const oldObserversStack = [...observersStack];
+    observersStack.clear();
+    observers.forEach(watcher => {
+        observersStack.add(watcher);
+        if (watcher instanceof Compute) {
+            computeStack.add(watcher);
+        }
+    });
+    oldObserversStack.forEach(observer => observersStack.add(observer));
+    if (useLoop) {
+        forceQueueWatchers();
+    }
+}
+/* invalidateCompute */
+const invalidateStack = [];
+let currentInvalidateObserver;
+function invalidateCompute(observer) {
+    const skipLoop = invalidateStack.length;
+    invalidateStack.push(observer);
+    if (skipLoop)
+        return;
+    while ((currentInvalidateObserver = invalidateStack.shift())) {
+        if (currentInvalidateObserver instanceof Compute) {
+            invalidateStack.push(...currentInvalidateObserver.observers);
+            currentInvalidateObserver.invalid = true;
+        }
+    }
+}
+/* Compute */
+/**
+ * Cached reactive computation with memoization.
+ * Recalculates value only when dependencies change and when it is actively consumed
+ * by a Watcher or another Compute that is itself consumed by a Watcher.
+ *
+ * This ensures that computations are only evaluated when their output is actually needed,
+ * enabling efficient lazy evaluation and automatic subscription management.
+ *
+ * @class Compute
+ * @extends Observable<V>
+ * @implements {Observer}
+ * @template V - computed value type
+ *
+ * @example
+ * const fullName = new State('Mighty Mike')
+ * const name = new Compute(() => fullName.value.split(' ')[1])
+ *
+ * // Only when accessed inside an `Observer`, `Compute` becomes active:
+ *
+ * const nameWatcher = new Watch(() => console.log(name.value))
+ * // Triggers computation and subscribes to `name`
+ *
+ * // This does NOT trigger recomputation:
+ * console.log(name.value)
+ *
+ * // If used inside another `Compute` that is watched, it triggers:
+ * const greeting = new Compute(() => `${name.value} How are you?`)
+ *
+ * const greetingWatcher new Watch(() => console.log(greeting.value))
+ * // Triggers greeting
+ *
+ * fullName.value = 'Mighty Michael'
+ * // Triggers full chain: fullName → name → greeting → greetingWatcher
+ *
+ * fullName.value = 'Deight Michael'
+ * // Triggers part of chain: fullName → name
+ */
+class Compute extends Observable {
+    // TODO: remove in major release
+    /** @deprecated Use `childrenObservers` */
+    get childWatchers() {
+        return this.childrenObservers;
+    }
+    constructor(watcher, freeParent, fireImmediately) {
+        super();
+        /** Indicates if computed value is stale and needs recalculation. */
+        this.invalid = true;
+        /** Tracks if the computation has run at least once. */
+        this.updated = false;
+        /**
+         * Indicates if observer has been destroyed.
+         * Prevents accidental use after cleanup.
+         */
+        this.destroyed = false;
+        // TODO: remove in major release
+        /** @deprecated Use `observer instanceof Compute` */
+        this.isCache = true;
+        /** Cleanup functions to run on destroy (e.g., unsubscribes). */
+        this.destructors = new Set();
+        /** Child watchers created within this watcher's scope */
+        this.childrenObservers = new Set();
+        this.watcher = watcher;
+        if (!freeParent) {
+            bindObserver(this);
+        }
+        if (fireImmediately) {
+            this.forceUpdate();
+        }
+    }
+    /** Mark computation as invalid and trigger propagation to parent observers. */
+    update() {
+        invalidateCompute(this);
+        const parents = [...this.observers];
+        let parent;
+        while ((parent = parents.pop())) {
+            if (!(parent instanceof Compute)) {
+                return this.forceUpdate();
+            }
+            parents.push(...parent.observers);
+        }
+    }
+    forceUpdate() {
+        if (!this.destroyed) {
+            this.invalid = false;
+            watchWithScope(this, () => {
+                const newValue = this.watcher(this.updated ? this.updated = true : false);
+                if (newValue !== this.rawValue) {
+                    this.rawValue = newValue;
+                    queueWatchers(this.observers);
+                }
+            });
+        }
+    }
+    /**
+     * Current value with automatic subscription.
+     *
+     * Accessing `value` inside an `Observer` automatically subscribes the watcher.
+     *
+     * @example
+     * const count = new State(0)
+     * const text = new Compute(() => `Count: ${count.value}`)
+     *
+     * new Watch(() => console.log(text.value)) // Count: 0
+     *
+     * count.value++ // Count: 1
+     */
+    get value() {
+        if (this.invalid) {
+            this.forceUpdate();
+        }
+        return this.destroyed ? this.rawValue : super.value;
+    }
+    /** Stop observation and remove all dependencies. */
+    destroy() {
+        destroyWatchers(this);
+    }
+}
+
+export { Compute, forceQueueWatchers, invalidateCompute, queueWatchers };

package/Compute/Compute.js

@@ -0,0 +1,191 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var constants = require('../constants.js');
+require('../helpers/bindObserver/index.js');
+require('../helpers/clearWatcher/index.js');
+require('../helpers/destroyWatchers/index.js');
+require('../helpers/watchWithScope/index.js');
+require('../Observable/index.js');
+require('../utils/shiftSet/index.js');
+var shiftSet = require('../utils/shiftSet/shiftSet.js');
+var clearWatcher = require('../helpers/clearWatcher/clearWatcher.js');
+var Observable = require('../Observable/Observable.js');
+var bindObserver = require('../helpers/bindObserver/bindObserver.js');
+var watchWithScope = require('../helpers/watchWithScope/watchWithScope.js');
+var destroyWatchers = require('../helpers/destroyWatchers/destroyWatchers.js');
+
+/* queue */
+let currentCompute;
+let currentObserver;
+let forcedQueue;
+const computeStack = new Set();
+const observersStack = new Set();
+function forceQueueWatchers() {
+    if (forcedQueue)
+        return;
+    forcedQueue = true;
+    while ((currentCompute = shiftSet.shiftSet(computeStack)) || (currentObserver = shiftSet.shiftSet(observersStack))) {
+        if (currentCompute) {
+            currentCompute.invalid = true;
+            continue;
+        }
+        clearWatcher.clearWatcher(currentObserver);
+        currentObserver.update();
+    }
+    forcedQueue = false;
+}
+function queueWatchers(observers) {
+    const useLoop = !constants.scope.eventDeep && !observersStack.size && !computeStack.size;
+    const oldObserversStack = [...observersStack];
+    observersStack.clear();
+    observers.forEach(watcher => {
+        observersStack.add(watcher);
+        if (watcher instanceof Compute) {
+            computeStack.add(watcher);
+        }
+    });
+    oldObserversStack.forEach(observer => observersStack.add(observer));
+    if (useLoop) {
+        forceQueueWatchers();
+    }
+}
+/* invalidateCompute */
+const invalidateStack = [];
+let currentInvalidateObserver;
+function invalidateCompute(observer) {
+    const skipLoop = invalidateStack.length;
+    invalidateStack.push(observer);
+    if (skipLoop)
+        return;
+    while ((currentInvalidateObserver = invalidateStack.shift())) {
+        if (currentInvalidateObserver instanceof Compute) {
+            invalidateStack.push(...currentInvalidateObserver.observers);
+            currentInvalidateObserver.invalid = true;
+        }
+    }
+}
+/* Compute */
+/**
+ * Cached reactive computation with memoization.
+ * Recalculates value only when dependencies change and when it is actively consumed
+ * by a Watcher or another Compute that is itself consumed by a Watcher.
+ *
+ * This ensures that computations are only evaluated when their output is actually needed,
+ * enabling efficient lazy evaluation and automatic subscription management.
+ *
+ * @class Compute
+ * @extends Observable<V>
+ * @implements {Observer}
+ * @template V - computed value type
+ *
+ * @example
+ * const fullName = new State('Mighty Mike')
+ * const name = new Compute(() => fullName.value.split(' ')[1])
+ *
+ * // Only when accessed inside an `Observer`, `Compute` becomes active:
+ *
+ * const nameWatcher = new Watch(() => console.log(name.value))
+ * // Triggers computation and subscribes to `name`
+ *
+ * // This does NOT trigger recomputation:
+ * console.log(name.value)
+ *
+ * // If used inside another `Compute` that is watched, it triggers:
+ * const greeting = new Compute(() => `${name.value} How are you?`)
+ *
+ * const greetingWatcher new Watch(() => console.log(greeting.value))
+ * // Triggers greeting
+ *
+ * fullName.value = 'Mighty Michael'
+ * // Triggers full chain: fullName → name → greeting → greetingWatcher
+ *
+ * fullName.value = 'Deight Michael'
+ * // Triggers part of chain: fullName → name
+ */
+class Compute extends Observable.Observable {
+    // TODO: remove in major release
+    /** @deprecated Use `childrenObservers` */
+    get childWatchers() {
+        return this.childrenObservers;
+    }
+    constructor(watcher, freeParent, fireImmediately) {
+        super();
+        /** Indicates if computed value is stale and needs recalculation. */
+        this.invalid = true;
+        /** Tracks if the computation has run at least once. */
+        this.updated = false;
+        /**
+         * Indicates if observer has been destroyed.
+         * Prevents accidental use after cleanup.
+         */
+        this.destroyed = false;
+        // TODO: remove in major release
+        /** @deprecated Use `observer instanceof Compute` */
+        this.isCache = true;
+        /** Cleanup functions to run on destroy (e.g., unsubscribes). */
+        this.destructors = new Set();
+        /** Child watchers created within this watcher's scope */
+        this.childrenObservers = new Set();
+        this.watcher = watcher;
+        if (!freeParent) {
+            bindObserver.bindObserver(this);
+        }
+        if (fireImmediately) {
+            this.forceUpdate();
+        }
+    }
+    /** Mark computation as invalid and trigger propagation to parent observers. */
+    update() {
+        invalidateCompute(this);
+        const parents = [...this.observers];
+        let parent;
+        while ((parent = parents.pop())) {
+            if (!(parent instanceof Compute)) {
+                return this.forceUpdate();
+            }
+            parents.push(...parent.observers);
+        }
+    }
+    forceUpdate() {
+        if (!this.destroyed) {
+            this.invalid = false;
+            watchWithScope.watchWithScope(this, () => {
+                const newValue = this.watcher(this.updated ? this.updated = true : false);
+                if (newValue !== this.rawValue) {
+                    this.rawValue = newValue;
+                    queueWatchers(this.observers);
+                }
+            });
+        }
+    }
+    /**
+     * Current value with automatic subscription.
+     *
+     * Accessing `value` inside an `Observer` automatically subscribes the watcher.
+     *
+     * @example
+     * const count = new State(0)
+     * const text = new Compute(() => `Count: ${count.value}`)
+     *
+     * new Watch(() => console.log(text.value)) // Count: 0
+     *
+     * count.value++ // Count: 1
+     */
+    get value() {
+        if (this.invalid) {
+            this.forceUpdate();
+        }
+        return this.destroyed ? this.rawValue : super.value;
+    }
+    /** Stop observation and remove all dependencies. */
+    destroy() {
+        destroyWatchers.destroyWatchers(this);
+    }
+}
+
+exports.Compute = Compute;
+exports.forceQueueWatchers = forceQueueWatchers;
+exports.invalidateCompute = invalidateCompute;
+exports.queueWatchers = queueWatchers;

package/Compute/Compute.test.d.ts

@@ -0,0 +1 @@
+export {};

package/Compute/index.d.ts

@@ -0,0 +1 @@
+export * from './Compute';

package/Compute/index.es6.js

@@ -0,0 +1 @@
+export { Compute, forceQueueWatchers, invalidateCompute, queueWatchers } from './Compute.es6.js';

package/Compute/index.js

@@ -0,0 +1,12 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var Compute = require('./Compute.js');
+
+
+
+exports.Compute = Compute.Compute;
+exports.forceQueueWatchers = Compute.forceQueueWatchers;
+exports.invalidateCompute = Compute.invalidateCompute;
+exports.queueWatchers = Compute.queueWatchers;