@yiin/reactive-proxy-state 1.0.4 → 1.0.6

package/README.md

@@ -91,60 +91,99 @@ console.log(unref(123)); // 123 (returns non-refs as is)
 ```
 
 ### `computed<T>(getter: () => T): ComputedRef<T>`
+### `computed<T>(options: { get: () => T, set: (value: T) => void }): WritableComputedRef<T>`
 
-Creates a computed property based on a getter function. The getter tracks reactive dependencies (`ref`s or reactive object properties) and its result is cached. The computed value only recalculates when a dependency changes.
-Computed refs are read-only.
+Creates a computed property based on a getter function or a getter/setter pair.
+
+-   **Getter-only:** The getter tracks reactive dependencies (`ref`s or reactive object properties) and its result is cached. The computed value only recalculates when a dependency changes. Computed refs created this way are **read-only**.
+-   **Getter/Setter:** Provides both a getter for deriving the value and a setter for mutating underlying reactive state when the computed ref's `.value` is assigned.
 
 ```typescript
 import { ref, computed, watchEffect, isComputed } from '@yiin/reactive-proxy-state';
 
+// Read-only computed
 const firstName = ref('John');
 const lastName = ref('Doe');
 
-const fullName = computed(() => {
-  console.log('Computing fullName...');
+const readOnlyFullName = computed(() => {
+  console.log('Computing readOnlyFullName...');
   return `${firstName.value} ${lastName.value}`;
 });
 
 // Accessing .value triggers computation
-console.log(fullName.value); 
-// Output: Computing fullName...
+console.log(readOnlyFullName.value); 
+// Output: Computing readOnlyFullName...
 // Output: John Doe
 
 // Accessing again uses the cache
-console.log(fullName.value);
+console.log(readOnlyFullName.value);
 // Output: John Doe
 
 watchEffect(() => {
-  console.log('Full name changed:', fullName.value);
+  console.log('Read-only full name changed:', readOnlyFullName.value);
 });
-// Output: Full name changed: John Doe
+// Output: Read-only full name changed: John Doe
 
 // Changing a dependency marks computed as dirty
 firstName.value = 'Jane';
 
 // Accessing .value again triggers re-computation and the effect
-console.log(fullName.value);
-// Output: Computing fullName...
-// Output: Full name changed: Jane Doe
+console.log(readOnlyFullName.value);
+// Output: Computing readOnlyFullName...
+// Output: Read-only full name changed: Jane Doe
 // Output: Jane Doe
 
 // Chained computed
-const message = computed(() => `User: ${fullName.value}`);
+const message = computed(() => `User: ${readOnlyFullName.value}`);
 console.log(message.value); // User: Jane Doe
 
 lastName.value = 'Smith';
-// Output: Computing fullName...
-// Output: Full name changed: Jane Smith
+// Output: Computing readOnlyFullName...
+// Output: Read-only full name changed: Jane Smith
 console.log(message.value); // User: Jane Smith (message recomputed automatically)
 
 // Read-only check
+console.warn = () => console.log('Warning triggered!'); // Mock console.warn
 try {
-  (fullName as any).value = 'Test'; // Throws warning
+  (readOnlyFullName as any).value = 'Test'; // Triggers warning
 } catch (e) { /* ... */ }
+// Output: Warning triggered!
+console.log(readOnlyFullName.value); // Jane Smith (value unchanged)
+
+// Writable computed
+const source = ref(1);
+const plusOne = computed({
+    get: () => source.value + 1,
+    set: (newValue) => { 
+        console.log(`Setting source based on new value: ${newValue}`);
+        source.value = newValue - 1; 
+    }
+});
+
+console.log(plusOne.value); // 2 (Initial get)
+console.log(source.value);  // 1
+
+watchEffect(() => {
+  console.log('Writable computed changed:', plusOne.value);
+});
+// Output: Writable computed changed: 2
+
+// Set the writable computed value
+plusOne.value = 10;
+// Output: Setting source based on new value: 10
+// Output: Writable computed changed: 10 
+
+console.log(plusOne.value); // 10
+console.log(source.value);  // 9 (Source was updated by the setter)
+
+// Changing the source ref also updates the computed
+source.value = 20;
+// Output: Writable computed changed: 21
+console.log(plusOne.value); // 21
 
 // Helper
-console.log(isComputed(fullName)); // true
+console.log(isComputed(readOnlyFullName)); // true
+console.log(isComputed(plusOne)); // true
 console.log(isComputed(firstName)); // false
 ```
 

package/dist/computed.d.ts

@@ -6,11 +6,16 @@ export interface ComputedRef<T = any> extends Omit<Ref<T>, 'value'> {
     readonly [isRefSymbol]: true;
 }
 export interface WritableComputedRef<T> extends Ref<T> {
+    readonly [isComputedSymbol]: true;
+    readonly [isRefSymbol]: true;
 }
 type ComputedGetter<T> = () => T;
+type ComputedSetter<T> = (v: T) => void;
+interface WritableComputedOptions<T> {
+    get: ComputedGetter<T>;
+    set: ComputedSetter<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 declare function computed<T>(options: WritableComputedOptions<T>): WritableComputedRef<T>;
+export declare function isComputed<T>(c: any): c is ComputedRef<T> | WritableComputedRef<T>;
 export {};

package/dist/computed.js

@@ -1,59 +1,58 @@
 import { watchEffect, track, trigger } from './watchEffect';
 import { isRefSymbol } from './ref';
-// Symbol for marking computed refs
+// symbol for identifying computed refs
 const isComputedSymbol = Symbol('isComputed');
-// Implementation v4 - Using watchEffect with scheduler
-export function computed(getter) {
+// 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; // Start dirty
-    let computedRef; // Placeholder
-    // Create a lazy effect with a scheduler
+    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, // Don't run the getter immediately
+        lazy: true,
         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 effects that depend on this computed ref
                 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, recompute value by running the getter
             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
+                _value = effectRunner.run();
+                _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');
+            if (setter) {
+                setter(newValue);
+            }
+            else {
+                console.warn('computed value is read-only');
+            }
         },
-        // Expose the stop function if needed
-        // stop: stopHandle
+        // stop: stopHandle // potentially expose stop handle
     };
-    // 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/reactive.js

@@ -3,18 +3,22 @@ import { wrapArray } from './wrapArray';
 import { wrapMap } from './wrapMap';
 import { wrapSet } from './wrapSet';
 import { track, trigger } from './watchEffect';
-// Pre-allocate type check function
+// avoid repeated typeof checks
 function isObject(v) {
     return v && typeof v === 'object';
 }
+// 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;
+            return val; // primitives are returned directly
         if (seen.has(val))
-            return seen.get(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)
@@ -22,43 +26,48 @@ export function reactive(obj, emit, path = [], seen = globalSeen) {
         if (val instanceof Set)
             return wrapSet(val, emit, subPath);
         if (val instanceof Date)
-            return new Date(val.getTime());
+            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 this property access for reactivity
+            // track property access for dependency tracking
             track(target, prop);
-            // Fast path for non-objects
+            // return non-objects directly without wrapping
             if (!isObject(value))
                 return value;
-            // Use cached path concatenation
-            const pathKey = `${path.join('.')}.${String(prop)}`;
+            // 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(String(prop));
+                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];
-            // Fast path for primitive equality
+            // avoid unnecessary triggers if the value hasn't changed
+            // fast path for primitives
             if (oldValue === value)
                 return true;
-            // Only do deep equality check for objects
-            if (isObject(oldValue) && isObject(value) && deepEqual(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 if the set was successful and it's not a setter property
+            // only emit and trigger if the set was successful and wasn't intercepted by a setter
             if (result && (!descriptor || !descriptor.set)) {
-                // Use cached path concatenation
-                const pathKey = `${path.join('.')}.${String(prop)}`;
+                // 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(String(prop));
+                    newPath = path.concat(propKey);
                     setPathConcat(pathKey, newPath);
                 }
                 const event = {
@@ -68,32 +77,38 @@ export function reactive(obj, emit, path = [], seen = globalSeen) {
                     newValue: value
                 };
                 emit(event);
-                // Trigger effects
+                // 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);
-            // 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);
+            // 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);
             }
-            const event = {
-                action: 'delete',
-                path: newPath,
-                oldValue
-            };
-            emit(event);
-            // Trigger effects
-            trigger(target, prop);
             return result;
         }
     });
+    // cache the proxy to handle circular references and improve performance
     seen.set(obj, proxy);
     return proxy;
 }

package/dist/ref.d.ts

@@ -4,19 +4,20 @@ export interface Ref<T = any> {
     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.
+ * 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.
  */
 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.
  */
 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.
+ * 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 declare function unref<T>(refValue: T | Ref<T>): T;

package/dist/ref.js

@@ -1,51 +1,51 @@
 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
+// symbol used to identify refs internally and via isRef()
+export const isRefSymbol = Symbol('isRef');
 export function ref(value) {
     return createRef(value);
 }
-// Internal function to create refs (no longer shallow distinction needed here)
+// internal factory for creating ref objects
 function createRef(rawValue) {
-    // If the value is already a ref, return it directly
+    // avoid wrapping if the value is already a ref
     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
+    // store the inner value
+    let _value = rawValue;
+    // create the ref object with a getter/setter on `.value`
     const r = {
-        [isRefSymbol]: true, // Mark as ref
+        [isRefSymbol]: true, // mark as a ref using the symbol
         get value() {
-            // Track dependency on the 'value' property of this ref object
-            // Ensure 'r' is treated as the target object for tracking
+            // track dependency when `.value` is accessed
+            // `r` (the ref object itself) is the target for tracking
             track(r, 'value');
-            return 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
+            // 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');
             }
         },
-    }; // Explicit cast to ensure type correctness
+    }; // cast to ensure the object conforms to the Ref interface
     return r;
 }
 /**
- * Checks if a value is a ref object.
+ * 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.
+ * 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;