@adbl/cells 0.0.4 → 0.0.6

package/README.md

@@ -186,7 +186,7 @@ When creating a source cell, you have fine-grained control over its behavior:
 ```javascript
 const cell = Cell.source(initialValue, {
   immutable: boolean, // If true, the cell will not allow updates
-  shallowProxied: boolean, // If true, only top-level properties are proxied
+  deep: boolean, // By default, the cell only reacts to changes at the top level of objects. Setting deep to true will proxy the cell to all nested properties and trigger updates when they change as well.
   equals: (oldValue, newValue) => boolean, // Custom equality function
 });
 ```

package/library/classes.js

@@ -36,8 +36,8 @@
  * @typedef {object} CellOptions
  * @property {boolean} [immutable]
  * Whether the cell should be immutable. If set to true, the cell will not allow updates and will throw an error if the value is changed.
- * @property {boolean} [shallowProxied]
- * Whether the cell's value should be shallowly proxied. If set to true, the cell will only proxy the top-level properties of the value, preventing any changes to nested properties. This can be useful for performance optimizations.
+ * @property {boolean} [deep]
+ * Whether the cell should watch for changes deep into the given value. By default the cell only reacts to changes at the top level.
  * @property {(oldValue: T, newValue: T) => boolean} [equals]
  * A function that determines whether two values are equal. If not provided, the default equality function will be used.
  */
@@ -48,6 +48,69 @@
  */
 
 import { activeComputedValues, root } from './root.js';
