mobx-vue-bridge 1.1.0 → 1.3.0

package/CHANGELOG.md

@@ -5,10 +5,31 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [1.1.0] - 2025-10-01
+## [1.2.0] - 2025-10-01
+
+### ✨ New Features
+
+#### Batched nested mutations for array correctness
+- **Feature**: Nested mutations are now batched via `queueMicrotask()` to prevent array corruption
+- **Benefit**: All array operations (`shift()`, `unshift()`, `splice()`, etc.) now work correctly without data corruption
+- **Trade-off**: Nested mutations are async (microtask delay). Use `await nextTick()` for immediate reads in same function
+- **Best Practice**: Keep logic in MobX Presenter = always synchronous, no `nextTick()` needed
+- **Documentation**: Comprehensive guide in README.md with examples and patterns
+- **Tests**: 7 new tests in `mobxVueBridgeArrayCorrectness.test.js` verifying correctness
+- **Total Test Count**: 148 tests passing (141 original + 7 new)
 
 ### 🐛 Bug Fixes
 
+#### Fixed array mutation corruption
+- **Issue**: Array methods like `shift()`, `unshift()`, and `splice()` were corrupting arrays during nested mutations. For example, `shift()` on `[1,2,3]` would produce `[2,2,3]` instead of `[2,3]`
+- **Root Cause**: Each index assignment during array operations triggered an immediate `clone()` + sync, interrupting the in-progress array method
+- **Impact**: Array mutations through nested proxies produced incorrect results, breaking data integrity
+- **Fix**: Implemented `queueMicrotask()` batching in `createDeepProxy` to defer updates until array operations complete. Uses `updatePending` flag to batch multiple mutations into a single update
+- **Location**: Line ~230-270 in `createDeepProxy` function
+- **Result**: All array methods now work correctly without corruption
+
+## [1.1.0] - 2025-10-01
+
 #### Fixed `updatingFromVue` guard implementation
 - **Issue**: The `updatingFromVue` Set was declared but never populated, making it a dead guard that didn't prevent potential echo loops
 - **Impact**: Potential for echo loops in edge cases with custom objects or special equality scenarios
@@ -39,11 +60,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### ✅ Testing
 - Added 14 new tests (7 for validation, 7 for circular references)
-- All 134 tests passing (120 original + 14 new)
+- Updated existing tests to handle async nested mutations with `nextTick()`
+- All 141 tests passing (127 original + 14 new)
 - No breaking changes to public API
 - Backward compatible with existing code
 
 ### 📝 Documentation
+- Updated README with async behavior notes for nested mutations
+- Added example showing `nextTick()` usage for immediate value access
 - Updated inline code comments for clarity
 - Added JSDoc comments for better IDE integration
 

package/README.md

@@ -215,6 +215,33 @@ const state = useMobxBridge(appStore)
 
 ## 🔧 Advanced Features
 
+### Configuration Options
+
+The bridge accepts an optional configuration object to customize its behavior:
+
+```javascript
+const state = useMobxBridge(mobxObject, {
+  allowDirectMutation: true  // default: true
+})
+```
+
+#### `allowDirectMutation` (boolean)
+Controls whether direct mutations are allowed on the Vue state:
+- `true` (default): Allows `state.name = 'New Name'`
+- `false`: Mutations must go through MobX actions
+
+```javascript
+// Allow direct mutations (default)
+const state = useMobxBridge(presenter, { allowDirectMutation: true })
+state.name = 'John' // ✅ Works
+
+// Disable direct mutations (action-only mode)
+const state = useMobxBridge(presenter, { allowDirectMutation: false })
+state.name = 'John' // ❌ Warning: use actions instead
+presenter.setName('John') // ✅ Works
+```
+- ✅ You can use `await nextTick()` when needed for immediate reads
+
 ### Deep Reactivity
 The bridge automatically handles deep changes in objects and arrays:
 
