mobx-vue-bridge 1.3.0 → 1.5.0

package/CHANGELOG.md

@@ -5,6 +5,104 @@ 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.5.0] - 2026-01-13
+
+### 🎯 Major Improvements
+
+#### Declarative helper functions for improved readability
+- **Feature**: Extracted bridge logic into self-documenting helper functions in `src/utils/helpers.js`
+- **Structure**: 396 lines of declarative helpers organized by concern:
+  - Value reading & initialization
+  - Property type categorization
+  - Echo loop prevention
+  - Read-only detection
+  - Setter creation (lazy validated, read-only, write-only, two-way binding)
+  - MobX observation helpers
+- **Benefit**: Code now reads like documentation with function names like `guardAgainstEchoLoop`, `createLazyValidatedSetter`, `safelyDisposeSubscription`
+
+#### Improved circular reference handling in equality checks
+- **Feature**: `isEqual()` now uses `Map` instead of `WeakSet` to track visited object pairs
+- **Benefit**: Correctly compares objects where one has circular refs and the other doesn't
+- **Previous bug**: `isEqual(circularObj, nonCircularObj)` incorrectly returned `true`
+- **Fix**: Now tracks `(a, b)` pairs so revisiting `a` checks if it was paired with same `b`
+
+### 🐛 Bug Fixes
+
+#### Fixed deepObserve stale subscription after property reassignment
+- **Issue**: When a property was reassigned to a new object/array, `deepObserve` continued watching the old value
+- **Example**: After `store.items = newArray`, mutations to `newArray` weren't detected
+- **Fix**: Added `onValueChanged` callback to `observeProperty` that re-subscribes `deepObserve` when property value changes
+- **Result**: Nested mutations are now correctly detected even after complete property reassignment
+
+#### Fixed -0 vs +0 edge case in equality comparison
+- **Issue**: `Object.is(-0, +0)` returns `false`, causing unnecessary updates for equivalent values
+- **Fix**: Added explicit number handling that treats `-0` and `+0` as equal while correctly handling `NaN === NaN`
+
+#### Improved warning messages
+- **Change**: Direct mutation warnings now include actionable guidance
+- **Before**: `"Direct mutation of 'name' is disabled"`
+- **After**: `"Direct mutation of 'name' is disabled. Use actions instead."`
+
+### ✅ Testing
+
+- **New test file**: `mobxVueBridgeBugVerification.test.js` - 10 tests verifying bug fixes
+  - Circular reference equality edge cases
+  - DeepObserve re-subscription after reassignment
+  - -0/+0 and NaN handling
+  - Single clone correctness
+  - Sibling nested array mutations
+  - Setter-only properties
+- **New test file**: `mobxVueBridgeCrossClassComputed.test.js` - 3 tests for cross-class dependencies
+  - Computed properties depending on other class's computed properties
+  - Chain of three classes with computed dependencies
+  - Changes detected even when only bridging the dependent class
+
+## [1.4.0] - 2025-11-25
+
+### 🎯 Major Improvements
+
+#### Zero-side-effect initialization with lazy detection
+- **Feature**: Bridge no longer calls any setters during initialization, eliminating all side effects
+- **Benefit**: Fixes production bugs where setter side effects (like `refreshDataOnTabChange()`) were triggered during bridge setup
+- **Mechanism**: Lazy detection pattern - properties are optimistically marked as writable during init, tested on first actual write attempt
+- **Caching**: `readOnlyDetected` Set caches detection results for O(1) lookups on subsequent writes
+- **Impact**: User's `currentRoom` setter with side effects now works correctly - side effects only occur during actual user interactions
+
+#### Modular architecture refactoring
+- **Feature**: Core logic separated into focused utility modules
+- **Structure**: 
+  - `src/utils/memberDetection.js` (210 lines) - MobX member categorization without side effects
+  - `src/utils/equality.js` (47 lines) - Deep equality with circular reference protection
+  - `src/utils/deepProxy.js` (109 lines) - Nested reactivity with microtask batching
+- **Main bridge**: Reduced from 523 lines → 321 lines (39% reduction)
+- **Benefit**: Better maintainability, testability, and code organization
+
+### 🐛 Bug Fixes
+
+#### Fixed computed property detection with MobX synthetic setters
+- **Issue**: MobX adds synthetic setters to computed-only properties that throw "not possible to assign" errors
+- **Previous approach**: Tested setters during initialization (caused side effects)
+- **New approach**: Check descriptor existence only (`descriptor.get && descriptor.set`), test lazily on first write
+- **Detection**: Catch MobX error message during first write attempt, cache as read-only
+- **Result**: Accurate detection without initialization side effects
+
+#### Fixed test equality assertions
+- **Issue**: One test expected reference equality for cloned objects
+- **Fix**: Changed `.toBe()` to `.toStrictEqual()` for deep equality comparison
+- **Context**: Bridge clones objects to prevent reference sharing between Vue and MobX
+
+### ✅ Testing
+
+- **Total tests**: 170 passing (was 168 + 2 skipped)
+- **New active tests**: Unskipped and fixed 2 comprehensive two-way binding demo tests
+- **Coverage**: All patterns verified including lazy detection, nested mutations, and error handling
+
+### 📚 Documentation
+
+- **Architecture notes**: Added inline documentation explaining lazy detection pattern
+- **Comments**: Clear explanation of why setters aren't called during init
+- **Examples**: Test files demonstrate proper usage patterns
+
 ## [1.2.0] - 2025-10-01
 
 ### ✨ New Features

