@adbl/cells 0.0.0

package/.vscode/settings.json

@@ -0,0 +1,4 @@
+{
+  "cSpell.words": ["wvalue"],
+  "deno.enable": false
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Sefunmi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,205 @@
+# @adbl/cells
+
+[![npm version](https://badge.fury.io/js/%40adbl%2Fcells.svg)](https://badge.fury.io/js/%40adbl%2Fcells)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Cells is a powerful yet lightweight library for reactive state management in JavaScript applications. It offers an intuitive API that simplifies the complexities of managing and propagating state changes throughout your application.
+
+## Features
+
+- **Simple API**: Easy to learn and use, even for developers new to reactive programming.
+- **Lightweight**: No external dependencies, keeping your project lean.
+- **Flexible**: Works seamlessly with any JavaScript framework or vanilla JS.
+- **Type-safe**: Built with TypeScript, providing excellent type inference and checking.
+- **Performant**: Optimized for efficiency, with features like batched updates to minimize unnecessary computations.
+
+## Installation
+
+Get started with Cells in your project:
+
+```bash
+npm install @adbl/cells
+```
+
+Or if you prefer Yarn:
+
+```bash
+yarn add @adbl/cells
+```
+
+## Core Concepts
+
+### 1. Source Cells
+
+Source cells are the building blocks of your reactive state. They hold values that can change over time, automatically notifying dependents when updates occur.
+
+```javascript
+import { Cell } from '@adbl/cells';
+
+const count = Cell.source(0);
+console.log(count.value); // Output: 0
+
+count.value = 5;
+console.log(count.value); // Output: 5
+```
+
+### 2. Derived Cells
+
+Derived cells allow you to create computed values based on other cells. They update automatically when their dependencies change, ensuring your derived state is always in sync.
+
+```javascript
+const count = Cell.source(0);
+const doubledCount = Cell.derived(() => count.value * 2);
+
+console.log(doubledCount.value); // Output: 0
+
+count.value = 5;
+console.log(doubledCount.value); // Output: 10
+```
+
+### 3. Reactive Effects
+
+Easily set up listeners to react to changes in cell values, allowing you to create side effects or update your UI in response to state changes.
+
+```javascript
+const count = Cell.source(0);
+
+count.listen((newValue) => {
+  console.log(`Count changed to: ${newValue}`);
+});
+
+count.value = 3; // Output: "Count changed to: 3"
+count.value = 7; // Output: "Count changed to: 7"
+```
+
+### 4. Global Effects
+
+Cells allows you to set up global effects that run before or after any cell is updated, giving you fine-grained control over your application's reactive behavior.
+
+```javascript
+Cell.beforeUpdate((value) => {
+  console.log(`About to update a cell with value: ${value}`);
+});
+
+Cell.afterUpdate((value) => {
+  console.log(`Just updated a cell with value: ${value}`);
+});
+```
+
+### 5. Batch Updates
+
+When you need to perform multiple updates but only want to trigger effects once, you can use batch updates to optimize performance:
+
+```javascript
+const cell1 = Cell.source(0);
+const cell2 = Cell.source(0);
+
+Cell.afterUpdate(() => {
+  console.log('Update occurred');
+});
+
+Cell.batch(() => {
+  cell1.value = 1;
+  cell2.value = 2;
+});
+// Output: "Update occurred" (only once)
+```
+
+### 6. Async Operations
+
+Cells provides utilities for handling asynchronous operations, making it easy to manage loading states, data, and errors:
+
+```javascript
+const fetchUser = Cell.async(async (userId) => {
+  const response = await fetch(`https://api.example.com/users/${userId}`);
+  return response.json();
+});
+
+const { pending, data, error, run } = fetchUser;
+
+pending.listen((isPending) => {
+  console.log(isPending ? 'Loading...' : 'Done!');
+});
+
+data.listen((userData) => {
+  if (userData) {
+    console.log('User data:', userData);
+  }
+});
+
+run(123); // Triggers the async operation
+```
+
+### 7. Flattening
+
+Cells offers utility functions to work with nested cell structures, making it easier to handle complex state shapes:
+
+```javascript
+const nestedCell = Cell.source(Cell.source(5));
+const flattenedValue = Cell.flatten(nestedCell);
+console.log(flattenedValue); // Output: 5
+
+const arrayOfCells = [Cell.source(1), Cell.source(2), Cell.source(3)];
+const flattenedArray = Cell.flattenArray(arrayOfCells);
+console.log(flattenedArray); // Output: [1, 2, 3]
+
+const objectWithCells = { a: Cell.source(1), b: Cell.source(2) };
+const flattenedObject = Cell.flattenObject(objectWithCells);
+console.log(flattenedObject); // Output: { a: 1, b: 2 }
+```
+
+### 8. Custom Equality Checks
+
+For more complex objects, you can provide custom equality functions to determine when a cell's value has truly changed:
+
+```javascript
+const userCell = Cell.source(
+  { name: 'Alice', age: 30 },
+  {
+    equals: (a, b) => a.name === b.name && a.age === b.age,
+  }
+);
+```
+
+### 9. Named Effects
+
+To aid in debugging, you can name your effects, making it easier to track and manage them:
+
+```javascript
+const count = Cell.source(0);
+
+count.listen((value) => console.log(`Count is now: ${value}`), {
+  name: 'countLogger',
+});
+
+console.log(count.isListeningTo('countLogger')); // Output: true
+
+count.stopListeningTo('countLogger');
+```
+
+## Advanced Features and API Details
+
+### Cell Options
+
+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
+  equals: (oldValue, newValue) => boolean, // Custom equality function
+});
+```
+
+### Effect Options
+
+When setting up listeners or effects, you can customize their behavior:
+
+```javascript
+cell.listen(callback, {
+  once: boolean, // If true, the effect will only run once
+  signal: AbortSignal, // An AbortSignal to cancel the effect
+  name: string, // A name for the effect (useful for debugging)
+  priority: number, // The priority of the effect (higher priority effects run first)
+});
+```

package/index.js

@@ -0,0 +1,3 @@
+/// <reference types="./types/index.d.ts" />
+
+export * from './library/index.js';

package/jsconfig.json

@@ -0,0 +1,25 @@
+{
+  "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/**/*"]
+}

