neo.mjs 10.0.0-beta.5 → 10.0.0

package/src/core/Config.mjs

@@ -14,13 +14,26 @@ import {isDescriptor} from './ConfigSymbols.mjs';
  */
 class Config {
     /**
-     * A Set to store callback functions that subscribe to changes in this config's value.
+     * Stores all subscriptions for this Config instance.
+     * The data structure is a Map where:
+     * - The key is the ID of the subscription owner (e.g., a component's `id`).
+     * - The value is another Map (the subscriberMap).
+     *
+     * The nested subscriberMap is structured as:
+     * - The key is the callback function (`fn`).
+     * - The value is a Set of scopes (`scopeSet`).
+     *
+     * This nested structure `Map<string, Map<function, Set<scope>>>` is intentionally chosen
+     * to robustly handle the edge case where the same function is subscribed multiple times
+     * with different scopes, all under the same owner ID. It ensures that each
+     * `fn`-`scope` combination is unique and that cleanup is precise.
+     * @member {Object} #subscribers={}
      * @private
      */
     #subscribers = {}
     /**
      * The internal value of the config property.
-     * @member #value
+     * @member {*} #value
      * @private
      */
     #value
@@ -67,7 +80,7 @@ class Config {
     get() {
         // Registers this Config instance as a dependency with the currently active Effect,
         // enabling automatic re-execution when this Config's value changes.
-        EffectManager.getActiveEffect()?.addDependency(this);
+        EffectManager.addDependency(this);
         return this.#value
     }
 
@@ -75,52 +88,56 @@ class Config {
      * Initializes the `Config` instance using a descriptor object.
      * Extracts `clone`, `mergeStrategy` and `isEqual` from the descriptor.
      * The internal `#value` is NOT set by this method.
-     * @param {Object}   descriptor                       - The descriptor object for the config.
-     * @param {any}      descriptor.value                 - The default value for the config (not set by this method).
+     * @param {Object}    descriptor                      - The descriptor object for the config.
      * @param {string}   [descriptor.clone='deep']        - The clone strategy for set.
      * @param {string}   [descriptor.cloneOnGet]          - The clone strategy for get. Defaults to 'shallow' if clone is 'deep' or 'shallow', and 'none' if clone is 'none'.
-     * @param {string}   [descriptor.merge='deep']        - The merge strategy.
      * @param {Function} [descriptor.isEqual=Neo.isEqual] - The equality comparison function.
+     * @param {string}   [descriptor.merge='deep']        - The merge strategy.
+     * @param {any}       descriptor.value                - The default value for the config (not set by this method).
      */
     initDescriptor({clone, cloneOnGet, isEqual, merge}) {
         let me = this;
 
         if (clone && clone !== me.clone) {
             Object.defineProperty(me, 'clone', {
-                value: clone, writable: true, configurable: true, enumerable: true
+                configurable: true, enumerable: true, value: clone, writable: true
             })
         }
 
         if (cloneOnGet && cloneOnGet !== me.cloneOnGet) {
             Object.defineProperty(me, 'cloneOnGet', {
-                value: cloneOnGet, writable: true, configurable: true, enumerable: true
+                configurable: true, enumerable: true, value: cloneOnGet, writable: true
             })
         }
 
         if (isEqual && isEqual !== me.isEqual) {
             Object.defineProperty(me, 'isEqual', {
-                value: isEqual, writable: true, configurable: true, enumerable: true
+                configurable: true, enumerable: true, value: isEqual, writable: true
             })
         }
 
         if (merge && merge !== me.mergeStrategy) {
             Object.defineProperty(me, 'mergeStrategy', {
-                value: merge, writable: true, configurable: true, enumerable: true
+                configurable: true, enumerable: true, value: merge, writable: true
             })
         }
     }
 
     /**
      * Notifies all subscribed callbacks about a change in the config's value.
+     * It iterates through the nested subscriber structure to ensure each callback
+     * is executed with its intended scope.
      * @param {any} newValue - The new value of the config.
      * @param {any} oldValue - The old value of the config.
      */
     notify(newValue, oldValue) {
         for (const id in this.#subscribers) {
             if (this.#subscribers.hasOwnProperty(id)) {
-                const subscriberSet = this.#subscribers[id];
-                for (const callback of subscriberSet) {
-                    callback(newValue, oldValue)
+                const subscriberMap = this.#subscribers[id];
+                for (const [fn, scopeSet] of subscriberMap) {
+                    for (const scope of scopeSet) {
+                        fn.call(scope || null, newValue, oldValue)
+                    }
                 }
             }
         }
@@ -164,12 +181,13 @@ class Config {
     /**
      * Subscribes a callback function to changes in this config's value.
      * The callback will be invoked with `(newValue, oldValue)` whenever the config changes.
-     * @param {Object} options      - An object containing the subscription details.
-     * @param {String} options.id   - The ID of the subscription owner (e.g., a Neo.core.Base instance's id).
-     * @param {Function} options.fn - The callback function.
+     * @param {Object}   options        - An object containing the subscription details.
+     * @param {String}   options.id     - The ID of the subscription owner (e.g., a Neo.core.Base instance's id).
+     * @param {Function} options.fn     - The callback function.
+     * @param {Object}  [options.scope] - The scope to execute the callback in.
      * @returns {Function} A cleanup function to unsubscribe the callback.
      */
-    subscribe({id, fn}) {
+    subscribe({id, fn, scope}) {
         if (typeof id !== 'string' || id.length === 0 || typeof fn !== 'function') {
             throw new Error([
                 'Config.subscribe: options must be an object with a non-empty string `id` ',
@@ -179,18 +197,36 @@ class Config {
 
         const me = this;
 
+        // Get or create the top-level Map for the subscription owner.
         if (!me.#subscribers[id]) {
-            me.#subscribers[id] = new Set()
+            me.#subscribers[id] = new Map()
         }
 
-        me.#subscribers[id].add(fn);
+        const subscriberMap = me.#subscribers[id];
+
+        // Get or create the Set of scopes for the specific callback function.
+        if (!subscriberMap.has(fn)) {
+            subscriberMap.set(fn, new Set())
+        }
 
+        const scopeSet = subscriberMap.get(fn);
+        scopeSet.add(scope);
+
+        // The returned cleanup function is precise. It removes only the specific
+        // scope for the function, and cleans up the parent data structures
+        // (the Set and the Maps) only if they become empty.
         return () => {
-            const subscriberSet = me.#subscribers[id];
-            if (subscriberSet) {
-                subscriberSet.delete(fn);
-                if (subscriberSet.size === 0) {
-                    delete me.#subscribers[id]
+            const currentSubscriberMap = me.#subscribers[id];
+            if (currentSubscriberMap) {
+                const currentScopeSet = currentSubscriberMap.get(fn);
+                if (currentScopeSet) {
+                    currentScopeSet.delete(scope);
+                    if (currentScopeSet.size === 0) {
+                        currentSubscriberMap.delete(fn);
+                        if (currentSubscriberMap.size === 0) {
+                            delete me.#subscribers[id]
+                        }
+                    }
                 }
             }
         }
@@ -198,33 +234,10 @@ class Config {
 }
 
 Object.defineProperties(Config.prototype, {
-    clone: {
-        value: 'deep',
-        writable: false,
-        configurable: true,
-        enumerable: false
-    },
-    cloneOnGet: {
-        value: null,
-        writable: false,
-        configurable: true,
-        enumerable: false
-    },
-    isEqual: {
-        value: Neo.isEqual,
-        writable: false,
-        configurable: true,
-        enumerable: false
-    },
-    mergeStrategy: {
-        value: 'replace',
-        writable: false,
-        configurable: true,
-        enumerable: false
-    }
+    clone        : {configurable: true, enumerable: false, value: 'deep',      writable: false},
+    cloneOnGet   : {configurable: true, enumerable: false, value: null,        writable: false},
+    isEqual      : {configurable: true, enumerable: false, value: Neo.isEqual, writable: false},
+    mergeStrategy: {configurable: true, enumerable: false, value: 'replace',   writable: false}
 });
 
-const ns = Neo.ns('Neo.core', true);
-ns.Config = Config;
-
-export default Config;
+export default Neo.gatekeep(Config, 'Neo.core.Config');

package/src/core/Effect.mjs

@@ -1,6 +1,6 @@
-import EffectManager     from './EffectManager.mjs';
-import EffectBatchManager from './EffectBatchManager.mjs';
-import IdGenerator        from './IdGenerator.mjs';
+import Config        from './Config.mjs';
+import EffectManager from './EffectManager.mjs';
+import IdGenerator   from './IdGenerator.mjs';
 
 /**
  * Creates a reactive effect that automatically tracks its dependencies and re-runs when any of them change.
@@ -9,6 +9,11 @@ import IdGenerator        from './IdGenerator.mjs';
  * @class Neo.core.Effect
  */
 class Effect {
+    /**
+     * The optional component id this effect belongs to.
+     * @member {String|null} componentId=null
+     */
+    componentId = null
     /**
      * A Map containing Config instances as keys and their cleanup functions as values.
      * @member {Map} dependencies=new Map()
@@ -31,10 +36,10 @@ class Effect {
      */
     isDestroyed = false
     /**
-     * @member {Boolean}
+     * @member {Neo.core.Config}
      * @protected
      */
-    isRunning = false
+    isRunning = null
 
     /**
      * @member fn
@@ -51,11 +56,44 @@ class Effect {
     }
 
     /**
-     * @param {Object} config
-     * @param {Function} config.fn The function to execute for the effect.
+     * @param {Function|Object}  fn              - The function to execute, or a config object for the effect.
+     * @param {Function}        [fn.fn]          - The function to execute for the effect (if the first argument is an object).
+     * @param {String}          [fn.componentId] - The component id this effect belongs to.
+     * @param {Boolean}         [fn.lazy=false]  - If true, the effect will not run immediately upon creation.
+     * @param {Object|Object[]} [fn.subscriber]  - A single subscriber or an array of subscribers for the isRunning config.
+     * @param {Object}          [options={}]     - Optional. Used if the first argument is a function, this object contains the options.
+     * @example
+     * // Signature 1: Function and Options
+     * const myEffect = new Effect(() => console.log('Run'), {lazy: true});
+     * @example
+     * // Signature 2: Single Config Object
+     * const myEffect = new Effect({fn: () => console.log('Run'), lazy: true});
      */
-    constructor({fn}) {
-        this.fn = fn
+    constructor(fn, options={}) {
+        const me = this;
+
+        const {
+              fn: effectFn,
+              componentId,
+              lazy = false,
+              subscriber
+        } = (typeof fn === 'function') ? { ...options, fn } : (fn || {});
+
+        if (componentId) {
+            me.componentId = componentId
+        }
+
+        me.isRunning = new Config(false);
+
+        if (subscriber) {
+            [].concat(subscriber).forEach(sub => me.isRunning.subscribe(sub))
+        }
+
+        if (lazy) {
+            me._fn = effectFn
+        } else {
+            me.fn = effectFn
+        }
     }
 
     /**
@@ -70,34 +108,53 @@ class Effect {
     }
 
     /**
-     * Executes the effect function, tracking its dependencies.
-     * This is called automatically on creation and whenever a dependency changes.
-     * The dynamic re-tracking ensures the effect always reflects its current dependencies,
-     * even if the logic within `fn` changes conditionally.
+     * Executes the effect function, re-evaluating its dependencies.
+     * If the EffectManager is paused (e.g., inside a batch), it queues itself to be run later.
      * @protected
      */
     run() {
         const me = this;
 
-        if (me.isDestroyed || me.isRunning) return;
+        if (me.isDestroyed) {
+            return
+        }
+
+        // Check if already running without creating a dependency on `isRunning`.
+        EffectManager.pauseTracking();
+        const isRunning = me.isRunning.get();
+        EffectManager.resumeTracking();
+
+        if (isRunning) {
+            return
+        }
 
-        if (EffectBatchManager.isBatchActive()) {
-            EffectBatchManager.queueEffect(me);
+        // If the manager is globally paused for batching, queue this effect and stop.
+        if (EffectManager.isPaused()) {
+            EffectManager.queue(me);
             return
         }
 
-        me.isRunning = true;
+        // Set `isRunning` to true without creating a dependency.
+        EffectManager.pauseTracking();
+        me.isRunning.set(true);
+        EffectManager.resumeTracking();
 
+        // Clear old dependencies and set this as the active effect.
         me.dependencies.forEach(cleanup => cleanup());
         me.dependencies.clear();
-
         EffectManager.push(me);
 
         try {
+            // Execute the function, which will collect new dependencies.
             me.fn()
         } finally {
+            // Clean up after the run.
             EffectManager.pop();
-            me.isRunning = false;
+
+            // Set `isRunning` to false without creating a dependency.
+            EffectManager.pauseTracking();
+            me.isRunning.set(false);
+            EffectManager.resumeTracking()
         }
     }
 
@@ -109,7 +166,6 @@ class Effect {
     addDependency(config) {
         const me = this;
 
-        // Only add if not already a dependency. Map uses strict equality (===) for object keys.
         if (!me.dependencies.has(config)) {
             const cleanup = config.subscribe({
                 id: me.id,
@@ -121,7 +177,13 @@ class Effect {
     }
 }
 
-const ns = Neo.ns('Neo.core', true);
-ns.Effect = Effect;
-
-export default Effect;
+export default Neo.gatekeep(Effect, 'Neo.core.Effect', () => {
+    /**
+     * Factory shortcut to create a new Neo.core.Effect instance.
+     * @function Neo.effect
+     * @param {Function|Object} fn - The function to execute, or a config object for the effect.
+     * @param {Object} [options] - Optional. Used if the first argument is a function.
+     * @returns {Neo.core.Effect}
+     */
+    Neo.effect = (fn, options) => new Effect(fn, options)
+});

package/src/core/EffectManager.mjs

@@ -1,11 +1,48 @@
 /**
- * A singleton manager to track the currently running effect.
- * This allows reactive properties to know which effect to subscribe to.
+ * A singleton manager to track the currently running effect and control global effect execution.
+ * It provides a centralized mechanism for pausing, resuming, and batching effect runs.
  * @class Neo.core.EffectManager
  * @singleton
  */
 const EffectManager = {
+    /**
+     * A stack to keep track of the currently active effect and its predecessors.
+     * @member {Neo.core.Effect[]} effectStack=[]
+     * @protected
+     */
     effectStack: [],
+    /**
+     * A flag to temporarily disable dependency tracking for the active effect.
+     * This is used internally to prevent effects from depending on their own state, like `isRunning`.
+     * @member {Boolean} isTrackingPaused=false
+     * @protected
+     */
+    isTrackingPaused: false,
+    /**
+     * A counter to manage nested calls to pause() and resume(). Effect execution is
+     * paused or batched while this counter is greater than 0.
+     * @member {Number} pauseCounter=0
+     * @protected
+     */
+    pauseCounter: 0,
+    /**
+     * A Set to store unique effects that are triggered while the manager is paused.
+     * These effects will be run when resume() is called and the pauseCounter returns to 0.
+     * @member {Set<Neo.core.Effect>} queuedEffects=new Set()
+     * @protected
+     */
+    queuedEffects: new Set(),
+
+    /**
+     * Adds a `Neo.core.Config` instance as a dependency for the currently active effect,
+     * unless dependency tracking is explicitly paused.
+     * @param {Neo.core.Config} config The config instance to add as a dependency.
+     */
+    addDependency(config) {
+        if (!this.isTrackingPaused) {
+            this.getActiveEffect()?.addDependency(config)
+        }
+    },
 
     /**
      * Returns the effect currently at the top of the stack (i.e., the one currently running).
@@ -16,7 +53,31 @@ const EffectManager = {
     },
 
     /**
-     * Pops the current effect from the stack, returning to the previous effect (if any).
+     * Checks if effect execution is currently paused or batched.
+     * @returns {Boolean} True if the pauseCounter is greater than 0.
+     */
+    isPaused() {
+        return this.pauseCounter > 0
+    },
+
+    /**
+     * Pauses effect execution and begins batching.
+     * Each call to pause() increments a counter, allowing for nested control.
+     */
+    pause() {
+        this.pauseCounter++
+    },
+
+    /**
+     * Disables dependency tracking for the currently active effect.
+     * @protected
+     */
+    pauseTracking() {
+        this.isTrackingPaused = true
+    },
+
+    /**
+     * Pops the current effect from the stack.
      * @returns {Neo.core.Effect|null}
      */
     pop() {
@@ -24,15 +85,63 @@ const EffectManager = {
     },
 
     /**
-     * Pushes an effect onto the stack, marking it as the currently running effect.
+     * Pushes an effect onto the stack.
      * @param {Neo.core.Effect} effect The effect to push.
      */
     push(effect) {
         this.effectStack.push(effect)
+    },
+
+    /**
+     * Queues a unique effect to be run later.
+     * @param {Neo.core.Effect} effect The effect to queue.
+     * @protected
+     */
+    queue(effect) {
+        this.queuedEffects.add(effect)
+    },
+
+    /**
+     * Resumes effect execution. If the pause counter returns to zero and effects
+     * have been queued, they will all be executed synchronously.
+     */
+    resume() {
+        let me = this;
+
+        if (me.pauseCounter > 0) {
+            me.pauseCounter--;
+
+            if (me.pauseCounter === 0 && me.queuedEffects.size > 0) {
+                const effectsToRun = [...me.queuedEffects];
+                me.queuedEffects.clear();
+                effectsToRun.forEach(effect => effect.run())
+            }
+        }
+    },
+
+    /**
+     * Re-enables dependency tracking for the currently active effect.
+     * @protected
+     */
+    resumeTracking() {
+        this.isTrackingPaused = false
     }
 };
 
-const ns = Neo.ns('Neo.core', true);
-ns.EffectManager = EffectManager;
-
-export default EffectManager;
+export default Neo.gatekeep(EffectManager, 'Neo.core.EffectManager', () => {
+    /**
+     * Wraps a function in a batch operation, ensuring that all effects triggered
+     * within it are run only once after the function completes.
+     * @function Neo.batch
+     * @param {Function} fn The function to execute.
+     */
+    Neo.batch = function(fn) {
+        EffectManager.pause();
+        try {
+            fn()
+        } finally {
+            // The public resume() method handles running queued effects.
+            EffectManager.resume()
+        }
+    }
+});

package/src/core/IdGenerator.mjs

@@ -1,44 +1,17 @@
 /**
- * This class gets used by core.Base, so it can not extend it.
- * It could get simplified to just being an object (needs to manually get put into the Neo namespace in this case).
- * @class Neo.core.IdGenerator
- * @singleton
+ * Provides a singleton utility for generating unique IDs.
+ * @namespace Neo.core.IdGenerator
  */
-class IdGenerator {
-    static config = {
-        /**
-         * @member {String} className='Neo.core.IdGenerator'
-         * @protected
-         */
-        className: 'Neo.core.IdGenerator',
-        /**
-         * @member {String} ntype='id-generator'
-         * @protected
-         */
-        ntype: 'id-generator',
-        /**
-         * The default prefix for neo instance ids
-         * @member {String} base='neo-'
-         */
-        base: 'neo-',
-        /**
-         * @member {Boolean} singleton='true
-         * @protected
-         */
-        singleton: true
-    }
-
+const IdGenerator = {
     /**
-     * @param config
+     * The default prefix for neo instance ids
+     * @member {String} base='neo-'
      */
-    construct(config) {
-        let me = this;
-
-        me.idCounter = {};
-
-        // alias
-        Neo.getId = me.getId.bind(me);
-    }
+    base: 'neo-',
+    /**
+     * @member {Object} idCounter={}
+     */
+    idCounter: {},
 
     /**
      * @param name
@@ -55,12 +28,8 @@ class IdGenerator {
 
         return me.base + (name === 'neo' ? '' : name + '-') + count;
     }
-
-    init() {}
-
-    onAfterConstructed() {}
-
-    onConstructed() {}
 }
 
-export default Neo.setupClass(IdGenerator);
+export default Neo.gatekeep(IdGenerator, 'Neo.core.IdGenerator', () => {
+    Neo.getId = IdGenerator.getId.bind(IdGenerator);
+});