mobx-vue-bridge 1.4.0 → 1.5.0

package/CHANGELOG.md

@@ -5,6 +5,58 @@ 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

package/package.json

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

package/src/mobxVueBridge.js

@@ -5,6 +5,23 @@ import clone from 'clone';
 import { categorizeMobxMembers } from './utils/memberDetection.js';
 import { isEqual } from './utils/equality.js';
 import { createDeepProxy } from './utils/deepProxy.js';
+import {
+  safelyReadInitialValue,
+  createReactiveRef,
+  separateGetterSetterPairs,
+  findGettersOnly,
+  findSettersOnly,
+  defineReactiveProperty,
+  createLazyValidatedSetter,
+  createReadOnlySetter,
+  createWriteOnlySetter,
+  createTwoWayBindingSetter,
+  isCurrentlyUpdating,
+  observeProperty,
+  deepObserveProperty,
+  observeGetter,
+  safelyDisposeSubscription,
+} from './utils/helpers.js';
 
 /**
  * 🌉 MobX-Vue Bridge
@@ -60,267 +77,185 @@ export function useMobxBridge(mobxObject, options = {}) {
   const updatingFromVue = new Set();
 
   // Warning helpers to reduce duplication
-  const warnDirectMutation = (prop) => console.warn(`Direct mutation of '${prop}' is disabled`);
-  const warnSetterMutation = (prop) => console.warn(`Direct mutation of setter '${prop}' is disabled`);
   const warnMethodAssignment = (prop) => console.warn(`Cannot assign to method '${prop}'`);
 
-  // ---- properties (two-way) -------------------------------------------------
+  // ---- Bridge observable properties (two-way binding) ----
   const propertyRefs = {};
   
-  members.properties.forEach(prop => {
-    propertyRefs[prop] = ref(toJS(mobxObject[prop]));
+  const bridgeObservableProperty = (propertyName) => {
+    propertyRefs[propertyName] = createReactiveRef(toJS(mobxObject[propertyName]));
 
-    Object.defineProperty(vueState, prop, {
-      get: () => {
-        const value = propertyRefs[prop].value;
-        // For objects/arrays, return a deep proxy that syncs mutations back
-        if (value && typeof value === 'object') {
-          return createDeepProxy(
-            value, 
-            prop, 
-            () => propertyRefs[prop].value,
-            allowDirectMutation,
-            updatingFromVue,
-            mobxObject,
-            propertyRefs
-          );
-        }
-        return value;
-      },
-      set: allowDirectMutation
-        ? (value) => {
-            // Update Vue ref
-            const cloned = clone(value);
-            if (!isEqual(propertyRefs[prop].value, cloned)) {
-              propertyRefs[prop].value = cloned;
-            }
-            // ALSO update MobX immediately (synchronous)
-            if (!isEqual(mobxObject[prop], cloned)) {
-              updatingFromVue.add(prop);
-              try {
-                mobxObject[prop] = cloned;
-              } finally {
-                updatingFromVue.delete(prop);
-              }
-            }
-          }
-        : () => warnDirectMutation(prop),
-      enumerable: true,
-      configurable: true,
+    const createDeepProxyForValue = (value) => {
+      if (value && typeof value === 'object') {
+        return createDeepProxy(
+          value, 
+          propertyName, 
+          () => propertyRefs[propertyName].value,
+          allowDirectMutation,
+          updatingFromVue,
+          mobxObject,
+          propertyRefs
+        );
+      }
+      return value;
+    };
+
+    defineReactiveProperty(vueState, propertyName, {
+      get: () => createDeepProxyForValue(propertyRefs[propertyName].value),
+      set: createTwoWayBindingSetter({
+        propertyName,
+        target: mobxObject,
+        allowDirectMutation,
+        guardSet: updatingFromVue,
+        propertyRef: propertyRefs[propertyName],
+        // No deepProxyCreator needed - createTwoWayBindingSetter already clones the value
+      }),
     });
+  };
 
-  });
+  members.properties.forEach(bridgeObservableProperty);
 
   // ---- getters and setters (handle both computed and two-way binding) ------
   const getterRefs = {};
   const setterRefs = {};
   const readOnlyDetected = new Set(); // Track properties detected as read-only on first write
 
-  // First, handle properties that have BOTH getters and setters (getter/setter pairs)
-  const getterSetterPairs = members.getters.filter(prop => members.setters.includes(prop));
-  const gettersOnly = members.getters.filter(prop => !members.setters.includes(prop));
-  const settersOnly = members.setters.filter(prop => !members.getters.includes(prop));
+  // Categorize properties by their getter/setter combinations
+  const getterSetterPairs = separateGetterSetterPairs(members.getters, members.setters);
+  const gettersOnly = findGettersOnly(members.getters, members.setters);
+  const settersOnly = findSettersOnly(members.setters, members.getters);
 
-  // Getter/setter pairs: potentially writable with reactive updates
+  // ---- Bridge getter/setter pairs (potentially writable computed properties) ----
   // Note: Some may have MobX synthetic setters that throw - we detect this lazily on first write
-  getterSetterPairs.forEach(prop => {
-    // Get initial value from getter
-    let initialValue;
-    try {
-      initialValue = toJS(mobxObject[prop]);
-    } catch (error) {
-      initialValue = undefined;
-    }
-    getterRefs[prop] = ref(initialValue);
+  const bridgeGetterSetterPair = (propertyName) => {
+    const initialValue = safelyReadInitialValue(mobxObject, propertyName);
+    getterRefs[propertyName] = createReactiveRef(initialValue);
 
-    Object.defineProperty(vueState, prop, {
-      // ALWAYS read from MobX so computed properties work correctly
-      get: () => getterRefs[prop].value,
-      set: allowDirectMutation
-        ? (value) => {
-            // Check if we've already detected this as read-only
-            if (readOnlyDetected.has(prop)) {
-              throw new Error(`Cannot assign to computed property '${prop}'`);
-            }
-            
-            // Try to call the MobX setter (first write test)
-            updatingFromVue.add(prop);
-            try {
-              mobxObject[prop] = value;
-              // The getter ref will be updated by the reaction
-            } catch (error) {
-              // Check if it's a MobX "not possible to assign" error (synthetic setter)
-              if (error.message && error.message.includes('not possible to assign')) {
-                // Mark as read-only so we don't try again
-                readOnlyDetected.add(prop);
-                // This is actually a read-only computed property
-                throw new Error(`Cannot assign to computed property '${prop}'`);
-              }
-              // For other errors (validation, side effects), just warn
-              console.warn(`Failed to set property '${prop}':`, error);
-            } finally {
-              updatingFromVue.delete(prop);
-            }
-          }
-        : () => warnDirectMutation(prop),
-      enumerable: true,
-      configurable: true,
+    defineReactiveProperty(vueState, propertyName, {
+      get: () => getterRefs[propertyName].value,
+      set: createLazyValidatedSetter({
+        propertyName,
+        target: mobxObject,
+        allowDirectMutation,
+        readOnlySet: readOnlyDetected,
+        guardSet: updatingFromVue,
+      }),
     });
-  });
+  };
+
+  getterSetterPairs.forEach(bridgeGetterSetterPair);
 
-  // Getter-only properties: read-only computed
-  gettersOnly.forEach(prop => {
-    // Safely get initial value of computed property, handle errors gracefully
-    let initialValue;
-    try {
-      initialValue = toJS(mobxObject[prop]);
-    } catch (error) {
-      // If computed property throws during initialization (e.g., accessing null.property),
-      // set initial value to undefined and let the reaction handle updates later
-      initialValue = undefined;
-    }
-    getterRefs[prop] = ref(initialValue);
+  // ---- Bridge getter-only properties (read-only computed) ----
+  const bridgeGetterOnly = (propertyName) => {
+    const initialValue = safelyReadInitialValue(mobxObject, propertyName);
+    getterRefs[propertyName] = createReactiveRef(initialValue);
 
-    Object.defineProperty(vueState, prop, {
-      get: () => getterRefs[prop].value,
-      set: () => {
-        throw new Error(`Cannot assign to computed property '${prop}'`)
-      },
-      enumerable: true,
-      configurable: true,
+    defineReactiveProperty(vueState, propertyName, {
+      get: () => getterRefs[propertyName].value,
+      set: createReadOnlySetter(propertyName),
     });
-  });
+  };
+
+  gettersOnly.forEach(bridgeGetterOnly);
 
-  // Setter-only properties: write-only
-  settersOnly.forEach(prop => {
-    // For setter-only properties, track the last set value
-    setterRefs[prop] = ref(undefined);
+  // ---- Bridge setter-only properties (write-only) ----
+  const bridgeSetterOnly = (propertyName) => {
+    setterRefs[propertyName] = createReactiveRef(undefined);
 
-    Object.defineProperty(vueState, prop, {
-      get: () => setterRefs[prop].value,
-      set: allowDirectMutation
-        ? (value) => {
-            // Update the setter ref
-            setterRefs[prop].value = value;
-            
-            // Call the MobX setter immediately
-            updatingFromVue.add(prop);
-            try {
-              mobxObject[prop] = value;
-            } catch (error) {
-              console.warn(`Failed to set property '${prop}':`, error);
-            } finally {
-              updatingFromVue.delete(prop);
-            }
-          }
-        : () => warnSetterMutation(prop),
-      enumerable: true,
-      configurable: true,
+    defineReactiveProperty(vueState, propertyName, {
+      get: () => setterRefs[propertyName].value,
+      set: createWriteOnlySetter({
+        propertyName,
+        target: mobxObject,
+        allowDirectMutation,
+        guardSet: updatingFromVue,
+        setterRef: setterRefs[propertyName],
+      }),
     });
-  });
+  };
+
+  settersOnly.forEach(bridgeSetterOnly);
 
-  // ---- methods (bound) ------------------------------------------------------
-  members.methods.forEach(prop => {
+  // ---- Bridge methods (bound to MobX context) ----
+  const bridgeMethod = (methodName) => {
     // Cache the bound method to avoid creating new functions on every access
-    const boundMethod = mobxObject[prop].bind(mobxObject);
-    Object.defineProperty(vueState, prop, {
+    const boundMethod = mobxObject[methodName].bind(mobxObject);
+    
+    defineReactiveProperty(vueState, methodName, {
       get: () => boundMethod,
-      set: () => warnMethodAssignment(prop),
-      enumerable: true,
-      configurable: true,
+      set: () => warnMethodAssignment(methodName),
     });
-  });
+  };
+
+  members.methods.forEach(bridgeMethod);
 
   // ---- MobX → Vue: property observation ----------------------------------------
   const subscriptions = [];
+  const deepObserveSubscriptions = {}; // Track deep observe subs per property for re-subscription
 
-  setupStandardPropertyObservers();
+  setupPropertyObservation();
+  setupGetterObservation();
 
-  // Standard property observation implementation
-  function setupStandardPropertyObservers() {
-    // Use individual observe for each property to avoid circular reference issues
-    members.properties.forEach(prop => {
-      try {
-        const sub = observe(mobxObject, prop, (change) => {
-          if (!propertyRefs[prop]) return;
-          if (updatingFromVue.has(prop)) return; // avoid echo
-          updatingFromMobx.add(prop);
-          try {
-            const next = toJS(mobxObject[prop]);
-            if (!isEqual(propertyRefs[prop].value, next)) {
-              propertyRefs[prop].value = next;
-            }
-          } finally {
-            updatingFromMobx.delete(prop);
-          }
-        });
-        subscriptions.push(sub);
-      } catch (error) {
-        // Silently ignore non-observable properties
-      }
-    });
+  // Observe observable properties for MobX → Vue sync
+  function setupPropertyObservation() {
+    members.properties.forEach(propertyName => {
+      // Helper to setup/re-setup deep observation for a value
+      const setupDeepObserve = (value) => {
+        // Dispose existing deep observe subscription if any
+        if (deepObserveSubscriptions[propertyName]) {
+          safelyDisposeSubscription(deepObserveSubscriptions[propertyName]);
+          deepObserveSubscriptions[propertyName] = null;
+        }
+        
+        // Only deep observe objects and arrays
+        if (!value || typeof value !== 'object') {
+          return;
+        }
 
-    // For nested objects and arrays, use deepObserve to handle deep changes
-    // This handles both object properties and array mutations
-    members.properties.forEach(prop => {
-      const value = mobxObject[prop];
-      if (value && typeof value === 'object') { // Include both objects AND arrays
-        try {
-          const sub = deepObserve(value, (change, path) => {
-            if (!propertyRefs[prop]) return;
-            if (updatingFromVue.has(prop)) return; // avoid echo
-            updatingFromMobx.add(prop);
-            try {
-              const next = toJS(mobxObject[prop]);
-              if (!isEqual(propertyRefs[prop].value, next)) {
-                propertyRefs[prop].value = next;
-              }
-            } finally {
-              updatingFromMobx.delete(prop);
-            }
-          });
-          subscriptions.push(sub);
-        } catch (error) {
-          // Silently ignore if deepObserve fails (e.g., circular references in nested objects)
+        const deepObserveSub = deepObserveProperty({
+          target: mobxObject,
+          propertyName,
+          refToUpdate: propertyRefs[propertyName],
+          echoGuard: updatingFromVue,
+          updateGuard: updatingFromMobx,
+        });
+        if (deepObserveSub) {
+          deepObserveSubscriptions[propertyName] = deepObserveSub;
+          subscriptions.push(deepObserveSub);
         }
-      }
+      };
+
+      // Observe direct property changes
+      const observeSub = observeProperty({
+        target: mobxObject,
+        propertyName,
+        refToUpdate: propertyRefs[propertyName],
+        echoGuard: updatingFromVue,
+        updateGuard: updatingFromMobx,
+        onValueChanged: setupDeepObserve, // Re-subscribe deepObserve when value changes
+      });
+      if (observeSub) subscriptions.push(observeSub);
+
+      // Initial deep observe setup
+      setupDeepObserve(mobxObject[propertyName]);
     });
   }
 
-  // Getters: keep them in sync via reaction (both getter-only and getter/setter pairs)
-  [...gettersOnly, ...getterSetterPairs].forEach(prop => {
-    const sub = reaction(
-      () => {
-        try {
-          return toJS(mobxObject[prop]);
-        } catch (error) {
-          // If computed property throws (e.g., accessing null.property), return undefined
-          return undefined;
-        }
-      },
-      (next) => {
-        if (!getterRefs[prop]) return;
-        if (!isEqual(getterRefs[prop].value, next)) {
-          getterRefs[prop].value = next;
-        }
-      }
-    );
-    subscriptions.push(sub);
-  });
+  // Observe computed properties (getters) for MobX → Vue sync
+  function setupGetterObservation() {
+    [...gettersOnly, ...getterSetterPairs].forEach(propertyName => {
+      const reactionSub = observeGetter({
+        target: mobxObject,
+        propertyName,
+        refToUpdate: getterRefs[propertyName],
+      });
+      subscriptions.push(reactionSub);
+    });
+  }
 
-  // Cleanup
+  // Cleanup subscriptions when component unmounts
   onUnmounted(() => {
-    subscriptions.forEach(unsub => {
-      try {
-        if (typeof unsub === 'function') {
-          unsub();
-        } else if (typeof unsub?.dispose === 'function') {
-          unsub.dispose();
-        }
-      } catch (error) {
-        // Silently handle cleanup errors
-      }
-    });
+    subscriptions.forEach(safelyDisposeSubscription);
   });
 
   return vueState;

package/src/utils/equality.js

@@ -1,30 +1,42 @@
 /**
  * Deep equality comparison with circular reference protection.
  * 
- * Uses WeakSet to track visited objects and prevent infinite recursion.
+ * Uses a Map to track visited object pairs and prevent infinite recursion.
  * This is used to prevent unnecessary updates when values haven't actually changed.
  * 
  * @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
+ * @param {Map} visited - Map of visited object pairs to prevent circular references
  * @returns {boolean} True if values are deeply equal
  */