package/library/classes.js

@@ -0,0 +1,645 @@
+/**
+ * @template Input, Output
+ * @typedef {Object} AsyncRequestAtoms
+ *
+ * @property {SourceCell<boolean>} pending
+ * Represents the loading state of an asynchronous request.
+ *
+ * @property {SourceCell<Output|null>} data
+ * Represents the data returned by the asynchronous request.
+ *
+ * @property {SourceCell<Error | null>} error
+ * Represents the errors returned by the asynchronous request, if any.
+ *
+ * @property {NeverIfAny<Input> extends never ? (input?: Input) => Promise<void> : (input: Input) => Promise<void>} run
+ * Triggers the asynchronous request.
+ *
+ * @property {(newInput?: Input, changeLoadingState?: boolean) => Promise<void>} reload Triggers the asynchronous request again with an optional new input and optionally changes the loading state.
+ */
+
+/**
+ * @typedef {object} EffectOptions
+ * @property {boolean} [once]
+ * Whether the effect should be removed after the first run.
+ * @property {AbortSignal} [signal]
+ * 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 {number} [priority]
+ * The priority of the effect. Higher priority effects are executed first. The default priority is 0.
+ */
+
+/**
+ * @template T
+ * @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 {(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.
+ */
+
+/**
+ * @template T
+ * @typedef {0 extends (1 & T) ? never : T} NeverIfAny
+ */
+
+import { activeComputedValues, root } from './root.js';
+
+/**
+ * @template T
+ */
+export class Cell {
+  /**
+   * @type {Array<({
+   *  effect: (newValue: T) => void,
+   *  options?: EffectOptions,
+   * })>}
+   * @protected
+   */
+  effects = [];
+
+  /**
+   * @type {Array<WeakRef<DerivedCell<any>>>}
+   * @protected
+   */
+  derivedCells = [];
+
+  /**
+   * @protected @type T
+   */
+  wvalue = /** @type {T} */ (null);
+
+  /**
+   * @protected
+   * @param {T} value
+   */
+  setValue(value) {
+    this.wvalue = value;
+  }
+
+  /**
+   * Overrides `Object.prototype.valueOf()` to return the value stored in the Cell.
+   * @returns {T} The value of the Cell.
+   */
+  valueOf() {
+    return this.wvalue;
+  }
+
+  /**
+   * The value stored in the Cell.
+   * @protected @type {T}
+   */
+  get revalued() {
+    const currentlyComputedValue = activeComputedValues.at(-1);
+
+    if (currentlyComputedValue !== undefined) {
+      const isAlreadySubscribed = this.derivedCells.some(
+        (ref) => ref.deref() === currentlyComputedValue
+      );
+      if (isAlreadySubscribed) return this.wvalue;
+
+      this.derivedCells.push(new WeakRef(currentlyComputedValue));
+    }
+
+    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.
+   * @param {EffectOptions} [options] - The options for the effect.
+   * @returns {() => void} A function that can be called to remove the effect.
+   */
+  listen(callback, options) {
+    let effect = callback;
+
+    if (options?.signal?.aborted) {
+      return () => {};
+    }
+
+    options?.signal?.addEventListener('abort', () => {
+      this.ignore(effect);
+    });
+
+    if (options?.once) {
+      effect = () => {
+        callback(this.wvalue);
+        this.ignore(effect);
+      };
+    }
+
+    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 (this.effects.some(({ effect }) => effect === callback)) {
+      throw new Error('This effect is already listening to this cell.');
+    }
+
+    this.effects.push({ effect, 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(effect);
+  }
+
+  /**
+   * 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.
+   * @returns {() => void} A function that can be called to remove the effect.
+   */
+  runAndListen(effect) {
+    effect(this.wvalue);
+    return this.listen(effect);
+  }
+
+  /**
+   * Removes the specified effect callback from the list of effects for this cell.
+   * @param {(newValue: T) => void} callback - The effect callback to remove.
+   */
+  ignore(callback) {
+    const index = this.effects.findIndex(({ effect }) => effect === callback);
+    if (index === -1) return;
+
+    this.effects.splice(index, 1);
+  }
+
+  /**
+   * Checks if the cell is listening to a watcher with the specified name.
+   * @param {string} name - The name of the watcher to check for.
+   * @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);
+  }
+
+  /**
+   * 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) {
+    const effectIndex = this.effects.findIndex(
+      ({ options }) => options?.name === name
+    );
+    if (effectIndex === -1) return;
+
+    this.effects.splice(effectIndex, 1);
+  }
+
+  /**
+   * Updates the root object and notifies any registered watchers and computed dependents.
+   * This method is called whenever the root object's value changes.
+   */
+  update() {
+    // Run watchers.
+    for (const { effect: watcher } of this.effects) {
+      if (root.batchNestingLevel > 0) {
+        root.batchedEffects.set(watcher, [this.wvalue]);
+        continue;
+      }
+
+      watcher(this.wvalue);
+    }
+
+    // Run computed dependents.
+    const computedDependents = this.derivedCells;
+    if (computedDependents !== undefined) {
+      for (const dependent of computedDependents) {
+        dependent.deref()?.update();
+      }
+    }
+    // Periodically remove dead references.
+    this.derivedCells = this.derivedCells.filter(
+      (ref) => ref.deref() !== undefined
+    );
+
+    // global effects
+    for (const [options, effect] of root.globalPostEffects) {
+      if (options.ignoreDerivedCells && this instanceof DerivedCell) {
+        continue;
+      }
+
+      effect(this.wvalue);
+
+      if (options.runOnce) {
+        root.globalPostEffects = root.globalPostEffects.filter(
+          ([_, e]) => e !== effect
+        );
+      }
+    }
+  }
+
+  /**
+   * Returns the current value of the cell without registering a watcher.
+   * @returns {T} - The current value of the cell.
+   */
+  peek() {
+    return this.wvalue;
+  }
+
+  /**
+   * Adds a global effect that runs before any Cell is updated.
+   * @param {(value: unknown) => void} effect - The effect function.
+   * @param {Partial<import('./root.js').GlobalEffectOptions>} [options] - The options for the effect.
+   * @example
+   * ```
+   * import { Cell } from '@adbl/cells';
+   *
+   * const cell = Cell.source(0);
+   * Cell.beforeUpdate((value) => console.log(value));
+   *
+   * cell.value = 1; // prints 1
+   * cell.value = 2; // prints 2
+   * ```
+   */
+  static beforeUpdate = (effect, options) => {
+    root.globalPreEffects.push([options ?? {}, effect]);
+  };
+
+  /**
+   * Adds a global post-update effect to the Cell system.
+   * @param {(value: unknown) => void} effect - The effect function to add.
+   * @param {Partial<import('./root.js').GlobalEffectOptions>} [options] - Options for the effect.
+   * @example
+   * ```
+   * import { Cell } from '@adbl/cells';
+   *
+   * const effect = (value) => console.log(value);
+   * Cell.afterUpdate(effect);
+   *
+   * const cell = Cell.source(0);
+   * cell.value = 1; // prints 1
+   * ```
+   */
+  static afterUpdate = (effect, options) => {
+    root.globalPostEffects.push([options ?? {}, effect]);
+  };
+
+  static removeGlobalEffects = () => {
+    root.globalPreEffects = [];
+    root.globalPostEffects = [];
+  };
+
+  /**
+   * Removes a global effect.
+   * @param {(value: unknown) => void} effect - The effect function added previously.
+   * @example
+   * ```
+   * import { Cell } from '@adbl/cells';
+   *
+   * const effect = (value) => console.log(value);
+   * Cell.beforeUpdate(effect);
+   *
+   * const cell = Cell.source(0);
+   * cell.value = 1; // prints 1
+   *
+   * Cell.removeGlobalEffect(effect);
+   *
+   * cell.value = 2; // prints nothing
+   * ```
+   */
+  static removeGlobalEffect = (effect) => {
+    root.globalPreEffects = root.globalPreEffects.filter(
+      ([_, e]) => e !== effect
+    );
+  };
+
+  /**
+   * @template T
+   * Creates a new Cell instance with the provided value.
+   * @param {T} value - The value to be stored in the Cell.
+   * @param {Partial<CellOptions<T>>} [options] - The options for the cell.
+   * @returns {SourceCell<T>} A new Cell instance.
+   * ```
+   * import { Cell } from '@adbl/cells';
+   *
+   * const cell = Cell.source('Hello world');
+   * console.log(cell.value); // Hello world.
+   *
+   * cell.value = 'Greetings!';
+   * console.log(cell.value) // Greetings!
+   * ```
+   */
+  static source = (value, options) => new SourceCell(value, options);
+
+  /**
+   * @template T
+   * Creates a new Derived instance with the provided callback function.
+   * @param {() => T} callback - The callback function to be used by the Derived instance.
+   * @returns {DerivedCell<T>} A new Derived instance.
+   * ```
+   * import { Cell } from '@adbl/cells';
+   *
+   * const cell = Cell.source(2);
+   * const derived = Cell.derived(() => cell.value * 2);
+   *
+   * console.log(derived.value); // 4
+   *
+   * cell.value = 3;
+   * console.log(derived.value); // 6
+   * ```
+   */
+  static derived = (callback) => new DerivedCell(callback);
+
+  /**
+   * Batches all the effects created to run only once.
+   * @param {() => void} callback - The function to be executed in a batched manner.
+   */
+  static batch = (callback) => {
+    root.batchNestingLevel++;
+    callback();
+    root.batchNestingLevel--;
+    if (root.batchNestingLevel === 0) {
+      for (const [effect, args] of root.batchedEffects) {
+        effect(...args);
+      }
+      root.batchedEffects = new Map();
+    }
+  };
+
+  /**
+   * 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.
+   */
+  static isCell = (value) => value instanceof Cell;
+
+  /**
+   * @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 = (value) => {
+    // @ts-ignore:
+    return value instanceof Cell
+      ? Cell.flatten(value.wvalue)
+      : Array.isArray(value)
+      ? Cell.flattenArray(value)
+      : value instanceof Object
+      ? Cell.flattenObject(value)
+      : value;
+  };
+
+  /**
+   * 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 = (array) => array.map(Cell.flatten);
+
+  /**
+   * 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 = (object) => {
+    const result =
+      /** @type {{ [K in keyof T]: T[K] extends Cell<infer U> ? U : T[K] }} */ ({});
+    for (const [key, value] of Object.entries(object)) {
+      Reflect.set(result, key, Cell.flatten(value));
+    }
+    return result;
+  };
+
+  /**
+   * Wraps an asynchronous function with managed state.
+   *
+   * @template X - The type of the input parameter for the getter function.
+   * @template Y - The type of the output returned by the getter function.
+   * @param {(input: X) => Promise<Y>} getter - A function that performs the asynchronous operation.
+   * @returns {AsyncRequestAtoms<X, Y>} An object containing cells for pending, data, and error states,
+   *          as well as functions to run and reload the operation.
+   *
+   * @example
+   * const { pending, data, error, run, reload } = Cell.async(async (input) => {
+   *   const response = await fetch(`https://example.com/api/data?input=${input}`);
+   *   return response.json();
+   * });
+   *
+   * run('input');
+   */
+  static async(getter) {
+    const pending = Cell.source(false);
+    const data = Cell.source(/** @type {Y | null} */ (null));
+    const error = Cell.source(/** @type {Error | null} */ (null));
+
+    /** @type {X | undefined} */
+    let initialInput = undefined;
+
+    async function run(input = initialInput) {
+      pending.value = true;
+      try {
+        initialInput = input;
+        const result = await getter(/** @type {X} */ (input));
+        data.value = result;
+      } catch (e) {
+        if (e instanceof Error) {
+          error.value = e;
+        } else {
+          throw e;
+        }
+      } finally {
+        pending.value = false;
+      }
+    }
+
+    /**
+     * @param {X} [newInput]
+     * @param {boolean} [changeLoadingState]
+     */
+    async function reload(newInput, changeLoadingState = true) {
+      if (changeLoadingState) {
+        pending.value = true;
+      }
+      try {
+        const result = await getter(
+          /** @type {X} */ (newInput ?? initialInput)
+        );
+        data.value = result;
+      } catch (e) {
+        if (e instanceof Error) {
+          error.value = e;
+        } else {
+          throw e;
+        }
+      } finally {
+        if (changeLoadingState) {
+          pending.value = false;
+        }
+      }
+    }
+
+    return {
+      pending,
+      data,
+      error,
+      run,
+      reload,
+    };
+  }
+}
+
+/**
+ * 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
+ * @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);
+    this.setValue(computedFn());
+    activeComputedValues.pop();
+  }
+
+  /**
+   * @readonly
+   */
+  get value() {
+    return this.revalued;
+  }
+
+  /**
+   * @readonly
+   */
+  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();
+  }
+}
+
+/**
+ * @template T
+ * @extends {Cell<T>}
+ */
+export class SourceCell extends Cell {
+  /** @type {Partial<CellOptions<T>>} */
+  options;
+
+  /**
+   * Creates a new Cell with the provided value.
+   * @param {T} value
+   * @param {Partial<CellOptions<T>>} [options]
+   */
+  constructor(value, options) {
+    super();
+
+    this.setValue(options?.shallowProxied ? value : this.proxy(value));
+    this.options = options ?? {};
+  }
+
+  get value() {
+    return this.revalued;
+  }
+
+  /**
+   * Sets the value stored in the Cell and triggers an update.
+   * @param {T} value
+   */
+  set value(value) {
+    if (this.options.immutable) {
+      throw new Error('Cannot set the value of an immutable cell.');
+    }
+
+    const oldValue = this.wvalue;
+
+    const isEqual = this.options.equals
+      ? this.options.equals(oldValue, value)
+      : oldValue === value;
+
+    if (isEqual) return;
+
+    // global effects
+    for (const [options, effect] of root.globalPreEffects) {
+      effect(this.wvalue);
+
+      if (options.runOnce) {
+        root.globalPreEffects = root.globalPreEffects.filter(
+          ([_, e]) => e !== effect
+        );
+      }
+    }
+
+    this.setValue(value);
+    this.update();
+  }
+
+  /**
+   * 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
+   */
+  proxy(value) {
+    if (typeof value !== 'object' || value === null) {
+      return value;
+    }
+
+    return new Proxy(value, {
+      get: (target, prop) => {
+        this.revalued;
+        return this.proxy(Reflect.get(target, prop));
+      },
+      set: (target, prop, value) => {
+        Reflect.set(target, prop, value);
+        this.update();
+        return true;
+      },
+    });
+  }
+}

