@yiin/reactive-proxy-state 1.0.2 → 1.0.3

package/README.md

@@ -16,20 +16,20 @@ bun add @yiin/reactive-proxy-state
 
 ## Core Concepts
 
-1.  **Reactive State**: Create reactive versions of your objects using `wrapState`. Any mutations to these wrapped objects will be tracked.
+1.  **Reactive State**: Create reactive versions of your objects using `reactive`. Any mutations to these wrapped objects will be tracked.
 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**.
 
 ## API
 
-### `wrapState<T extends object>(obj: T): T`
+### `reactive<T extends object>(obj: T): T`
 
 Creates a reactive proxy for the given object, Array, Map, or Set. Nested objects/collections are also recursively wrapped.
 
 ```typescript
-import { wrapState } from '@yiin/reactive-proxy-state';
+import { reactive } from '@yiin/reactive-proxy-state';
 
-const state = wrapState({
+const state = reactive({
   count: 0,
   user: { name: 'Alice' },
   items: ['a', 'b'],
@@ -49,7 +49,7 @@ state.ids.add(3);
 
 Creates a reactive "reference" object for any value type (primitive or object). The value is accessed and mutated through the `.value` property. Reactivity is tracked on the `.value` property itself.
 
-**Note:** If a plain object is passed to `ref`, the object *itself* is not made deeply reactive. Only assignment to the `.value` property is tracked. Use `wrapState` for deep object reactivity.
+**Note:** If a plain object is passed to `ref`, the object *itself* is not made deeply reactive. Only assignment to the `.value` property is tracked. Use `reactive` for deep object reactivity.
 
 ```typescript
 import { ref, watchEffect, isRef, unref } from '@yiin/reactive-proxy-state';
@@ -157,9 +157,9 @@ Runs a function immediately, tracks its reactive dependencies, and re-runs it sy
 *   `onTrigger?(event)`: Debug hook called when the effect is triggered by a mutation.
 
 ```typescript
-import { wrapState, ref, watchEffect } from '@yiin/reactive-proxy-state';
+import { reactive, ref, watchEffect } from '@yiin/reactive-proxy-state';
 
-// ... existing watchEffect example using wrapState ...
+// ... existing watchEffect example using reactive ...
 
 // Using watchEffect with refs
 const counter = ref(10);
@@ -173,7 +173,7 @@ counter.value--;
 
 ### `watch<T>(source: WatchSource<T> | T, callback: (newValue: T, oldValue: T | undefined) => void, options?: WatchOptions)`
 
-Watches a specific reactive source (either a getter function, a direct reactive object/value created by `wrapState`, or a `ref`) and runs a callback when the source's value changes.
+Watches a specific reactive source (either a getter function, a direct reactive object/value created by `reactive`, or a `ref`) and runs a callback when the source's value changes.
 
 `WatchSource<T>`: A function that returns the value to watch, or a `ref`.
 `callback`: Function executed on change. Receives the new value and the old value.
@@ -182,9 +182,9 @@ Watches a specific reactive source (either a getter function, a direct reactive
 *   `deep?: boolean`: If `true`, deeply traverses the source for dependency tracking and uses deep comparison logic. **Defaults to `true`**. Set to `false` for shallow watching (only triggers on direct assignment or identity change).
 
 ```typescript
-import { wrapState, ref, watch } from '@yiin/reactive-proxy-state';
+import { reactive, ref, watch } from '@yiin/reactive-proxy-state';
 
-// ... existing watch examples using wrapState ...
+// ... existing watch examples using reactive ...
 
 // Watching a ref
 const count = ref(0);
@@ -206,12 +206,12 @@ doubleCount.value = 110; // Output: Double changed from 200 to 220
 
 ## Collections (Arrays, Maps, Sets)
 
