@yiin/reactive-proxy-state 1.0.8 → 1.0.10

package/README.md

@@ -24,6 +24,94 @@ bun add @yiin/reactive-proxy-state
 2.  **Dependency Tracking**: When code inside a `watchEffect` reads a property of a reactive object, a dependency is established.
 3.  **Effect Triggering**: When a tracked property is mutated, any dependent effects (`watchEffect` or `watch` callbacks) are re-run **synchronously**.
 
+## State Synchronization with `updateState`
+
+A key feature is `updateState`, which allows applying changes from a plain JavaScript object (often received from serialization) onto an existing reactive state object. It intelligently updates properties, adds/removes array elements, and modifies Maps/Sets to match the target structure, triggering reactive effects only where necessary.
+
+This is typically used with the `emit` callback of `reactive` for state synchronization:
+
+```typescript
+import { reactive, updateState, watchEffect } from '@yiin/reactive-proxy-state';
+
+// Assume these functions exist:
+// - getInitialStateFromServer(): Fetches the initial state snapshot.
+// - sendEventToClient(event): Sends a state change event to the client.
+// - listenForServerEvents(callback): Sets up a listener for events from the server.
+
+// --- Source State (e.g., Server) ---
+const sourceData = {
+  counter: 0,
+  user: { name: 'Alice' },
+  items: ['a']
+};
+
+// 1. Server creates reactive state & emits deltas via sendEventToClient
+const sourceState = reactive(sourceData, sendEventToClient);
+
+
+// --- Client Initialization & Sync ---
+// 2. Client creates its reactive state holder *before* data arrives
+const targetState = reactive({});
+console.log('Client: Initial empty target state created:', targetState);
+
+// 3. Client watches its local state for changes (e.g., for UI updates)
+watchEffect(() => {
+  console.log('Client: Target state updated:', targetState);
+});
+// Initial output: Client: Target state updated: {}
+
+// 4. Client fetches the initial state snapshot
+const initialSnapshot = getInitialStateFromServer(); // Assume fetches { counter: 0, ... }
+console.log('\n--- Client Received Initial Snapshot ---');
+console.log(initialSnapshot);
+
+// 5. Client applies the initial snapshot using a 'replace' action
+// (Requires updateState implementation to support action: 'replace')
+updateState(targetState, {
+  action: 'replace', 
+  path: [], // Apply to the root
+  newValue: initialSnapshot
+});
+// Output after 'replace': 
+// Client: Target state updated: { counter: 0, user: { name: 'Alice' }, items: [ 'a' ] }
+
+// 6. Client starts listening for subsequent delta events from the server
+listenForServerEvents((event) => {
+  console.log(`Client: Received delta event <- Server:`, event);
+  // Apply the delta event normally
+  updateState(targetState, event);
+});
+
+
+// --- Subsequent Server Modifications ---
+// 7. Server state is modified *after* the client has initialized
+console.log('\n--- Server Modifying State (Post-Init) ---');
+sourceState.counter++;
+// Output: (sendEventToClient called with { action: 'set', path: [ 'counter' ], ... })
+sourceState.user.name = 'Charlie';
+// Output: (sendEventToClient called with { action: 'set', path: [ 'user', 'name' ], ... })
+sourceState.items.push('b');
+// Output: (sendEventToClient called with { action: 'array-push', path: [ 'items' ], ... })
+
+// --- Delta Events arrive and are processed asynchronously by the client ---
+
+// Example Console Output Order (assuming async processing):
+// Client: Initial empty target state created: {}
+// Client: Target state updated: {}
+// --- Client Received Initial Snapshot ---
+// { counter: 0, user: { name: 'Alice' }, items: ['a'] }
+// Client: Target state updated: { counter: 0, user: { name: 'Alice' }, items: [ 'a' ] } // From 'replace'
+// --- Server Modifying State (Post-Init) ---
+// Client: Received delta event <- Server: { action: 'set', path: [ 'counter' ], oldValue: 0, newValue: 1 }
+// Client: Target state updated: { counter: 1, user: { name: 'Alice' }, items: [ 'a' ] }
+// Client: Received delta event <- Server: { action: 'set', path: [ 'user', 'name' ], oldValue: 'Alice', newValue: 'Charlie' }
+// Client: Target state updated: { counter: 1, user: { name: 'Charlie' }, items: [ 'a' ] }
+// Client: Received delta event <- Server: { action: 'array-push', path: [ 'items' ], key: 1, items: [ 'b' ] }
+// Client: Target state updated: { counter: 1, user: { name: 'Charlie' }, items: [ 'a', 'b' ] }
+```
+
+See the [`updateState` documentation](./docs/api/update-state.md) and [`reactive` documentation](./docs/api/reactive.md) for more details on event emission and application.
+
 ## API
 
 ### `reactive<T extends object>(obj: T): T`

package/dist/computed.js

@@ -1,4 +1,4 @@
-import { watchEffect, track, trigger } from './watchEffect';
+import { watchEffect, track, trigger } from './watch-effect';
 import { isRefSymbol } from './ref';
 // symbol for identifying computed refs
 const isComputedSymbol = Symbol('isComputed');

package/dist/index.d.ts