package/library/index.js

@@ -0,0 +1,18 @@
+import { DerivedCell, SourceCell, Cell } from './classes.js';
+
+/**
+ * Represents a partial map of cells, where each key in the object type `T` is mapped to either a `Cell<T[key]>` or the raw type `T[key]`.
+ * This type can be used to represent a partial set of cells for an object, where some properties are represented as cells and others are the raw values.
+ * @template {object} T The object type whose properties are mapped to cells or raw values.
+ * @typedef {{ [key in keyof T]: Cell<T[key]> | T[key] }} PartialCellMap
+ */
+
+/**
+ * Represents a full set of cells for an object,
+ * where all properties are represented as cells.
+ * @template {object} T The object type whose properties are mapped to cells.
+ * @typedef {{ [key in keyof T]: Cell<T[key]> }} CellMap
+ */
+
+export { SourceCell, DerivedCell, Cell };
+export default Cell;

package/library/root.js

@@ -0,0 +1,44 @@
+/**
+ * @typedef {import('./classes.js').Cell<any>} Watchable
+ * @typedef {import('./classes.js').DerivedCell<any>} DerivedCell
+ *
+ * @typedef GlobalEffectOptions
+ * @property {boolean} runOnce - Whether the effect should be removed after the first run.
+ * @property {boolean} ignoreDerivedCells - Whether the effect should be run even if the cell is a derived cell.
+ */
+
+export const root = {
+  /**
+   * An array of global effects that run before a source Cell is updated.
+   * @type {[Partial<GlobalEffectOptions>, ((value: unknown) => void)][]}
+   */
+  globalPreEffects: [],
+
+  /**
+   * An array of global effects that run after a source Cell is updated.
+   * @type {[Partial<GlobalEffectOptions>, ((value: unknown) => void)][]}
+   */
+  globalPostEffects: [],
+
+  /**
+   * The nesting level of batch operations.
+   * This will prevent nested batch operations from triggering effects when they finish.
+   * @type {number}
+   */
+  batchNestingLevel: 0,
+
+  /**
+   * A map of effect tuples to be executed in a batch.
+   * The key in each entry is the effect, and the value is the list of arguments call it with.
+   * All callbacks in this map  will be executed only once in a batch.
+   * @type {Map<Function, any[]>}
+   */
+  batchedEffects: new Map(),
+};
+
+/**
+ * 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[]}
+ */
+export const activeComputedValues = [];

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@adbl/cells",
+  "version": "0.0.0",
+  "description": "A simple implementation of reactive updates for JavaScript",
+  "main": "index.js",
+  "private": false,
+  "type": "module",
+  "module": "./index.js",
+  "typings": "./types/index.d.ts",
+  "scripts": {
+    "test": "vitest",
+    "types": "tsc --p jsconfig.json"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/adebola-io/signals.git"
+  },
+  "keywords": [
+    "reactive",
+    "signals",
+    "events"
+  ],
+  "author": "Sefunmi Adebola Akomolafe",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/adebola-io/signals/issues"
+  },
+  "homepage": "https://github.com/adebola-io/signals#readme",
+  "devDependencies": {
+    "typescript": "^5.4.5",
+    "vitest": "^1.6.0"
+  }
+}

