@adbl/cells 0.0.0 → 0.0.2

package/library/classes.js

@@ -25,6 +25,8 @@
  * An AbortSignal to be used to ignore the effect if it is aborted.
  * @property {string} [name]
  * The name of the effect for debugging purposes.
+ * @property {boolean} [weak]
+ * Whether the effect should be weakly referenced. This means that the effect will be garbage collected if there are no other references to it.
  * @property {number} [priority]
  * The priority of the effect. Higher priority effects are executed first. The default priority is 0.
  */
@@ -47,24 +49,81 @@
 
 import { activeComputedValues, root } from './root.js';
 
+/**
+ * @template T
+ * @typedef {{
+ *    deref: () => T | undefined
+ * }} Reference
+ */
+
+/** @template T */
+class Effect {
+  /**
+   * @type {EffectOptions | undefined}
+   */
+  options;
+
+  /**
+   * @type {WeakRef<(newValue: T) => void> | ((newValue: T) => void) }
+   */
+  #callback;
+
+  /**
+   * @param {(newValue: T) => void} callback
+   * @param {EffectOptions} [options]
+   */
+  constructor(callback, options) {
+    if (options?.weak) {
+      this.#callback = new WeakRef(callback);
+    } else {
+      this.#callback = callback;
+    }
+    this.options = options;
+  }
+
+  /**
+   * Returns the callback function, if it still exists.
+   * @returns {((newValue: T) => void) | undefined}
+   */
+  get callback() {
+    if (this.#callback instanceof WeakRef) {
+      return this.#callback.deref();
+    }
+    return this.#callback;
+  }
+}
+
 /**
  * @template T
  */
 export class Cell {
   /**
-   * @type {Array<({
-   *  effect: (newValue: T) => void,
-   *  options?: EffectOptions,
-   * })>}
+   * @type {Array<Effect<T>>}
    * @protected
    */
-  effects = [];
+  __effects = [];
 
   /**
-   * @type {Array<WeakRef<DerivedCell<any>>>}
+   * @type {Array<[WeakRef<DerivedCell<any>>, () => any]>}
    * @protected
    */
-  derivedCells = [];
+  __derivedCells = [];
+
+  /**
+   * @readonly
+   */
+  get effects() {
+    return this.__effects;
+  }
+
+  /**
+   * @readonly
+   * @returns {Array<DerivedCell<any>>}
+   */
+  get derivedCells() {
+    // @ts-ignore
+    return this.__derivedCells.map((cell) => cell.deref()).filter(Boolean);
+  }
 
   /**
    * @protected @type T
@@ -84,9 +143,22 @@ export class Cell {
    * @returns {T} The value of the Cell.
    */
   valueOf() {
+    return this.revalued;
+  }
+
+  get value() {
     return this.wvalue;
   }
 
+  /**
+   * Stringifies the value of the Cell.
+   * @returns {string}
+   */
+  toString() {
+    // @ts-ignore
+    return this.wvalue.toString();
+  }
+
   /**
    * The value stored in the Cell.
    * @protected @type {T}
@@ -95,12 +167,15 @@ export class Cell {
     const currentlyComputedValue = activeComputedValues.at(-1);
 
     if (currentlyComputedValue !== undefined) {
-      const isAlreadySubscribed = this.derivedCells.some(
-        (ref) => ref.deref() === currentlyComputedValue
+      const isAlreadySubscribed = this.__derivedCells.some(
+        (ref) => ref[0].deref() === currentlyComputedValue[0]
       );
       if (isAlreadySubscribed) return this.wvalue;
 
-      this.derivedCells.push(new WeakRef(currentlyComputedValue));
+      this.__derivedCells.push([
+        new WeakRef(currentlyComputedValue[0]),
+        currentlyComputedValue[1],
+      ]);
     }
 
     return this.wvalue;
@@ -138,26 +213,25 @@ export class Cell {
       };
     }
 
-    if (options?.name) {
-      if (this.isListeningTo(options.name)) {
-        throw new Error(
-          `An effect with the name "${options.name}" is already listening to this cell.`
-        );
-      }
+    if (options?.name && this.isListeningTo(options.name)) {
+      throw new Error(
+        `An effect with the name "${options.name}" is already listening to this cell.`
+      );
     }
 
-    if (this.effects.some(({ effect }) => effect === callback)) {
-      throw new Error('This effect is already listening to this cell.');
-    }
+    const isAlreadySubscribed = this.__effects.some((effect) => {
+      return effect.callback === callback;
+    });
 
-    this.effects.push({ effect, options });
+    if (!isAlreadySubscribed) {
+      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;
-      if (aPriority === bPriority) {
-        return 0;
-      }
+
+      if (aPriority === bPriority) return 0;
       return aPriority < bPriority ? 1 : -1;
     });
 
@@ -166,12 +240,46 @@ export class Cell {
 
   /**
    * Creates an effect that is immediately executed with the current value of the cell, and then added to the list of effects for the cell.
-   * @param {(newValue: T) => void} effect - The effect callback to add.
+   * @param {(newValue: T) => void} callback - The effect callback to add.
+   * @param {Partial<EffectOptions>} [options] - The options for the effect.
    * @returns {() => void} A function that can be called to remove the effect.
    */
-  runAndListen(effect) {
-    effect(this.wvalue);
-    return this.listen(effect);
+  runAndListen(callback, options) {
+    const cb = callback;
+
+    cb(this.wvalue);
+
+    if (options?.signal?.aborted) {
+      return () => {};
+    }
+
+    options?.signal?.addEventListener('abort', () => {
+      this.ignore(cb);
+    });
+
+    if (options?.once) return () => this.ignore(cb);
+
+    if (options?.name && this.isListeningTo(options.name)) {
+      const message = `An effect with the name "${options.name}" is already listening to this cell.`;
+      throw new Error(message);
+    }
+
+    const isAlreadySubscribed = this.__effects.some((e) => {
+      return e.callback === callback;
+    });
+
+    if (!isAlreadySubscribed) {
+      this.__effects.push(new Effect(cb, options));
+    }
+
+    this.__effects.sort((a, b) => {
+      const aPriority = a.options?.priority ?? 0;
+      const bPriority = b.options?.priority ?? 0;
+      if (aPriority === bPriority) return 0;
+      return aPriority < bPriority ? 1 : -1;
+    });
+
+    return () => this.ignore(cb);
   }
 
   /**
@@ -179,10 +287,12 @@ export class Cell {
    * @param {(newValue: T) => void} callback - The effect callback to remove.
    */
   ignore(callback) {
-    const index = this.effects.findIndex(({ effect }) => effect === callback);
+    const index = this.__effects.findIndex((e) => {
+      return e.callback === callback;
+    });
     if (index === -1) return;
 
-    this.effects.splice(index, 1);
+    this.__effects.splice(index, 1);
   }
 
   /**
@@ -191,7 +301,9 @@ 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(({ options }) => options?.name === name);
+    return this.__effects.some((effect) => {
+      return effect?.options?.name === name && effect.callback;
+    });
   }
 
   /**
@@ -199,12 +311,12 @@ export class Cell {
    * @param {string} name - The name of the watcher to stop listening to.
    */
   stopListeningTo(name) {
-    const effectIndex = this.effects.findIndex(
-      ({ options }) => options?.name === name
-    );
+    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);
   }
 
   /**
@@ -213,7 +325,10 @@ export class Cell {
    */
   update() {
     // Run watchers.
-    for (const { effect: watcher } of this.effects) {
+    for (const effect of this.__effects) {
+      const watcher = effect.callback;
+      if (watcher === undefined) continue;
+
       if (root.batchNestingLevel > 0) {
         root.batchedEffects.set(watcher, [this.wvalue]);
         continue;
@@ -222,16 +337,40 @@ export class Cell {
       watcher(this.wvalue);
     }
 
+    // Remove dead effects.
+    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) {
-        dependent.deref()?.update();
+        // global effects
+        for (const [options, effect] of root.globalPreEffects) {
+          if (options.ignoreDerivedCells) continue;
+
+          effect(this.wvalue);
+        }
+
+        const deref = dependent[0].deref();
+        if (deref === undefined) continue;
+
+        const computedCell = deref;
+        const computedFn = dependent[1];
+
+        if (root.batchNestingLevel > 0) {
+          root.batchedEffects.set(
+            () => computedCell.setValue(computedFn()),
+            []
+          );
+        } else {
+          computedCell.setValue(computedFn());
+        }
+        computedCell.update();
       }
     }
-    // Periodically remove dead references.
-    this.derivedCells = this.derivedCells.filter(
-      (ref) => ref.deref() !== undefined
+    // Periodically drop dead references.
+    this.__derivedCells = this.__derivedCells.filter(
+      (ref) => ref[0].deref() !== undefined
     );
 
     // global effects
@@ -380,8 +519,10 @@ export class Cell {
 
   /**
    * Checks if the provided value is an instance of the Cell class.
-   * @param {any} value - The value to check.
-   * @returns {value is Cell<any>} True if the value is an instance of Cell, false otherwise.
+   * @template [T=any]
+   * @template [U=any]
+   * @param {Cell<T> | U} value - The value to check.
+   * @returns {value is Cell<T>} True if the value is an instance of Cell, false otherwise.
    */
   static isCell = (value) => value instanceof Cell;
 
@@ -452,6 +593,8 @@ export class Cell {
 
     async function run(input = initialInput) {
       pending.value = true;
+      error.value = null;
+      data.value = null;
       try {
         initialInput = input;
         const result = await getter(/** @type {X} */ (input));
@@ -510,19 +653,12 @@ export class Cell {
  * @extends {Cell<T>}
  */
 export class DerivedCell extends Cell {
-  /**
-   * @type {() => T}
-   * @protected
-   */
-  computedFn;
-
   /**
    * @param {() => T} computedFn - A function that generates the value of the computed.
    */
   constructor(computedFn) {
     super();
-    this.computedFn = computedFn;
-    activeComputedValues.push(this);
+    activeComputedValues.push([this, computedFn]);
     this.setValue(computedFn());
     activeComputedValues.pop();
   }
@@ -540,26 +676,6 @@ export class DerivedCell extends Cell {
   set value(_) {
     throw new Error('Cannot set a derived Cell value.');
   }
-
-  /**
-   * Updates the current value with the result of the computed function.
-   */
-  update() {
-    // global effects
-    for (const [options, effect] of root.globalPreEffects) {
-      if (options.ignoreDerivedCells) continue;
-
-      effect(this.wvalue);
-    }
-
-    if (root.batchNestingLevel > 0) {
-      root.batchedEffects.set(() => this.setValue(this.computedFn()), []);
-    } else {
-      this.setValue(this.computedFn());
-    }
-
-    super.update();
-  }
 }
 
 /**
@@ -599,7 +715,7 @@ export class SourceCell extends Cell {
 
     const isEqual = this.options.equals
       ? this.options.equals(oldValue, value)
-      : oldValue === value;
+      : deepEqual(oldValue, value);
 
     if (isEqual) return;
 
@@ -614,7 +730,7 @@ export class SourceCell extends Cell {
       }
     }
 
-    this.setValue(value);
+    this.setValue(this.options?.shallowProxied ? value : this.proxy(value));
     this.update();
   }
 
@@ -636,10 +752,53 @@ export class SourceCell extends Cell {
         return this.proxy(Reflect.get(target, prop));
       },
       set: (target, prop, value) => {
+        const formerValue = Reflect.get(target, prop);
         Reflect.set(target, prop, value);
-        this.update();
+
+        const isEqual = deepEqual(formerValue, value);
+        if (!isEqual) this.update();
+
         return true;
       },
     });
   }
 }
+
+/**
+ * Recursively compares two values for deep equality.
+ * @param {any} a - The first value to compare.
+ * @param {any} b - The second value to compare.
+ * @returns {boolean} - True if the values are deeply equal, false otherwise.
+ */
+function deepEqual(a, b) {
+  if (a === b) return true;
+
+  if (
+    typeof a !== typeof b ||
+    typeof a !== 'object' ||
+    a === null ||
+    b === null
+  )
+    return false;
+
+  if (Array.isArray(a)) {
+    const aLength = a.length;
+    if (!Array.isArray(b) || aLength !== b.length) return false;
+
+    for (let i = 0; i < aLength; i++) {
+      if (!deepEqual(a[i], b[i])) return false;
+    }
+  } else {
+    const keysA = Object.keys(a);
+    const keysB = Object.keys(b);
+    const keysALength = keysA.length;
+    if (keysALength !== keysB.length) return false;
+
+    for (let i = 0; i < keysALength; i++) {
+      const key = keysA[i];
+      if (a === b) return true;
+      if (!(key in b) || !deepEqual(a[key], b[key])) return false;
+    }
+  }
+  return true;
+}

package/library/root.js

@@ -39,6 +39,6 @@ export const root = {
 /**
  * A value representing the computed values that are currently being calculated.
  * It is an array so it can keep track of nested computed values.
- * @type {DerivedCell[]}
+ * @type {[DerivedCell, () => any][]}
  */
 export const activeComputedValues = [];

package/package.json

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

package/types/library/classes.d.ts

@@ -96,31 +96,33 @@ export class Cell<T> {
     static batch: (callback: () => void) => void;
     /**
      * Checks if the provided value is an instance of the Cell class.
-     * @param {any} value - The value to check.
-     * @returns {value is Cell<any>} True if the value is an instance of Cell, false otherwise.
+     * @template [T=any]
+     * @template [U=any]
+     * @param {Cell<T> | U} value - The value to check.
+     * @returns {value is Cell<T>} True if the value is an instance of Cell, false otherwise.
      */
-    static isCell: (value: any) => value is Cell<any>;
+    static isCell: <T_3 = any, U = any>(value: U | Cell<T_3>) => value is Cell<T_3>;
     /**
      * @template T
      * Flattens the provided value by returning the value if it is not a Cell instance, or the value of the Cell instance if it is.
      * @param {T | Cell<T>} value - The value to be flattened.
      * @returns {T} The flattened value.
      */
-    static flatten: <T_3>(value: T_3 | Cell<T_3>) => T_3;
+    static flatten: <T_4>(value: T_4 | Cell<T_4>) => T_4;
     /**
      * Flattens an array by applying the `flatten` function to each element.
      * @template T
      * @param {Array<T | Cell<T>>} array - The array to be flattened.
      * @returns {Array<T>} A new array with the flattened elements.
      */
-    static flattenArray: <T_4>(array: (T_4 | Cell<T_4>)[]) => T_4[];
+    static flattenArray: <T_5>(array: (T_5 | Cell<T_5>)[]) => T_5[];
     /**
      * Flattens an object by applying the `flatten` function to each value.
      * @template {object} 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_5 extends object>(object: T_5) => { [K in keyof T_5]: T_5[K] extends Cell<infer U> ? U : T_5[K]; };
+    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]; };
     /**
      * Wraps an asynchronous function with managed state.
      *
@@ -140,21 +142,24 @@ export class Cell<T> {
      */
     static async<X, Y>(getter: (input: X) => Promise<Y>): AsyncRequestAtoms<X, Y>;
     /**
-     * @type {Array<({
-     *  effect: (newValue: T) => void,
-     *  options?: EffectOptions,
-     * })>}
+     * @type {Array<Effect<T>>}
      * @protected
      */
-    protected effects: Array<({
-        effect: (newValue: T) => void;
-        options?: EffectOptions;
-    })>;
+    protected __effects: Array<Effect<T>>;
     /**
-     * @type {Array<WeakRef<DerivedCell<any>>>}
+     * @type {Array<[WeakRef<DerivedCell<any>>, () => any]>}
      * @protected
      */
-    protected derivedCells: Array<WeakRef<DerivedCell<any>>>;
+    protected __derivedCells: Array<[WeakRef<DerivedCell<any>>, () => any]>;
+    /**
+     * @readonly
+     */
+    readonly get effects(): Effect<T>[];
+    /**
+     * @readonly
+     * @returns {Array<DerivedCell<any>>}
+     */
+    readonly get derivedCells(): DerivedCell<any>[];
     /**
      * @protected @type T
      */
@@ -169,6 +174,12 @@ export class Cell<T> {
      * @returns {T} The value of the Cell.
      */
     valueOf(): T;
+    get value(): T;
+    /**
+     * Stringifies the value of the Cell.
+     * @returns {string}
+     */
+    toString(): string;
     /**
      * The value stored in the Cell.
      * @protected @type {T}
@@ -188,10 +199,11 @@ export class Cell<T> {
     listen(callback: (newValue: T) => void, options?: EffectOptions | undefined): () => void;
     /**
      * Creates an effect that is immediately executed with the current value of the cell, and then added to the list of effects for the cell.
-     * @param {(newValue: T) => void} effect - The effect callback to add.
+     * @param {(newValue: T) => void} callback - The effect callback to add.
+     * @param {Partial<EffectOptions>} [options] - The options for the effect.
      * @returns {() => void} A function that can be called to remove the effect.
      */
-    runAndListen(effect: (newValue: T) => void): () => void;
+    runAndListen(callback: (newValue: T) => void, options?: Partial<EffectOptions> | undefined): () => void;
     /**
      * Removes the specified effect callback from the list of effects for this cell.
      * @param {(newValue: T) => void} callback - The effect callback to remove.
@@ -203,6 +215,11 @@ export class Cell<T> {
      * @returns {boolean} `true` if the cell is listening to a watcher with the specified name, `false` otherwise.
      */
     isListeningTo(name: string): boolean;
+    /**
+     * Removes the watcher with the specified name from the list of effects for this cell.
+     * @param {string} name - The name of the watcher to stop listening to.
+     */
+    stopListeningTo(name: string): void;
     /**
      * Updates the root object and notifies any registered watchers and computed dependents.
      * This method is called whenever the root object's value changes.
@@ -225,11 +242,6 @@ export class DerivedCell<T> extends Cell<T> {
      * @param {() => T} computedFn - A function that generates the value of the computed.
      */
     constructor(computedFn: () => T);
-    /**
-     * @type {() => T}
-     * @protected
-     */
-    protected computedFn: () => T;
     /**
      * @readonly
      */
@@ -302,6 +314,10 @@ export type EffectOptions = {
      * The name of the effect for debugging purposes.
      */
     name?: string | undefined;
+    /**
+     * Whether the effect should be weakly referenced. This means that the effect will be garbage collected if there are no other references to it.
+     */
+    weak?: boolean | undefined;
     /**
      * The priority of the effect. Higher priority effects are executed first. The default priority is 0.
      */
@@ -322,3 +338,31 @@ export type CellOptions<T> = {
     equals?: ((oldValue: T, newValue: T) => boolean) | undefined;
 };
 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 {};

package/types/library/root.d.ts

@@ -7,9 +7,9 @@ export namespace root {
 /**
  * A value representing the computed values that are currently being calculated.
  * It is an array so it can keep track of nested computed values.
- * @type {DerivedCell[]}
+ * @type {[DerivedCell, () => any][]}
  */
-export const activeComputedValues: import("./classes.js").DerivedCell<any>[];
+export const activeComputedValues: [import("./classes.js").DerivedCell<any>, () => any][];
 export type Watchable = import('./classes.js').Cell<any>;
 export type DerivedCell = import('./classes.js').DerivedCell<any>;
 export type GlobalEffectOptions = {

package/jsconfig.json

@@ -1,25 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ESNext",
-    "module": "NodeNext",
-    "moduleResolution": "NodeNext",
-    "noUnusedLocals": true,
-    "noUnusedParameters": true,
-    "noImplicitAny": true,
-    "allowUnreachableCode": false,
-    "allowJs": true,
-
-    "noImplicitReturns": true,
-
-    "noEmit": false,
-    "emitDeclarationOnly": true,
-    "declaration": true,
-
-    "checkJs": true,
-    "strict": true,
-
-    "outDir": "types"
-  },
-  "include": ["library/**/*", "index.js"],
-  "exclude": ["types/**/*", "tests/**/*"]
-}