@@ -2,10 +2,10 @@ export * from './types';
 export * from './utils';
 export * from './state';
 export * from './reactive';
-export * from './wrapArray';
-export * from './wrapMap';
-export * from './wrapSet';
+export * from './wrap-array';
+export * from './wrap-map';
+export * from './wrap-set';
 export * from './watch';
-export * from './watchEffect';
+export * from './watch-effect';
 export * from './ref';
 export * from './computed';

package/dist/index.js

@@ -2,10 +2,10 @@ export * from './types';
 export * from './utils';
 export * from './state';
 export * from './reactive';
-export * from './wrapArray';
-export * from './wrapMap';
-export * from './wrapSet';
+export * from './wrap-array';
+export * from './wrap-map';
+export * from './wrap-set';
 export * from './watch';
-export * from './watchEffect';
+export * from './watch-effect';
 export * from './ref';
 export * from './computed';

package/dist/reactive.js

@@ -1,8 +1,8 @@
 import { deepEqual, globalSeen, getPathConcat, setPathConcat } from './utils';
-import { wrapArray } from './wrapArray';
-import { wrapMap } from './wrapMap';
-import { wrapSet } from './wrapSet';
-import { track, trigger } from './watchEffect';
+import { wrapArray } from './wrap-array';
+import { wrapMap } from './wrap-map';
+import { wrapSet } from './wrap-set';
+import { track, trigger } from './watch-effect';
 // avoid repeated typeof checks
 function isObject(v) {
     return v && typeof v === 'object';

package/dist/ref.d.ts

@@ -21,3 +21,19 @@ export declare function isRef<T>(r: any): r is Ref<T>;
  * otherwise returns the argument itself. this is a sugar for `isRef(val) ? val.value : val`.
  */
 export declare function unref<T>(refValue: T | Ref<T>): T;
+/**
+ * Converts an object's properties to reactive refs.
+ * This is useful when you want to destructure reactive objects but maintain reactivity.
+ * @param object The reactive object to convert to refs
+ * @returns An object with the same properties, where each property is a ref connected to the original object
+ */
+export declare function toRefs<T extends object>(object: T): {
+    [K in keyof T]: Ref<T[K]>;
+};
+/**
+ * Creates a ref that is connected to a property on an object.
+ * @param object The source object
+ * @param key The property key
+ * @returns A ref connected to the object's property
+ */
+export declare function toRef<T extends object, K extends keyof T>(object: T, key: K): Ref<T[K]>;

package/dist/ref.js

@@ -1,4 +1,4 @@
-import { track, trigger } from './watchEffect';
+import { track, trigger } from './watch-effect';
 // Removed reactive import as ref doesn't automatically make contained objects reactive
 // import { reactive } from './reactive';
 // symbol used to identify refs internally and via isRef()
@@ -50,6 +50,37 @@ export function isRef(r) {
 export function unref(refValue) {
     return isRef(refValue) ? refValue.value : refValue;
 }
+/**
+ * Converts an object's properties to reactive refs.
+ * This is useful when you want to destructure reactive objects but maintain reactivity.
+ * @param object The reactive object to convert to refs
+ * @returns An object with the same properties, where each property is a ref connected to the original object
+ */
+export function toRefs(object) {
+    const result = {};
+    for (const key in object) {
+        result[key] = toRef(object, key);
+    }
+    return result;
+}
+/**
+ * Creates a ref that is connected to a property on an object.
+ * @param object The source object
+ * @param key The property key
+ * @returns A ref connected to the object's property
+ */
+export function toRef(object, key) {
+    return {
+        [isRefSymbol]: true,
+        get value() {
+            track(this, 'value');
+            return object[key];
+        },
+        set value(newVal) {
+            object[key] = newVal;
+        }
+    };
+}
 // Basic triggerRef function (may need refinement if used)
 /*
 export function triggerRef(ref: Ref<any>): void {

package/dist/watch-effect.d.ts

@@ -0,0 +1,54 @@
+type EffectCallback<T = any> = () => T;
+type Scheduler = (job: () => void) => void;
+export interface WatchEffectStopHandle<T = any> {
+    (): void;
+    effect: TrackedEffect<T>;
+}
+export interface TrackedEffect<T = any> {
+    run: () => T;
+    dependencies?: Set<Set<TrackedEffect<any>>>;
+    options?: WatchEffectOptions;
+    active?: boolean;
+    _rawCallback: EffectCallback<T>;
+}
+export declare let activeEffect: TrackedEffect<any> | null;
+export declare function setActiveEffect(effect: TrackedEffect<any> | null): void;
+/**
+ * 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;
+/**
+ * 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;
+/**
+ * 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 {
+    lazy?: boolean;
+    scheduler?: Scheduler;
+    onTrack?: (event: {
+        effect: EffectCallback<any>;
+        target: object;
+        key: string | symbol;
+        type: 'track';
+    }) => void;
+    onTrigger?: (event: {
+        effect: EffectCallback<any>;
+        target: object;
+        key: string | symbol;
+        type: 'trigger';
+    }) => void;
+}
+/**
+ * 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/watch-effect.js

@@ -0,0 +1,154 @@
+// tracks the currently executing effect to establish dependencies
+export let activeEffect = null;
+// allows setting the active effect, used internally by the effect runner
+export function setActiveEffect(effect) {
+    activeEffect = effect;
+}
+// storage for dependencies: target object -> property key -> set of effects that depend on this key
+const targetMap = new WeakMap();
+/**
+ * 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);
+        });
+        // clear the effect's own list of dependencies for the next run
+        effect.dependencies.clear();
+    }
+}
+/**
+ * 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) {
+    // do nothing if there is no active effect or if the effect is stopped
+    if (!activeEffect || !activeEffect.active)
+        return;
+    // 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 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 current effect to the dependency set if it's not already there
+    const effectToAdd = activeEffect;
+    if (!dep.has(effectToAdd)) {
+        dep.add(effectToAdd);
+        // 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 the onTrack debug hook if provided
+        if (effectToAdd.options?.onTrack) {
+            // pass the original user callback to the hook, not the internal wrapper
+            effectToAdd.options.onTrack({ effect: effectToAdd._rawCallback, target, key, type: 'track' });
+        }
+    }
+}
+/**
+ * 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; // 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 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);
+    // 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 the onTrigger debug hook if provided
+        if (effect.options?.onTrigger) {
+            effect.options.onTrigger({ effect: effect._rawCallback, target, key, type: 'trigger' });
+        }
+        // use a custom scheduler if provided, otherwise run the effect synchronously
+        if (effect.options?.scheduler) {
+            effect.options.scheduler(effect.run);
+        }
+        else {
+            effect.run(); // execute the effect's wrapper function (`run`)
+        }
+    });
+}
+/**
+ * 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 wrapper function that manages the effect lifecycle (cleanup, tracking, execution)
+    const run = () => {
+        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); // 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); // restore the previous active effect
+        }
+    };
+    // create the internal effect object
+    const effectFn = {
+        run: run,
+        dependencies: new Set(), // initialize empty dependencies
+        options: options,
+        active: true, // start as active
+        _rawCallback: effectCallback // store the original callback
+    };
+    // run the effect immediately unless the `lazy` option is true
+    if (!options.lazy) {
+        effectFn.run();
+    }
+    // create the function that stops the effect
+    const stopHandle = () => {
+        if (effectFn.active) {
+            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 for potential advanced usage
+    stopHandle.effect = effectFn;
+    return stopHandle;
+}

package/dist/watch.js

@@ -1,4 +1,4 @@
-import { watchEffect } from './watchEffect';
+import { watchEffect } from './watch-effect';
 import { traverse, deepClone } from './utils';
 /**
  * watches a reactive source (getter function or reactive object/ref)

package/dist/wrap-array.d.ts

@@ -0,0 +1,2 @@
+import { EmitFunction, Path } from './types';
+export declare function wrapArray<T extends any[]>(arr: T, emit: EmitFunction, path: Path): T;

package/dist/wrap-array.js

@@ -0,0 +1,237 @@
+import { deepEqual, getPathConcat, setPathConcat, wrapperCache } from './utils';
+import { reactive } from './reactive';
+import { wrapMap } from './wrap-map';
+import { wrapSet } from './wrap-set';
+import { track, trigger } from './watch-effect';
+// avoid repeated typeof checks
+function isObject(v) {
+    return v && typeof v === 'object';
+}
+export function wrapArray(arr, emit, path) {
+    // reuse existing proxy if available for performance
+    const cachedProxy = wrapperCache.get(arr);
+    if (cachedProxy)
+        return cachedProxy;
+    // cache for wrapped methods to avoid re-creating them on each call
+    const methodCache = {};
+    const proxy = new Proxy(arr, {
+        get(target, prop, receiver) {
+            track(target, prop);
+            if (methodCache[prop]) {
+                return methodCache[prop];
+            }
+            // handle specific array mutation methods that require custom logic and event emission
+            switch (prop) {
+                case 'push':
+                    track(target, 'length');
+                    methodCache[prop] = function (...items) {
+                        const oldLength = target.length;
+                        const result = target.push(...items);
+                        const newLength = target.length;
+                        if (items.length > 0) {
+                            const event = {
+                                action: 'array-push',
+                                path: path,
+                                key: oldLength, // start index was the old length
+                                items: items
+                            };
+                            emit(event);
+                            trigger(target, Symbol.iterator);
+                            if (oldLength !== newLength) {
+                                trigger(target, 'length');
+                            }
+                        }
+                        return result;
+                    };
+                    return methodCache[prop];
+                case 'pop':
+                    track(target, 'length');
+                    methodCache[prop] = function () {
+                        if (target.length === 0)
+                            return undefined;
+                        const oldLength = target.length;
+                        const poppedIndex = oldLength - 1;
+                        const oldValue = target[poppedIndex];
+                        const result = target.pop();
+                        const newLength = target.length;
+                        const event = {
+                            action: 'array-pop',
+                            path: path,
+                            key: poppedIndex,
+                            oldValue: oldValue
+                        };
+                        emit(event);
+                        trigger(target, Symbol.iterator);
+                        if (oldLength !== newLength) {
+                            trigger(target, 'length');
+                        }
+                        return result;
+                    };
+                    return methodCache[prop];
+                case 'shift':
+                    track(target, 'length');
+                    methodCache[prop] = function () {
+                        if (target.length === 0)
+                            return undefined;
+                        const oldLength = target.length;
+                        const oldValue = target[0];
+                        const result = target.shift();
+                        const newLength = target.length;
+                        const event = {
+                            action: 'array-shift',
+                            path: path,
+                            key: 0,
+                            oldValue: oldValue
+                        };
+                        emit(event);
+                        trigger(target, Symbol.iterator);
+                        if (oldLength !== newLength) {
+                            trigger(target, 'length');
+                        }
+                        return result;
+                    };
+                    return methodCache[prop];
+                case 'unshift':
+                    track(target, 'length');
+                    methodCache[prop] = function (...items) {
+                        const oldLength = target.length;
+                        const result = target.unshift(...items);
+                        const newLength = target.length;
+                        if (items.length > 0) {
+                            const event = {
+                                action: 'array-unshift',
+                                path: path,
+                                key: 0,
+                                items: items
+                            };
+                            emit(event);
+                            trigger(target, Symbol.iterator);
+                            if (oldLength !== newLength) {
+                                trigger(target, 'length');
+                            }
+                        }
+                        return result;
+                    };
+                    return methodCache[prop];
+                case 'splice':
+                    track(target, 'length');
+                    methodCache[prop] = function (start, deleteCount, ...items) {
+                        const oldLength = target.length;
+                        const actualStart = start < 0 ? Math.max(target.length + start, 0) : Math.min(start, target.length);
+                        const deleteCountNum = deleteCount === undefined ? target.length - actualStart : Number(deleteCount);
+                        const actualDeleteCount = Math.min(deleteCountNum, target.length - actualStart);
+                        const deletedItems = target.slice(actualStart, actualStart + actualDeleteCount);
+                        const result = target.splice(start, deleteCountNum, ...items);
+                        const newLength = target.length;
+                        if (actualDeleteCount > 0 || items.length > 0) {
+                            const event = {
+                                action: 'array-splice',
+                                path: path,
+                                key: actualStart,
+                                deleteCount: actualDeleteCount,
+                                items: items.length > 0 ? items : undefined,
+                                oldValues: deletedItems.length > 0 ? deletedItems : undefined
+                            };
+                            emit(event);
+                            trigger(target, Symbol.iterator);
+                            if (oldLength !== newLength) {
+                                trigger(target, 'length');
+                            }
+                        }
+                        return result;
+                    };
+                    return methodCache[prop];
+                // handle methods that rely on iteration state
+                case Symbol.iterator:
+                case 'values':
+                case 'keys':
+                case 'entries':
+                case 'forEach':
+                case 'map':
+                case 'filter':
+                case 'reduce':
+                case 'reduceRight':
+                case 'find':
+                case 'findIndex':
+                case 'every':
+                case 'some':
+                case 'join':
+                    track(target, Symbol.iterator);
+                    // fall through to default behavior (usually binding)
+                    break;
+                case 'length':
+                    track(target, 'length');
+                    return Reflect.get(target, prop, receiver);
+            }
+            const value = Reflect.get(target, prop, receiver);
+            // 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(target, String(prop));
+                if (!isObject(value))
+                    return value;
+                // reuse existing proxy for nested object/array if available
+                const cachedValueProxy = wrapperCache.get(value);
+                if (cachedValueProxy)
+                    return cachedValueProxy;
+                // calculate the nested path for the element, optimizing with caching
+                const propKey = String(prop);
+                const pathKey = path.length > 0 ? `${path.join('.')}.${propKey}` : propKey;
+                let newPath = getPathConcat(pathKey);
+                if (newPath === undefined) {
+                    newPath = path.concat(propKey);
+                    setPathConcat(pathKey, newPath);
+                }
+                // recursively wrap nested structures
+                if (Array.isArray(value))
+                    return wrapArray(value, emit, newPath);
+                if (value instanceof Map)
+                    return wrapMap(value, emit, newPath);
+                if (value instanceof Set)
+                    return wrapSet(value, emit, newPath);
+                if (value instanceof Date)
+                    return new Date(value.getTime()); // dates are not proxied, return a copy
+                return reactive(value, emit, newPath);
+            }
+            // ensure functions accessed directly are bound to the original target
+            if (typeof value === 'function') {
+                return value.bind(target);
+            }
+            return value;
+        },
+        set(target, prop, value, receiver) {
+            const oldValue = target[prop];
+            // avoid unnecessary triggers if value hasn't changed
+            if (oldValue === value)
+                return true;
+            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;
+                let newPath = getPathConcat(pathKey);
+                if (newPath === undefined) {
+                    newPath = path.concat(propKey);
+                    setPathConcat(pathKey, newPath);
+                }
+                const event = {
+                    action: 'set',
+                    path: newPath,
+                    oldValue,
+                    newValue: value
+                };
+                emit(event);
+                trigger(target, prop);
+            }
+            return result;
+        }
+    });
+    // cache the newly created proxy before returning
+    wrapperCache.set(arr, proxy);
+    return proxy;
+}

package/dist/wrap-map.d.ts

@@ -0,0 +1,2 @@
+import { EmitFunction, Path } from './types';
+export declare function wrapMap<K, V>(map: Map<K, V>, emit: EmitFunction, path: Path): Map<K, V>;

package/dist/wrap-map.js

@@ -0,0 +1,252 @@
+import { deepEqual, getPathConcat, setPathConcat, wrapperCache } from './utils';
+import { reactive } from './reactive';
+import { wrapArray } from './wrap-array';
+import { wrapSet } from './wrap-set';
+import { track, trigger } from './watch-effect';
+export function wrapMap(map, emit, path) {
+    // reuse existing proxy if available for performance
+    const cachedProxy = wrapperCache.get(map);
+    if (cachedProxy)
+        return cachedProxy;
+    // cache for wrapped methods to avoid re-creating them on each call
+    const methodCache = {};
+    const proxy = new Proxy(map, {
+        get(target, prop, receiver) {
+            track(target, prop);
+            // iteration methods need to track the iterator symbol on every access
+            // to re-establish dependency after effect cleanup, even when cached
+            if (prop === Symbol.iterator || prop === 'entries' || prop === 'values' || prop === 'keys' || prop === 'forEach') {
+                track(target, Symbol.iterator);
+            }
+            if (methodCache[prop]) {
+                return methodCache[prop];
+            }
+            if (prop === 'set') {
+                methodCache[prop] = function (key, value) {
+                    const existed = target.has(key);
+                    const oldValue = target.get(key);
+                    const oldSize = target.size;
+                    // avoid unnecessary work if value hasn't changed
+                    if (oldValue === value)
+                        return receiver;
+                    if (oldValue && typeof oldValue === 'object' && value && typeof value === 'object' && deepEqual(oldValue, value, new WeakMap()))
+                        return receiver;
+                    target.set(key, value);
+                    const newSize = target.size;
+                    // optimize path calculation by caching concatenated paths
+                    const pathKey = path.join('.');
+                    let cachedPath = getPathConcat(pathKey);
+                    if (cachedPath === undefined) {
+                        cachedPath = path;
+                        setPathConcat(pathKey, cachedPath);
+                    }
+                    const event = {
+                        action: 'map-set',
+                        path: cachedPath,
+                        key,
+                        oldValue,
+                        newValue: value
+                    };
+                    emit(event);
+                    // trigger effects based on whether it was an add or update
+                    if (!existed) {
+                        trigger(target, Symbol.iterator);
+                        if (oldSize !== newSize) {
+                            trigger(target, 'size');
+                        }
+                    }
+                    else {
+                        trigger(target, String(key));
+                    }
+                    return receiver;
+                };
+                return methodCache[prop];
+            }
+            if (prop === 'delete') {
+                methodCache[prop] = function (key) {
+                    const existed = target.has(key);
+                    if (!existed)
+                        return false;
+                    const oldValue = target.get(key);
+                    const oldSize = target.size;
+                    const result = target.delete(key);
+                    const newSize = target.size;
+                    if (result) { // only emit and trigger if delete was successful
+                        const pathKey = path.join('.');
+                        let cachedPath = getPathConcat(pathKey);
+                        if (cachedPath === undefined) {
+                            cachedPath = path;
+                            setPathConcat(pathKey, cachedPath);
+                        }
+                        const event = {
+                            action: 'map-delete',
+                            path: cachedPath,
+                            key,
+                            oldValue
+                        };
+                        emit(event);
+                        trigger(target, Symbol.iterator);
+                        if (oldSize !== newSize) {
+                            trigger(target, 'size');
+                        }
+                        trigger(target, String(key));
+                    }
+                    return result;
+                };
+                return methodCache[prop];
+            }
+            if (prop === 'clear') {
+                methodCache[prop] = function () {
+                    const oldSize = target.size;
+                    if (oldSize === 0)
+                        return;
+                    target.clear();
+                    const newSize = target.size;
+                    const event = {
+                        action: 'map-clear',
+                        path: path,
+                        key: null
+                    };
+                    emit(event);
+                    trigger(target, Symbol.iterator);
+                    if (oldSize !== newSize) {
+                        trigger(target, 'size');
+                    }
+                };
+                return methodCache[prop];
+            }
+            if (prop === 'get') {
+                // return a function that tracks the specific key only when called
+                methodCache[prop] = function (key) {
+                    track(target, String(key));
+                    const value = target.get(key);
+                    if (!value || typeof value !== 'object')
+                        return value;
+                    const cachedValueProxy = wrapperCache.get(value);
+                    if (cachedValueProxy)
+                        return cachedValueProxy;
+                    const keyString = String(key);
+                    const pathKey = path.length > 0 ? `${path.join('.')}.${keyString}` : keyString;
+                    let newPath = getPathConcat(pathKey);
+                    if (newPath === undefined) {
+                        newPath = path.concat(keyString);
+                        setPathConcat(pathKey, newPath);
+                    }
+                    // recursively wrap nested structures
+                    if (value instanceof Map)
+                        return wrapMap(value, emit, newPath);
+                    if (value instanceof Set)
+                        return wrapSet(value, emit, newPath);
+                    if (Array.isArray(value))
+                        return wrapArray(value, emit, newPath);
+                    if (value instanceof Date)
+                        return new Date(value.getTime()); // dates are not proxied, return a copy
+                    return reactive(value, emit, newPath);
+                };
+                return methodCache[prop];
+            }
+            if (prop === 'has') {
+                track(target, Symbol.iterator);
+                methodCache[prop] = function (key) {
+                    // track the specific key only when 'has' is called
+                    track(target, String(key));
+                    return target.has(key);
+                }.bind(target); // bind is still okay here, doesn't interfere with caching
+                return methodCache[prop];
+            }
+            // handle iteration methods
+            if (prop === Symbol.iterator || prop === 'entries' || prop === 'values' || prop === 'keys' || prop === 'forEach') {
+                track(target, Symbol.iterator);
+                const originalMethod = Reflect.get(target, prop, receiver);
+                // return custom iterators/foreach that wrap values during iteration
+                if (prop === 'forEach') {
+                    methodCache[prop] = (callbackfn, thisArg) => {
+                        // use the proxied .entries() to ensure values passed to callback are wrapped and tracked
+                        const entriesIterator = proxy.entries();
+                        for (const [key, value] of entriesIterator) {
+                            callbackfn.call(thisArg, value, key, proxy);
+                        }
+                    };
+                    return methodCache[prop];
+                }
+                // handle symbol.iterator, entries, values, keys by creating generator functions
+                methodCache[prop] = function* (...args) {
+                    const iterator = originalMethod.apply(target, args);
+                    for (const entry of iterator) {
+                        let keyToWrap = entry;
+                        let valueToWrap = entry;
+                        let isEntry = false;
+                        if (prop === 'entries' || prop === Symbol.iterator) {
+                            keyToWrap = entry[0];
+                            valueToWrap = entry[1];
+                            isEntry = true;
+                        }
+                        // wrap key if it's an object
+                        // note: reactivity on map keys can be complex/unexpected
+                        let wrappedKey = keyToWrap;
+                        if (isEntry && keyToWrap && typeof keyToWrap === 'object') {
+                            const pathKey = path.length > 0 ? `${path.join('.')}.${String(keyToWrap)}` : String(keyToWrap);
+                            let keyPath = getPathConcat(pathKey);
+                            if (keyPath === undefined) {
+                                keyPath = path.concat(String(keyToWrap));
+                                setPathConcat(pathKey, keyPath);
+                            }
+                            // todo: decide if map keys should be deeply reactive
+                            wrappedKey = reactive(keyToWrap, emit, keyPath);
+                        }
+                        // wrap value if it's an object
+                        let wrappedValue = valueToWrap;
+                        if (valueToWrap && typeof valueToWrap === 'object') {
+                            const cachedValueProxy = wrapperCache.get(valueToWrap);
+                            if (cachedValueProxy) {
+                                wrappedValue = cachedValueProxy;
+                            }
+                            else {
+                                const keyString = String(keyToWrap); // use original key for path
+                                const pathKey = path.length > 0 ? `${path.join('.')}.${keyString}` : keyString;
+                                let newPath = getPathConcat(pathKey);
+                                if (newPath === undefined) {
+                                    newPath = path.concat(keyString);
+                                    setPathConcat(pathKey, newPath);
+                                }
+                                if (valueToWrap instanceof Map)
+                                    wrappedValue = wrapMap(valueToWrap, emit, newPath);
+                                else if (valueToWrap instanceof Set)
+                                    wrappedValue = wrapSet(valueToWrap, emit, newPath);
+                                else if (Array.isArray(valueToWrap))
+                                    wrappedValue = wrapArray(valueToWrap, emit, newPath);
+                                else if (valueToWrap instanceof Date)
+                                    wrappedValue = new Date(valueToWrap.getTime());
+                                else
+                                    wrappedValue = reactive(valueToWrap, emit, newPath);
+                            }
+                        }
+                        if (prop === 'entries' || prop === Symbol.iterator) {
+                            yield [wrappedKey, wrappedValue];
+                        }
+                        else if (prop === 'values') {
+                            yield wrappedValue;
+                        }
+                        else { // keys
+                            yield wrappedKey;
+                        }
+                    }
+                };
+                return methodCache[prop];
+            }
+            if (prop === 'size') {
+                track(target, 'size');
+                return target.size;
+            }
+            const value = Reflect.get(target, prop, receiver);
+            // Bind plain functions accessed directly (e.g., toString)
+            if (typeof value === 'function') {
+                return value.bind(target);
+            }
+            return value;
+        }
+    });
+    // cache the newly created proxy before returning
+    wrapperCache.set(map, proxy);
+    return proxy;
+}

package/dist/wrap-set.d.ts

@@ -0,0 +1,2 @@
+import { EmitFunction, Path } from './types';
+export declare function wrapSet<T>(set: Set<T>, emit: EmitFunction, path: Path): Set<T>;

package/dist/wrap-set.js

@@ -0,0 +1,182 @@
+import { getPathConcat, setPathConcat, wrapperCache } from './utils';
+import { reactive } from './reactive';
+import { wrapArray } from './wrap-array';
+import { wrapMap } from './wrap-map';
+import { track, trigger } from './watch-effect';
+export function wrapSet(set, emit, path) {
+    // reuse existing proxy if available for performance
+    const cachedProxy = wrapperCache.get(set);
+    if (cachedProxy)
+        return cachedProxy;
+    // cache for wrapped methods to avoid re-creating them on each call
+    const methodCache = {};
+    const proxy = new Proxy(set, {
+        get(target, prop, receiver) {
+            track(target, prop);
+            if (methodCache[prop]) {
+                return methodCache[prop];
+            }
+            if (prop === 'add') {
+                methodCache[prop] = function (value) {
+                    const existed = target.has(value);
+                    const oldSize = target.size;
+                    // only add and trigger if the value doesn't already exist
+                    if (!existed) {
+                        target.add(value);
+                        const newSize = target.size;
+                        const event = {
+                            action: 'set-add',
+                            path: path,
+                            value: value
+                        };
+                        emit(event);
+                        trigger(target, Symbol.iterator);
+                        if (oldSize !== newSize) {
+                            trigger(target, 'size');
+                        }
+                    }
+                    return receiver; // return the proxy itself for chaining
+                };
+                return methodCache[prop];
+            }
+            if (prop === 'delete') {
+                methodCache[prop] = function (value) {
+                    const existed = target.has(value);
+                    const oldSize = target.size;
+                    if (existed) {
+                        const oldValue = value;
+                        const result = target.delete(value);
+                        const newSize = target.size;
+                        if (result) { // only emit and trigger if delete was successful
+                            const event = {
+                                action: 'set-delete',
+                                path: path,
+                                value: value,
+                                oldValue: oldValue
+                            };
+                            emit(event);
+                            trigger(target, Symbol.iterator);
+                            if (oldSize !== newSize) {
+                                trigger(target, 'size');
+                            }
+                        }
+                        return result;
+                    }
+                    return false;
+                };
+                return methodCache[prop];
+            }
+            if (prop === 'clear') {
+                methodCache[prop] = function () {
+                    const oldSize = target.size;
+                    if (oldSize === 0)
+                        return;
+                    target.clear();
+                    const newSize = target.size;
+                    const event = {
+                        action: 'set-clear',
+                        path: path,
+                        value: null
+                    };
+                    emit(event);
+                    trigger(target, Symbol.iterator);
+                    if (oldSize !== newSize) {
+                        trigger(target, 'size');
+                    }
+                };
+                return methodCache[prop];
+            }
+            if (prop === 'has') {
+                track(target, Symbol.iterator);
+                methodCache[prop] = function (value) {
+                    // track specific primitive value when 'has' is called
+                    // tracking object values for existence is complex and less common, handled by iteration track
+                    if (typeof value === 'string' || typeof value === 'number' || typeof value === 'symbol') {
+                        track(target, String(value));
+                    }
+                    return target.has(value);
+                }.bind(target); // bind is still okay here, doesn't interfere with caching
+                return methodCache[prop];
+            }
+            // handle iteration methods
+            if (prop === 'values' || prop === Symbol.iterator || prop === 'entries' || prop === 'keys' || prop === 'forEach') {
+                track(target, Symbol.iterator);
+                const originalMethod = Reflect.get(target, prop, receiver);
+                // return custom iterators/foreach that wrap values during iteration
+                if (prop === 'forEach') {
+                    methodCache[prop] = (callbackfn, thisArg) => {
+                        // use the proxied values() to ensure values passed to callback are wrapped and tracked
+                        const valuesIterator = proxy.values();
+                        for (const value of valuesIterator) {
+                            callbackfn.call(thisArg, value, value, proxy);
+                        }
+                    };
+                    return methodCache[prop];
+                }
+                // handle symbol.iterator, values, keys, entries by creating generator functions
+                methodCache[prop] = function* (...args) {
+                    let index = 0; // use index for path generation if value is not primitive
+                    const iterator = originalMethod.apply(target, args);
+                    for (const entry of iterator) {
+                        let valueToWrap = entry;
+                        let mapKey = undefined; // key for entries() which yields [value, value]
+                        if (prop === 'entries') {
+                            mapKey = entry[0]; // for Set.entries(), key and value are the same
+                            valueToWrap = entry[1];
+                        }
+                        track(target, String(index));
+                        let wrappedValue = valueToWrap;
+                        if (valueToWrap && typeof valueToWrap === 'object') {
+                            const cachedValueProxy = wrapperCache.get(valueToWrap);
+                            if (cachedValueProxy) {
+                                wrappedValue = cachedValueProxy;
+                            }
+                            else {
+                                // calculate path using index as key, as set values don't have inherent keys
+                                const keyForPath = String(index);
+                                const pathKey = path.length > 0 ? `${path.join('.')}.${keyForPath}` : keyForPath;
+                                let newPath = getPathConcat(pathKey);
+                                if (newPath === undefined) {
+                                    newPath = path.concat(keyForPath);
+                                    setPathConcat(pathKey, newPath);
+                                }
+                                // recursively wrap nested structures
+                                if (valueToWrap instanceof Map)
+                                    wrappedValue = wrapMap(valueToWrap, emit, newPath);
+                                else if (valueToWrap instanceof Set)
+                                    wrappedValue = wrapSet(valueToWrap, emit, newPath);
+                                else if (Array.isArray(valueToWrap))
+                                    wrappedValue = wrapArray(valueToWrap, emit, newPath);
+                                else if (valueToWrap instanceof Date)
+                                    wrappedValue = new Date(valueToWrap.getTime()); // dates are not proxied, return copy
+                                else
+                                    wrappedValue = reactive(valueToWrap, emit, newPath);
+                            }
+                        }
+                        if (prop === 'entries') {
+                            yield [wrappedValue, wrappedValue]; // set entries yield [value, value]
+                        }
+                        else {
+                            yield wrappedValue;
+                        }
+                        index++;
+                    }
+                };
+                return methodCache[prop];
+            }
+            if (prop === 'size') {
+                track(target, 'size');
+                return target.size;
+            }
+            const value = Reflect.get(target, prop, receiver);
+            // Bind plain functions accessed directly (e.g., toString)
+            if (typeof value === 'function') {
+                return value.bind(target);
+            }
+            return value;
+        }
+    });
+    // cache the newly created proxy before returning
+    wrapperCache.set(set, proxy);
+    return proxy;
+}

package/dist/wrapArray.js

@@ -1,8 +1,8 @@
 import { deepEqual, getPathConcat, setPathConcat, wrapperCache } from './utils';
 import { reactive } from './reactive';
-import { wrapMap } from './wrapMap';
-import { wrapSet } from './wrapSet';
-import { track, trigger } from './watchEffect';
+import { wrapMap } from './wrap-map';
+import { wrapSet } from './wrap-set';
+import { track, trigger } from './watch-effect';
 // avoid repeated typeof checks
 function isObject(v) {
     return v && typeof v === 'object';

package/dist/wrapMap.js

@@ -1,8 +1,8 @@
 import { deepEqual, getPathConcat, setPathConcat, wrapperCache } from './utils';
 import { reactive } from './reactive';
-import { wrapArray } from './wrapArray';
-import { wrapSet } from './wrapSet';
-import { track, trigger } from './watchEffect';
+import { wrapArray } from './wrap-array';
+import { wrapSet } from './wrap-set';
+import { track, trigger } from './watch-effect';
 export function wrapMap(map, emit, path) {
     // reuse existing proxy if available for performance
     const cachedProxy = wrapperCache.get(map);

package/dist/wrapSet.js

@@ -1,8 +1,8 @@
 import { getPathConcat, setPathConcat, wrapperCache } from './utils';
 import { reactive } from './reactive';
-import { wrapArray } from './wrapArray';
-import { wrapMap } from './wrapMap';
-import { track, trigger } from './watchEffect';
+import { wrapArray } from './wrap-array';
+import { wrapMap } from './wrap-map';
+import { track, trigger } from './watch-effect';
 export function wrapSet(set, emit, path) {
     // reuse existing proxy if available for performance
     const cachedProxy = wrapperCache.get(set);

package/package.json

@@ -1,30 +1,34 @@
 {
   "name": "@yiin/reactive-proxy-state",
-  "private": false,
-  "version": "1.0.8",
-  "description": "A simple, standalone reactivity library using Proxies",
+  "version": "1.0.10",
+  "author": "Yiin <stanislovas@yiin.lt>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Yiin/reactive-proxy-state.git"
+  },
   "main": "dist/index.js",
-  "types": "dist/index.d.ts",
+  "devDependencies": {
+    "bun-types": "^1.2.8",
+    "typescript": "^5.0.4",
+    "vitepress": "^1.6.3",
+    "vue": "^3.5.13"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "require": "./dist/index.js"
     }
   },
+  "bugs": {
+    "url": "https://github.com/Yiin/reactive-proxy-state/issues"
+  },
+  "description": "A simple, standalone reactivity library using Proxies",
   "files": [
     "dist",
     "README.md",
     "LICENSE"
   ],
-  "scripts": {
-    "build": "tsc",
-    "test": "bun test",
-    "test:watch": "bun test --watch",
-    "test:bench": "bun --bun ./benchmarks/state-sync.bench.ts",
-    "docs:dev": "vitepress dev docs",
-    "docs:build": "vitepress build docs",
-    "docs:preview": "vitepress preview docs"
-  },
+  "homepage": "https://Yiin.github.io/reactive-proxy-state/",
   "keywords": [
     "state",
     "sync",
@@ -35,23 +39,19 @@
     "vue",
     "reactivity"
   ],
-  "author": "Yiin <stanislovas@yiin.lt>",
   "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/Yiin/reactive-proxy-state.git"
-  },
-  "bugs": {
-    "url": "https://github.com/Yiin/reactive-proxy-state/issues"
-  },
-  "homepage": "https://Yiin.github.io/reactive-proxy-state/",
+  "private": false,
   "publishConfig": {
     "access": "public"
   },
-  "devDependencies": {
-    "bun-types": "^1.2.8",
-    "typescript": "^5.0.4",
-    "vitepress": "^1.6.3",
-    "vue": "^3.5.13"
-  }
+  "scripts": {
+    "build": "tsc",
+    "test": "bun test",
+    "test:watch": "bun test --watch",
+    "test:bench": "bun --bun ./benchmarks/state-sync.bench.ts",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs"
+  },
+  "types": "dist/index.d.ts"
 }