@yiin/reactive-proxy-state 1.0.12 → 1.0.14

package/dist/utils.js

@@ -1,220 +0,0 @@
-// cache for memoized deepEqual results, using weakmap to avoid memory leaks
-const deepEqualCache = new WeakMap();
-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(); // 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 weakmap for circular reference detection during deep operations like clone or equal
-export const globalSeen = new WeakMap();
-// 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%)
-        const entriesToRemove = Math.floor(MAX_CACHE_SIZE * 0.2);
-        let count = 0;
-        for (const key of cache.keys()) {
-            if (count >= entriesToRemove)
-                break;
-            cache.delete(key);
-            count++;
-        }
-        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%)
-        const entriesToRemove = Math.floor(MAX_PATH_CACHE_SIZE * 0.2);
-        let count = 0;
-        for (const key of pathConcatCache.keys()) {
-            if (count >= entriesToRemove)
-                break;
-            pathConcatCache.delete(key);
-            count++;
-        }
-    }
-}
-export function deepEqual(a, b, seen = globalSeen) {
-    if (a === b)
-        return true;
-    if (a == null || b == null)
-        return a === b;
-    if (typeof a !== typeof b)
-        return false;
-    if (a instanceof Date && b instanceof Date)
-        return a.getTime() === b.getTime();
-    if (typeof a !== 'object')
-        return false;
-    if (Array.isArray(a) !== Array.isArray(b))
-        return false;
-    // handle circular references
-    if (seen.has(a))
-        return seen.get(a) === b;
-    seen.set(a, b);
-    // check memoization cache before diving deeper
-    if (deepEqualCache.has(a) && deepEqualCache.get(a)?.has(b)) {
-        return deepEqualCache.get(a).get(b);
-    }
-    if (!deepEqualCache.has(a)) {
-        deepEqualCache.set(a, new WeakMap());
-    }
-    let result;
-    if (Array.isArray(a)) {
-        result = a.length === b.length && a.every((val, idx) => deepEqual(val, b[idx], seen));
-    }
-    else {
-        const keysA = Object.keys(a);
-        const keysB = Object.keys(b);
-        result = keysA.length === keysB.length && keysA.every(key => Object.prototype.hasOwnProperty.call(b, key) && deepEqual(a[key], b[key], seen));
-    }
-    // cache the result before returning
-    deepEqualCache.get(a).set(b, result);
-    return result;
-}
-export function getFromPathCache(root, pathKey) {
-    const cache = pathCache.get(root);
-    if (!cache)
-        return undefined;
-    const result = cache.get(pathKey);
-    if (result !== undefined) {
-        // simulate lru by deleting and re-setting the key
-        cache.delete(pathKey);
-        cache.set(pathKey, result);
-    }
-    return result;
-}
-export function setInPathCache(root, pathKey, value) {
-    if (!pathCache.has(root)) {
-        pathCache.set(root, new Map());
-        pathCacheSize.set(root, 0);
-    }
-    const cache = pathCache.get(root);
-    // 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);
-    cleanupPathCache(root); // check if cleanup is needed after adding
-}
-export function getPathConcat(path) {
-    const result = pathConcatCache.get(path);
-    if (result !== undefined) {
-        // 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(); // check size limit
-}
-function isObject(val) {
-    return val !== null && typeof val === 'object';
-}
-/**
- * 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);
-    if (Array.isArray(value)) {
-        value.length; // track length
-        for (let i = 0; i < value.length; i++) {
-            traverse(value[i], seen);
-        }
-    }
-    else if (value instanceof Set || value instanceof Map) {
-        for (const v of value) {
-            if (Array.isArray(v)) { // map entries [key, value]
-                traverse(v[0], seen); // key
-                traverse(v[1], seen); // value
-            }
-            else { // set values
-                traverse(v, seen);
-            }
-        }
-        return value; // no need to iterate plain object keys for map/set
-    }
-    else {
-        for (const key in value) {
-            traverse(value[key], seen);
-        }
-    }
-    return value;
-}
-/**
- * creates a deep clone of a value.
- * includes cycle detection using a weakmap.
- */
-export function deepClone(value, seen = new WeakMap()) {
-    if (value === null || typeof value !== 'object') {
-        return value;
-    }
-    if (value instanceof Date) {
-        return new Date(value.getTime());
-    }
-    if (seen.has(value)) {
-        return seen.get(value);
-    }
-    if (Array.isArray(value)) {
-        const 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;
-    }
-    if (value instanceof Map) {
-        const newMap = new Map();
-        seen.set(value, newMap); // store ref before recursing
-        value.forEach((val, key) => {
-            newMap.set(deepClone(key, seen), deepClone(val, seen));
-        });
-        return newMap;
-    }
-    if (value instanceof Set) {
-        const newSet = new Set();
-        seen.set(value, newSet); // store ref before recursing
-        value.forEach(val => {
-            newSet.add(deepClone(val, seen));
-        });
-        return newSet;
-    }
-    // handle plain objects
-    const newObject = Object.create(Object.getPrototypeOf(value));
-    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
-    const symbolKeys = Object.getOwnPropertySymbols(value);
-    for (const symbolKey of symbolKeys) {
-        const descriptor = Object.getOwnPropertyDescriptor(value, symbolKey);
-        if (descriptor && Object.prototype.propertyIsEnumerable.call(value, symbolKey)) {
-            newObject[symbolKey] = deepClone(value[symbolKey], seen);
-        }
-    }
-    return newObject;
-}

package/dist/watch-effect.js

@@ -1,154 +0,0 @@
-// 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,44 +0,0 @@
-import { watchEffect } from './watch-effect';
-import { traverse, deepClone } from './utils';
-/**
- * watches a reactive source (getter function or reactive object/ref)
- * and runs a callback when the source's value changes.
- */
-export function watch(sourceInput, callback, options = {}) {
-    const { immediate = false, deep = true } = options;
-    // normalize source to always be a getter function
-    const source = typeof sourceInput === 'function'
-        ? sourceInput
-        : () => sourceInput;
-    let oldValue;
-    let initialized = false;
-    // use watchEffect internally to handle dependency tracking
-    const stopEffect = watchEffect(() => {
-        const currentValue = source();
-        // if deep watching, traverse the current value to track nested dependencies
-        if (deep) {
-            traverse(currentValue);
-        }
-        if (initialized) {
-            let hasChanged = false;
-            // for deep watches, the effect running implies a dependency changed.
-            // for shallow, explicitly check reference equality.
-            hasChanged = deep || currentValue !== oldValue;
-            if (hasChanged) {
-                const prevOldValue = oldValue;
-                // 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: store initial value (cloned if deep) and run immediate callback if requested
-            oldValue = deep ? deepClone(currentValue) : currentValue;
-            initialized = true;
-            if (immediate) {
-                callback(currentValue, undefined); // pass undefined as oldValue for immediate
-            }
-        }
-    }, { lazy: false }); // run immediately (watchEffect handles `immediate` option internally)
-    return stopEffect;
-}

package/dist/watchEffect.d.ts

@@ -1,54 +0,0 @@
-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/watchEffect.js

@@ -1,154 +0,0 @@
-// 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;
-}