scope-state 0.1.4 → 0.1.6

package/dist/index.js

@@ -353,6 +353,7 @@ function logSubscriptionRemoved(path) {
 
 // Track proxy to path mapping for type-safe activation
 const proxyPathMap = new WeakMap();
+const proxyTargetMap = new WeakMap();
 // Store a deep clone of the initial store state for use with $reset
 let initialStoreState$1 = {};
 // Path usage tracking
@@ -570,6 +571,11 @@ function createAdvancedProxy(target, path = [], depth = 0) {
             if (typeof prop === 'symbol') {
                 return Reflect.get(obj, prop, receiver);
             }
+            const value = Reflect.get(obj, prop, receiver);
+            // Functions are commands/helpers, not reactive data dependencies.
+            if (typeof value === 'function') {
+                return value;
+            }
             const currentPropPath = [...path, prop.toString()];
             const propPathKey = currentPropPath.join('.');
             // Track path access during dependency tracking
@@ -580,9 +586,12 @@ function createAdvancedProxy(target, path = [], depth = 0) {
             }
             // Track path access for dependency tracking (inline to avoid circular dependency)
             trackPathAccess(currentPropPath);
-            const value = obj[prop];
             // For objects, create proxies for nested values
             if (value && typeof value === 'object' && path.length < proxyConfig.maxDepth) {
+                // If value is already a proxy, return it directly to prevent double-wrapping
+                if (proxyPathMap.has(value)) {
+                    return value;
+                }
                 const shouldProxy = !proxyConfig.lazyProxyDeepObjects ||
                     pathUsageStats.accessedPaths.has(propPathKey) ||
                     pathUsageStats.modifiedPaths.has(propPathKey) ||
@@ -594,27 +603,16 @@ function createAdvancedProxy(target, path = [], depth = 0) {
             }
             return value;
         },
-        set(obj, prop, value, receiver) {
+        set(obj, prop, value) {
             if (typeof prop === 'symbol') {
-                return Reflect.set(obj, prop, value, receiver);
+                return Reflect.set(obj, prop, value);
             }
             const propPath = [...path, prop.toString()];
             const propPathKey = propPath.join('.');
-            // Track modification
             if (proxyConfig.trackPathUsage) {
                 pathUsageStats.modifiedPaths.add(propPathKey);
             }
-            // Handle object assignment with proxying
-            if (value && typeof value === 'object' && !proxyCache.has(value)) {
-                const newPath = [...path, prop.toString()];
-                const proxiedValue = createAdvancedProxy(value, newPath, 0);
-                const result = Reflect.set(obj, prop, proxiedValue, receiver);
-                // Notify the specific property path and all parent/child paths
-                notifyListeners(propPath);
-                return result;
-            }
-            const result = Reflect.set(obj, prop, value, receiver);
-            // Notify the specific property path (this will also notify parent/child paths)
+            const result = Reflect.set(obj, prop, value);
             notifyListeners(propPath);
             return result;
         },
@@ -640,6 +638,7 @@ function createAdvancedProxy(target, path = [], depth = 0) {
     proxyCacheLRU.add(target, proxy);
     // Track the path for this proxy
     proxyPathMap.set(proxy, [...path]);
+    proxyTargetMap.set(proxy, target);
     return proxy;
 }
 /**
@@ -656,16 +655,7 @@ function addObjectMethods(target, path) {
                         const propPath = [...currentPath, key].join('.');
                         pathUsageStats.modifiedPaths.add(propPath);
                     }
-                    const newValue = newProps[key];
-                    if (newValue && typeof newValue === 'object' && !proxyCache.has(newValue)) {
-                        const newPath = [...currentPath, key];
-                        // Use Reflect.set with this proxy as the receiver to trigger the set handler
-                        Reflect.set(this, key, createAdvancedProxy(newValue, newPath, 0), this);
-                    }
-                    else {
-                        // Use Reflect.set with this proxy as the receiver to trigger the set handler
-                        Reflect.set(this, key, newValue, this);
-                    }
+                    Reflect.set(this, key, newProps[key], this);
                 });
                 return this;
             },
@@ -676,28 +666,17 @@ function addObjectMethods(target, path) {
         methodsToDefine.$set = {
             value: function (newProps) {
                 const currentPath = proxyPathMap.get(this) || path;
-                // Clear existing properties
                 Object.keys(this).forEach(key => {
                     if (typeof this[key] !== 'function') {
                         Reflect.deleteProperty(this, key);
                     }
                 });
-                // Set new properties
                 Object.keys(newProps || {}).forEach(key => {
                     if (proxyConfig.trackPathUsage) {
                         const propPath = [...currentPath, key].join('.');
                         pathUsageStats.modifiedPaths.add(propPath);
                     }
-                    const newValue = newProps[key];
-                    if (newValue && typeof newValue === 'object' && !proxyCache.has(newValue)) {
-                        const newPath = [...currentPath, key];
-                        // Use Reflect.set with this proxy as the receiver to trigger the set handler
-                        Reflect.set(this, key, createAdvancedProxy(newValue, newPath, 0), this);
-                    }
-                    else {
-                        // Use Reflect.set with this proxy as the receiver to trigger the set handler
-                        Reflect.set(this, key, newValue, this);
-                    }
+                    Reflect.set(this, key, newProps[key], this);
                 });
                 return this;
             },
@@ -727,12 +706,7 @@ function addObjectMethods(target, path) {
                     pathUsageStats.modifiedPaths.add(propPath);
                 }
                 const currentValue = this[key];
-                let newValue = updater(currentValue);
-                if (newValue && typeof newValue === 'object' && !proxyCache.has(newValue)) {
-                    const newPath = [...currentPath, key];
-                    newValue = createAdvancedProxy(newValue, newPath, 0);
-                }
-                // Use Reflect.set with this proxy as the receiver to trigger the set handler
+                const newValue = updater(currentValue);
                 Reflect.set(this, key, newValue, this);
                 return this;
             },
@@ -790,20 +764,13 @@ function addObjectMethods(target, path) {
  * Add custom methods to array targets
  */
 function addArrayMethods(target, path) {
-    const originalPush = target.push;
-    const originalSplice = target.splice;
+    const originalPush = Array.prototype.push;
+    const originalSplice = Array.prototype.splice;
     // Override push
     Object.defineProperty(target, 'push', {
         value: function (...items) {
             const currentPath = proxyPathMap.get(this) || path;
-            const processedItems = items.map(item => {
-                if (item && typeof item === 'object' && !proxyCache.has(item)) {
-                    const itemPath = [...currentPath, '_item'];
-                    return createAdvancedProxy(item, itemPath, 0);
-                }
-                return item;
-            });
-            const result = originalPush.apply(this, processedItems);
+            const result = originalPush.apply(this, items);
             if (currentPath.length > 0) {
                 if (proxyConfig.trackPathUsage) {
                     pathUsageStats.modifiedPaths.add(currentPath.join('.'));
@@ -820,22 +787,13 @@ function addArrayMethods(target, path) {
         value: function (start, deleteCount, ...items) {
             const currentPath = proxyPathMap.get(this) || path;
             const arrayLength = this.length;
-            const processedItems = items.map((item, index) => {
-                if (item && typeof item === 'object' && !proxyCache.has(item)) {
-                    const itemPath = [...currentPath, (start + index).toString()];
-                    return createAdvancedProxy(item, itemPath, 0);
-                }
-                return item;
-            });
             const actualDeleteCount = deleteCount === undefined ? (arrayLength - start) : deleteCount;
-            const result = originalSplice.apply(this, [start, actualDeleteCount, ...processedItems]);
+            const result = originalSplice.apply(this, [start, actualDeleteCount, ...items]);
             if (currentPath.length > 0) {
                 if (proxyConfig.trackPathUsage) {
                     pathUsageStats.modifiedPaths.add(currentPath.join('.'));
                 }
-                // Notify the array itself
                 notifyListeners(currentPath);
-                // Also notify about each index that was affected
                 for (let i = start; i < arrayLength; i++) {
                     const indexPath = [...currentPath, i.toString()];
                     notifyListeners(indexPath);
@@ -856,14 +814,7 @@ function addArrayMethods(target, path) {
                 }
                 const currentPath = proxyPathMap.get(this) || path;
                 this.length = 0;
-                const processedItems = newArray.map((item, index) => {
-                    if (item && typeof item === 'object' && !proxyCache.has(item)) {
-                        const itemPath = [...currentPath, index.toString()];
-                        return createAdvancedProxy(item, itemPath, 0);
-                    }
-                    return item;
-                });
-                originalPush.apply(this, processedItems);
+                originalPush.apply(this, newArray);
                 if (currentPath.length > 0) {
                     if (proxyConfig.trackPathUsage) {
                         pathUsageStats.modifiedPaths.add(currentPath.join('.'));
@@ -895,15 +846,8 @@ function addArrayMethods(target, path) {
                     initialValue = [];
                 }
                 this.length = 0;
-                const processedItems = initialValue.map((item, index) => {
-                    if (item && typeof item === 'object' && !proxyCache.has(item)) {
-                        const itemPath = [...currentPath, index.toString()];
-                        return createAdvancedProxy(item, itemPath, 0);
-                    }
-                    return item;
-                });
-                if (processedItems.length > 0) {
-                    originalPush.apply(this, processedItems);
+                if (initialValue.length > 0) {
+                    originalPush.apply(this, JSON.parse(JSON.stringify(initialValue)));
                 }
                 if (currentPath.length > 0) {
                     notifyListeners(currentPath);
@@ -1020,6 +964,52 @@ function trackPathAccess(path) {
     }
 }
 
+function isPlainObject(value) {
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function unwrapProxyTarget(value) {
+    if (value && typeof value === 'object' && proxyTargetMap.has(value)) {
+        return proxyTargetMap.get(value);
+    }
+    return value;
+}
+/**
+ * Create a read-only snapshot suitable for rendering.
+ *
+ * Snapshots are plain arrays/objects with no proxy methods, which makes them
+ * safe for React Compiler memoization while keeping `$` as the mutable API.
+ */
+function createReadonlySnapshot(value, seen = new WeakMap()) {
+    if (value === null || typeof value !== 'object') {
+        return value;
+    }
+    const source = unwrapProxyTarget(value);
+    if (seen.has(source)) {
+        return seen.get(source);
+    }
+    if (Array.isArray(source)) {
+        const snapshot = [];
+        seen.set(source, snapshot);
+        source.forEach(item => {
+            snapshot.push(createReadonlySnapshot(item, seen));
+        });
+        return snapshot;
+    }
+    if (!isPlainObject(source)) {
+        return source;
+    }
+    const snapshot = {};
+    seen.set(source, snapshot);
+    Object.keys(source).forEach(key => {
+        const propertyValue = source[key];
+        if (typeof propertyValue !== 'function') {
+            snapshot[key] = createReadonlySnapshot(propertyValue, seen);
+        }
+    });
+    return snapshot;
+}
+
 /**
  * Hook to subscribe to the global store and re-render when specific data changes.
  *
@@ -1027,15 +1017,16 @@ function trackPathAccess(path) {
  * re-renders the component when those specific paths change. This provides
  * fine-grained reactivity without unnecessary renders.
  *
- * For objects, the returned value includes custom methods ($merge, $set, $delete, $update)
- * that allow you to modify the data directly and trigger reactive updates.
+ * The returned value is a read-only snapshot of the selected state. Mutate the
+ * store through the main `$` proxy (or a proxy created explicitly for commands),
+ * and use the hook return value only for rendering.
  *
  * @example
  * // Subscribe to user data
  * const user = useScope(() => $.user);
  *
- * // Update user data directly (triggers re-render only for components using $.user)
- * user.$merge({ name: 'New Name' });
+ * // Mutate through the main store proxy
+ * $.user.$merge({ name: 'New Name' });
  *
  * // Subscribe to a specific property
  * const userName = useScope(() => $.user.name);
@@ -1044,22 +1035,24 @@ function trackPathAccess(path) {
  * const isAdmin = useScope(() => $.user.role === 'admin');
  *
  * @param selector - Function that returns the data you want to subscribe to
- * @returns The selected data, with custom methods attached if it's an object
+ * @returns A read-only snapshot of the selected data
  */
 function useScope(selector) {
-    // Use ref to store the latest selector to avoid stale closures
-    const selectorRef = react.useRef(selector);
-    selectorRef.current = selector;
-    // Track dependencies and get initial value with advanced tracking
-    const { value: initialValue, paths: trackedPaths } = trackDependencies(selector);
+    const snapshotCacheRef = react.useRef({
+        revision: -1,
+        source: undefined,
+        snapshot: undefined,
+    });
+    // Track dependencies and get the selected value from the store
+    const { value: selectedValue, paths: trackedPaths } = trackDependencies(selector);
     // Add tracked paths to selector paths for ultra-selective proxying
     trackedPaths.forEach(path => {
         selectorPaths.add(path);
         pathUsageStats.subscribedPaths.add(path);
     });
-    // Use a counter to force re-renders instead of storing the value
-    // This way we always return the fresh proxy object from the selector
-    const [, forceUpdate] = react.useState(0);
+    // Use a counter to invalidate the cached snapshot only when this hook
+    // receives a relevant store notification.
+    const [revision, forceUpdate] = react.useState(0);
     // Create stable update handler that forces re-render
     const handleChange = react.useCallback(() => {
         try {
@@ -1070,6 +1063,16 @@ function useScope(selector) {
         }
     }, []);
     react.useEffect(() => {
+        if (typeof requestAnimationFrame === 'function') {
+            requestAnimationFrame(() => {
+                handleChange();
+            });
+        }
+        else {
+            setTimeout(() => {
+                handleChange();
+            }, 16);
+        }
         // Create path keys for subscription using the original approach
         // If trackedPaths is ['user', 'name'], create subscriptions for ['user', 'user.name']
         const pathKeys = trackedPaths.length > 0
@@ -1086,8 +1089,18 @@ function useScope(selector) {
             unsubscribeFunctions.forEach(unsubscribe => unsubscribe());
         };
     }, [trackedPaths.join(','), handleChange]); // Stable dependencies
-    // Always return the fresh result from the selector (preserves proxy and methods)
-    return selectorRef.current();
+    if (selectedValue === null || typeof selectedValue !== 'object') {
+        return selectedValue;
+    }
+    if (snapshotCacheRef.current.revision !== revision ||
+        snapshotCacheRef.current.source !== selectedValue) {
+        snapshotCacheRef.current = {
+            revision,
+            source: selectedValue,
+            snapshot: createReadonlySnapshot(selectedValue),
+        };
+    }
+    return snapshotCacheRef.current.snapshot;
 }
 
 /**