-`wrapState` automatically handles Arrays, Maps, and Sets. Mutations via standard methods (`push`, `pop`, `splice`, `set`, `delete`, `add`, `clear`, etc.) are reactive and will trigger effects that depend on the collection or its contents (if watched deeply).
+`reactive` automatically handles Arrays, Maps, and Sets. Mutations via standard methods (`push`, `pop`, `splice`, `set`, `delete`, `add`, `clear`, etc.) are reactive and will trigger effects that depend on the collection or its contents (if watched deeply).
 
 ```typescript
-import { wrapState, watchEffect } from '@yiin/reactive-proxy-state';
+import { reactive, watchEffect } from '@yiin/reactive-proxy-state';
 
-const state = wrapState({
+const state = reactive({
   list: [1, 2],
   data: new Map<string, number>(),
   tags: new Set<string>()

package/dist/computed.d.ts

@@ -0,0 +1,16 @@
+import { Ref, isRefSymbol } from './ref';
+declare const isComputedSymbol: unique symbol;
+export interface ComputedRef<T = any> extends Omit<Ref<T>, 'value'> {
+    readonly value: T;
+    readonly [isComputedSymbol]: true;
+    readonly [isRefSymbol]: true;
+}
+export interface WritableComputedRef<T> extends Ref<T> {
+}
+type ComputedGetter<T> = () => T;
+export declare function computed<T>(getter: ComputedGetter<T>): ComputedRef<T>;
+/**
+ * Checks if a value is a computed ref.
+ */
+export declare function isComputed<T>(c: any): c is ComputedRef<T>;
+export {};

package/dist/computed.js

@@ -0,0 +1,59 @@
+import { watchEffect, track, trigger } from './watchEffect';
+import { isRefSymbol } from './ref';
+// Symbol for marking computed refs
+const isComputedSymbol = Symbol('isComputed');
+// Implementation v4 - Using watchEffect with scheduler
+export function computed(getter) {
+    let _value;
+    let _dirty = true; // Start dirty
+    let computedRef; // Placeholder
+    // Create a lazy effect with a scheduler
+    const stopHandle = watchEffect(getter, {
+        lazy: true, // Don't run the getter immediately
+        scheduler: () => {
+            // When a dependency changes, don't re-run the getter immediately.
+            // Instead, mark the computed as dirty and trigger downstream effects.
+            if (!_dirty) {
+                _dirty = true;
+                // Trigger effects that depend on the computed ref's value
+                trigger(computedRef, 'value');
+            }
+        },
+    });
+    // Access the internal effect runner
+    const effectRunner = stopHandle.effect;
+    computedRef = {
+        [isRefSymbol]: true,
+        [isComputedSymbol]: true,
+        get value() {
+            // 1. Track access to this computed value for any outer effects
+            track(computedRef, 'value');
+            // 2. If dirty, run the effect manually. This will:
+            //    - Execute the getter
+            //    - Update _value (via getter's return)
+            //    - Track dependencies for the getter (handled by watchEffect internals)
+            //    - Set _dirty to false
+            if (_dirty) {
+                // console.log('Recomputing computed value via getter access');
+                _value = effectRunner.run(); // Run the getter, update value, track deps
+                _dirty = false; // Mark as clean *after* successful run
+            }
+            // 3. Return the (now current) value.
+            return _value;
+        },
+        set value(newValue) {
+            console.warn('Computed value is read-only');
+        },
+        // Expose the stop function if needed
+        // stop: stopHandle
+    };
+    // Initial computation is lazy, happens on first .value access.
+    // The scheduler ensures dependency changes only mark it dirty.
+    return computedRef;
+}
+/**
+ * Checks if a value is a computed ref.
+ */
+export function isComputed(c) {
+    return !!(c && c[isComputedSymbol]);
+}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export * from './types';
+export * from './utils';
+export * from './state';
+export * from './reactive';
+export * from './wrapArray';
+export * from './wrapMap';
+export * from './wrapSet';
+export * from './watch';
+export * from './watchEffect';
+export * from './ref';
+export * from './computed';

package/dist/index.js

@@ -0,0 +1,11 @@
+export * from './types';
+export * from './utils';
+export * from './state';
+export * from './reactive';
+export * from './wrapArray';
+export * from './wrapMap';
+export * from './wrapSet';
+export * from './watch';
+export * from './watchEffect';
+export * from './ref';
+export * from './computed';

package/dist/reactive.d.ts

@@ -0,0 +1,2 @@
+import { EmitFunction, Path } from './types';
+export declare function reactive<T extends object>(obj: T, emit: EmitFunction, path?: Path, seen?: WeakMap<any, any>): T;

package/dist/reactive.js

@@ -0,0 +1,99 @@
+import { deepEqual, globalSeen, getPathConcat, setPathConcat } from './utils';
+import { wrapArray } from './wrapArray';
+import { wrapMap } from './wrapMap';
+import { wrapSet } from './wrapSet';
+import { track, trigger } from './watchEffect';
+// Pre-allocate type check function
+function isObject(v) {
+    return v && typeof v === 'object';
+}
+export function reactive(obj, emit, path = [], seen = globalSeen) {
+    if (seen.has(obj))
+        return seen.get(obj);
+    function wrapValue(val, subPath) {
+        if (!isObject(val))
+            return val;
+        if (seen.has(val))
+            return seen.get(val);
+        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());
+        return reactive(val, emit, subPath, seen);
+    }
+    const proxy = new Proxy(obj, {
+        get(target, prop, receiver) {
+            const value = Reflect.get(target, prop, receiver);
+            // Track this property access for reactivity
+            track(target, prop);
+            // Fast path for non-objects
+            if (!isObject(value))
+                return value;
+            // Use cached path concatenation
+            const pathKey = `${path.join('.')}.${String(prop)}`;
+            let newPath = getPathConcat(pathKey);
+            if (newPath === undefined) {
+                newPath = path.concat(String(prop));
+                setPathConcat(pathKey, newPath);
+            }
+            return wrapValue(value, newPath);
+        },
+        set(target, prop, value, receiver) {
+            const oldValue = target[prop];
+            // Fast path for primitive equality
+            if (oldValue === value)
+                return true;
+            // Only do deep equality check for objects
+            if (isObject(oldValue) && isObject(value) && deepEqual(oldValue, value))
+                return true;
+            const descriptor = Reflect.getOwnPropertyDescriptor(target, prop);
+            const result = Reflect.set(target, prop, value, receiver);
+            // Only emit if the set was successful and it's not a setter property
+            if (result && (!descriptor || !descriptor.set)) {
+                // Use cached path concatenation
+                const pathKey = `${path.join('.')}.${String(prop)}`;
+                let newPath = getPathConcat(pathKey);
+                if (newPath === undefined) {
+                    newPath = path.concat(String(prop));
+                    setPathConcat(pathKey, newPath);
+                }
+                const event = {
+                    action: 'set',
+                    path: newPath,
+                    oldValue,
+                    newValue: value
+                };
+                emit(event);
+                // Trigger effects
+                trigger(target, prop);
+            }
+            return result;
+        },
+        deleteProperty(target, prop) {
+            const oldValue = target[prop];
+            const result = Reflect.deleteProperty(target, prop);
+            // Use cached path concatenation
+            const pathKey = `${path.join('.')}.${String(prop)}`;
+            let newPath = getPathConcat(pathKey);
+            if (newPath === undefined) {
+                newPath = path.concat(String(prop));
+                setPathConcat(pathKey, newPath);
+            }
+            const event = {
+                action: 'delete',
+                path: newPath,
+                oldValue
+            };
+            emit(event);
+            // Trigger effects
+            trigger(target, prop);
+            return result;
+        }
+    });
+    seen.set(obj, proxy);
+    return proxy;
+}

package/dist/ref.d.ts

@@ -0,0 +1,22 @@
+export declare const isRefSymbol: unique symbol;
+export interface Ref<T = any> {
+    value: T;
+    readonly [isRefSymbol]: true;
+}
+/**
+ * Takes an inner value and returns a reactive and mutable ref object,
+ * which has a single property `.value` that points to the inner value.
+ * The ref tracks access and mutations to its `.value` property.
+ * If the initial value is an object, it is NOT automatically made reactive.
+ */
+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.
+ */
+export declare function isRef<T>(r: any): r is Ref<T>;
+/**
+ * Returns the inner value if the argument is a ref, otherwise returns the
+ * argument itself.
+ */
+export declare function unref<T>(refValue: T | Ref<T>): T;

package/dist/ref.js

@@ -0,0 +1,60 @@
+import { track, trigger } from './watchEffect';
+// Removed reactive import as ref doesn't automatically make contained objects reactive
+// import { reactive } from './reactive';
+// Symbol for marking refs
+export const isRefSymbol = Symbol('isRef'); // Add export and Simplified symbol description
+export function ref(value) {
+    return createRef(value);
+}
+// Internal function to create refs (no longer shallow distinction needed here)
+function createRef(rawValue) {
+    // If the value is already a ref, return it directly
+    if (isRef(rawValue)) {
+        // Cast rawValue back to Ref<T> after type guard
+        return rawValue;
+    }
+    // The ref holds the raw value directly
+    let value = rawValue;
+    // Create the ref object with getter/setter for reactivity
+    const r = {
+        [isRefSymbol]: true, // Mark as ref
+        get value() {
+            // Track dependency on the 'value' property of this ref object
+            // Ensure 'r' is treated as the target object for tracking
+            track(r, 'value');
+            return value;
+        },
+        set value(newValue) {
+            // Check if value actually changed (using simple comparison)
+            // For objects, this means identity change, not deep mutation.
+            if (value !== newValue) {
+                value = newValue;
+                // Trigger effects depending on the 'value' property of this ref object
+                // Ensure 'r' is treated as the target object for triggering
+                trigger(r, 'value');
+            }
+        },
+    }; // Explicit cast to ensure type correctness
+    return r;
+}
+/**
+ * Checks if a value is a ref object.
+ */
+export function isRef(r) {
+    return !!(r && r[isRefSymbol]);
+}
+/**
+ * Returns the inner value if the argument is a ref, otherwise returns the
+ * argument itself.
+ */
+export function unref(refValue) {
+    return isRef(refValue) ? refValue.value : refValue;
+}
+// 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.d.ts

@@ -0,0 +1,2 @@
+import { StateEvent } from './types';
+export declare function updateState(root: any, event: StateEvent): void;

package/dist/state.js

@@ -0,0 +1,207 @@
+import { pathCache, setInPathCache } from './utils';
+// Pre-allocate helper functions to avoid recreation
+function getValue(obj, key) {
+    if (obj instanceof Map)
+        return obj.get(key);
+    return obj[key];
+}
+function setValue(obj, key, value) {
+    if (obj instanceof Map)
+        obj.set(key, value);
+    else
+        obj[key] = value;
+}
+function deleteValue(obj, key) {
+    if (obj instanceof Map)
+        obj.delete(key);
+    else
+        delete obj[key];
+}
+// Cache for action handlers to avoid switch statement overhead
+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;
+        }
+        // Note: event.key is the starting index, but push always adds to the 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;
+        }
+        // We don't need event.key or event.oldValue to perform the 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;
+        }
+        // Call splice with appropriate arguments
+        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;
+        }
+        // We don't need event.key or event.oldValue to perform the 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;
+        }
+        // We don't need event.key to perform unshift
+        targetArray.unshift(...event.items);
+    },
+    'map-set': function (parent, key, event) {
+        const target = getValue(parent, key);
+        if (target instanceof Map) {
+            target.set(event.key, event.newValue);
+        }
+        else {
+            console.warn(`Expected Map at path ${key}`);
+        }
+    },
+    'map-delete': function (parent, key, event) {
+        const target = getValue(parent, key);
+        if (target instanceof Map) {
+            target.delete(event.key);
+        }
+        else {
+            console.warn(`Expected Map at path ${key}`);
+        }
+    },
+    'map-clear': function (parent, key, event) {
+        const target = getValue(parent, key);
+        if (target instanceof Map) {
+            target.clear();
+        }
+        else {
+            console.warn(`Expected Map at path ${key}`);
+        }
+    },
+    'set-add': function (targetSet, _keyIgnored, event) {
+        if (targetSet instanceof Set) {
+            targetSet.add(event.value);
+        }
+        else {
+            console.warn(`Expected Set at path ${event.path.join('.')}`);
+        }
+    },
+    'set-delete': function (targetSet, _keyIgnored, event) {
+        if (targetSet instanceof Set) {
+            targetSet.delete(event.value);
+        }
+        else {
+            console.warn(`Expected Set at path ${event.path.join('.')}`);
+        }
+    },
+    'set-clear': function (targetSet, _keyIgnored, event) {
+        if (targetSet instanceof Set) {
+            targetSet.clear();
+        }
+        else {
+            console.warn(`Expected Set at path ${event.path.join('.')}`);
+        }
+    }
+};
+export function updateState(root, event) {
+    const { action, path } = event;
+    if (path.length === 0) {
+        console.warn('Event path is empty');
+        return;
+    }
+    const handler = actionHandlers[action];
+    if (!handler) {
+        throw new Error(`Unhandled action: ${action}`);
+    }
+    // Determine target and key based on action type
+    let targetForHandler;
+    let keyForHandler = null; // Key is only relevant for set/delete/map actions
+    if (action === 'set' || action === 'delete' || action.startsWith('map-')) {
+        // Actions where path leads to parent, last element is key
+        if (path.length === 1) {
+            targetForHandler = root;
+            keyForHandler = path[0];
+        }
+        else {
+            const parentPathKey = path.slice(0, -1).join('.');
+            let parent = pathCache.get(root)?.get(parentPathKey);
+            if (parent === undefined) {
+                parent = path.slice(0, -1).reduce((acc, key) => acc ? getValue(acc, key) : undefined, root);
+                if (parent !== undefined)
+                    setInPathCache(root, parentPathKey, parent);
+            }
+            if (parent === undefined) {
+                console.warn(`Parent path ${parentPathKey} not found for action ${action}`);
+                return;
+            }
+            targetForHandler = parent;
+            keyForHandler = path[path.length - 1];
+        }
+    }
+    else if (action.startsWith('array-') || action.startsWith('set-')) {
+        // Actions where path leads directly to the collection (Array or Set)
+        if (path.length === 1) {
+            targetForHandler = getValue(root, path[0]);
+        }
+        else {
+            const parentPathKey = path.slice(0, -1).join('.');
+            let parent = pathCache.get(root)?.get(parentPathKey);
+            if (parent === undefined) {
+                parent = path.slice(0, -1).reduce((acc, key) => acc ? getValue(acc, key) : undefined, root);
+                if (parent !== undefined)
+                    setInPathCache(root, parentPathKey, parent);
+            }
+            if (parent === undefined) {
+                console.warn(`Parent path ${parentPathKey} not found for action ${action}`);
+                return;
+            }
+            targetForHandler = getValue(parent, path[path.length - 1]);
+        }
+        if (targetForHandler === undefined) {
+            console.warn(`Target collection at path ${path.join('.')} not found for action ${action}`);
+            return;
+        }
+    }
+    else {
+        // Should not happen if handler exists
+        console.error(`Unexpected action type passed checks: ${action}`);
+        return;
+    }
+    // Call the handler with the appropriately determined target and key
+    handler(targetForHandler, keyForHandler, event);
+}

package/dist/types.d.ts

@@ -0,0 +1,15 @@
+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 interface StateEvent {
+    action: ActionType;
+    path: Path;
+    oldValue?: any;
+    newValue?: any;
+    key?: any;
+    value?: any;
+    args?: any[];
+    items?: any[];
+    deleteCount?: number;
+    oldValues?: any[];
+}
+export type EmitFunction = (event: StateEvent) => void;

package/dist/types.js

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

package/dist/utils.d.ts

@@ -0,0 +1,25 @@
+export declare const pathCache: WeakMap<object, Map<string, any>>;
+export declare const pathConcatCache: Map<string, any[]>;
+export declare const globalSeen: WeakMap<any, any>;
+export declare const wrapperCache: WeakMap<object, object>;
+export declare function deepEqual(a: any, b: any, seen?: WeakMap<any, any>): boolean;
+export declare function getFromPathCache(root: object, pathKey: string): any | undefined;
+export declare function setInPathCache(root: object, pathKey: string, value: any): void;
+export declare function getPathConcat(path: string): any[] | undefined;
+export declare function setPathConcat(path: string, value: any[]): void;
+/**
+ * Recursively traverses an object to track all nested properties.
+ * Used for deep watching.
+ * @param value - The value to traverse.
+ * @param seen - A Set to handle circular references.
+ */
+export declare function traverse(value: any, seen?: Set<any>): any;
+/**
+ * Creates a deep clone of a value.
+ * Handles primitives, Dates, Arrays, Maps, Sets, and plain objects.
+ * Includes cycle detection.
+ * @param value The value to clone.
+ * @param seen A WeakMap to handle circular references during recursion.
+ * @returns A deep clone of the value.
+ */
+export declare function deepClone<T>(value: T, seen?: WeakMap<WeakKey, any>): T;