package/types/index.d.ts

@@ -0,0 +1 @@
+export * from "./library/index.js";

package/types/library/classes.d.ts

@@ -0,0 +1,324 @@
+/**
+ * @template T
+ */
+export class Cell<T> {
+    /**
+     * Adds a global effect that runs before any Cell is updated.
+     * @param {(value: unknown) => void} effect - The effect function.
+     * @param {Partial<import('./root.js').GlobalEffectOptions>} [options] - The options for the effect.
+     * @example
+     * ```
+     * import { Cell } from '@adbl/cells';
+     *
+     * const cell = Cell.source(0);
+     * Cell.beforeUpdate((value) => console.log(value));
+     *
+     * cell.value = 1; // prints 1
+     * cell.value = 2; // prints 2
+     * ```
+     */
+    static beforeUpdate: (effect: (value: unknown) => void, options?: Partial<import("./root.js").GlobalEffectOptions> | undefined) => void;
+    /**
+     * Adds a global post-update effect to the Cell system.
+     * @param {(value: unknown) => void} effect - The effect function to add.
+     * @param {Partial<import('./root.js').GlobalEffectOptions>} [options] - Options for the effect.
+     * @example
+     * ```
+     * import { Cell } from '@adbl/cells';
+     *
+     * const effect = (value) => console.log(value);
+     * Cell.afterUpdate(effect);
+     *
+     * const cell = Cell.source(0);
+     * cell.value = 1; // prints 1
+     * ```
+     */
+    static afterUpdate: (effect: (value: unknown) => void, options?: Partial<import("./root.js").GlobalEffectOptions> | undefined) => void;
+    static removeGlobalEffects: () => void;
+    /**
+     * Removes a global effect.
+     * @param {(value: unknown) => void} effect - The effect function added previously.
+     * @example
+     * ```
+     * import { Cell } from '@adbl/cells';
+     *
+     * const effect = (value) => console.log(value);
+     * Cell.beforeUpdate(effect);
+     *
+     * const cell = Cell.source(0);
+     * cell.value = 1; // prints 1
+     *
+     * Cell.removeGlobalEffect(effect);
+     *
+     * cell.value = 2; // prints nothing
+     * ```
+     */
+    static removeGlobalEffect: (effect: (value: unknown) => void) => void;
+    /**
+     * @template T
+     * Creates a new Cell instance with the provided value.
+     * @param {T} value - The value to be stored in the Cell.
+     * @param {Partial<CellOptions<T>>} [options] - The options for the cell.
+     * @returns {SourceCell<T>} A new Cell instance.
+     * ```
+     * import { Cell } from '@adbl/cells';
+     *
+     * const cell = Cell.source('Hello world');
+     * console.log(cell.value); // Hello world.
+     *
+     * cell.value = 'Greetings!';
+     * console.log(cell.value) // Greetings!
+     * ```
+     */
+    static source: <T_1>(value: T_1, options?: Partial<CellOptions<T_1>> | undefined) => SourceCell<T_1>;
+    /**
+     * @template T
+     * Creates a new Derived instance with the provided callback function.
+     * @param {() => T} callback - The callback function to be used by the Derived instance.
+     * @returns {DerivedCell<T>} A new Derived instance.
+     * ```
+     * import { Cell } from '@adbl/cells';
+     *
+     * const cell = Cell.source(2);
+     * const derived = Cell.derived(() => cell.value * 2);
+     *
+     * console.log(derived.value); // 4
+     *
+     * cell.value = 3;
+     * console.log(derived.value); // 6
+     * ```
+     */
+    static derived: <T_2>(callback: () => T_2) => DerivedCell<T_2>;
+    /**
+     * Batches all the effects created to run only once.
+     * @param {() => void} callback - The function to be executed in a batched manner.
+     */
+    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.
+     */
+    static isCell: (value: any) => value is Cell<any>;
+    /**
+     * @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;
+    /**
+     * 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[];
+    /**
+     * 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]; };
+    /**
+     * Wraps an asynchronous function with managed state.
+     *
+     * @template X - The type of the input parameter for the getter function.
+     * @template Y - The type of the output returned by the getter function.
+     * @param {(input: X) => Promise<Y>} getter - A function that performs the asynchronous operation.
+     * @returns {AsyncRequestAtoms<X, Y>} An object containing cells for pending, data, and error states,
+     *          as well as functions to run and reload the operation.
+     *
+     * @example
+     * const { pending, data, error, run, reload } = Cell.async(async (input) => {
+     *   const response = await fetch(`https://example.com/api/data?input=${input}`);
+     *   return response.json();
+     * });
+     *
+     * run('input');
+     */
+    static async<X, Y>(getter: (input: X) => Promise<Y>): AsyncRequestAtoms<X, Y>;
+    /**
+     * @type {Array<({
+     *  effect: (newValue: T) => void,
+     *  options?: EffectOptions,
+     * })>}
+     * @protected
+     */
+    protected effects: Array<({
+        effect: (newValue: T) => void;
+        options?: EffectOptions;
+    })>;
+    /**
+     * @type {Array<WeakRef<DerivedCell<any>>>}
+     * @protected
+     */
+    protected derivedCells: Array<WeakRef<DerivedCell<any>>>;
+    /**
+     * @protected @type T
+     */
+    protected wvalue: T;
+    /**
+     * @protected
+     * @param {T} value
+     */
+    protected setValue(value: T): void;
+    /**
+     * Overrides `Object.prototype.valueOf()` to return the value stored in the Cell.
+     * @returns {T} The value of the Cell.
+     */
+    valueOf(): T;
+    /**
+     * The value stored in the Cell.
+     * @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.
+     * @param {EffectOptions} [options] - The options for the effect.
+     * @returns {() => void} A function that can be called to remove the effect.
+     */
+    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.
+     * @returns {() => void} A function that can be called to remove the effect.
+     */
+    runAndListen(effect: (newValue: T) => void): () => void;
+    /**
+     * Removes the specified effect callback from the list of effects for this cell.
+     * @param {(newValue: T) => void} callback - The effect callback to remove.
+     */
+    ignore(callback: (newValue: T) => void): void;
+    /**
+     * Checks if the cell is listening to a watcher with the specified name.
+     * @param {string} name - The name of the watcher to check for.
+     * @returns {boolean} `true` if the cell is listening to a watcher with the specified name, `false` otherwise.
+     */
+    isListeningTo(name: string): boolean;
+    /**
+     * Updates the root object and notifies any registered watchers and computed dependents.
+     * This method is called whenever the root object's value changes.
+     */
+    update(): void;
+    /**
+     * Returns the current value of the cell without registering a watcher.
+     * @returns {T} - The current value of the cell.
+     */
+    peek(): T;
+}
+/**
+ * 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
+ * @extends {Cell<T>}
+ */
+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
+     */
+    readonly set value(_: T);
+    /**
+     * @readonly
+     */
+    readonly get value(): T;
+}
+/**
+ * @template T
+ * @extends {Cell<T>}
+ */
+export class SourceCell<T> extends Cell<T> {
+    /**
+     * Creates a new Cell with the provided value.
+     * @param {T} value
+     * @param {Partial<CellOptions<T>>} [options]
+     */
+    constructor(value: T, options?: Partial<CellOptions<T>> | undefined);
+    /** @type {Partial<CellOptions<T>>} */
+    options: Partial<CellOptions<T>>;
+    /**
+     * Sets the value stored in the Cell and triggers an update.
+     * @param {T} value
+     */
+    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;
+}
+export type AsyncRequestAtoms<Input, Output> = {
+    /**
+     * Represents the loading state of an asynchronous request.
+     */
+    pending: SourceCell<boolean>;
+    /**
+     * Represents the data returned by the asynchronous request.
+     */
+    data: SourceCell<Output | null>;
+    /**
+     * Represents the errors returned by the asynchronous request, if any.
+     */
+    error: SourceCell<Error | null>;
+    /**
+     * Triggers the asynchronous request.
+     */
+    run: NeverIfAny<Input> extends never ? (input?: Input) => Promise<void> : (input: Input) => Promise<void>;
+    /**
+     * Triggers the asynchronous request again with an optional new input and optionally changes the loading state.
+     */
+    reload: (newInput?: Input, changeLoadingState?: boolean) => Promise<void>;
+};
+export type EffectOptions = {
+    /**
+     * Whether the effect should be removed after the first run.
+     */
+    once?: boolean | undefined;
+    /**
+     * An AbortSignal to be used to ignore the effect if it is aborted.
+     */
+    signal?: AbortSignal | undefined;
+    /**
+     * The name of the effect for debugging purposes.
+     */
+    name?: string | undefined;
+    /**
+     * The priority of the effect. Higher priority effects are executed first. The default priority is 0.
+     */
+    priority?: number | undefined;
+};
+export type CellOptions<T> = {
+    /**
+     * 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.
+     */
+    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.
+     */
+    shallowProxied?: boolean | undefined;
+    /**
+     * A function that determines whether two values are equal. If not provided, the default equality function will be used.
+     */
+    equals?: ((oldValue: T, newValue: T) => boolean) | undefined;
+};
+export type NeverIfAny<T> = 0 extends (1 & T) ? never : T;