@@ -225,6 +252,50 @@ state.todos.push(newTodo)             // Array mutation
 state.settings.colors[0] = '#FF0000'  // Nested array mutation
 ```
 
+**Note on Async Behavior:** Nested mutations (via the deep proxy) are batched using `queueMicrotask()` to prevent corruption during array operations like `shift()`, `unshift()`, and `splice()`. This ensures data correctness. If you need immediate access to updated values after nested mutations in the same function, use Vue's `nextTick()`:
+
+```javascript
+import { nextTick } from 'vue'
+
+state.items.push(newItem)
+await nextTick()  // Wait for batched update to complete
+console.log(state.items)  // Now updated
+```
+
+**However, Vue templates, computed properties, and watchers work automatically without `nextTick()`:**
+
+```vue
+<template>
+  <!-- Auto-updates, no nextTick needed -->
+  <div>{{ state.items.length }}</div>
+</template>
+
+<script setup>
+// Computed auto-updates, no nextTick needed
+const itemCount = computed(() => state.items.length)
+
+// Watcher auto-fires, no nextTick needed
+watch(() => state.items, (newItems) => {
+  console.log('Items changed:', newItems)
+})
+</script>
+```
+
+Top-level property assignments are synchronous:
+```javascript
+state.count = 42           // Immediate (sync)
+state.items = [1, 2, 3]    // Immediate (sync)
+state.items.push(4)        // Batched (async - requires nextTick for immediate read)
+```
+
+**Best Practice:** Keep business logic in your MobX Presenter. When you mutate via the Presenter, everything is synchronous:
+
+```javascript
+// ✅ Presenter pattern - always synchronous, no nextTick needed
+presenter.items.push(newItem)
+console.log(presenter.items)  // Immediately updated!
+```
+
 ### Error Handling
 The bridge gracefully handles edge cases:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mobx-vue-bridge",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "A lightweight bridge for seamless two-way data binding between MobX observables and Vue 3 reactivity",
   "main": "src/mobxVueBridge.js",
   "module": "src/mobxVueBridge.js",
@@ -22,7 +22,11 @@
     "test": "vitest",
     "test:watch": "vitest --watch",
     "test:coverage": "vitest --coverage",
-    "prepublishOnly": "npm test && node scripts/pre-publish.js",
+    "test:run": "vitest --run",
+    "lint": "echo 'No linter configured yet. Consider adding ESLint.'",
+    "format": "echo 'No formatter configured yet. Consider adding Prettier.'",
+    "validate": "npm run test:run",
+    "prepublishOnly": "npm run validate && node scripts/pre-publish.js",
     "publish:dry": "npm publish --dry-run"
   },
   "repository": {
@@ -47,6 +51,10 @@
     "url": "https://github.com/visaruruqi/mobx-vue-bridge/issues"
   },
   "homepage": "https://github.com/visaruruqi/mobx-vue-bridge#readme",
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/visaruruqi"
+  },
   "peerDependencies": {
     "vue": "^3.0.0",
     "mobx": "^6.0.0"

package/src/mobxVueBridge.js

@@ -6,10 +6,34 @@ import clone from 'clone';
 /**
  * 🌉 MobX-Vue Bridge
  * 
- * @param {object} mobxObject - The MobX observable object to bridge
+ * Creates a bidirectional bridge between MobX observables and Vue 3 reactivity.
+ * Automatically synchronizes changes in both directions while preventing infinite loops.
+ * 
+ * @param {object} mobxObject - The MobX observable object to bridge (created with makeAutoObservable)
  * @param {object} options - Configuration options
- * @param {boolean} options.allowDirectMutation - Whether to allow direct mutation of properties
- * @returns {object} Vue reactive state object
+ * @param {boolean} options.allowDirectMutation - Whether to allow direct mutation of properties (default: true)
+ * @returns {object} Vue reactive state object with synchronized properties, getters, setters, and methods
+ * 
+ * @example
+ * ```javascript
+ * import { useMobxBridge } from 'mobx-vue-bridge'
+ * import { makeAutoObservable } from 'mobx'
+ * 
+ * class UserStore {
+ *   constructor() {
+ *     this.name = 'John'
+ *     this.age = 30
+ *     makeAutoObservable(this)
+ *   }
+ *   
+ *   get displayName() {
+ *     return `${this.name} (${this.age})`
+ *   }
+ * }
+ * 
+ * const store = new UserStore()
+ * const state = useMobxBridge(store)
+ * ```
  */
 export function useMobxBridge(mobxObject, options = {}) {
   // Validate mobxObject parameter
@@ -22,6 +46,7 @@ export function useMobxBridge(mobxObject, options = {}) {
   const allowDirectMutation = safeOptions.allowDirectMutation !== undefined 
     ? Boolean(safeOptions.allowDirectMutation) 
     : true; // Keep the original default of true
+  
   const vueState = reactive({});
 
   // Discover props/methods via MobX introspection (don’t rely on raw descriptors)
@@ -132,6 +157,15 @@ export function useMobxBridge(mobxObject, options = {}) {
   const updatingFromMobx = new Set();
   const updatingFromVue = new Set();
 
+  /**
+   * Deep equality comparison with circular reference protection.
+   * Uses WeakSet to track visited objects and prevent infinite recursion.
+   * 
+   * @param {any} a - First value to compare
+   * @param {any} b - Second value to compare  
+   * @param {WeakSet} visited - Set of visited objects to prevent circular references
+   * @returns {boolean} True if values are deeply equal
+   */
   const isEqual = (a, b, visited = new WeakSet()) => {
     if (Object.is(a, b)) return true;
     
@@ -171,13 +205,38 @@ export function useMobxBridge(mobxObject, options = {}) {
   const warnSetterMutation = (prop) => console.warn(`Direct mutation of setter '${prop}' is disabled`);
   const warnMethodAssignment = (prop) => console.warn(`Cannot assign to method '${prop}'`);
 
-  // Helper to create deep proxies for nested objects and arrays
-  const createDeepProxy = (value, prop) => {
+  /**
+   * Creates a deep proxy for nested objects/arrays to handle mutations at any level.
+   * This enables mutations like state.items.push(item) to work correctly.
+   * Respects the allowDirectMutation configuration for all nesting levels.
+   * 
+   * Note: Mutations are batched via queueMicrotask to prevent corruption during 
+   * array operations like shift(), unshift(), splice() which modify multiple indices.
+   * This ensures data correctness at the cost of a microtask delay.
+   * 
+   * IMPORTANT: The proxy wraps the value stored in propertyRefs[prop].value, which is
+   * a clone. When nested mutations occur, we update the clone in-place, then trigger
+   * a sync back to MobX by re-assigning the entire cloned structure.
+   * 
+   * @param {object|array} value - The nested value to wrap in a proxy
+   * @param {string} prop - The parent property name for error messages and sync
+   * @param {function} getRoot - Function that returns the current root value from propertyRef
+   * @returns {Proxy} Proxied object/array with reactive mutation handling
+   */
+  const createDeepProxy = (value, prop, getRoot = null) => {
     // Don't proxy built-in objects that should remain unchanged
     if (value instanceof Date || value instanceof RegExp || value instanceof Map || 
         value instanceof Set || value instanceof WeakMap || value instanceof WeakSet) {
       return value;
     }
+
+    // If no getRoot provided, use the default which gets from propertyRefs
+    if (!getRoot) {
+      getRoot = () => propertyRefs[prop].value;
+    }
+
+    // Track pending updates to batch array mutations
+    let updatePending = false;
     
     return new Proxy(value, {
       get: (target, key) => {
@@ -186,7 +245,7 @@ export function useMobxBridge(mobxObject, options = {}) {
         if (result && typeof result === 'object' && 
             !(result instanceof Date || result instanceof RegExp || result instanceof Map || 
               result instanceof Set || result instanceof WeakMap || result instanceof WeakSet)) {
-          return createDeepProxy(result, prop);
+          return createDeepProxy(result, prop, getRoot);
         }
         return result;
       },
@@ -194,19 +253,39 @@ export function useMobxBridge(mobxObject, options = {}) {
         // Check if direct mutation is allowed
         if (!allowDirectMutation) {
           warnDirectMutation(`${prop}.${String(key)}`);
-          return false;
+          return true; // Must return true to avoid TypeError in strict mode
         }
         
+        // Update the target in-place (this modifies the clone in propertyRefs[prop].value)
         target[key] = val;
-        // Update the Vue ref to trigger reactivity
-        propertyRefs[prop].value = clone(propertyRefs[prop].value);
-        // Update MobX immediately
-        updatingFromVue.add(prop);
-        try {
-          mobxObject[prop] = clone(propertyRefs[prop].value);
-        } finally {
-          updatingFromVue.delete(prop);
+        
+        // Batch updates to avoid corrupting in-progress array operations
+        // like shift(), unshift(), splice() which modify multiple indices synchronously
+        if (!updatePending) {
+          updatePending = true;
+          queueMicrotask(() => {
+            updatePending = false;
+            // The root value has already been modified in-place above (target[key] = val)
+            // Now we need to trigger Vue reactivity and sync to MobX
+            
+            // Clone the root to create a new reference for Vue reactivity
+            // This ensures Vue detects the change
+            const rootValue = getRoot();
+            const cloned = clone(rootValue);
+            
+            // Update the Vue ref to trigger reactivity
+            propertyRefs[prop].value = cloned;
+            
+            // Update MobX immediately with the cloned value
+            updatingFromVue.add(prop);
+            try {
+              mobxObject[prop] = cloned;
+            } finally {
+              updatingFromVue.delete(prop);
+            }
+          });
         }
+        
         return true;
       }
     });