@yiin/reactive-proxy-state 1.0.12 → 1.0.14

package/dist/reactive.d.ts

@@ -1,2 +1,14 @@
-import { EmitFunction, Path } from './types';
-export declare function reactive<T extends object>(obj: T, emit: EmitFunction, path?: Path, seen?: WeakMap<any, any>): T;
+import { EmitFunction, Path } from "./types";
+/**
+ * Checks if an object is a reactive proxy
+ */
+export declare function isReactive(value: any): boolean;
+/**
+ * Returns the raw, original object underlying a reactive proxy.
+ * If the input is not a proxy, returns the input itself.
+ */
+export declare function toRaw<T>(observed: T): T;
+/**
+ * Create a reactive proxy for an object
+ */
+export declare function reactive<T extends object>(obj: T, emit?: EmitFunction, path?: Path): T;

package/dist/ref.d.ts

@@ -4,26 +4,36 @@ export interface Ref<T = any> {
     readonly [isRefSymbol]: true;
 }
 /**
- * creates a reactive reference object.
- * the object has a single `.value` property.
- * reactivity is tracked on access and mutation of the `.value` property.
- * if an object is passed as the initial value, the object itself is *not* made deeply reactive.
- * only the assignment to `.value` is tracked.
+ * Creates a reactive reference object.
+ * The object has a single `.value` property.
+ * Reactivity is tracked on access and mutation of the `.value` property.
+ * If an object is passed as the initial value, the object itself is *not* made deeply reactive.
+ * Only the assignment to `.value` is tracked.
+ *
+ * @param value - The value to wrap in a ref
+ * @returns A ref object with the value
  */
 export declare function ref<T>(value: T): Ref<T>;
 export declare function ref<T = undefined>(): Ref<T | undefined>;
 /**
- * checks if a value is a ref object.
+ * Checks if a value is a ref object.
+ *
+ * @param r - The value to check
+ * @returns true if the value is a ref, false otherwise
  */
 export declare function isRef<T>(r: any): r is Ref<T>;
 /**
- * returns the inner value if the argument is a ref,
+ * Returns the inner value if the argument is a ref,
  * otherwise returns the argument itself. this is a sugar for `isRef(val) ? val.value : val`.
+ *
+ * @param refValue - The value to unref
+ * @returns The inner value if the argument is a ref, otherwise the argument itself
  */
 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
  */
@@ -32,8 +42,15 @@ export declare function toRefs<T extends object>(object: T): {
 };
 /**
  * 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]>;
+/**
+ * Basic triggerRef function
+ *
+ * @param ref - The ref object to trigger
+ */
+export declare function triggerRef(ref: Ref<any>): void;

package/dist/state.d.ts

@@ -1,2 +1,8 @@
 import { StateEvent } from './types';
+/**
+ * Applies a state change event to a plain javascript object/array (the target state)
+ *
+ * @param root - The root object/array to apply the event to
+ * @param event - The state change event to apply
+ */
 export declare function updateState(root: any, event: StateEvent): void;

package/dist/types.d.ts

@@ -1,5 +1,5 @@
 export type Path = (string | number | symbol)[];
