@yiin/reactive-proxy-state 1.0.4 → 1.0.6

package/dist/watch.js

@@ -1,74 +1,44 @@
 import { watchEffect } from './watchEffect';
 import { traverse, deepClone } from './utils';
 /**
- * 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 function watch(sourceInput, // Renamed parameter
-callback, options = {}) {
-    // Default deep to true unless explicitly false
+export function watch(sourceInput, callback, options = {}) {
     const { immediate = false, deep = true } = options;
-    // Normalize sourceInput to always be a function
+    // normalize source to always be a getter function
     const source = typeof sourceInput === 'function'
         ? sourceInput
         : () => sourceInput;
     let oldValue;
     let initialized = false;
-    // Use watchEffect to track dependencies and re-run when they change
+    // use watchEffect internally to handle dependency tracking
     const stopEffect = watchEffect(() => {
-        // 1. Run the source function to get the current value
         const currentValue = source();
-        // Determine if deep watching is needed for tracking
-        // Use the defaulted 'deep' value
-        let needsDeepTracking = deep === true;
-        // This check becomes redundant if deep defaults to true, but keep for potential explicit {deep: false} on collections?
-        // Maybe simplify: if deep is true, always traverse.
-        /*
-        if (!needsDeepTracking && currentValue && typeof currentValue === 'object') {
-            if (Array.isArray(currentValue) || currentValue instanceof Map || currentValue instanceof Set) {
-                needsDeepTracking = true; // Track collections even if deep:false? Vue does shallow on collections by default.
-            }
-        }
-        */
-        // 2. If deep tracking needed, traverse the value *for tracking purposes only*
-        if (needsDeepTracking) {
-            traverse(currentValue); // Discard result, only needed for effect tracking
+        // if deep watching, traverse the current value to track nested dependencies
+        if (deep) {
+            traverse(currentValue);
         }
-        // 3. Compare the actual currentValue with the oldValue
         if (initialized) {
             let hasChanged = false;
-            // Use the defaulted 'deep' value for comparison logic
-            if (!deep) {
-                hasChanged = currentValue !== oldValue;
-            }
-            else {
-                // For deep watches, the effect running *implies* a relevant change occurred.
-                // The traverse() call ensures dependencies were tracked. If the effect
-                // runs, we assume a change happened without needing deepEqual.
-                hasChanged = true;
-            }
+            // for deep watches, the effect running implies a dependency changed.
+            // for shallow, explicitly check reference equality.
+            hasChanged = deep || currentValue !== oldValue;
             if (hasChanged) {
-                // Get the value to pass as the previous oldValue to the callback
                 const prevOldValue = oldValue;
-                // Update the stored oldValue. Clone *only if* deep watching is enabled.
+                // store a clone for deep watches to pass as the correct oldValue next time
                 oldValue = deep ? deepClone(currentValue) : currentValue;
                 callback(currentValue, prevOldValue);
             }
         }
         else {
-            // First run: establish initial oldValue (cloned if deep) and handle immediate call
+            // first run: store initial value (cloned if deep) and run immediate callback if requested
             oldValue = deep ? deepClone(currentValue) : currentValue;
             initialized = true;
             if (immediate) {
-                // Pass undefined as oldValue for immediate calls
-                callback(currentValue, undefined);
+                callback(currentValue, undefined); // pass undefined as oldValue for immediate
             }
         }
-    });
-    // Return the stop handle from watchEffect
+    }, { lazy: false }); // run immediately (watchEffect handles `immediate` option internally)
     return stopEffect;
 }

package/dist/watchEffect.d.ts

@@ -14,15 +14,19 @@ export interface TrackedEffect<T = any> {
 export declare let activeEffect: TrackedEffect<any> | null;
 export declare function setActiveEffect(effect: TrackedEffect<any> | null): void;
 /**
- * Clean up dependencies for a specific effect
+ * removes an effect from all dependency sets it belongs to.
+ * this is crucial to prevent memory leaks and unnecessary updates when an effect is stopped or re-run.
  */
 export declare function cleanupEffect(effect: TrackedEffect<any>): void;
 /**
- * Track a property access for the active effect
+ * establishes a dependency between the currently active effect and a specific object property.
+ * called by proxy getters or ref getters.
  */
 export declare function track(target: object, key: string | symbol): void;
 /**
- * Trigger effects associated with a property (Synchronous Only)
+ * triggers all active effects associated with a specific object property.
+ * called by proxy setters/deleters or ref setters.
+ * currently runs effects synchronously.
  */
 export declare function trigger(target: object, key: string | symbol): void;
 export interface WatchEffectOptions {
@@ -42,8 +46,9 @@ export interface WatchEffectOptions {
     }) => void;
 }
 /**
- * Runs a function and re-runs it when its reactive dependencies change.
- * Returns a stop handle that also exposes the effect instance.
+ * runs a function immediately, tracks its reactive dependencies, and re-runs it
+ * synchronously whenever any of those dependencies change.
+ * returns a stop handle to manually stop the effect.
  */
 export declare function watchEffect<T>(effectCallback: EffectCallback<T>, options?: WatchEffectOptions): WatchEffectStopHandle<T>;
 export {};

