scope-state 0.1.5 → 0.1.7

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('.'));
@@ -815,27 +782,40 @@ function addArrayMethods(target, path) {
         writable: true,
         configurable: true
     });
+    // Override find with smart tracking during dependency collection
+    Object.defineProperty(target, 'find', {
+        value: function (predicate, thisArg) {
+            if (!isCurrentlyTracking() || !proxyConfig.smartArrayTracking) {
+                return Array.prototype.find.call(this, predicate, thisArg);
+            }
+            const currentPath = proxyPathMap.get(this) || path;
+            const length = skipTracking(() => this.length);
+            for (let i = 0; i < length; i++) {
+                const element = skipTracking(() => Reflect.get(this, i));
+                const { value: matched, paths } = capturePathsDuring(() => Boolean(predicate.call(thisArg, element, i, this)));
+                if (matched) {
+                    addTrackedPaths([[...currentPath, String(i)].join('.')]);
+                    addTrackedPaths(paths);
+                    return element;
+                }
+            }
+            return undefined;
+        },
+        writable: true,
+        configurable: true
+    });
     // Override splice
     Object.defineProperty(target, 'splice', {
         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 +836,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 +868,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);
@@ -978,48 +944,125 @@ function optimizeMemoryUsage(aggressive = false) {
     };
 }
 
-// Track the current path we're accessing during a selector function
-let currentPath = [];
+// Unique full dotted paths accessed during selector execution
+let trackedPaths = new Set();
 let isTracking = false;
 let skipTrackingDepth = 0;
 /**
- * Track dependencies during selector execution - tracks individual path segments
+ * Track dependencies during selector execution - tracks full dotted paths
  */
 function trackDependencies(selector) {
-    // Start tracking
     isTracking = true;
-    currentPath = [];
+    trackedPaths = new Set();
     skipTrackingDepth = 0;
-    // Execute selector to track dependencies
     const value = selector();
-    // Stop tracking and get the tracked paths
     isTracking = false;
-    // Clean up and return individual path segments (not full paths)
-    const cleanedPaths = [...currentPath].filter(segment => {
-        // Filter out segments that would create overly long paths
-        return segment && segment.length < 100; // Basic length check for individual segments
+    const paths = Array.from(trackedPaths).filter(path => path && path.length < 500);
+    trackedPaths = new Set();
+    return { value, paths };
+}
+/**
+ * Check if we're currently tracking dependencies
+ */
+function isCurrentlyTracking() {
+    return isTracking && skipTrackingDepth === 0;
+}
+/**
+ * Temporarily skip tracking (for array method internals)
+ */
+function skipTracking(fn) {
+    skipTrackingDepth++;
+    try {
+        return fn();
+    }
+    finally {
+        skipTrackingDepth--;
+    }
+}
+/**
+ * Run fn while capturing any newly tracked paths, then remove them from the main set.
+ * Caller decides whether to re-add captured paths (e.g. on a matched find iteration).
+ */
+function capturePathsDuring(fn) {
+    const snapshot = new Set(trackedPaths);
+    const value = fn();
+    const newPaths = [];
+    trackedPaths.forEach(path => {
+        if (!snapshot.has(path)) {
+            newPaths.push(path);
+            trackedPaths.delete(path);
+        }
     });
-    currentPath = [];
-    return { value, paths: cleanedPaths };
+    return { value, paths: newPaths };
+}
+/**
+ * Add paths to the active tracking set (used by smart array method overrides)
+ */
+function addTrackedPaths(paths) {
+    if (!isTracking)
+        return;
+    paths.forEach(path => trackedPaths.add(path));
 }
 /**
- * Add a path segment to tracking during proxy get operations
+ * Add a full path to tracking during proxy get operations
  */
 function trackPathAccess(path) {
     if (!isTracking || skipTrackingDepth > 0)
         return;
-    // Track only the last property name (individual segment)
-    const prop = path[path.length - 1];
-    // Only track if prop exists and path isn't too deep
-    if (prop && path.length <= proxyConfig.maxPathLength) {
-        currentPath.push(prop);
-        // Add full path to usage stats and selector paths for ultra-selective proxying
+    if (path.length <= proxyConfig.maxPathLength) {
         const fullPath = path.join('.');
+        trackedPaths.add(fullPath);
         pathUsageStats.accessedPaths.add(fullPath);
         selectorPaths.add(fullPath);
     }
 }
 
+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 +1070,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 +1088,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 {
@@ -1080,11 +1126,7 @@ function useScope(selector) {
                 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
-            ? trackedPaths.map((_, index, array) => array.slice(0, index + 1).join('.'))
-            : [''];
+        const pathKeys = trackedPaths.length > 0 ? trackedPaths : [''];
         // Subscribe to all relevant paths
         const unsubscribeFunctions = pathKeys.map(pathKey => {
             // Mark this path as subscribed for usage tracking
@@ -1096,8 +1138,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;
 }
 
 /**