-export type ActionType = 'set' | 'delete' | 'array-push' | 'array-pop' | 'array-splice' | 'array-shift' | 'array-unshift' | 'map-set' | 'map-delete' | 'map-clear' | 'set-add' | 'set-delete' | 'set-clear';
+export type ActionType = 'set' | 'delete' | 'array-push' | 'array-pop' | 'array-splice' | 'array-shift' | 'array-unshift' | 'map-set' | 'map-delete' | 'map-clear' | 'set-add' | 'set-delete' | 'set-clear' | 'replace';
 export interface StateEvent {
     action: ActionType;
     path: Path;

package/dist/watch-effect.d.ts

@@ -10,6 +10,7 @@ export interface TrackedEffect<T = any> {
     options?: WatchEffectOptions;
     active?: boolean;
     _rawCallback: EffectCallback<T>;
+    triggerDepth?: number;
 }
 export declare let activeEffect: TrackedEffect<any> | null;
 export declare function setActiveEffect(effect: TrackedEffect<any> | null): void;
@@ -26,7 +27,7 @@ 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.
+ * now batches effects to run in the same tick.
  */
 export declare function trigger(target: object, key: string | symbol): void;
 export interface WatchEffectOptions {

package/dist/wrap-array.d.ts

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

package/dist/wrap-map.d.ts

@@ -1,2 +1,2 @@
-import { EmitFunction, Path } from './types';
-export declare function wrapMap<K, V>(map: Map<K, V>, emit: EmitFunction, path: Path): Map<K, V>;
+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-set.d.ts

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yiin/reactive-proxy-state",
-  "version": "1.0.12",
+  "version": "1.0.14",
   "author": "Yiin <stanislovas@yiin.lt>",
   "repository": {
     "type": "git",
@@ -45,7 +45,7 @@
     "access": "public"
   },
   "scripts": {
-    "build": "tsc",
+    "build": "bun build src/index.ts --outdir dist --target node --format esm && tsc --emitDeclarationOnly --outDir dist",
     "test": "bun test",
     "test:watch": "bun test --watch",
     "test:bench": "bun --bun ./benchmarks/state-sync.bench.ts",

package/dist/computed.js

@@ -1,58 +0,0 @@
-import { watchEffect, track, trigger } from './watch-effect';
-import { isRefSymbol } from './ref';
-// symbol for identifying computed refs
-const isComputedSymbol = Symbol('isComputed');
-// implementation using a lazy watchEffect with a custom scheduler for caching
-export function computed(getterOrOptions) {
-    let getter;
-    let setter;
-    const isGetter = typeof getterOrOptions === 'function';
-    if (isGetter) {
-        getter = getterOrOptions;
-    }
-    else {
-        getter = getterOrOptions.get;
-        setter = getterOrOptions.set;
-    }
-    let _value;
-    let _dirty = true; // flag to track if the cached value is stale
-    let computedRef; // placeholder to allow self-reference in scheduler
-    // create a lazy effect; scheduler intercepts triggers to mark dirty instead of recomputing immediately
-    const stopHandle = watchEffect(getter, {
-        lazy: true,
-        scheduler: () => {
-            if (!_dirty) {
-                _dirty = true;
-                // trigger effects that depend on this computed ref
-                trigger(computedRef, 'value');
-            }
-        },
-    });
-    const effectRunner = stopHandle.effect;
-    computedRef = {
-        [isRefSymbol]: true,
-        [isComputedSymbol]: true,
-        get value() {
-            track(computedRef, 'value');
-            // if dirty, recompute value by running the getter
-            if (_dirty) {
-                _value = effectRunner.run();
-                _dirty = false; // mark as clean after successful run
-            }
-            return _value;
-        },
-        set value(newValue) {
-            if (setter) {
-                setter(newValue);
-            }
-            else {
-                console.warn('computed value is read-only');
-            }
-        },
-        // stop: stopHandle // potentially expose stop handle
-    };
-    return computedRef;
-}
-export function isComputed(c) {
-    return !!(c && c[isComputedSymbol]);
-}

package/dist/reactive.js

@@ -1,114 +0,0 @@
-import { deepEqual, globalSeen, getPathConcat, setPathConcat } from './utils';
-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';
-}
-// create a reactive proxy for an object
-export function reactive(obj, emit, path = [], seen = globalSeen) {
-    // prevent infinite recursion with circular references
-    if (seen.has(obj))
-        return seen.get(obj);
-    // helper to wrap nested values recursively
-    function wrapValue(val, subPath) {
-        if (!isObject(val))
-            return val; // primitives are returned directly
-        if (seen.has(val))
-            return seen.get(val); // handle cycles within nested structures
-        // delegate wrapping to specific functions based on type
-        if (Array.isArray(val))
-            return wrapArray(val, emit, subPath);
-        if (val instanceof Map)
-            return wrapMap(val, emit, subPath);
-        if (val instanceof Set)
-            return wrapSet(val, emit, subPath);
-        if (val instanceof Date)
-            return new Date(val.getTime()); // dates are not proxied, return copy
-        // default to reactive for plain objects
-        return reactive(val, emit, subPath, seen);
-    }
-    const proxy = new Proxy(obj, {
-        get(target, prop, receiver) {
-            const value = Reflect.get(target, prop, receiver);
-            // track property access for dependency tracking
-            track(target, prop);
-            // return non-objects directly without wrapping
-            if (!isObject(value))
-                return value;
-            // calculate the path for the nested property, using cache for performance
-            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);
-            }
-            // wrap the nested value if it's an object/collection
-            return wrapValue(value, newPath);
-        },
-        set(target, prop, value, receiver) {
-            const oldValue = target[prop];
-            // avoid unnecessary triggers if the value hasn't changed
-            // fast path for primitives
-            if (oldValue === value)
-                return true;
-            // deep equality check for objects/arrays
-            if (isObject(oldValue) && isObject(value) && deepEqual(oldValue, value, new WeakMap()))
-                return true; // use new WeakMap for deepEqual seen
-            const descriptor = Reflect.getOwnPropertyDescriptor(target, prop);
-            const result = Reflect.set(target, prop, value, receiver);
-            // only emit and trigger if the set was successful and wasn't intercepted by a setter
-            if (result && (!descriptor || !descriptor.set)) {
-                // calculate path, using cache
-                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);
-                // notify effects watching this property
-                trigger(target, prop);
-            }
-            return result;
-        },
-        deleteProperty(target, prop) {
-            const oldValue = target[prop];
-            const hadProperty = Object.prototype.hasOwnProperty.call(target, prop);
-            const result = Reflect.deleteProperty(target, prop);
-            // only emit and trigger if the property existed and deletion was successful
-            if (hadProperty && result) {
-                // calculate path, using cache
-                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: 'delete',
-                    path: newPath,
-                    oldValue
-                };
-                emit(event);
-                // notify effects watching this property
-                trigger(target, prop);
-            }
-            return result;
-        }
-    });
-    // cache the proxy to handle circular references and improve performance
-    seen.set(obj, proxy);
-    return proxy;
-}