package/dist/watchEffect.js

@@ -1,139 +1,154 @@
-// Track currently running effect
-// Note: activeEffect can hold effects with different return types
+// tracks the currently executing effect to establish dependencies
 export let activeEffect = null;
-// Setter function for activeEffect
+// allows setting the active effect, used internally by the effect runner
 export function setActiveEffect(effect) {
     activeEffect = effect;
 }
-// Store for tracking dependencies: target -> key -> Set<TrackedEffect>
-// The Sets will hold effects of potentially different types
+// storage for dependencies: target object -> property key -> set of effects that depend on this key
 const targetMap = new WeakMap();
 /**
- * Clean up dependencies for a specific effect
+ * removes an effect from all dependency sets it belongs to.
+ * this is crucial to prevent memory leaks and unnecessary updates when an effect is stopped or re-run.
  */
 export function cleanupEffect(effect) {
     if (effect.dependencies) {
         effect.dependencies.forEach(dep => {
+            // remove this effect from the dependency set associated with a specific target/key
             dep.delete(effect);
         });
-        effect.dependencies.clear(); // Clear the set for the next run
+        // clear the effect's own list of dependencies for the next run
+        effect.dependencies.clear();
     }
 }
 /**
- * Track a property access for the active effect
+ * establishes a dependency between the currently active effect and a specific object property.
+ * called by proxy getters or ref getters.
  */
 export function track(target, key) {
-    // Only track if there's an active effect that should be running
+    // do nothing if there is no active effect or if the effect is stopped
     if (!activeEffect || !activeEffect.active)
         return;
-    // Get the dependency map for this target
+    // get or create the dependency map for the target object
     let depsMap = targetMap.get(target);
     if (!depsMap) {
         depsMap = new Map();
         targetMap.set(target, depsMap);
     }
-    // Get the set of effects for this property
+    // get or create the set of effects for the specific property key
     let dep = depsMap.get(key);
     if (!dep) {
         dep = new Set();
         depsMap.set(key, dep);
     }
-    // Add the active effect to the set if not already present
-    // Ensure we are adding the correct type to the Set
+    // add the current effect to the dependency set if it's not already there
     const effectToAdd = activeEffect;
     if (!dep.has(effectToAdd)) {
         dep.add(effectToAdd);
-        // Add this dep set to the effect's own dependency list for cleanup
+        // also add this dependency set to the effect's own tracking list for cleanup purposes
         if (!effectToAdd.dependencies) {
             effectToAdd.dependencies = new Set();
         }
         effectToAdd.dependencies.add(dep);
-        // Trigger onTrack if available
+        // trigger the onTrack debug hook if provided
         if (effectToAdd.options?.onTrack) {
-            // Pass the raw user callback, not the internal effect object
+            // pass the original user callback to the hook, not the internal wrapper
             effectToAdd.options.onTrack({ effect: effectToAdd._rawCallback, target, key, type: 'track' });
         }
     }
 }
 /**
- * Trigger effects associated with a property (Synchronous Only)
+ * triggers all active effects associated with a specific object property.
+ * called by proxy setters/deleters or ref setters.
+ * currently runs effects synchronously.
  */
 export function trigger(target, key) {
     const depsMap = targetMap.get(target);
     if (!depsMap)
-        return;
-    // Use a Set to avoid duplicate runs within the same trigger
+        return; // no effects tracked for this target
+    // use a set to collect effects to run, avoiding duplicate executions within the same trigger cycle
     const effectsToRun = new Set();
+    // helper to add effects from a specific dependency set to the run queue
     const addEffects = (depKey) => {
         const dep = depsMap.get(depKey);
         if (dep) {
             dep.forEach(effect => {
-                // Avoid infinite loops by not scheduling the currently running effect
-                // Also check if effect is active
+                // avoid triggering the effect if it's the one currently running (prevents infinite loops)
+                // also ensure the effect hasn't been stopped
                 if (effect !== activeEffect && effect.active) {
                     effectsToRun.add(effect);
                 }
             });
         }
     };
+    // add effects associated with the specific key that changed
     addEffects(key);
-    // Schedule or run effects
+    // todo: consider adding effects associated with iteration keys (like Symbol.iterator or 'length' for arrays) if applicable
+    // schedule or run the collected effects
     effectsToRun.forEach(effect => {
-        // Trigger onTrigger if available
+        // trigger the onTrigger debug hook if provided
         if (effect.options?.onTrigger) {
             effect.options.onTrigger({ effect: effect._rawCallback, target, key, type: 'trigger' });
         }
-        // Use scheduler if available, otherwise run directly
+        // use a custom scheduler if provided, otherwise run the effect synchronously
         if (effect.options?.scheduler) {
             effect.options.scheduler(effect.run);
         }
         else {
-            effect.run(); // Run the effect's wrapper
+            effect.run(); // execute the effect's wrapper function (`run`)
         }
     });
 }
 /**
- * Runs a function and re-runs it when its reactive dependencies change.
- * Returns a stop handle that also exposes the effect instance.
+ * runs a function immediately, tracks its reactive dependencies, and re-runs it
+ * synchronously whenever any of those dependencies change.
+ * returns a stop handle to manually stop the effect.
  */
 export function watchEffect(effectCallback, options = {}) {
-    // The core runner function that handles cleanup, activeEffect setting, and execution
+    // the wrapper function that manages the effect lifecycle (cleanup, tracking, execution)
     const run = () => {
-        if (!effectFn.active)
-            return effectCallback(); // If stopped, just return value (though likely undefined)
+        if (!effectFn.active) {
+            // if stopped, potentially run the callback once without tracking, though behavior might be undefined
+            // vue's behavior here might differ, review needed if exact compatibility matters
+            try {
+                return effectCallback();
+            }
+            catch (e) {
+                console.error("error in stopped watchEffect callback:", e);
+                // decide on return value for stopped effects that error
+                return undefined; // or rethrow?
+            }
+        }
         const previousEffect = activeEffect;
         try {
-            cleanupEffect(effectFn);
-            setActiveEffect(effectFn);
-            return effectCallback(); // Execute the user's function
+            cleanupEffect(effectFn); // clean up dependencies from the previous run
+            setActiveEffect(effectFn); // set this effect as the one currently tracking
+            return effectCallback(); // execute the user's function, triggering tracks
         }
         finally {
-            setActiveEffect(previousEffect);
+            setActiveEffect(previousEffect); // restore the previous active effect
         }
     };
-    // The effect object itself
+    // create the internal effect object
     const effectFn = {
         run: run,
-        dependencies: new Set(),
+        dependencies: new Set(), // initialize empty dependencies
         options: options,
-        active: true,
-        _rawCallback: effectCallback
+        active: true, // start as active
+        _rawCallback: effectCallback // store the original callback
     };
-    // Run effect immediately unless lazy
+    // run the effect immediately unless the `lazy` option is true
     if (!options.lazy) {
         effectFn.run();
     }
-    // Create the stop handle function
+    // create the function that stops the effect
     const stopHandle = () => {
         if (effectFn.active) {
-            cleanupEffect(effectFn);
-            effectFn.active = false;
-            // Clear references
-            // effectFn.dependencies = undefined; // Keep dependencies for potential re-activation?
-            // effectFn.options = undefined;
+            cleanupEffect(effectFn); // remove from dependency lists
+            effectFn.active = false; // mark as inactive
+            // potentially clear other properties like dependencies/options if desired, but keeping them might allow restart? TBD.
         }
     };
-    // Attach the effect instance to the stop handle
+    // attach the effect instance to the stop handle for potential advanced usage
     stopHandle.effect = effectFn;
     return stopHandle;
 }