package/README.md

@@ -14,6 +14,8 @@ A seamless bridge between MobX observables and Vue 3's reactivity system, enabli
 - 🔒 **Type-safe bridging** between reactive systems
 - 🚀 **Optimized performance** with intelligent change detection
 - 🛡️ **Error handling** for edge cases and circular references
+- ⚡ **Zero-side-effect initialization** with lazy detection (v1.4.0+)
+- 📦 **Modular architecture** for better maintainability
 
 ## 📦 Installation
 
@@ -296,6 +298,51 @@ presenter.items.push(newItem)
 console.log(presenter.items)  // Immediately updated!
 ```
 
+## 🏗️ Architecture & Implementation
+
+### Modular Design (v1.4.0+)
+
+The bridge uses a clean, modular architecture for better maintainability:
+
+```
+src/
+├── mobxVueBridge.js           # Main bridge (321 lines)
+└── utils/
+    ├── memberDetection.js     # MobX property categorization (210 lines)
+    ├── equality.js            # Deep equality with circular protection (47 lines)
+    └── deepProxy.js           # Nested reactivity with batching (109 lines)
+```
+
+### Zero-Side-Effect Initialization
+
+The bridge uses **lazy detection** to avoid calling setters during initialization:
+
+```javascript
+class GuestPresenter {
+  get currentRoom() {
+    return this.repository.currentRoomId
+  }
+  
+  set currentRoom(val) {
+    this.repository.currentRoomId = val
+    this.refreshDataOnTabChange()  // Side effect!
+  }
+}
+
+// ✅ v1.4.0+: No side effects during bridge creation
+const state = useMobxBridge(presenter)  // refreshDataOnTabChange() NOT called
+
+// ✅ Side effects only happen during actual mutations
+state.currentRoom = 'room-123'  // refreshDataOnTabChange() called here
+```
+
+**How it works:**
+1. **Detection phase**: Checks descriptor existence only (`descriptor.get && descriptor.set`)
+2. **First write**: Tests if setter actually works by attempting the write
+3. **Caching**: Results stored in `readOnlyDetected` Set for O(1) future lookups
+
+This prevents bugs where setter side effects were triggered during bridge setup, while maintaining accurate runtime behavior.
+
 ### Error Handling
 The bridge gracefully handles edge cases:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mobx-vue-bridge",
-  "version": "1.3.0",
+  "version": "1.5.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",