Refactor state.Provider to Support Intuitive Deep-Merging and Runtime Data Creation #7099

Author: tobiu

learn/blog/v10-deep-dive-state-provider.md

@@ -78,6 +78,19 @@ const provider = myComponent.getStateProvider();
 
 // This one line is all it takes to trigger a reactive update.
 provider.data.user.firstname = 'Max';
+
+// Does not overwrite the lastname
+provider.setData({user: {firstname: 'Robert'}})
+
+// You can update multiple properties at once. Thanks to automatic batching,
+// this results in only a single UI update cycle.
+provider.setData({user: {firstname: 'John', lastname: 'Doe'}})
+
+// Alternative Syntax:
+provider.setData({
+    'user.firstname': 'John',
+    'user.lastname' : 'Doe'
+});
 ```
 
 There are no special setter functions to call, no reducers to write. You just change the data, and the UI updates.
@@ -98,7 +111,8 @@ The beautiful API above is powered by a sophisticated proxy created by `Neo.stat
 When you interact with `provider.data`, you're not touching a plain object; you're interacting with an intelligent agent
 that works with Neo's `EffectManager`.
 
-You can see the full implementation in [state/createHierarchicalDataProxy.mjs](../../src/state/createHierarchicalDataProxy.mjs)
+You can see the full implementation in
+**[src/state/createHierarchicalDataProxy.mjs](../../src/state/createHierarchicalDataProxy.mjs)**.
 
 Here’s how it works:
 
@@ -154,7 +168,7 @@ t.it('State Provider should trigger parent effects when a leaf node changes (bub
     t.is(effectRunCount, 2, 'Effect should re-run after changing a leaf property');
 });
 ```
-This behavior is made possible by the `internalSetData` method in [state/Provider.mjs](../../src/state/Provider.mjs).
+This behavior is made possible by the `internalSetData` method in **[state/Provider.mjs](../../src/state/Provider.mjs)**.
 When you set `'user.age'`, the provider doesn't just update that one value. It then "bubbles up," creating a new `user`
 object reference that incorporates the change: `{...oldUser, age: 31}`. This new object reference is what the reactivity
 system detects, ensuring that any component bound to `user` updates correctly.

src/state/Provider.mjs

@@ -474,24 +474,24 @@ 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)
             });
             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);
@@ -522,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
             }
         }
     }
@@ -586,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);
@@ -602,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) {
@@ -633,7 +637,7 @@ class Provider extends Base {
      * are run only once.
      *
      * @param {Object|String} key
-     * @param {*} value
+     * @param {*}             value
      */
     setData(key, value) {
         EffectManager.pause();
@@ -652,7 +656,7 @@ class Provider extends Base {
      * are run only once.
      *
      * @param {Object|String} key
-     * @param {*} value
+     * @param {*}             value
      */
     setDataAtSameLevel(key, value) {
         EffectManager.pause();

test/siesta/tests/state/ProviderNestedDataConfigs.mjs

@@ -69,6 +69,65 @@ StartTest(t => {
         component.destroy();
     });
 
+    t.it('setData with a nested object should deep-merge and bubble reactivity', t => {
+        const component = Neo.create(MockComponent, {
+            stateProvider: {
+                data: {
+                    user: {
+                        firstname: 'John',
+                        lastname : 'Doe'
+                    }
+                }
+            }
+        });
+
+        const provider = component.getStateProvider();
+        let effectRunCount = 0;
+
+        provider.createBinding(component.id, 'user', data => {
+            effectRunCount++;
+            return data.user;
+        });
+
+        t.is(effectRunCount, 1, 'Effect ran initially');
+        t.isDeeply(proxyToObject(component.user), { firstname: 'John', lastname: 'Doe' }, 'Initial user object is correct');
+
+        // ACTION: Set data with a nested object. This should MERGE, not replace.
+        provider.setData({
+            user: { firstname: 'Jane' }
+        });
+
+        // ASSERT: The object was merged, and the old 'lastname' property is preserved.
+        t.is(effectRunCount, 2, 'Effect re-ran after setting the branch node');
+
+        const updatedUser = proxyToObject(component.user);
+        t.isDeeply(updatedUser, { firstname: 'Jane', lastname: 'Doe' }, 'User object should be deep-merged');
+        t.is(updatedUser.lastname, 'Doe', 'The "lastname" property should be preserved after merge');
+
+        // For contrast, let's show the path-based "bubbling" behavior which has the same outcome.
+        // First, reset the state.
+        provider.setData({
+            user: {
+                firstname: 'John',
+                lastname: 'Doe'
+            }
+        });
+        t.is(effectRunCount, 3, 'Effect ran after resetting state');
+
+        // ACTION: Set a leaf node using a path string.
+        provider.setData({
+            'user.firstname': 'Robert'
+        });
+
+        // ASSERT: The object was updated via bubbling, preserving the 'lastname' property.
+        t.is(effectRunCount, 4, 'Effect re-ran after setting a leaf node via path');
+        const mergedUser = proxyToObject(component.user);
+        t.isDeeply(mergedUser, { firstname: 'Robert', lastname: 'Doe' }, 'Path-based set should merge/preserve other properties');
+        t.is(mergedUser.lastname, 'Doe', 'The "lastname" property should be preserved');
+
+        component.destroy();
+    });
+
     t.it('Formulas should react to leaf node changes via bubbling', t => {
         let effectRunCount = 0;