-export function isEqual(a, b, visited = new WeakSet()) {
+export function isEqual(a, b, visited = new Map()) {
+  // Handle null/undefined cases first
+  if (a == null || b == null) return a === b;
+  
+  // Handle -0 vs +0 edge case (Object.is treats them as different)
+  if (typeof a === 'number' && typeof b === 'number') {
+    // Both are numbers - use === which treats -0 and +0 as equal
+    // Special case for NaN: NaN === NaN is false, but we want true
+    if (Number.isNaN(a) && Number.isNaN(b)) return true;
+    return a === b;
+  }
+  
   // Same reference or primitive equality
   if (Object.is(a, b)) return true;
   
-  // Handle null/undefined cases
-  if (a == null || b == null) return a === b;
-  
   // Different types are not equal
   if (typeof a !== typeof b) return false;
   
   // For primitives, Object.is should have caught them
   if (typeof a !== 'object') return false;
   
-  // Check for circular references
-  if (visited.has(a)) return true;
-  visited.add(a);
+  // Check for circular references - we need to track PAIRS of (a, b)
+  // Using a Map where keys are objects from 'a' and values are objects from 'b'
+  if (visited.has(a)) {
+    // We've seen 'a' before - check if it was paired with the same 'b'
+    return visited.get(a) === b;
+  }
+  visited.set(a, b);
   
   // Fast array comparison
   if (Array.isArray(a) && Array.isArray(b)) {
@@ -32,6 +44,9 @@ export function isEqual(a, b, visited = new WeakSet()) {
     return a.every((val, i) => isEqual(val, b[i], visited));
   }
   
+  // One is array, one is not
+  if (Array.isArray(a) !== Array.isArray(b)) return false;
+  
   // Fast object comparison - check keys first
   const aKeys = Object.keys(a);
   const bKeys = Object.keys(b);
@@ -43,3 +58,4 @@ export function isEqual(a, b, visited = new WeakSet()) {
   // Check values (recursive)
   return aKeys.every(key => isEqual(a[key], b[key], visited));
 }
+

package/src/utils/helpers.js

@@ -0,0 +1,395 @@
+import { ref } from 'vue';
+import { toJS, observe, reaction } from 'mobx';
+import { deepObserve } from 'mobx-utils';
+import clone from 'clone';
+import { isEqual } from './equality.js';
+
+/**
+ * Declarative helper functions for the MobX-Vue bridge.
+ * These functions use human-oriented language to make the code self-documenting.
+ */
+
+// ============================================================================
+// VALUE READING & INITIALIZATION
+// ============================================================================
+
+/**
+ * Safely reads the initial value of a property, returning undefined if it throws.
+ */
+export const safelyReadInitialValue = (object, propertyName) => {
+  try {
+    return toJS(object[propertyName]);
+  } catch {
+    return undefined;
+  }
+};
+
+/**
+ * Creates a Vue reactive reference with an initial value.
+ */
+export const createReactiveRef = (initialValue) => ref(initialValue);
+
+// ============================================================================
+// PROPERTY TYPE CATEGORIZATION
+// ============================================================================
+
+/**
+ * Separates properties that have both getters and setters.
+ */
+export const separateGetterSetterPairs = (getters, setters) => 
+  getters.filter(prop => setters.includes(prop));
+
+/**
+ * Finds getters that don't have corresponding setters (read-only computed).
+ */
+export const findGettersOnly = (getters, setters) => 
+  getters.filter(prop => !setters.includes(prop));
+
+/**
+ * Finds setters that don't have corresponding getters (write-only).
+ */
+export const findSettersOnly = (setters, getters) => 
+  setters.filter(prop => !getters.includes(prop));
+
+// ============================================================================
+// ECHO LOOP PREVENTION
+// ============================================================================
+
+/**
+ * Executes an operation while preventing echo loops between Vue and MobX.
+ * Uses a guard set to track when Vue is updating MobX.
+ */
+export const guardAgainstEchoLoop = (propertyName, guardSet, operation) => {
+  guardSet.add(propertyName);
+  try {
+    operation();
+  } finally {
+    guardSet.delete(propertyName);
+  }
+};
+
+/**
+ * Checks if a property is currently being updated (to prevent echo loops).
+ */
+export const isCurrentlyUpdating = (propertyName, guardSet) => 
+  guardSet.has(propertyName);
+
+// ============================================================================
+// READ-ONLY DETECTION
+// ============================================================================
+
+/**
+ * Checks if a property has been detected as read-only.
+ */
+export const isKnownReadOnly = (propertyName, readOnlySet) => 
+  readOnlySet.has(propertyName);
+
+/**
+ * Marks a property as read-only (adds to set).
+ */
+export const markAsReadOnly = (propertyName, readOnlySet) => {
+  readOnlySet.add(propertyName);
+};
+
+/**
+ * Throws an error for read-only computed property assignment.
+ */
+export const throwReadOnlyError = (propertyName) => {
+  throw new Error(`Cannot assign to computed property '${propertyName}'`);
+};
+
+/**
+ * Checks if an error is a MobX read-only computed property error.
+ */
+export const isMobxReadOnlyError = (error) => 
+  error.message?.includes('not possible to assign');
+
+// ============================================================================
+// PROPERTY DEFINITION
+// ============================================================================
+
+/**
+ * Defines a reactive property on the Vue state object.
+ */
+export const defineReactiveProperty = (vueState, propertyName, descriptor) => {
+  Object.defineProperty(vueState, propertyName, {
+    get: descriptor.get,
+    set: descriptor.set,
+    enumerable: true,
+    configurable: true,
+  });
+};
+
+// ============================================================================
+// MUTATION WARNINGS
+// ============================================================================
+
+/**
+ * Warns that direct mutation is disabled for a property.
+ */
+export const warnDirectMutation = (propertyName) => {
+  console.warn(`Direct mutation of '${propertyName}' is disabled. Use actions instead.`);
+};
+
+/**
+ * Logs a warning when a property fails to set.
+ */
+export const logSetterWarning = (propertyName, error) => {
+  console.warn(`Failed to set property '${propertyName}':`, error);
+};
+
+// ============================================================================
+// SETTER CREATION
+// ============================================================================
+
+/**
+ * Creates a validated setter that lazily detects read-only properties.
+ * This prevents calling setters during initialization (avoiding side effects).
+ */
+export const createLazyValidatedSetter = ({
+  propertyName,
+  target,
+  allowDirectMutation,
+  readOnlySet,
+  guardSet,
+}) => {
+  if (!allowDirectMutation) {
+    return () => warnDirectMutation(propertyName);
+  }
+  
+  return (value) => {
+    // Fast-fail if already detected as read-only
+    if (isKnownReadOnly(propertyName, readOnlySet)) {
+      throwReadOnlyError(propertyName);
+    }
+    
+    // Attempt write with guard against echo loops
+    guardAgainstEchoLoop(propertyName, guardSet, () => {
+      try {
+        target[propertyName] = value;
+      } catch (error) {
+        if (isMobxReadOnlyError(error)) {
+          markAsReadOnly(propertyName, readOnlySet);
+          throwReadOnlyError(propertyName);
+        } else {
+          logSetterWarning(propertyName, error);
+        }
+      }
+    });
+  };
+};
+
+/**
+ * Creates a simple setter that always throws an error (for computed properties).
+ */
+export const createReadOnlySetter = (propertyName) => {
+  return () => {
+    throw new Error(`Cannot assign to computed property '${propertyName}'`);
+  };
+};
+
+/**
+ * Creates a setter for write-only properties (no corresponding getter).
+ */
+export const createWriteOnlySetter = ({
+  propertyName,
+  target,
+  allowDirectMutation,
+  guardSet,
+  setterRef,
+}) => {
+  if (!allowDirectMutation) {
+    return () => warnDirectMutation(propertyName);
+  }
+  
+  return (value) => {
+    setterRef.value = value;
+    guardAgainstEchoLoop(propertyName, guardSet, () => {
+      target[propertyName] = value;
+    });
+  };
+};
+
+// ============================================================================
+// OBSERVABLE PROPERTY SETTERS
+// ============================================================================
+
+/**
+ * Creates a two-way binding setter for observable properties.
+ */
+export const createTwoWayBindingSetter = ({
+  propertyName,
+  target,
+  allowDirectMutation,
+  guardSet,
+  propertyRef,
+}) => {
+  if (!allowDirectMutation) {
+    return () => warnDirectMutation(propertyName);
+  }
+
+  return (value) => {
+    if (!isEqual(propertyRef.value, value)) {
+      const cloned = clone(value);
+      propertyRef.value = cloned;
+      
+      guardAgainstEchoLoop(propertyName, guardSet, () => {
+        target[propertyName] = cloned;
+      });
+    }
+  };
+};
+
+// ============================================================================
+// MOBX OBSERVATION HELPERS
+// ============================================================================
+
+/**
+ * Creates a MobX → Vue update handler that respects echo guards.
+ */
+export const createMobxToVueUpdater = ({
+  propertyName,
+  target,
+  refToUpdate,
+  echoGuard,
+  updateGuard,
+}) => {
+  return () => {
+    if (!refToUpdate) return;
+    if (echoGuard.has(propertyName)) return; // Prevent echo loops
+    
+    updateGuard.add(propertyName);
+    try {
+      const nextValue = toJS(target[propertyName]);
+      if (!isEqual(refToUpdate.value, nextValue)) {
+        refToUpdate.value = nextValue;
+      }
+    } finally {
+      updateGuard.delete(propertyName);
+    }
+  };
+};
+
+/**
+ * Observes a single MobX property and syncs changes to Vue.
+ * When the property value changes, it also re-subscribes deepObserve to the new value.
+ */
+export const observeProperty = ({
+  target,
+  propertyName,
+  refToUpdate,
+  echoGuard,
+  updateGuard,
+  onValueChanged, // Optional callback when value changes (for re-subscribing deepObserve)
+}) => {
+  try {
+    const updater = createMobxToVueUpdater({
+      propertyName,
+      target,
+      refToUpdate,
+      echoGuard,
+      updateGuard,
+    });
+
+    return observe(target, propertyName, (change) => {
+      updater();
+      // Notify that the value changed so deepObserve can be re-subscribed
+      if (onValueChanged && change.type === 'update') {
+        onValueChanged(change.newValue);
+      }
+    });
+  } catch (error) {
+    // Only silently ignore expected MobX errors for non-observable properties
+    // These errors indicate the property isn't observable, which is expected for some properties
+    const isExpectedError = error.message?.includes('not observable') || 
+                            error.message?.includes('no observable') ||
+                            error.message?.includes('[MobX]');
+    if (!isExpectedError) {
+      console.warn(`[mobx-vue-bridge] Unexpected error observing '${propertyName}':`, error);
+    }
+    return null;
+  }
+};
+
+/**
+ * Deep observes nested objects/arrays and syncs changes to Vue.
+ */
+export const deepObserveProperty = ({
+  target,
+  propertyName,
+  refToUpdate,
+  echoGuard,
+  updateGuard,
+}) => {
+  const value = target[propertyName];
+  
+  // Only deep observe objects and arrays
+  if (!value || typeof value !== 'object') {
+    return null;
+  }
+
+  try {
+    const updater = createMobxToVueUpdater({
+      propertyName,
+      target,
+      refToUpdate,
+      echoGuard,
+      updateGuard,
+    });
+
+    return deepObserve(value, (change, path) => {
+      updater();
+    });
+  } catch (error) {
+    // Only silently ignore expected errors (circular references, non-observable objects)
+    const isExpectedError = error.message?.includes('circular') || 
+                            error.message?.includes('not observable') ||
+                            error.message?.includes('[MobX]');
+    if (!isExpectedError) {
+      console.warn(`[mobx-vue-bridge] Unexpected error deep-observing '${propertyName}':`, error);
+    }
+    return null;
+  }
+};
+
+/**
+ * Creates a reactive subscription to a MobX computed property (getter).
+ */
+export const observeGetter = ({
+  target,
+  propertyName,
+  refToUpdate,
+}) => {
+  const safelyReadGetter = () => {
+    try {
+      return toJS(target[propertyName]);
+    } catch (error) {
+      // If computed property throws (e.g., accessing null.property), return undefined
+      return undefined;
+    }
+  };
+
+  const updateRefWhenChanged = (nextValue) => {
+    if (!refToUpdate) return;
+    if (!isEqual(refToUpdate.value, nextValue)) {
+      refToUpdate.value = nextValue;
+    }
+  };
+
+  return reaction(safelyReadGetter, updateRefWhenChanged);
+};
+
+/**
+ * Safely disposes a subscription (handles both function and object with dispose).
+ */
+export const safelyDisposeSubscription = (subscription) => {
+  try {
+    if (typeof subscription === 'function') {
+      subscription();
+    } else if (typeof subscription?.dispose === 'function') {
+      subscription.dispose();
+    }
+  } catch (error) {
+    // Silently handle cleanup errors
+  }
+};