@adbl/cells 0.0.11 → 0.0.13

package/README.md

@@ -72,20 +72,6 @@ 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:

package/dist/index.js

@@ -0,0 +1,2 @@
+export * from './library/index.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.js"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC"}

package/{types → dist}/library/classes.d.ts

@@ -1,59 +1,23 @@
 /**
- * @template {*} T
+ * @template {*} T The type of value stored in the cell
+ *
+ * Base class for reactive cells.
+ * This class should not be instantiated directly - use `Cell.source` or
+ * `Cell.derived` instead.
+ *
+ * @example
+ * ```typescript
+ * // Create a source cell
+ * const count = Cell.source(0);
+ *
+ * // Listen to changes
+ * count.listen(value => console.log('Count changed:', value));
+ *
+ * // Update the value
+ * count.value = 1; // Logs: Count changed: 1
+ * ```
  */
 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.
-     * @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.
@@ -162,6 +126,9 @@ export class Cell<T extends unknown> {
      * @returns {T} The value of the Cell.
      */
     valueOf(): T;
+    /**
+     * Gets the current value of the cell.
+     */
     get value(): T;
     /**
      * Stringifies the value of the Cell.
@@ -204,10 +171,11 @@ export class Cell<T extends unknown> {
      */
     stopListeningTo(name: string): void;
     /**
+     * @protected
      * 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;
+    protected update(): void;
     /**
      * Returns the current value of the cell without registering a watcher.
      * @returns {T} - The current value of the cell.
@@ -226,8 +194,11 @@ export class DerivedCell<T extends unknown> extends Cell<T> {
      * @param {() => T} computedFn - A function that generates the value of the computed.
      */
     constructor(computedFn: () => T);
+    /** @type {WeakRef<this>} */
+    ref: WeakRef<this>;
     /** @type {() => T} */
     computedFn: () => T;
+    initialized: boolean;
     /**
      * @readonly
      */
@@ -236,10 +207,41 @@ export class DerivedCell<T extends unknown> extends Cell<T> {
      * @readonly
      */
     readonly get value(): T;
+    /**
+     * Listens for changes to the cell, initializing the value if not already done.
+     * @param {(newValue: T) => void} callback - The function to call when the cell's value changes.
+     * @param {object} [options] - Optional configuration for listening.
+     */
+    listen(callback: (newValue: T) => void, options?: object | undefined): () => void;
+    /**
+     * Runs the callback and sets up a listener, initializing the cell's value if not already done.
+     * @param {(newValue: T) => void} callback - The function to call when the cell's value changes.
+     * @param {object} [options] - Optional configuration for listening and running.
+     * @returns {*} The result of the parent class's runAndListen method.
+     */
+    runAndListen(callback: (newValue: T) => void, options?: object | undefined): any;
+    deproxy(): void;
 }
 /**
  * @template {*} T
  * @extends {Cell<T>}
+ * A cell whose value can be directly modified.
+ * Source cells are the primary way to introduce reactivity.
+ * They can hold any value type and will automatically handle proxying of objects
+ * to enable deep reactivity when needed.
+ *
+ * @example
+ * ```typescript
+ * const count = Cell.source(0);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With options
+ * const immutableCell = Cell.source(42, { immutable: true });
+ * // Will throw error:
+ * immutableCell.value = 43;
+ * ```
  */
 export class SourceCell<T extends unknown> extends Cell<T> {
     /**
@@ -248,8 +250,7 @@ export class SourceCell<T extends unknown> extends Cell<T> {
      * @param {Partial<CellOptions<T>>} [options]
      */
     constructor(value: T, options?: Partial<CellOptions<T>> | undefined);
-    /** @type {Partial<CellOptions<T>>} */
-    options: Partial<CellOptions<T>>;
+    options: Partial<CellOptions<T>> | undefined;
     /**
      * For cells containing objects, returns the object itself.
      * This can be useful in scenarios where unfettered access to the original object is needed,
@@ -257,10 +258,10 @@ export class SourceCell<T extends unknown> extends Cell<T> {
      *
      * @example
      * const cell = new SourceCell({ a: 1, b: 2 });
-     * console.log(cell.originalObject); // { a: 1, b: 2 }
+     * console.log(cell.deproxy()); // { a: 1, b: 2 }
      *
      * cell.value = { a: 3, b: 4 };
-     * console.log(cell.originalObject); // { a: 3, b: 4 }
+     * console.log(cell.deproxy()); // { a: 3, b: 4 }
      *
      * @returns {T extends object ? T : never} The original object if T is an object, otherwise never.
      */
@@ -273,6 +274,27 @@ export class SourceCell<T extends unknown> extends Cell<T> {
     get value(): T;
     #private;
 }
+/**
+ * An error class that aggregates multiple errors thrown during a cell update cycle.
+ *
+ * This error is thrown when one or more errors are encountered while updating cells,
+ * such as when running effect callbacks or computed updates. The `errors` property
+ * contains an array of all the errors that occurred during the update cycle.
+ *
+ * @example
+ * try {
+ *   // Some cell update logic that may throw
+ * } catch (e) {
+ *   if (e instanceof CellUpdateError) {
+ *     console.error('Multiple errors occurred:', e.errors);
+ *   }
+ * }
+ */
+export class CellUpdateError extends Error {
+    /** @param {Error[]} errors */
+    constructor(errors: Error[]);
+    errors: Error[];
+}
 export type AsyncRequestAtoms<Input, Output> = {
     /**
      * Represents the loading state of an asynchronous request.