@yiin/reactive-proxy-state 1.0.3 → 1.0.5

package/dist/state.js

@@ -1,23 +1,26 @@
 import { pathCache, setInPathCache } from './utils';
-// Pre-allocate helper functions to avoid recreation
+// helper to abstract getting a value from a map or object property
 function getValue(obj, key) {
     if (obj instanceof Map)
         return obj.get(key);
     return obj[key];
 }
+// helper to abstract setting a value on a map or object property
 function setValue(obj, key, value) {
     if (obj instanceof Map)
         obj.set(key, value);
     else
         obj[key] = value;
 }
+// helper to abstract deleting a key from a map or object
 function deleteValue(obj, key) {
     if (obj instanceof Map)
         obj.delete(key);
     else
         delete obj[key];
 }
-// Cache for action handlers to avoid switch statement overhead
+// dispatch table for applying state events based on action type
+// this avoids a large switch statement and makes adding new actions easier
 const actionHandlers = {
     'set': function (parent, key, event) {
         setValue(parent, key, event.newValue);
@@ -27,36 +30,36 @@ const actionHandlers = {
     },
     'array-push': function (targetArray, _keyIgnored, event) {
         if (!Array.isArray(targetArray)) {
-            console.warn(`Expected Array at path ${event.path.join('.')}`);
+            console.warn(`expected array at path ${event.path.join('.')}`);
             return;
         }
         if (!event.items) {
             console.warn('array-push event missing items');
             return;
         }
-        // Note: event.key is the starting index, but push always adds to the end.
+        // event.key is the starting index, but push always adds to end
         targetArray.push(...event.items);
     },
     'array-pop': function (targetArray, _keyIgnored, event) {
         if (!Array.isArray(targetArray)) {
-            console.warn(`Expected Array at path ${event.path.join('.')}`);
+            console.warn(`expected array at path ${event.path.join('.')}`);
             return;
         }
-        // We don't need event.key or event.oldValue to perform the pop.
+        // event info (key, oldvalue) not needed to perform pop
         if (targetArray.length > 0) {
             targetArray.pop();
         }
     },
     'array-splice': function (targetArray, _keyIgnored, event) {
         if (!Array.isArray(targetArray)) {
-            console.warn(`Expected Array at path ${event.path.join('.')}`);
+            console.warn(`expected array at path ${event.path.join('.')}`);
             return;
         }
         if (event.key === undefined || event.deleteCount === undefined) {
-            console.warn('array-splice event missing key or deleteCount');
+            console.warn('array-splice event missing key or deletecount');
             return;
         }
-        // Call splice with appropriate arguments
+        // handle splice with or without items to insert
         if (event.items && event.items.length > 0) {
             targetArray.splice(event.key, event.deleteCount, ...event.items);
         }
@@ -66,142 +69,143 @@ const actionHandlers = {
     },
     'array-shift': function (targetArray, _keyIgnored, event) {
         if (!Array.isArray(targetArray)) {
-            console.warn(`Expected Array at path ${event.path.join('.')}`);
+            console.warn(`expected array at path ${event.path.join('.')}`);
             return;
         }
-        // We don't need event.key or event.oldValue to perform the shift.
+        // event info not needed to perform shift
         if (targetArray.length > 0) {
             targetArray.shift();
         }
     },
     'array-unshift': function (targetArray, _keyIgnored, event) {
         if (!Array.isArray(targetArray)) {
-            console.warn(`Expected Array at path ${event.path.join('.')}`);
+            console.warn(`expected array at path ${event.path.join('.')}`);
             return;
         }
         if (!event.items) {
             console.warn('array-unshift event missing items');
             return;
         }
-        // We don't need event.key to perform unshift
+        // event.key (always 0) not needed to perform unshift
         targetArray.unshift(...event.items);
     },
-    'map-set': function (parent, key, event) {
-        const target = getValue(parent, key);
-        if (target instanceof Map) {
-            target.set(event.key, event.newValue);
-        }
-        else {
-            console.warn(`Expected Map at path ${key}`);
+    // note: for map/set operations originating from the proxy wrapper (e.g., map.set(k,v)),
+    // the *event path* points to the map itself, and event.key/event.value hold the map's key/value.
+    // however, the actionHandlers expect `target` to be the collection and `key` to be the map/set key.
+    // the logic in `updateState` below handles finding the correct target collection first.
+    'map-set': function (targetMap, _parentKeyIgnored, event) {
+        if (!(targetMap instanceof Map)) {
+            console.warn(`expected map at path ${event.path.join('.')}`);
+            return;
         }
+        targetMap.set(event.key, event.newValue);
     },
-    'map-delete': function (parent, key, event) {
-        const target = getValue(parent, key);
-        if (target instanceof Map) {
-            target.delete(event.key);
-        }
-        else {
-            console.warn(`Expected Map at path ${key}`);
+    'map-delete': function (targetMap, _parentKeyIgnored, event) {
+        if (!(targetMap instanceof Map)) {
+            console.warn(`expected map at path ${event.path.join('.')}`);
+            return;
         }
+        targetMap.delete(event.key);
     },
-    'map-clear': function (parent, key, event) {
-        const target = getValue(parent, key);
-        if (target instanceof Map) {
-            target.clear();
-        }
-        else {
-            console.warn(`Expected Map at path ${key}`);
+    'map-clear': function (targetMap, _parentKeyIgnored, event) {
+        if (!(targetMap instanceof Map)) {
+            console.warn(`expected map at path ${event.path.join('.')}`);
+            return;
         }
+        targetMap.clear();
     },
     'set-add': function (targetSet, _keyIgnored, event) {
-        if (targetSet instanceof Set) {
-            targetSet.add(event.value);
-        }
-        else {
-            console.warn(`Expected Set at path ${event.path.join('.')}`);
+        if (!(targetSet instanceof Set)) {
+            console.warn(`expected set at path ${event.path.join('.')}`);
+            return;
         }
+        targetSet.add(event.value);
     },
     'set-delete': function (targetSet, _keyIgnored, event) {
-        if (targetSet instanceof Set) {
-            targetSet.delete(event.value);
-        }
-        else {
-            console.warn(`Expected Set at path ${event.path.join('.')}`);
+        if (!(targetSet instanceof Set)) {
+            console.warn(`expected set at path ${event.path.join('.')}`);
+            return;
         }
+        targetSet.delete(event.value);
     },
     'set-clear': function (targetSet, _keyIgnored, event) {
-        if (targetSet instanceof Set) {
-            targetSet.clear();
-        }
-        else {
-            console.warn(`Expected Set at path ${event.path.join('.')}`);
+        if (!(targetSet instanceof Set)) {
+            console.warn(`expected set at path ${event.path.join('.')}`);
+            return;
         }
+        targetSet.clear();
     }
 };
+// applies a state change event to a plain javascript object/array (the target state)
 export function updateState(root, event) {
     const { action, path } = event;
-    if (path.length === 0) {
-        console.warn('Event path is empty');
+    if (!path || path.length === 0) {
+        console.warn('event path is empty, cannot apply update', event);
         return;
     }
     const handler = actionHandlers[action];
     if (!handler) {
-        throw new Error(`Unhandled action: ${action}`);
+        // maybe allow custom handlers or ignore unknown actions?
+        console.error(`unhandled action type: ${action}`, event);
+        return;
+        // throw new Error(`Unhandled action: ${action}`);
     }
-    // Determine target and key based on action type
+    // determine the target object/collection and the specific key (if applicable)
+    // based on the action type and the event path.
     let targetForHandler;
-    let keyForHandler = null; // Key is only relevant for set/delete/map actions
-    if (action === 'set' || action === 'delete' || action.startsWith('map-')) {
-        // Actions where path leads to parent, last element is key
+    let keyForHandler = null; // key passed to handler, relevant for set/delete
+    // path resolution logic differs based on action type:
+    // - set/delete: path leads to the *value* being set/deleted, so we need the parent object and the final path segment (key).
+    // - array-*/map-*/set-*: path leads to the *collection* itself.
+    if (action === 'set' || action === 'delete') {
+        // need the parent object and the final key
         if (path.length === 1) {
-            targetForHandler = root;
+            targetForHandler = root; // parent is the root object
             keyForHandler = path[0];
         }
         else {
-            const parentPathKey = path.slice(0, -1).join('.');
+            const parentPath = path.slice(0, -1);
+            const parentPathKey = parentPath.join('.');
+            // try cache first for performance
             let parent = pathCache.get(root)?.get(parentPathKey);
             if (parent === undefined) {
-                parent = path.slice(0, -1).reduce((acc, key) => acc ? getValue(acc, key) : undefined, root);
+                // traverse path manually if not in cache
+                parent = parentPath.reduce((acc, key) => acc ? getValue(acc, key) : undefined, root);
                 if (parent !== undefined)
-                    setInPathCache(root, parentPathKey, parent);
+                    setInPathCache(root, parentPathKey, parent); // cache if found
             }
             if (parent === undefined) {
-                console.warn(`Parent path ${parentPathKey} not found for action ${action}`);
+                console.warn(`parent path ${parentPathKey} not found for action ${action}`);
                 return;
             }
             targetForHandler = parent;
             keyForHandler = path[path.length - 1];
         }
     }
-    else if (action.startsWith('array-') || action.startsWith('set-')) {
-        // Actions where path leads directly to the collection (Array or Set)
-        if (path.length === 1) {
-            targetForHandler = getValue(root, path[0]);
-        }
-        else {
-            const parentPathKey = path.slice(0, -1).join('.');
-            let parent = pathCache.get(root)?.get(parentPathKey);
-            if (parent === undefined) {
-                parent = path.slice(0, -1).reduce((acc, key) => acc ? getValue(acc, key) : undefined, root);
-                if (parent !== undefined)
-                    setInPathCache(root, parentPathKey, parent);
-            }
-            if (parent === undefined) {
-                console.warn(`Parent path ${parentPathKey} not found for action ${action}`);
-                return;
-            }
-            targetForHandler = getValue(parent, path[path.length - 1]);
-        }
-        if (targetForHandler === undefined) {
-            console.warn(`Target collection at path ${path.join('.')} not found for action ${action}`);
+    else if (action.startsWith('array-') || action.startsWith('map-') || action.startsWith('set-')) {
+        // need the collection object itself (array, map, or set)
+        const targetPath = path;
+        const targetPathKey = targetPath.join('.');
+        // try cache first
+        let targetCollection = pathCache.get(root)?.get(targetPathKey);
+        if (targetCollection === undefined) {
+            // traverse path manually if not in cache
+            targetCollection = targetPath.reduce((acc, key) => acc ? getValue(acc, key) : undefined, root);
+            if (targetCollection !== undefined)
+                setInPathCache(root, targetPathKey, targetCollection); // cache if found
+        }
+        if (targetCollection === undefined) {
+            console.warn(`target collection at path ${targetPathKey} not found for action ${action}`);
             return;
         }
+        targetForHandler = targetCollection;
+        // keyForHandler remains null for these actions as the handler operates directly on the collection
     }
     else {
-        // Should not happen if handler exists
-        console.error(`Unexpected action type passed checks: ${action}`);
+        // this should not be reachable if handler lookup succeeded
+        console.error(`unexpected action type passed checks: ${action}`);
         return;
     }
-    // Call the handler with the appropriately determined target and key
+    // call the appropriate handler with the resolved target and key
     handler(targetForHandler, keyForHandler, event);
 }

package/dist/types.d.ts

@@ -3,11 +3,10 @@ export type ActionType = 'set' | 'delete' | 'array-push' | 'array-pop' | 'array-
 export interface StateEvent {
     action: ActionType;
     path: Path;
-    oldValue?: any;
     newValue?: any;
+    oldValue?: any;
     key?: any;
     value?: any;
-    args?: any[];
     items?: any[];
     deleteCount?: number;
     oldValues?: any[];

package/dist/utils.d.ts

@@ -8,18 +8,13 @@ export declare function setInPathCache(root: object, pathKey: string, value: any
 export declare function getPathConcat(path: string): any[] | undefined;
 export declare function setPathConcat(path: string, value: any[]): void;
 /**
- * Recursively traverses an object to track all nested properties.
- * Used for deep watching.
- * @param value - The value to traverse.
- * @param seen - A Set to handle circular references.
+ * recursively traverses an object or array, accessing each property/element.
+ * used by `watch` with `deep: true` to establish dependencies on all nested properties.
+ * the actual tracking is done by the proxy `get` handlers triggered during traversal.
  */
 export declare function traverse(value: any, seen?: Set<any>): any;
 /**
- * Creates a deep clone of a value.
- * Handles primitives, Dates, Arrays, Maps, Sets, and plain objects.
- * Includes cycle detection.
- * @param value The value to clone.
- * @param seen A WeakMap to handle circular references during recursion.
- * @returns A deep clone of the value.
+ * creates a deep clone of a value.
+ * includes cycle detection using a weakmap.
  */
 export declare function deepClone<T>(value: T, seen?: WeakMap<WeakKey, any>): T;

package/dist/utils.js

@@ -1,20 +1,22 @@
-// Cache for memoized deepEqual results with cleanup
+// cache for memoized deepEqual results, using weakmap to avoid memory leaks
 const deepEqualCache = new WeakMap();
-const MAX_CACHE_SIZE = 1000; // Prevent unbounded growth
-// Path traversal cache with LRU-like behavior
+const MAX_CACHE_SIZE = 1000;
+// path traversal cache (object -> pathString -> value) with lru-like behavior
+// weakmap for the root object ensures the cache entry is garbage collected when the object is
 export const pathCache = new WeakMap();
-const pathCacheSize = new WeakMap();
-// Path concatenation cache with size limit
+const pathCacheSize = new WeakMap(); // track individual map sizes
+// path concatenation cache ('a.b.c' -> ['a', 'b', 'c']) with size limit
 export const pathConcatCache = new Map();
 const MAX_PATH_CACHE_SIZE = 1000;
-// Global seen map for circular reference detection
+// global weakmap for circular reference detection during deep operations like clone or equal
 export const globalSeen = new WeakMap();
-// Global cache for proxy wrappers
+// global cache to reuse proxy wrappers for the same original object
 export const wrapperCache = new WeakMap();
+// simple lru-like cleanup for individual object path caches
 function cleanupPathCache(root) {
     const cache = pathCache.get(root);
     if (cache && pathCacheSize.get(root) > MAX_CACHE_SIZE) {
-        // Clear oldest entries (first 20%)
+        // clear oldest entries (first 20%)
         const entriesToRemove = Math.floor(MAX_CACHE_SIZE * 0.2);
         let count = 0;
         for (const key of cache.keys()) {
@@ -26,9 +28,10 @@ function cleanupPathCache(root) {
         pathCacheSize.set(root, MAX_CACHE_SIZE - entriesToRemove);
     }
 }
+// simple lru-like cleanup for the global path concatenation cache
 function cleanupPathConcatCache() {
     if (pathConcatCache.size > MAX_PATH_CACHE_SIZE) {
-        // Remove oldest entries (first 20%)
+        // remove oldest entries (first 20%)
         const entriesToRemove = Math.floor(MAX_PATH_CACHE_SIZE * 0.2);
         let count = 0;
         for (const key of pathConcatCache.keys()) {
@@ -40,216 +43,176 @@ function cleanupPathConcatCache() {
     }
 }
 export function deepEqual(a, b, seen = globalSeen) {
-    // Fast path for primitive equality
     if (a === b)
         return true;
-    // Fast path for null/undefined
     if (a == null || b == null)
         return a === b;
-    // Fast path for different types
     if (typeof a !== typeof b)
         return false;
-    // Fast path for Date objects
     if (a instanceof Date && b instanceof Date)
         return a.getTime() === b.getTime();
-    // Fast path for non-objects
     if (typeof a !== 'object')
         return false;
-    // Fast path for different array types
     if (Array.isArray(a) !== Array.isArray(b))
         return false;
-    // Check for circular references
+    // handle circular references
     if (seen.has(a))
         return seen.get(a) === b;
     seen.set(a, b);
-    // Check cache for memoized results
+    // check memoization cache before diving deeper
     if (deepEqualCache.has(a) && deepEqualCache.get(a)?.has(b)) {
         return deepEqualCache.get(a).get(b);
     }
-    // Initialize cache for this object if needed
     if (!deepEqualCache.has(a)) {
         deepEqualCache.set(a, new WeakMap());
     }
     let result;
-    // Compare arrays
     if (Array.isArray(a)) {
-        if (a.length !== b.length) {
-            result = false;
-        }
-        else {
-            result = a.every((val, idx) => deepEqual(val, b[idx], seen));
-        }
+        result = a.length === b.length && a.every((val, idx) => deepEqual(val, b[idx], seen));
     }
     else {
-        // Compare objects
         const keysA = Object.keys(a);
         const keysB = Object.keys(b);
-        if (keysA.length !== keysB.length) {
-            result = false;
-        }
-        else {
-            result = keysA.every(key => deepEqual(a[key], b[key], seen));
-        }
+        result = keysA.length === keysB.length && keysA.every(key => Object.prototype.hasOwnProperty.call(b, key) && deepEqual(a[key], b[key], seen));
     }
-    // Cache the result
+    // cache the result before returning
     deepEqualCache.get(a).set(b, result);
     return result;
 }
-// Helper to safely get from path cache with cleanup
 export function getFromPathCache(root, pathKey) {
     const cache = pathCache.get(root);
     if (!cache)
         return undefined;
     const result = cache.get(pathKey);
     if (result !== undefined) {
-        // Move to end (most recently used)
+        // simulate lru by deleting and re-setting the key
         cache.delete(pathKey);
         cache.set(pathKey, result);
     }
     return result;
 }
-// Helper to safely set in path cache with cleanup
 export function setInPathCache(root, pathKey, value) {
     if (!pathCache.has(root)) {
         pathCache.set(root, new Map());
         pathCacheSize.set(root, 0);
     }
     const cache = pathCache.get(root);
-    const size = pathCacheSize.get(root);
-    // If key exists, remove it first (will be added at end)
-    if (cache.has(pathKey)) {
-        cache.delete(pathKey);
+    // adjust size only if the key is new
+    if (!cache.has(pathKey)) {
+        pathCacheSize.set(root, pathCacheSize.get(root) + 1);
+    }
+    else {
+        cache.delete(pathKey); // remove old entry before adding to end
     }
     cache.set(pathKey, value);
-    pathCacheSize.set(root, size + 1);
-    cleanupPathCache(root);
+    cleanupPathCache(root); // check if cleanup is needed after adding
 }
-// Helper to safely get/set path concatenation with cleanup
 export function getPathConcat(path) {
     const result = pathConcatCache.get(path);
     if (result !== undefined) {
-        // Move to end (most recently used)
+        // simulate lru
         pathConcatCache.delete(path);
         pathConcatCache.set(path, result);
     }
     return result;
 }
 export function setPathConcat(path, value) {
+    // delete first to ensure it's added at the end (most recent)
+    if (pathConcatCache.has(path)) {
+        pathConcatCache.delete(path);
+    }
     pathConcatCache.set(path, value);
-    cleanupPathConcatCache();
+    cleanupPathConcatCache(); // check size limit
 }
-// Helper to check if a value is an object (and not null)
 function isObject(val) {
     return val !== null && typeof val === 'object';
 }
 /**
- * Recursively traverses an object to track all nested properties.
- * Used for deep watching.
- * @param value - The value to traverse.
- * @param seen - A Set to handle circular references.
+ * recursively traverses an object or array, accessing each property/element.
+ * used by `watch` with `deep: true` to establish dependencies on all nested properties.
+ * the actual tracking is done by the proxy `get` handlers triggered during traversal.
  */
 export function traverse(value, seen = new Set()) {
     if (!isObject(value) || seen.has(value)) {
         return value;
     }
     seen.add(value);
-    // Traverse arrays
     if (Array.isArray(value)) {
-        // Access length for tracking
-        value.length;
+        value.length; // track length
         for (let i = 0; i < value.length; i++) {
             traverse(value[i], seen);
         }
     }
-    // Traverse Sets and Maps
     else if (value instanceof Set || value instanceof Map) {
         for (const v of value) {
-            // For Maps, traverse both keys (if objects) and values
-            if (Array.isArray(v)) {
-                traverse(v[0], seen); // Key
-                traverse(v[1], seen); // Value
+            if (Array.isArray(v)) { // map entries [key, value]
+                traverse(v[0], seen); // key
+                traverse(v[1], seen); // value
             }
-            else {
-                traverse(v, seen); // Value for Set
+            else { // set values
+                traverse(v, seen);
             }
         }
-        // --- Stop after handling Map/Set --- 
-        return value;
+        return value; // no need to iterate plain object keys for map/set
     }
-    // Traverse plain objects (Only if not Array, Map, or Set)
     else {
         for (const key in value) {
-            // Access the property to trigger tracking via the proxy's get handler
             traverse(value[key], seen);
         }
     }
     return value;
 }
 /**
- * Creates a deep clone of a value.
- * Handles primitives, Dates, Arrays, Maps, Sets, and plain objects.
- * Includes cycle detection.
- * @param value The value to clone.
- * @param seen A WeakMap to handle circular references during recursion.
- * @returns A deep clone of the value.
+ * creates a deep clone of a value.
+ * includes cycle detection using a weakmap.
  */
 export function deepClone(value, seen = new WeakMap()) {
-    // Primitives and null are returned directly
     if (value === null || typeof value !== 'object') {
         return value;
     }
-    // Handle Dates
     if (value instanceof Date) {
         return new Date(value.getTime());
     }
-    // Handle cycles
     if (seen.has(value)) {
         return seen.get(value);
     }
-    // Handle Arrays
     if (Array.isArray(value)) {
         const newArray = [];
-        seen.set(value, newArray);
+        seen.set(value, newArray); // store ref before recursing
         for (let i = 0; i < value.length; i++) {
             newArray[i] = deepClone(value[i], seen);
         }
         return newArray;
     }
-    // Handle Maps
     if (value instanceof Map) {
         const newMap = new Map();
-        seen.set(value, newMap);
+        seen.set(value, newMap); // store ref before recursing
         value.forEach((val, key) => {
-            // Clone both key and value in case they are objects
             newMap.set(deepClone(key, seen), deepClone(val, seen));
         });
         return newMap;
     }
-    // Handle Sets
     if (value instanceof Set) {
         const newSet = new Set();
-        seen.set(value, newSet);
+        seen.set(value, newSet); // store ref before recursing
         value.forEach(val => {
             newSet.add(deepClone(val, seen));
         });
         return newSet;
     }
-    // Handle plain objects
-    // Create object with same prototype
+    // handle plain objects
     const newObject = Object.create(Object.getPrototypeOf(value));
-    seen.set(value, newObject);
-    // Copy properties
+    seen.set(value, newObject); // store ref before recursing
     for (const key in value) {
         if (Object.prototype.hasOwnProperty.call(value, key)) {
             newObject[key] = deepClone(value[key], seen);
         }
     }
-    // Copy symbol properties (if any)
+    // copy symbol properties
     const symbolKeys = Object.getOwnPropertySymbols(value);
     for (const symbolKey of symbolKeys) {
-        // Check if property descriptor exists and has get/set or is value
         const descriptor = Object.getOwnPropertyDescriptor(value, symbolKey);
-        if (descriptor && (descriptor.value !== undefined || descriptor.get || descriptor.set)) {
+        if (descriptor && Object.prototype.propertyIsEnumerable.call(value, symbolKey)) {
             newObject[symbolKey] = deepClone(value[symbolKey], seen);
         }
     }

package/dist/watch.d.ts

@@ -7,13 +7,8 @@ export interface WatchOptions {
     deep?: boolean;
 }
 /**
- * Watches a reactive source and runs a callback when it changes
- *
- * @param source - A function that returns the value to watch
- * @param callback - Function to call when the source changes
- * @param options - Watch options (immediate, deep)
- * @returns A function to stop watching
+ * watches a reactive source (getter function or reactive object/ref)
+ * and runs a callback when the source's value changes.
  */
-export declare function watch<T = any>(sourceInput: WatchSourceInput<T>, // Renamed parameter
-callback: WatchCallback<T>, options?: WatchOptions): WatchStopHandle;
+export declare function watch<T = any>(sourceInput: WatchSourceInput<T>, callback: WatchCallback<T>, options?: WatchOptions): WatchStopHandle;
 export {};