package/types/library/index.d.ts

@@ -0,0 +1,15 @@
+export default Cell;
+/**
+ * Represents a partial map of cells, where each key in the object type `T` is mapped to either a `Cell<T[key]>` or the raw type `T[key]`.
+ * This type can be used to represent a partial set of cells for an object, where some properties are represented as cells and others are the raw values.
+ */
+export type PartialCellMap<T extends object> = { [key in keyof T]: T[key] | Cell<T[key]>; };
+/**
+ * Represents a full set of cells for an object,
+ * where all properties are represented as cells.
+ */
+export type CellMap<T extends object> = { [key in keyof T]: Cell<T[key]>; };
+import { SourceCell } from './classes.js';
+import { DerivedCell } from './classes.js';
+import { Cell } from './classes.js';
+export { SourceCell, DerivedCell, Cell };

package/types/library/root.d.ts

@@ -0,0 +1,24 @@
+export namespace root {
+    let globalPreEffects: [Partial<GlobalEffectOptions>, ((value: unknown) => void)][];
+    let globalPostEffects: [Partial<GlobalEffectOptions>, ((value: unknown) => void)][];
+    let batchNestingLevel: number;
+    let batchedEffects: Map<Function, any[]>;
+}
+/**
+ * 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[]}
+ */
+export const activeComputedValues: import("./classes.js").DerivedCell<any>[];
+export type Watchable = import('./classes.js').Cell<any>;
+export type DerivedCell = import('./classes.js').DerivedCell<any>;
+export type GlobalEffectOptions = {
+    /**
+     * - Whether the effect should be removed after the first run.
+     */
+    runOnce: boolean;
+    /**
+     * - Whether the effect should be run even if the cell is a derived cell.
+     */
+    ignoreDerivedCells: boolean;
+};