package/dist/wrapArray.js

@@ -3,20 +3,19 @@ import { reactive } from './reactive';
 import { wrapMap } from './wrapMap';
 import { wrapSet } from './wrapSet';
 import { track, trigger } from './watchEffect';
-// Pre-allocate type check function
+// avoid repeated typeof checks
 function isObject(v) {
     return v && typeof v === 'object';
 }
 export function wrapArray(arr, emit, path) {
-    // Check wrapper cache first
+    // reuse existing proxy if available for performance
     const cachedProxy = wrapperCache.get(arr);
     if (cachedProxy)
         return cachedProxy;
     const proxy = new Proxy(arr, {
         get(target, prop, receiver) {
-            // Original track call - might be redundant if handled below but keep for now
             track(target, prop);
-            // Handle specific array mutation methods first
+            // handle specific array mutation methods that require custom logic and event emission
             switch (prop) {
                 case 'push':
                     track(target, 'length');
@@ -28,7 +27,7 @@ export function wrapArray(arr, emit, path) {
                             const event = {
                                 action: 'array-push',
                                 path: path,
-                                key: oldLength, // Start index was the old length
+                                key: oldLength, // start index was the old length
                                 items: items
                             };
                             emit(event);
@@ -132,15 +131,11 @@ export function wrapArray(arr, emit, path) {
                         }
                         return result;
                     };
-                // Handle iteration methods
+                // handle methods that rely on iteration state
                 case Symbol.iterator:
-                case 'values': // values() returns an iterator
-                case 'keys': // keys() returns an iterator
-                case 'entries': // entries() returns an iterator
-                    // Track dependency on iteration
-                    track(target, Symbol.iterator);
-                    // Fall through to Reflect.get and bind below
-                    break;
+                case 'values':
+                case 'keys':
+                case 'entries':
                 case 'forEach':
                 case 'map':
                 case 'filter':
@@ -150,38 +145,34 @@ export function wrapArray(arr, emit, path) {
                 case 'findIndex':
                 case 'every':
                 case 'some':
-                case 'join': // join depends on iteration
-                    // These methods depend on iteration
+                case 'join':
                     track(target, Symbol.iterator);
-                    // Fall through to Reflect.get and bind below
+                    // fall through to default behavior (usually binding)
                     break;
                 case 'length':
-                    // Explicitly track length access
                     track(target, 'length');
                     return Reflect.get(target, prop, receiver);
             }
-            // Fallback for index access and other properties
             const value = Reflect.get(target, prop, receiver);
-            // Handle index access: wrap retrieved element if it's an object
+            // determine if the property access is numeric array index access
             const isNumericIndex = typeof prop === 'number' || (typeof prop === 'string' && !isNaN(parseInt(prop, 10)));
             if (isNumericIndex) {
-                // Track access to specific index
                 track(target, String(prop));
                 if (!isObject(value))
                     return value;
-                // Check wrapper cache for the element
+                // reuse existing proxy for nested object/array if available
                 const cachedValueProxy = wrapperCache.get(value);
                 if (cachedValueProxy)
                     return cachedValueProxy;
-                // Calculate path for the element
+                // calculate the nested path for the element, optimizing with caching
                 const propKey = String(prop);
-                const pathKey = path.length > 0 ? `${path.join('.')}.${propKey}` : propKey; // Fix pathKey generation for index 0
+                const pathKey = path.length > 0 ? `${path.join('.')}.${propKey}` : propKey;
                 let newPath = getPathConcat(pathKey);
                 if (newPath === undefined) {
                     newPath = path.concat(propKey);
                     setPathConcat(pathKey, newPath);
                 }
-                // Wrap based on type (no longer passing seen)
+                // recursively wrap nested structures
                 if (Array.isArray(value))
                     return wrapArray(value, emit, newPath);
                 if (value instanceof Map)
@@ -189,12 +180,10 @@ export function wrapArray(arr, emit, path) {
                 if (value instanceof Set)
                     return wrapSet(value, emit, newPath);
                 if (value instanceof Date)
-                    return new Date(value.getTime()); // Dates are not proxied
-                // Default to reactive for plain objects
+                    return new Date(value.getTime()); // dates are not proxied, return a copy
                 return reactive(value, emit, newPath);
             }
-            // For non-numeric properties or properties that aren't objects, return value directly
-            // Also handle functions bound to the target
+            // ensure functions accessed directly are bound to the original target
             if (typeof value === 'function') {
                 return value.bind(target);
             }
@@ -202,18 +191,19 @@ export function wrapArray(arr, emit, path) {
         },
         set(target, prop, value, receiver) {
             const oldValue = target[prop];
-            // Fast path for primitive equality
+            // avoid unnecessary triggers if value hasn't changed
             if (oldValue === value)
                 return true;
-            // Deep equality check with new WeakMap
             if (isObject(oldValue) && isObject(value) && deepEqual(oldValue, value, new WeakMap()))
                 return true;
             const descriptor = Reflect.getOwnPropertyDescriptor(target, prop);
             const result = Reflect.set(target, prop, value, receiver);
             const isNumericIndex = typeof prop === 'number' || (typeof prop === 'string' && !isNaN(parseInt(String(prop))));
+            // emit event and trigger effects only if the set was successful and wasn't intercepted by a setter
+            // (unless it's a direct numeric index set, which doesn't have a descriptor.set)
             if (result && (!descriptor || !descriptor.set || isNumericIndex)) {
                 const propKey = String(prop);
-                const pathKey = path.length > 0 ? `${path.join('.')}.${propKey}` : propKey; // Fix pathKey generation for index 0
+                const pathKey = path.length > 0 ? `${path.join('.')}.${propKey}` : propKey;
                 let newPath = getPathConcat(pathKey);
                 if (newPath === undefined) {
                     newPath = path.concat(propKey);
@@ -231,7 +221,7 @@ export function wrapArray(arr, emit, path) {
             return result;
         }
     });
-    // Cache the newly created proxy before returning
+    // cache the newly created proxy before returning
     wrapperCache.set(arr, proxy);
     return proxy;
 }