package/dist/ref.js

@@ -1,91 +0,0 @@
-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()
-export const isRefSymbol = Symbol('isRef');
-export function ref(value) {
-    return createRef(value);
-}
-// internal factory for creating ref objects
-function createRef(rawValue) {
-    // avoid wrapping if the value is already a ref
-    if (isRef(rawValue)) {
-        return rawValue;
-    }
-    // store the inner value
-    let _value = rawValue;
-    // create the ref object with a getter/setter on `.value`
-    const r = {
-        [isRefSymbol]: true, // mark as a ref using the symbol
-        get value() {
-            // track dependency when `.value` is accessed
-            // `r` (the ref object itself) is the target for tracking
-            track(r, 'value');
-            return _value;
-        },
-        set value(newValue) {
-            // only update and trigger if the value has actually changed
-            // this uses strict equality (===), so for objects, it checks reference equality
-            if (_value !== newValue) {
-                _value = newValue;
-                // trigger effects when `.value` is assigned a new value
-                // `r` (the ref object itself) is the target for triggering
-                trigger(r, 'value');
-            }
-        },
-    }; // cast to ensure the object conforms to the Ref interface
-    return r;
-}
-/**
- * checks if a value is a ref object.
- */
-export function isRef(r) {
-    // check for the presence of the internal symbol
-    return !!(r && r[isRefSymbol]);
-}
-/**
- * returns the inner value if the argument is a ref,
- * otherwise returns the argument itself. this is a sugar for `isRef(val) ? val.value : val`.
- */
-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 {
-  trigger(ref, 'value');
-}
-*/
-// TODO: Implement shallowRef if needed (uses createRef(value, true))
-// TODO: Implement customRef if needed (more advanced) 

package/dist/state.js

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

package/dist/types.js

@@ -1 +0,0 @@
-export {};