neo.mjs 10.0.0-beta.4 → 10.0.0-beta.6

package/src/core/Base.mjs

@@ -3,7 +3,8 @@ import Compare                                                  from '../core/Co
 import Util                                                     from '../core/Util.mjs';
 import Config                                                   from './Config.mjs';
 import {isDescriptor}                                           from './ConfigSymbols.mjs';
-import IdGenerator                                              from './IdGenerator.mjs'
+import IdGenerator                                              from './IdGenerator.mjs';
+import EffectBatchManager                                       from './EffectBatchManager.mjs';
 
 const configSymbol       = Symbol.for('configSymbol'),
       forceAssignConfigs = Symbol('forceAssignConfigs'),
@@ -57,7 +58,26 @@ class Base {
      */
     static overwrittenMethods = {}
     /**
-     * Configs will get merged throughout the class hierarchy
+     * Defines the default configuration properties for the class. These configurations are
+     * merged throughout the class hierarchy and can be overridden at the instance level.
+     *
+     * There are two main types of configs:
+     *
+     * 1.  **Reactive Configs:** Property names ending with a trailing underscore (e.g., `myConfig_`).
+     *     The framework automatically generates a public getter and setter, removing the underscore
+     *     from the property name (e.g., `this.myConfig`). This system enables powerful, optional
+     *     lifecycle hooks that are called automatically if they are implemented on the class:
+     *     - `beforeGetMyConfig(value)`: Executed before the getter returns. Can be used to dynamically modify the returned value.
+     *     - `beforeSetMyConfig(newValue, oldValue)`: Executed before a new value is set. Can be used for validation or transformation. Returning `undefined` from this hook will cancel the update.
+     *     - `afterSetMyConfig(newValue, oldValue)`: Executed after a new value has been successfully set. Ideal for triggering side effects.
+     *
+     * 2.  **Non-Reactive (Prototype-based) Configs:** Property names without a trailing underscore.
+     *     These are applied directly to the class's **prototype** during the `Neo.setupClass`
+     *     process. This is highly memory-efficient as the value is shared across all instances.
+     *     It also allows for powerful, application-wide modifications of default behaviors
+     *     by using the `Neo.overwrites` mechanism, which modifies these prototype values at
+     *     load time.
+     *
      * @returns {Object} config
      */
     static config = {
@@ -82,6 +102,7 @@ class Base {
         /**
          * The unique component id
          * @member {String|null} id_=null
+         * @reactive
          */
         id_: null,
         /**
@@ -98,12 +119,21 @@ class Base {
          * @protected
          */
         isConstructed: false,
+        /**
+         * This config will be set to `true` as the very first action within the `destroy()` method.
+         * Effects can observe this config to clean themselves up.
+         * @member {Boolean} isDestroying_=false
+         * @protected
+         * @reactive
+         */
+        isDestroying_: false,
         /**
          * The config will get set to `true` once the Promise of `async initAsync()` is resolved.
          * You can use `afterSetIsReady()` to get notified once the ready state is reached.
          * Since not all classes use the Observable mixin, Neo will not fire an event.
          * method body.
-         * @member {Boolean} isReady=false
+         * @member {Boolean} isReady_=false
+         * @reactive
          */
         isReady_: false,
         /**
@@ -125,6 +155,7 @@ class Base {
          *
          * @member {Object|null} remote_=null
          * @protected
+         * @reactive
          */
         remote_: null
     }
@@ -135,6 +166,12 @@ class Base {
      * @private
      */
     #configs = {};
+    /**
+     * Internal cache for all config subscription cleanup functions.
+     * @member {Function[]} #configSubscriptionCleanups=[]
+     * @private
+     */
+    #configSubscriptionCleanups = []
     /**
      * Internal cache for all timeout ids when using this.timeout()
      * @member {Number[]} timeoutIds=[]
@@ -239,7 +276,7 @@ class Base {
         if (oldValue) {
             if (hasManager) {
                 Neo.manager.Instance.unregister(oldValue)
-            } else {
+            } else if (Neo.idMap) {
                 delete Neo.idMap[oldValue]
             }
         }
@@ -249,7 +286,7 @@ class Base {
                 Neo.manager.Instance.register(me);
             } else {
                 Neo.idMap ??= {};
-                Neo.idMap[me.id] = me
+                Neo.idMap[value] = me
             }
         }
     }
@@ -276,9 +313,38 @@ class Base {
     }
 
     /**
-     * Applying overwrites and adding overwrittenMethods to the class constructors
-     * @param {Object} cfg
+     * This static method is called by `Neo.setupClass()` during the class creation process.
+     * It allows for modifying a class's default prototype-based configs from outside the
+     * class hierarchy, which is a powerful way to avoid boilerplate code.
+     *
+     * It looks for a matching entry in the global `Neo.overwrites` object based on the
+     * class's `className`. If found, it merges the properties from the overwrite object
+     * into the class's static `config`. This provides a powerful mechanism for theming
+     * or applying application-wide customizations to framework or library classes without
+     * needing to extend them.
+     *
+     * @example
+     * // Imagine you have hundreds of buttons in your app, and you want all of them
+     * // to have `labelPosition: 'top'` instead of the default `'left'`. 
+     * // Instead of configuring each instance, you can define an overwrite.
+     * 
+     * // inside an Overwrites.mjs file loaded by your app:
+     * Neo.overwrites = {
+     *     Neo: {
+     *         button: {
+     *             Base: {
+     *                 labelPosition: 'top'
+     *             }
+     *         }
+     *     }
+     * };
+     * 
+     * // Now, every `Neo.button.Base` (and any class that extends it) will have this
+     * // new default value on its prototype.
+     *
+     * @param {Object} cfg The static `config` object of the class being processed.
      * @protected
+     * @static
      */
     static applyOverwrites(cfg) {
         let overwrites = Neo.ns(cfg.className, false, Neo.overwrites),
@@ -386,10 +452,16 @@ class Base {
     destroy() {
         let me = this;
 
+        me.isDestroying = true;
+
         me.#timeoutIds.forEach(id => {
             clearTimeout(id)
         });
 
+        me.#configSubscriptionCleanups.forEach(cleanup => {
+            cleanup()
+        });
+
         if (Base.instanceManagerAvailable === true) {
             Neo.manager.Instance.unregister(me)
         } else if (Neo.idMap) {
@@ -423,7 +495,7 @@ class Base {
         let me = this;
 
         if (!me.#configs[key] && me.isConfig(key)) {
-            me.#configs[key] = new Config()
+            me.#configs[key] = new Config(me.constructor.configDescriptors?.[key])
         }
 
         return me.#configs[key]
@@ -488,7 +560,7 @@ class Base {
         Object.assign(me[configSymbol], me.mergeConfig(config, preventOriginalConfig));
         delete me[configSymbol].id;
         me.processConfigs();
-        me.isConfiguring = false;
+        me.isConfiguring = false
     }
 
     /**
@@ -524,10 +596,12 @@ class Base {
      * @returns {Boolean}
      */
     isConfig(key) {
-        // A config is considered "reactive" if it has a generated property setter
+        let me = this;
+        // If a `core.Config` controller is already created, return true (fastest possible check).
+        // If not, a config is considered "reactive" if it has a generated property setter
         // AND it is present as a defined config in the merged static config hierarchy.
         // Neo.setupClass() removes the underscore from the static config keys.
-        return Neo.hasPropertySetter(this, key) && (key in this.constructor.config);
+        return me.#configs[key] || (Neo.hasPropertySetter(me, key) && (key in me.constructor.config))
     }
 
     /**
@@ -539,7 +613,8 @@ class Base {
      */
     mergeConfig(config, preventOriginalConfig) {
         let me   = this,
-            ctor = me.constructor;
+            ctor = me.constructor,
+            configDescriptors, staticConfig;
 
         if (!ctor.config) {
             throw new Error('Neo.applyClassConfig has not been run on ' + me.className)
@@ -549,7 +624,70 @@ class Base {
             me.originalConfig = Neo.clone(config, true, true)
         }
 
-        return {...ctor.config, ...config}
+        configDescriptors = ctor.configDescriptors;
+        staticConfig      = ctor.config;
+
+        if (configDescriptors) {
+            Object.entries(config).forEach(([key, instanceValue]) => {
+                const descriptor = configDescriptors[key];
+
+                if (descriptor?.merge) {
+                    config[key] = Neo.mergeConfig(staticConfig[key], instanceValue, descriptor.merge)
+                }
+            })
+        }
+
+        return {...staticConfig, ...config}
+    }
+
+    /**
+     * Subscribes *this* instance (the subscriber) to changes of a specific config property on another instance (the publisher).
+     * Ensures automatic cleanup when *this* instance (the subscriber) is destroyed.
+     *
+     * @param {String|Neo.core.Base} publisher  - The ID of the publisher instance or the instance reference itself.
+     * @param {String}               configName - The name of the config property on the publisher to subscribe to (e.g., 'myConfig').
+     * @param {Function}             fn         - The callback function to execute when the config changes.
+     * @returns {Function} A cleanup function to manually unsubscribe if needed before this instance's destruction.
+     *
+     * @example
+     * // Subscribing to a config on another instance
+     * this.observeConfig(someOtherInstance, 'myConfig', (newValue, oldValue) => {
+     *     console.log('myConfig changed:', newValue);
+     * });
+     *
+     * // Discouraged: Self-observation. Use afterSet<ConfigName>() hooks instead.
+     * this.observeConfig(this, 'myOwnConfig', (newValue, oldValue) => {
+     *     console.log('myOwnConfig changed:', newValue);
+     * });
+     */
+    observeConfig(publisher, configName, fn) {
+        let publisherInstance = publisher;
+
+        if (Neo.isString(publisher)) {
+            publisherInstance = Neo.get(publisher);
+            if (!publisherInstance) {
+                console.warn(`Publisher instance with ID '${publisher}' not found. Cannot subscribe.`);
+                return Neo.emptyFn
+            }
+        }
+
+        if (!(publisherInstance instanceof Neo.core.Base)) {
+            console.warn(`Invalid publisher provided. Must be a Neo.core.Base instance or its ID.`);
+            return Neo.emptyFn
+        }
+
+        const configController = publisherInstance.getConfig(configName);
+
+        if (!configController) {
+            console.warn(`Config '${configName}' not found on publisher instance ${publisherInstance.id}. Cannot subscribe.`);
+            return Neo.emptyFn
+        }
+
+        const cleanup = configController.subscribe({id: this.id, fn});
+
+        this.#configSubscriptionCleanups.push(cleanup);
+
+        return cleanup
     }
 
     /**
@@ -670,24 +808,58 @@ class Base {
     }
 
     /**
-     * Change multiple configs at once, ensuring that all afterSet methods get all new assigned values
+     * set() accepts the following input as keys:
+     * 1. Non-reactive configs
+     * 2. Reactive configs
+     * 3. Class fields defined via value
+     * 4. Class fields defined via get() & set()
+     * 5. "Anything else" will get directly get assigned to the instance
+     *
+     * The logic resolves circular dependencies as good as possible and ensures that config related hooks:
+     * - beforeGet<Config>
+     * - beforeSet<Config>
+     * - afterSet<Config>
+     * can access all new values from the batch operation.
      * @param {Object} values={}
      */
     set(values={}) {
-        let me = this;
+        let me                = this,
+            classFieldsViaSet = {};
+
+        // Start batching for effects
+        EffectBatchManager.startBatch();
 
         values = me.setFields(values);
 
         // If the initial config processing is still running,
         // finish this one first before dropping new values into the configSymbol.
-        // see: https://github.com/neomjs/neo/issues/2201
+        // See: https://github.com/neomjs/neo/issues/2201
         if (me[forceAssignConfigs] !== true && Object.keys(me[configSymbol]).length > 0) {
             me.processConfigs()
         }
 
+        // Store class fields which are defined via get() & set() and ensure they won't get added to the config symbol.
+        Object.entries(values).forEach(([key, value]) => {
+            if (!me.isConfig(key)) {
+                classFieldsViaSet[key] = value;
+                delete values[key]
+            }
+        })
+
+        // Add reactive configs to the configSymbol
         Object.assign(me[configSymbol], values);
 
-        me.processConfigs(true)
+        // Process class fields which are defined via get() & set() => now they can access the latest values
+        // for reactive and non-reactive configs, as well as class fields defined with values.
+        Object.entries(classFieldsViaSet).forEach(([key, value]) => {
+            me[key] = value
+        })
+
+        // Process reactive configs
+        me.processConfigs(true);
+
+        // End batching for effects
+        EffectBatchManager.endBatch();
     }
 
     /**
@@ -698,15 +870,14 @@ class Base {
      * @protected
      */
     setFields(config) {
-        let me          = this,
-            configNames = me.constructor.config;
+        let me = this;
 
         Object.entries(config).forEach(([key, value]) => {
-            if (!configNames.hasOwnProperty(key) && !Neo.hasPropertySetter(me, key)) {
+            if (!me.isConfig(key) && !Neo.hasPropertySetter(me, key)) {
                 me[key] = value;
                 delete config[key]
             }
-        })
+        });
 
         return config
     }
@@ -748,7 +919,7 @@ class Base {
      * @returns {String}
      */
     get [Symbol.toStringTag]() {
-        return `${this.className} (id: ${this.id})`
+        return this.className
     }
 
     /**

package/src/core/Compare.mjs

@@ -163,10 +163,7 @@ class Compare {
     }
 }
 
-const ns = Neo.ns('Neo.core', true);
-ns.Compare = Compare;
-
-// alias
-Neo.isEqual = Compare.isEqual;
-
-export default Compare;
+export default Neo.gatekeep(Compare, 'Neo.core.Compare', () => {
+    // alias
+    Neo.isEqual = Compare.isEqual
+});

package/src/core/Config.mjs

@@ -1,45 +1,65 @@
+import EffectManager  from './EffectManager.mjs';
 import {isDescriptor} from './ConfigSymbols.mjs';
 
 /**
- * @src/util/ClassSystem.mjs Neo.core.Config
- * @private
- * @internal
- *
  * Represents an observable container for a config property.
  * This class manages the value of a config, its subscribers, and custom behaviors
  * like merge strategies and equality checks defined via a descriptor object.
  *
  * The primary purpose of this class is to enable fine-grained reactivity and
  * decoupled cross-instance state sharing within the Neo.mjs framework.
+ * @class Neo.core.Config
+ * @private
+ * @internal
  */
 class Config {
     /**
-     * The internal value of the config property.
+     * 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
-     * @apps/portal/view/about/MemberContainer.mjs {any} #value
      */
-    #value;
-
+    #subscribers = {}
     /**
-     * A Set to store callback functions that subscribe to changes in this config's value.
+     * The internal value of the config property.
+     * @member {*} #value
      * @private
-     * @apps/portal/view/about/MemberContainer.mjs {Set<Function>} #subscribers
      */
-    #subscribers = new Set();
+    #value
+    /**
+     * The cloning strategy to use when setting a new value.
+     * Supported values: 'deep', 'shallow', 'none'.
+     * @member {String} clone='deep'
+     */
 
     /**
-     * The strategy to use when merging new values into this config.
-     * Defaults to 'deep'. Can be overridden via a descriptor.
-     * @apps/portal/view/about/MemberContainer.mjs {string} mergeStrategy
+     * The cloning strategy to use when getting a value.
+     * Supported values: 'deep', 'shallow', 'none'.
+     * @member {String} cloneOnGet=null
      */
-    mergeStrategy = 'deep';
 
     /**
      * The function used to compare new and old values for equality.
      * Defaults to `Neo.isEqual`. Can be overridden via a descriptor.
-     * @apps/portal/view/about/MemberContainer.mjs {Function} isEqual
+     * @member {Function} isEqual=Neo.isEqual
+     */
+
+    /**
+     * The strategy to use when merging new values into this config.
+     * Defaults to 'replace'. Can be overridden via a descriptor merge property.
+     * @member {Function|String} mergeStrategy='replace'
      */
-    isEqual = Neo.isEqual;
 
     /**
      * Creates an instance of Config.
@@ -58,34 +78,68 @@ class Config {
      * @returns {any} The current value.
      */
     get() {
-        return this.#value;
+        // Registers this Config instance as a dependency with the currently active Effect,
+        // enabling automatic re-execution when this Config's value changes.
+        EffectManager.addDependency(this);
+        return this.#value
     }
 
     /**
      * Initializes the `Config` instance using a descriptor object.
-     * Extracts `mergeStrategy` and `isEqual` from the descriptor.
+     * 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 {string} [descriptor.merge='deep'] - The merge strategy.
+     * @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 {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({isEqual, merge, value}) {
+    initDescriptor({clone, cloneOnGet, isEqual, merge}) {
         let me = this;
 
-        me.#value        = value
-        me.mergeStrategy = merge   || me.mergeStrategy;
-        me.isEqual       = isEqual || me.isEqual;
+        if (clone && clone !== me.clone) {
+            Object.defineProperty(me, 'clone', {
+                configurable: true, enumerable: true, value: clone, writable: true
+            })
+        }
+
+        if (cloneOnGet && cloneOnGet !== me.cloneOnGet) {
+            Object.defineProperty(me, 'cloneOnGet', {
+                configurable: true, enumerable: true, value: cloneOnGet, writable: true
+            })
+        }
+
+        if (isEqual && isEqual !== me.isEqual) {
+            Object.defineProperty(me, 'isEqual', {
+                configurable: true, enumerable: true, value: isEqual, writable: true
+            })
+        }
+
+        if (merge && merge !== me.mergeStrategy) {
+            Object.defineProperty(me, 'mergeStrategy', {
+                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 callback of this.#subscribers) {
-            callback(newValue, oldValue);
+        for (const id in this.#subscribers) {
+            if (this.#subscribers.hasOwnProperty(id)) {
+                const subscriberMap = this.#subscribers[id];
+                for (const [fn, scopeSet] of subscriberMap) {
+                    for (const scope of scopeSet) {
+                        fn.call(scope || null, newValue, oldValue)
+                    }
+                }
+            }
         }
     }
 
@@ -127,13 +181,63 @@ 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 {Function} callback - The function to call when the config value 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.scope] - The scope to execute the callback in.
      * @returns {Function} A cleanup function to unsubscribe the callback.
      */
-    subscribe(callback) {
-        this.#subscribers.add(callback);
-        return () => this.#subscribers.delete(callback)
+    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` ',
+                '(the subscription owner\'s id), and a callback function `fn`.'
+            ].join(''))
+        }
+
+        const me = this;
+
+        // Get or create the top-level Map for the subscription owner.
+        if (!me.#subscribers[id]) {
+            me.#subscribers[id] = new Map()
+        }
+
+        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 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]
+                        }
+                    }
+                }
+            }
+        }
     }
 }
 
-export default Config;
+Object.defineProperties(Config.prototype, {
+    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}
+});
+
+export default Neo.gatekeep(Config, 'Neo.core.Config');