neo.mjs 10.0.0-beta.6 → 10.0.0

package/src/manager/VDomUpdate.mjs

@@ -1,6 +1,34 @@
 import Collection from '../collection/Base.mjs';
 
 /**
+ * The VDomUpdate manager is a singleton responsible for orchestrating and optimizing
+ * component VDOM updates within the Neo.mjs framework. It acts as a central coordinator
+ * to optimize the VDOM update process. Its primary goal is to reduce the amount of
+ * message roundtrips between the application and VDOM workers by aggregating multiple
+ * component updates into a single, optimized VDOM tree.
+ *
+ * Key Responsibilities:
+ * 1. **Update Merging & Aggregation:** Allows a parent component to absorb the update
+ *    requests of its children. Instead of each child triggering a separate VDOM update
+ *    message to the VDOM worker, the parent sends a single, aggregated VDOM tree. This
+ *    significantly reduces the overhead of worker communication and can result in smaller,
+ *    more focused data for the VDOM worker to process. While the amount of final DOM
+ *    modifications remains the same, this aggregation is key to performance.
+ *
+ * 2. **Asynchronous Flow Control:** Manages the asynchronous nature of VDOM updates, which
+ *    are often processed in a worker thread. It ensures that code awaiting an update
+ *    (e.g., via a returned Promise) is correctly notified upon completion.
+ *
+ * 3. **Dependency Chaining:** Provides a "post-update" queue, allowing one component's
+ *    update to be declaratively chained to another's, ensuring a predictable order of
+ *    operations.
+ *
+ * 4. **State Tracking:** Keeps track of updates that are "in-flight" (i.e., currently
+ *    being processed), which helps to avoid race conditions and redundant work.
+ *
+ * By centralizing these concerns, VDomUpdate plays a critical role in the framework's
+ * performance and rendering efficiency.
+ *
  * @class Neo.manager.VDomUpdate
  * @extends Neo.collection.Base
  * @singleton
@@ -13,34 +41,68 @@ class VDomUpdate extends Collection {
          */
         className: 'Neo.manager.VDomUpdate',
         /**
-         * @member {Boolean} singleton=true
-         * @protected
-         */
-        singleton: true,
-        /**
+         * A collection that maps a parent component's ID (`ownerId`) to the set of child
+         * components whose VDOM updates have been merged into that parent's update cycle.
+         *
+         * The structure for each entry is:
+         * `{ ownerId: 'parent-id', children: Map<'child-id', {childUpdateDepth, distance}> }`
+         *
+         * - `ownerId`: The `id` of the parent component taking responsibility for the update.
+         * - `children`: A Map where keys are the `id`s of the merged children and values
+         *   are objects containing metadata needed to calculate the total update scope.
+         *
          * @member {Neo.collection.Base|null} mergedCallbackMap=null
          * @protected
          */
         mergedCallbackMap: null,
         /**
+         * A collection that queues components that need to be updated immediately after
+         * another component's update cycle completes. This is used to handle rendering
+         * dependencies.
+         *
+         * The structure for each entry is:
+         * `{ ownerId: 'component-id', children: [{childId, resolve}] }`
+         *
+         * - `ownerId`: The `id` of the component whose update completion will trigger the queued updates.
+         * - `children`: An array of objects, where `childId` is the component to update and
+         *   `resolve` is the Promise resolver to call after that subsequent update is done.
+         *
          * @member {Neo.collection.Base|null} postUpdateQueueMap=null
          * @protected
          */
         postUpdateQueueMap: null,