+const mutativeMethods = {
+  Map: {
+    set: Symbol('set'),
+    delete: Symbol('delete'),
+    clear: Symbol('clear'),
+  },
+  Set: {
+    add: Symbol('add'),
+    delete: Symbol('delete'),
+    clear: Symbol('clear'),
+  },
+  Array: {
+    push: Symbol('push'),
+    pop: Symbol('pop'),
+    shift: Symbol('shift'),
+    unshift: Symbol('unshift'),
+    splice: Symbol('splice'),
+    sort: Symbol('sort'),
+    reverse: Symbol('reverse'),
+  },
+  Date: {
+    setDate: Symbol('setDate'),
+    setMonth: Symbol('setMonth'),
+    setFullYear: Symbol('setFullYear'),
+    setHours: Symbol('setHours'),
+    setMinutes: Symbol('setMinutes'),
+    setSeconds: Symbol('setSeconds'),
+    setMilliseconds: Symbol('setMilliseconds'),
+  },
+};
+const mutativeMapMethods = /^(set|delete|clear)$/;
+const mutativeSetMethods = /^(add|delete|clear)$/;
+const mutativeArrayMethods = /^(push|pop|shift|unshift|splice|sort|reverse)$/;
+const mutativeDateMethods =
+  /^(setDate|setMonth|setFullYear|setHours|setMinutes|setSeconds|setMilliseconds)$/;
+
+/**
+ * Proxies mutative methods of a given value to trigger cell updates when called.
+ *
+ * @template {object} T
+ * @param {T} value - The object whose methods are to be proxied.
+ * @param {keyof typeof mutativeMethods} prototypeName - The name of the prototype (e.g., 'Map', 'Set') whose methods are being proxied.
+ * @param {Cell<any>} cell - The cell to be updated when a mutative method is called.
+ */
+const proxyMutativeMethods = (value, prototypeName, cell) => {
+  for (const method in mutativeMethods[prototypeName]) {
+    Reflect.set(
+      value,
+      Reflect.get(mutativeMethods[prototypeName], method),
+      /**
+       * @param {...any} args - The arguments passed to the mutative method.
+       * @returns {any} The result of calling the original method.
+       */
+      (...args) => {
+        // @ts-ignore
+        const innerMethod = value[method]; // Direct access is faster than Reflection here.
+        const result = innerMethod.apply(value, args);
+        cell.update();
+        return result;
+      }
+    );
+  }
+};
 
 /**
  * @template T
@@ -94,27 +157,18 @@ class Effect {
 }
 
 /**
- * @template T
+ * @template {*} T
  */
 export class Cell {
   /**
    * @type {Array<Effect<T>>}
-   * @protected
    */
-  __effects = [];
+  #effects = [];
 
   /**
    * @type {Array<[WeakRef<DerivedCell<any>>, () => any]>}
-   * @protected
-   */
-  __derivedCells = [];
-
-  /**
-   * @readonly
    */
-  get effects() {
-    return this.__effects;
-  }
+  #derivedCells = [];
 
   /**
    * @readonly
@@ -122,7 +176,7 @@ export class Cell {
    */
   get derivedCells() {
     // @ts-ignore
-    return this.__derivedCells.map((cell) => cell.deref()).filter(Boolean);
+    return this.#derivedCells.map((cell) => cell.deref()).filter(Boolean);
   }
 
   /**
@@ -167,12 +221,12 @@ export class Cell {
     const currentlyComputedValue = activeComputedValues.at(-1);
 
     if (currentlyComputedValue !== undefined) {
-      const isAlreadySubscribed = this.__derivedCells.some(
+      const isAlreadySubscribed = this.#derivedCells.some(
         (ref) => ref[0].deref() === currentlyComputedValue[0]
       );
       if (isAlreadySubscribed) return this.wvalue;
 
-      this.__derivedCells.push([
+      this.#derivedCells.push([
         new WeakRef(currentlyComputedValue[0]),
         currentlyComputedValue[1],
       ]);
@@ -181,14 +235,6 @@ export class Cell {
     return this.wvalue;
   }
 
-  /**
-   * Sets a callback function that will be called whenever the value of the Cell changes.
-   * @param {(newValue: T) => void} callback - The function to be called when the value changes.
-   */
-  set onchange(callback) {
-    this.listen(callback);
-  }
-
   /**
    * Adds the provided effect callback to the list of effects for this cell, and returns a function that can be called to remove the effect.
    * @param {(newValue: T) => void} callback - The effect callback to add.
@@ -219,15 +265,15 @@ export class Cell {
       );
     }
 
-    const isAlreadySubscribed = this.__effects.some((effect) => {
+    const isAlreadySubscribed = this.#effects.some((effect) => {
       return effect.callback === callback;
     });
 
     if (!isAlreadySubscribed) {
-      this.__effects.push(new Effect(callback, options));
+      this.#effects.push(new Effect(callback, options));
     }
 
-    this.__effects.sort((a, b) => {
+    this.#effects.sort((a, b) => {
       const aPriority = a.options?.priority ?? 0;
       const bPriority = b.options?.priority ?? 0;
 
@@ -264,15 +310,15 @@ export class Cell {
       throw new Error(message);
     }
 
-    const isAlreadySubscribed = this.__effects.some((e) => {
+    const isAlreadySubscribed = this.#effects.some((e) => {
       return e.callback === callback;
     });
 
     if (!isAlreadySubscribed) {
-      this.__effects.push(new Effect(cb, options));
+      this.#effects.push(new Effect(cb, options));
     }
 
-    this.__effects.sort((a, b) => {
+    this.#effects.sort((a, b) => {
       const aPriority = a.options?.priority ?? 0;
       const bPriority = b.options?.priority ?? 0;
       if (aPriority === bPriority) return 0;
@@ -287,12 +333,12 @@ export class Cell {
    * @param {(newValue: T) => void} callback - The effect callback to remove.
    */
   ignore(callback) {
-    const index = this.__effects.findIndex((e) => {
+    const index = this.#effects.findIndex((e) => {
       return e.callback === callback;
     });
     if (index === -1) return;
 
-    this.__effects.splice(index, 1);
+    this.#effects.splice(index, 1);
   }
 
   /**
@@ -301,7 +347,7 @@ export class Cell {
    * @returns {boolean} `true` if the cell is listening to a watcher with the specified name, `false` otherwise.
    */
   isListeningTo(name) {
-    return this.__effects.some((effect) => {
+    return this.#effects.some((effect) => {
       return effect?.options?.name === name && effect.callback;
     });
   }
@@ -311,12 +357,12 @@ export class Cell {
    * @param {string} name - The name of the watcher to stop listening to.
    */
   stopListeningTo(name) {
-    const effectIndex = this.__effects.findIndex((e) => {
+    const effectIndex = this.#effects.findIndex((e) => {
       return e.options?.name === name;
     });
     if (effectIndex === -1) return;
 
-    this.__effects.splice(effectIndex, 1);
+    this.#effects.splice(effectIndex, 1);
   }
 
   /**
@@ -325,23 +371,27 @@ export class Cell {
    */
   update() {
     // Run watchers.
-    for (const effect of this.__effects) {
-      const watcher = effect.callback;
+    const batchNestingLevel = root.batchNestingLevel;
+    const wvalue = this.wvalue;
+    const effects = this.#effects;
+    const len = effects.length;
+
+    for (let i = 0; i < len; i++) {
+      const watcher = effects[i].callback;
       if (watcher === undefined) continue;
 
-      if (root.batchNestingLevel > 0) {
-        root.batchedEffects.set(watcher, [this.wvalue]);
-        continue;
+      if (batchNestingLevel > 0) {
+        root.batchedEffects.set(watcher, [wvalue]);
+      } else {
+        watcher(wvalue);
       }
-
-      watcher(this.wvalue);
     }
 
     // Remove dead effects.
-    this.__effects = this.__effects.filter((effect) => effect.callback);
+    this.#effects = this.#effects.filter((effect) => effect.callback);
 
     // Run computed dependents.
-    const computedDependents = this.__derivedCells;
+    const computedDependents = this.#derivedCells;
     if (computedDependents !== undefined) {
       for (const dependent of computedDependents) {
         // global effects
@@ -369,7 +419,7 @@ export class Cell {
       }
     }
     // Periodically drop dead references.
-    this.__derivedCells = this.__derivedCells.filter(
+    this.#derivedCells = this.#derivedCells.filter(
       (ref) => ref[0].deref() !== undefined
     );
 
@@ -649,7 +699,7 @@ export class Cell {
 /**
  * A class that represents a computed value that depends on other reactive values.
  * The computed value is automatically updated when any of its dependencies change.
- * @template T
+ * @template {*} T
  * @extends {Cell<T>}
  */
 export class DerivedCell extends Cell {
@@ -658,9 +708,14 @@ export class DerivedCell extends Cell {
    */
   constructor(computedFn) {
     super();
-    activeComputedValues.push([this, computedFn]);
-    this.setValue(computedFn());
-    activeComputedValues.pop();
+    // Ensures that the cell is derived every time the computing function is called.
+    const derivationWrapper = () => {
+      activeComputedValues.push([this, derivationWrapper]);
+      const value = computedFn();
+      activeComputedValues.pop();
+      return value;
+    };
+    this.setValue(derivationWrapper());
   }
 
   /**
@@ -679,7 +734,7 @@ export class DerivedCell extends Cell {
 }
 
 /**
- * @template T
+ * @template {*} T
  * @extends {Cell<T>}
  */
 export class SourceCell extends Cell {
@@ -697,8 +752,8 @@ export class SourceCell extends Cell {
   constructor(value, options) {
     super();
 
-    this.setValue(options?.shallowProxied ? value : this.proxy(value));
     this.options = options ?? {};
+    this.setValue(this.#proxy(value));
 
     if (typeof value === 'object' && value !== null) {
       this.#originalObject = value;
@@ -759,7 +814,7 @@ export class SourceCell extends Cell {
       }
     }
 
-    this.setValue(this.options?.shallowProxied ? value : this.proxy(value));
+    this.setValue(this.#proxy(value));
     if (typeof value === 'object' && value !== null) {
       this.#originalObject = value;
     }
@@ -771,17 +826,62 @@ export class SourceCell extends Cell {
    * @template T
    * @param {T} value - The value to be proxied.
    * @returns {T} - The proxied value.
-   * @private
    */
-  proxy(value) {
+  #proxy(value) {
     if (typeof value !== 'object' || value === null) {
       return value;
     }
 
+    if (value instanceof Map) {
+      proxyMutativeMethods(value, 'Map', this);
+    } else if (value instanceof Set) {
+      proxyMutativeMethods(value, 'Set', this);
+    } else if (value instanceof Date) {
+      proxyMutativeMethods(value, 'Date', this);
+    } else if (ArrayBuffer.isView(value) || Array.isArray(value)) {
+      proxyMutativeMethods(value, 'Array', this);
+    }
+
     return new Proxy(value, {
       get: (target, prop) => {
         this.revalued;
-        return this.proxy(Reflect.get(target, prop));
+        if (this.options.deep) {
+          // @ts-ignore: Direct access is faster than Reflection here.
+          return this.#proxy(target[prop]);
+        }
+        // @ts-ignore: Direct access is faster than Reflection here.
+        let value = target[prop];
+
+        if (typeof value === 'function') {
+          value = value.bind(target);
+        }
+
+        if (typeof prop === 'string') {
+          if (target instanceof Map && mutativeMapMethods.test(prop)) {
+            // @ts-ignore: Direct access is faster than Reflection here.
+            return target[mutativeMethods.Map[prop]];
+          }
+
+          if (target instanceof Set && mutativeSetMethods.test(prop)) {
+            // @ts-ignore: Direct access is faster than Reflection here.
+            return target[mutativeMethods.Set[prop]];
+          }
+
+          if (target instanceof Date && mutativeDateMethods.test(prop)) {
+            // @ts-ignore: Direct access is faster than Reflection here.
+            return target[mutativeMethods.Date[prop]];
+          }
+
+          if (
+            (ArrayBuffer.isView(target) || Array.isArray(target)) &&
+            mutativeArrayMethods.test(prop)
+          ) {
+            // @ts-ignore: Direct access is faster than Reflection here.
+            return target[mutativeMethods.Array[prop]];
+          }
+        }
+
+        return value;
       },
       set: (target, prop, value) => {
         const formerValue = Reflect.get(target, prop);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adbl/cells",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "description": "A simple implementation of reactive updates for JavaScript",
   "main": "index.js",
   "private": false,

package/types/library/classes.d.ts

@@ -1,7 +1,7 @@
 /**
- * @template T
+ * @template {*} T
  */
-export class Cell<T> {
+export class Cell<T extends unknown> {
     /**
      * Adds a global effect that runs before any Cell is updated.
      * @param {(value: unknown) => void} effect - The effect function.
@@ -122,7 +122,7 @@ export class Cell<T> {
      * @param {T} object - The object to be flattened.
      * @returns {{ [K in keyof T]: T[K] extends Cell<infer U> ? U : T[K] }} A new object with the flattened values.
      */
-    static flattenObject: <T_6 extends object>(object: T_6) => { [K in keyof T_6]: T_6[K] extends Cell<infer U_1> ? U_1 : T_6[K]; };
+    static flattenObject: <T_6 extends object>(object: T_6) => { [K in keyof T_6]: T_6[K] extends Cell<infer U_1 extends unknown> ? U_1 : T_6[K]; };
     /**
      * Wraps an asynchronous function with managed state.
      *
@@ -141,20 +141,6 @@ export class Cell<T> {
      * run('input');
      */
     static async<X, Y>(getter: (input: X) => Promise<Y>): AsyncRequestAtoms<X, Y>;
-    /**
-     * @type {Array<Effect<T>>}
-     * @protected
-     */
-    protected __effects: Array<Effect<T>>;
-    /**
-     * @type {Array<[WeakRef<DerivedCell<any>>, () => any]>}
-     * @protected
-     */
-    protected __derivedCells: Array<[WeakRef<DerivedCell<any>>, () => any]>;
-    /**
-     * @readonly
-     */
-    readonly get effects(): Effect<T>[];
     /**
      * @readonly
      * @returns {Array<DerivedCell<any>>}
@@ -185,11 +171,6 @@ export class Cell<T> {
      * @protected @type {T}
      */
     protected get revalued(): T;
-    /**
-     * Sets a callback function that will be called whenever the value of the Cell changes.
-     * @param {(newValue: T) => void} callback - The function to be called when the value changes.
-     */
-    set onchange(callback: (newValue: T) => void);
     /**
      * Adds the provided effect callback to the list of effects for this cell, and returns a function that can be called to remove the effect.
      * @param {(newValue: T) => void} callback - The effect callback to add.
@@ -230,14 +211,15 @@ export class Cell<T> {
      * @returns {T} - The current value of the cell.
      */
     peek(): T;
+    #private;
 }
 /**
  * A class that represents a computed value that depends on other reactive values.
  * The computed value is automatically updated when any of its dependencies change.
- * @template T
+ * @template {*} T
  * @extends {Cell<T>}
  */
-export class DerivedCell<T> extends Cell<T> {
+export class DerivedCell<T extends unknown> extends Cell<T> {
     /**
      * @param {() => T} computedFn - A function that generates the value of the computed.
      */
@@ -252,10 +234,10 @@ export class DerivedCell<T> extends Cell<T> {
     readonly get value(): T;
 }
 /**
- * @template T
+ * @template {*} T
  * @extends {Cell<T>}
  */
-export class SourceCell<T> extends Cell<T> {
+export class SourceCell<T extends unknown> extends Cell<T> {
     /**
      * Creates a new Cell with the provided value.
      * @param {T} value
@@ -285,14 +267,6 @@ export class SourceCell<T> extends Cell<T> {
      */
     set value(value: T);
     get value(): T;
-    /**
-     * Proxies the provided value deeply, allowing it to be observed and updated.
-     * @template T
-     * @param {T} value - The value to be proxied.
-     * @returns {T} - The proxied value.
-     * @private
-     */
-    private proxy;
     #private;
 }
 export type AsyncRequestAtoms<Input, Output> = {
@@ -345,9 +319,9 @@ export type CellOptions<T> = {
      */
     immutable?: boolean | undefined;
     /**
-     * Whether the cell's value should be shallowly proxied. If set to true, the cell will only proxy the top-level properties of the value, preventing any changes to nested properties. This can be useful for performance optimizations.
+     * Whether the cell should watch for changes deep into the given value. By default the cell only reacts to changes at the top level.
      */
-    shallowProxied?: boolean | undefined;
+    deep?: boolean | undefined;
     /**
      * A function that determines whether two values are equal. If not provided, the default equality function will be used.
      */
@@ -357,28 +331,3 @@ export type NeverIfAny<T> = 0 extends (1 & T) ? never : T;
 export type Reference<T> = {
     deref: () => T | undefined;
 };
-/**
- * @template T
- * @typedef {{
- *    deref: () => T | undefined
- * }} Reference
- */
-/** @template T */
-declare class Effect<T> {
-    /**
-     * @param {(newValue: T) => void} callback
-     * @param {EffectOptions} [options]
-     */
-    constructor(callback: (newValue: T) => void, options?: EffectOptions | undefined);
-    /**
-     * @type {EffectOptions | undefined}
-     */
-    options: EffectOptions | undefined;
-    /**
-     * Returns the callback function, if it still exists.
-     * @returns {((newValue: T) => void) | undefined}
-     */
-    get callback(): ((newValue: T) => void) | undefined;
-    #private;
-}
-export {};