+        /**
+         * @member {Boolean} singleton=true
+         * @protected
+         */
+        singleton: true
     }
 
     /**
+     * A Map that tracks VDOM updates that have been dispatched to the VDOM worker but
+     * have not yet completed. This prevents redundant updates for the same component.
+     *
+     * The structure is: `Map<'component-id', updateDepth>`
+     *
      * @member {Map|null} inFlightUpdateMap=null
      * @protected
      */
     inFlightUpdateMap = null;
     /**
+     * A Map that stores Promise `resolve` functions associated with a component's update.
+     * When a component's VDOM update is finalized, the callbacks for its ID are executed,
+     * resolving the Promise returned by the component's `update()` method.
+     *
+     * The structure is: `Map<'component-id', [callback1, callback2, ...]>`
+     *
      * @member {Map|null} promiseCallbackMap=null
      * @protected
      */
     promiseCallbackMap = null;
 
     /**
+     * Initializes the manager's internal collections and maps.
+     * This is called automatically when the singleton instance is created.
      * @param {Object} config
      */
     construct(config) {
@@ -55,8 +117,11 @@ class VDomUpdate extends Collection {
     }
 
     /**
-     * @param {String} ownerId
-     * @param {Function} callback
+     * Registers a callback function to be executed when a specific component's
+     * VDOM update completes. This is the mechanism that resolves the Promise
+     * returned by `Component#update()`.
+     * @param {String}   ownerId  The `id` of the component owning the update.
+     * @param {Function} callback The function to execute upon completion.
      */
     addPromiseCallback(ownerId, callback) {
         let me = this;
@@ -69,72 +134,53 @@ class VDomUpdate extends Collection {
     }
 
     /**
-     * Registers an update that is currently in-flight to the worker.
-     * @param {String} ownerId The ID of the component owning the update.
-     * @param {Number} updateDepth The depth of the in-flight update.
-     */
-    registerInFlightUpdate(ownerId, updateDepth) {
-        this.inFlightUpdateMap.set(ownerId, updateDepth);
-    }
-
-    /**
-     * Retrieves the update depth for an in-flight update.
-     * @param {String} ownerId The ID of the component owning the update.
-     * @returns {Number|undefined} The update depth, or undefined if not found.
-     */
-    getInFlightUpdateDepth(ownerId) {
-        return this.inFlightUpdateMap.get(ownerId);
-    }
-
-    /**
-     * Unregisters an in-flight update once it has completed.
-     * @param {String} ownerId The ID of the component owning the update.
-     */
-    unregisterInFlightUpdate(ownerId) {
-        this.inFlightUpdateMap.delete(ownerId);
-    }
-
-    /**
-     * @param {String} ownerId
-     * @param {String} childId
-     * @param {Number} childUpdateDepth
-     * @param {Number} distance
+     * Executes all callbacks associated with a completed VDOM update for a given `ownerId`.
+     * This method first processes callbacks for any children that were merged into this
+     * update cycle, then executes the callbacks for the `ownerId` itself.
+     * @param {String} ownerId The `id` of the component whose update has just completed.
+     * @param {Object} [data]  Optional data to pass to the callbacks.
      */
-    registerMerged(ownerId, childId, childUpdateDepth, distance) {
-        let me   = this,
-            item = me.mergedCallbackMap.get(ownerId);
+    executeCallbacks(ownerId, data) {
+        let me           = this,
+            item         = me.mergedCallbackMap.get(ownerId),
+            callbackData = data ? [data] : [];
 
-        if (!item) {
-            item = {ownerId, children: new Map()};
-            me.mergedCallbackMap.add(item);
+        if (item) {
+            item.children.forEach((value, key) => {
+                me.executePromiseCallbacks(key, ...callbackData)
+            });
+            me.mergedCallbackMap.remove(item);
         }
 
-        item.children.set(childId, {childUpdateDepth, distance});
+        me.executePromiseCallbacks(ownerId, ...callbackData)
     }
 
     /**
-     * @param {String} ownerId
-     * @param {String} childId
-     * @param {Function} [resolve]
+     * A helper method that invokes all registered promise callbacks for a given
+     * component ID and then clears them from the queue.
+     * @param {String} ownerId The `id` of the component.
+     * @param {Object} [data]  Optional data to pass to the callbacks.
      */
-    registerPostUpdate(ownerId, childId, resolve) {
-        let me   = this,
-            item = me.postUpdateQueueMap.get(ownerId),
-            childCallbacks;
-
-        if (!item) {
-            item = {ownerId, children: []};
-            me.postUpdateQueueMap.add(item);
-        }
+    executePromiseCallbacks(ownerId, data) {
+        let me        = this,
+            callbacks = me.promiseCallbackMap.get(ownerId);
 
-        item.children.push({childId, resolve})
+        callbacks?.forEach(callback => callback(data));
+        me.promiseCallbackMap.delete(ownerId);
     }
 
     /**
-     * Calculates the adjusted updateDepth for a parent component based on its merged children.
-     * This method is called by the parent component right before it executes its own VDOM update.
-     * @param {String} ownerId
-     * @returns {Number|null} The adjusted update depth or null if no merged children are found
+     * Calculates the required `updateDepth` for a parent component based on its own
+     * needs and the needs of all child components whose updates have been merged into it.
+     * The final depth is the maximum required depth to ensure all changes are rendered.
+     *
+     * For example, if a parent needs to update its direct content (`updateDepth: 1`) but
+     * a merged child 3 levels down needs a full subtree update (`childUpdateDepth: -1`),
+     * this method will return -1, signaling a full recursive update from the parent.
+     *
+     * This method is called by the parent component right before it dispatches its VDOM update.
+     * @param {String} ownerId The `id` of the parent component.
+     * @returns {Number|null} The adjusted update depth, or `null` if no merged children exist.
      */
     getAdjustedUpdateDepth(ownerId) {
         let me       = this,
@@ -146,71 +192,101 @@ class VDomUpdate extends Collection {
         if (item) {
             item.children.forEach(value => {
                 if (value.childUpdateDepth === -1) {
-                    newDepth = -1;
+                    newDepth = -1
                 } else {
                     // The new depth is the distance to the child plus the child's own required update depth.
-                    newDepth = value.distance + value.childUpdateDepth;
+                    newDepth = value.distance + value.childUpdateDepth
                 }
 
                 if (newDepth === -1) {
-                    maxDepth = -1;
+                    maxDepth = -1
                 } else if (maxDepth !== -1) {
-                    maxDepth = Math.max(maxDepth, newDepth);
+                    maxDepth = Math.max(maxDepth, newDepth)
                 }
             });
 
-            return maxDepth;
+            return maxDepth
         }
 
-        return null;
+        return null
+    }
+
+    /**
+     * Retrieves the `updateDepth` for a component's update that is currently in-flight.
+     * @param {String} ownerId The `id` of the component owning the update.
+     * @returns {Number|undefined} The update depth, or `undefined` if no update is in-flight.
+     */
+    getInFlightUpdateDepth(ownerId) {
+        return this.inFlightUpdateMap.get(ownerId)
     }
 
     /**
-     * Returns a Set of child IDs that have been merged into a parent's update.
-     * @param {String} ownerId The ID of the parent component owning the update.
-     * @returns {Set<String>|null} A Set containing the IDs of the merged children, or null.
+     * Returns a Set of child component IDs that have been merged into a parent's update cycle.
+     * This is used by the parent to know which children it is responsible for updating.
+     * @param {String} ownerId The `id` of the parent component.
+     * @returns {Set<String>|null} A Set containing the IDs of the merged children, or `null`.
      */
     getMergedChildIds(ownerId) {
         const item = this.mergedCallbackMap.get(ownerId);
         if (item) {
-            return new Set(item.children.keys());
+            return new Set(item.children.keys())
         }
-        return null;
+        return null
     }
 
     /**
-     * @param {String} ownerId
-     * @param {Object} [data]
+     * Marks a component's VDOM update as "in-flight," meaning it has been sent to the
+     * worker for processing.
+     * @param {String} ownerId     The `id` of the component owning the update.
+     * @param {Number} updateDepth The depth of the in-flight update.
      */
-    executeCallbacks(ownerId, data) {
-        let me           = this,
-            item         = me.mergedCallbackMap.get(ownerId),
-            callbackData = data ? [data] : [];
+    registerInFlightUpdate(ownerId, updateDepth) {
+        this.inFlightUpdateMap.set(ownerId, updateDepth)
+    }
 
-        if (item) {
-            item.children.forEach((value, key) => {
-                me.executePromiseCallbacks(key, ...callbackData)
-            });
-            me.mergedCallbackMap.remove(item);
+    /**
+     * Registers a child's update request to be merged into its parent's update cycle.
+     * This is called by a child component when it determines it can delegate its update
+     * to an ancestor.
+     * @param {String} ownerId          The `id` of the parent component that will own the merged update.
+     * @param {String} childId          The `id` of the child component requesting the merge.
+     * @param {Number} childUpdateDepth The update depth required by the child.
+     * @param {Number} distance         The component tree distance (number of levels) between the parent and child.
+     */
+    registerMerged(ownerId, childId, childUpdateDepth, distance) {
+        let me   = this,
+            item = me.mergedCallbackMap.get(ownerId);
+
+        if (!item) {
+            item = {ownerId, children: new Map()};
+            me.mergedCallbackMap.add(item)
         }
 
-        me.executePromiseCallbacks(ownerId, ...callbackData)
+        item.children.set(childId, {childUpdateDepth, distance})
     }
 
     /**
-     * @param {String} ownerId
-     * @param {Object} [data]
+     * Queues a component update to be executed after another component's update is complete.
+     * @param {String} ownerId     The `id` of the component to wait for.
+     * @param {String} childId     The `id` of the component to update afterward.
+     * @param {Function} [resolve] The Promise resolver to be called when the `childId`'s subsequent update finishes.
      */
-    executePromiseCallbacks(ownerId, data) {
-        let me        = this,
-            callbacks = me.promiseCallbackMap.get(ownerId);
+    registerPostUpdate(ownerId, childId, resolve) {
+        let me   = this,
+            item = me.postUpdateQueueMap.get(ownerId);
 
-        callbacks?.forEach(callback => callback(data));
-        me.promiseCallbackMap.delete(ownerId);
+        if (!item) {
+            item = {ownerId, children: []};
+            me.postUpdateQueueMap.add(item)
+        }
+
+        item.children.push({childId, resolve})
     }
 
     /**
-     * @param {String} ownerId
+     * Triggers all pending updates that were queued to run after the specified `ownerId`'s
+     * update has completed.
+     * @param {String} ownerId The `id` of the component whose update has just finished.
      */
     triggerPostUpdates(ownerId) {
         let me   = this,
@@ -223,13 +299,22 @@ class VDomUpdate extends Collection {
 
                 if (component) {
                     entry.resolve && me.addPromiseCallback(component.id, entry.resolve);
-                    component.update();
+                    component.update()
                 }
             });
 
-            me.postUpdateQueueMap.remove(item);
+            me.postUpdateQueueMap.remove(item)
         }
     }
+
+    /**
+     * Removes a component's update from the "in-flight" registry. This is called after
+     * the VDOM worker confirms the update has been processed.
+     * @param {String} ownerId The `id` of the component owning the update.
+     */
+    unregisterInFlightUpdate(ownerId) {
+        this.inFlightUpdateMap.delete(ownerId)
+    }
 }
 
 export default Neo.setupClass(VDomUpdate);

package/src/mixin/VdomLifecycle.mjs

@@ -440,6 +440,7 @@ class VdomLifecycle extends Base {
      * - you pass true for the mount param
      * - or the autoMount config is set to true
      * @param {Boolean} [mount] Mount the DOM after the vnode got created
+     * @returns {Promise<any>} If getting there, we return the data from vdom.Helper: create(), containing the vnode.
      */
     async render(mount) {
         let me                            = this,
@@ -486,7 +487,9 @@ class VdomLifecycle extends Base {
 
             autoMount && !useVdomWorker && me.mount();
 
-            me.resolveVdomUpdate()
+            me.resolveVdomUpdate();
+
+            return data
         }
     }
 

package/src/state/Provider.mjs

@@ -2,7 +2,7 @@ import Base                          from '../core/Base.mjs';
 import ClassSystemUtil               from '../util/ClassSystem.mjs';
 import Config                        from '../core/Config.mjs';
 import Effect                        from '../core/Effect.mjs';
-import EffectBatchManager            from '../core/EffectBatchManager.mjs';
+import EffectManager                 from '../core/EffectManager.mjs';
 import Observable                    from '../core/Observable.mjs';
 import {createHierarchicalDataProxy} from './createHierarchicalDataProxy.mjs';
 import {isDescriptor}                from '../core/ConfigSymbols.mjs';
@@ -474,17 +474,6 @@ class Provider extends Base {
     internalSetData(key, value, originStateProvider) {
         const me = this;
 
-        // If the value is a Neo.data.Record, treat it as an atomic value
-        // and set it directly without further recursive processing of its properties.
-        if (Neo.isRecord(value)) {
-            const
-                ownerDetails   = me.getOwnerOfDataProperty(key),
-                targetProvider = ownerDetails ? ownerDetails.owner : (originStateProvider || me);
-
-            me.#setConfigValue(targetProvider, key, value, null);
-            return
-        }
-
         if (Neo.isObject(key)) {
             Object.entries(key).forEach(([dataKey, dataValue]) => {
                 me.internalSetData(dataKey, dataValue, originStateProvider)
@@ -492,13 +481,28 @@ class Provider extends Base {
             return
         }
 
+        // Now 'key' is a string path.
+        // If 'value' is a plain object, we need to drill down further.
+        // If the value is a Neo.data.Record, treat it as an atomic value => it will not enter this block.
+        if (Neo.typeOf(value) === 'Object') {
+            Object.entries(value).forEach(([nestedKey, nestedValue]) => {
+                const fullPath = `${key}.${nestedKey}`;
+                me.internalSetData(fullPath, nestedValue, originStateProvider);
+            });
+            return // We've delegated the setting to deeper paths.
+        }
+
         const
             ownerDetails   = me.getOwnerOfDataProperty(key),
             targetProvider = ownerDetails ? ownerDetails.owner : (originStateProvider || me);
 
         me.#setConfigValue(targetProvider, key, value, null);
 
-        // Bubble up the change to parent configs to trigger their effects
+        // This is the "reactivity bubbling" logic. When a leaf property like 'user.name' changes,
+        // we must also trigger effects that depend on the parent object 'user'. We do this by
+        // creating a new object reference for each parent in the path. The spread syntax
+        // `{ ...oldParentValue, [leafKey]: latestValue }` is key, as it creates a new
+        // object, which the reactivity system detects as a change.
         let path        = key,
             latestValue = value;
 
@@ -518,7 +522,11 @@ class Provider extends Base {
                     break // Stop if parent is not an object
                 }
             } else {
-                break // Stop if parent config does not exist
+                // If the parent config doesn't exist, we need to create it to support bubbling.
+                // This is crucial for creating new nested data structures at runtime.
+                const newParentValue = {[leafKey]: latestValue};
+                me.#setConfigValue(targetProvider, path, newParentValue);
+                latestValue = newParentValue
             }
         }
     }
@@ -582,8 +590,8 @@ class Provider extends Base {
 
     /**
      * @param {Neo.component.Base} component
-     * @param {String} configName
-     * @param {String} storeName
+     * @param {String}             configName
+     * @param {String}             storeName
      */
     resolveStore(component, configName, storeName) {
         let store = this.getStore(storeName);
@@ -598,9 +606,9 @@ class Provider extends Base {
      * This method creates a new Config instance if one doesn't exist for the given path,
      * or updates an existing one. It also triggers binding effects and calls onDataPropertyChange.
      * @param {Neo.state.Provider} provider The StateProvider instance owning the config.
-     * @param {String} path The full path of the data property (e.g., 'user.firstname').
-     * @param {*} newValue The new value to set.
-     * @param {*} oldVal The old value (optional, used for initial setup).
+     * @param {String}             path     The full path of the data property (e.g., 'user.firstname').
+     * @param {*}                  newValue The new value to set.
+     * @param {*}                 [oldVal]  The old value (optional, used for initial setup).
      * @private
      */
     #setConfigValue(provider, path, newValue, oldVal) {
@@ -629,12 +637,15 @@ class Provider extends Base {
      * are run only once.
      *
      * @param {Object|String} key
-     * @param {*} value
+     * @param {*}             value
      */
     setData(key, value) {
-        EffectBatchManager.startBatch();
-        this.internalSetData(key, value, this);
-        EffectBatchManager.endBatch()
+        EffectManager.pause();
+        try {
+            this.internalSetData(key, value, this)
+        } finally {
+            EffectManager.resume()
+        }
     }
 
     /**
@@ -645,12 +656,15 @@ class Provider extends Base {
      * are run only once.
      *
      * @param {Object|String} key
-     * @param {*} value
+     * @param {*}             value
      */
     setDataAtSameLevel(key, value) {
-        EffectBatchManager.startBatch();
-        this.internalSetData(key, value);
-        EffectBatchManager.endBatch()
+        EffectManager.pause();
+        try {
+            this.internalSetData(key, value)
+        } finally {
+            EffectManager.resume()
+        }
     }
 }
 

package/src/util/VDom.mjs

@@ -391,16 +391,23 @@ class VDom extends Base {
                     vdom.id = vnode.id
                 }
             } else {
-                // we only want to change vdom ids in case there is not already an own id
-                // (think of adding & removing nodes in parallel)
-                if (!vdom.id && vnode.id) {
+                // We only want to add an ID if the vdom node does not already have one.
+                // This preserves developer-provided IDs while allowing the framework
+                // to assign IDs to nodes that need them for reconciliation.
+                // Also think of adding and removing nodes in parallel.
+                if (vnode.id && (!vdom.id || vdom.id.startsWith('neo-vnode-'))) {
                     vdom.id = vnode.id
                 }
             }
 
             if (childNodes) {
                 cn  = childNodes.map(item => VDom.getVdom(item));
-                cn  = cn.filter(item => item.removeDom !== true);
+                // The vnode.childNodes array is already filtered by the worker.
+                // We must filter the component's vdom.cn array identically to ensure
+                // both arrays are structurally aligned for the sync loop.
+                // The boolean check `item &&` is critical to remove falsy values
+                // from conditional rendering and prevent runtime errors.
+                cn  = cn.filter(item => item && item.removeDom !== true);
                 i   = 0;
                 len = cn?.length || 0;