@adbl/cells 0.0.21 → 0.0.23

package/dist/library/classes.js

@@ -1,29 +1,21 @@
 /// <reference types="./classes.d.ts" />
 /**
- * @template Input, Output, Getter
- * @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 {Getter extends (...args: infer P) => any ? P['length'] extends 0 ? SimplePromiseFn<Output>: PromiseFnWithArgs<P, Output> : SimplePromiseFn<Output>} 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.
- */
-/**
- * @template Output
- * @typedef {() => Promise<Output | null>} SimplePromiseFn
+ * @template T
+ * @typedef {(track: <T>(cell: Cell<T>) => T) => T} ComputedFn
  */
 /**
- * @template {Array<any>} Args, Output
- * @typedef {(...args: Args) => Promise<Output | null>} PromiseFnWithArgs
+ * @template {Record<string, Cell<any>>} CellData
+ * @typedef Composite
+ * An object of barrier-synchronized async derived cells. Each member waits for
+ * *all* inputs to settle before yielding.
+ * @property {{
+ *  [key in keyof CellData]:
+ *    CellData[key] extends AsyncDerivedCell<infer T>
+ *    ? AsyncDerivedCell<T> :
+ *    CellData[key] extends Cell<infer X> ? AsyncDerivedCell<X> : never }} values
+ * @property {Cell<boolean>} pending
+ * @property {Cell<Error | null>} error
+ * @property {Cell<boolean>} loaded Whether the composite has completed its initial load.
  */
 /**
  * @typedef {object} EffectOptions
@@ -31,8 +23,6 @@
  * 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 {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]
@@ -41,10 +31,6 @@
 /**
  * @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} [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.
  */
@@ -117,12 +103,14 @@ const GlobalTrackingContext = {};
 let CurrentTrackingContext = GlobalTrackingContext;
 const Depth = Symbol();
 const IsScheduled = Symbol();
+const Deferred = Symbol();
+const DisposeAsyncCell = Symbol();
 /**
  * Tracks cells that need to be updated during the update cycle.
  * Cells are added to this stack to be processed and updated sequentially.
  * @type {Array<Cell<any>>}
  */
-const UPDATE_BUFFER = [];
+let UPDATE_BUFFER = [];
 let IS_UPDATING = false;
 /** @type {object[]} */
 const CONTEXT_STACK = [GlobalTrackingContext];
@@ -147,14 +135,35 @@ function triggerUpdate() {
             if (cell instanceof DerivedCell) {
                 const depth = cell[Depth];
                 if (depth > currentDepth + 1) {
+                    if (cell[Deferred]) {
+                        currentDepth++;
+                    }
+                    else {
+                        cell[Deferred] = true;
+                    }
                     // Move nodes with higher depths to the end of the array so they
                     // are processed last.
                     UPDATE_BUFFER.push(cell);
                     continue;
                 }
+                cell[Deferred] = false;
                 if (depth > currentDepth)
                     currentDepth = depth;
                 const newValue = cell.computedFn();
+                if (cell instanceof AsyncDerivedCell) {
+                    // async cells will handle propagation manually.
+                    cell[IsScheduled] = false;
+                    const computedDependents = cell.derivations;
+                    for (const computedCell of computedDependents) {
+                        if (computedCell instanceof AsyncDerivedCell)
+                            continue;
+                        if (computedCell[IsScheduled])
+                            continue;
+                        UPDATE_BUFFER.push(computedCell);
+                        computedCell[IsScheduled] = true;
+                    }
+                    continue;
+                }
                 // @ts-expect-error: wvalue is protected.
                 if (deepEqual(cell.wvalue, newValue)) {
                     cell[IsScheduled] = false;
@@ -168,17 +177,9 @@ function triggerUpdate() {
             for (const computedCell of computedDependents) {
                 if (computedCell[IsScheduled])
                     continue;
-                if (BATCH_NESTING_LEVEL > 0)
-                    BATCHED_EFFECTS.set(() => UPDATE_BUFFER.push(computedCell), undefined);
-                else
-                    UPDATE_BUFFER.push(computedCell);
+                UPDATE_BUFFER.push(computedCell);
                 computedCell[IsScheduled] = true;
             }
-            // Check the last cell.
-            const last = UPDATE_BUFFER[UPDATE_BUFFER.length - 1];
-            if (last instanceof DerivedCell && last[Depth] - 1 > currentDepth) {
-                currentDepth = last[Depth] - 1;
-            }
         }
         // A cell can update in another's effect, triggering a rerun
         // of the whole process. Since the UPDATE_BUFFER is the same array,
@@ -208,27 +209,7 @@ function throwAnyErrors() {
         throw new CellUpdateError(errors);
     }
 }
-const mutativeMapMethods = new Set(['set', 'delete', 'clear']);
-const mutativeSetMethods = new Set(['add', 'delete', 'clear']);
-const mutativeArrayMethods = new Set([
-    'push',
-    'pop',
-    'shift',
-    'unshift',
-    'splice',
-    'sort',
-    'reverse',
-]);
-const mutativeDateMethods = new Set([
-    'setDate',
-    'setMonth',
-    'setFullYear',
-    'setHours',
-    'setMinutes',
-    'setSeconds',
-    'setMilliseconds',
-]);
-/** @template T */
+/** @template {*} out T */
 class Effect {
     /**
      * @type {EffectOptions | undefined}
@@ -275,6 +256,8 @@ export class LocalContext {
             for (const source of sources) {
                 source.derivations.delete(derivation);
             }
+            if (derivation instanceof AsyncCell)
+                derivation[DisposeAsyncCell]();
         }
         for (const [cell, effects] of this.effects) {
             if (cell instanceof DerivedCell && this.derivationSourceMap.has(cell)) {
@@ -363,13 +346,6 @@ export class Cell {
      * @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.
@@ -436,9 +412,6 @@ export class Cell {
                 this.ignore(effect);
             };
         }
-        if (options?.name && this.isListeningTo(options.name)) {
-            throw new Error(`An effect with the name "${options.name}" is already listening to this cell.`);
-        }
         const isAlreadySubscribed = this.#effects.some((effect) => {
             return effect.callback === callback;
         });
@@ -480,10 +453,6 @@ export class Cell {
         });
         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;
         });
@@ -514,28 +483,6 @@ export class Cell {
             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((effect) => {
-            return effect?.options?.name === name && effect.callback;
-        });
-    }
-    /**
-     * 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((e) => {
-            return e.options?.name === name;
-        });
-        if (effectIndex === -1)
-            return;
-        this.#effects.splice(effectIndex, 1);
-    }
     /**
      * @protected
      * Updates the root object and notifies any registered watchers and computed dependents.
@@ -544,7 +491,8 @@ export class Cell {
     update() {
         // Run watchers.
         const wvalue = this.wvalue;
-        const effects = this.#effects;
+        // Make a copy to avoid issues if effects are removed during iteration (e.g., once: true)
+        const effects = [...this.#effects];
         let hasUndefinedEffect = false;
         for (const { callback: watcher } of effects) {
             if (watcher === undefined) {
@@ -621,6 +569,168 @@ export class Cell {
      * @returns {LocalContext} A new LocalContext instance.
      */
     static context = () => new LocalContext();
+    /**
+     * Creates a new AsyncDerivedCell that computes its value asynchronously.
+     * The cell automatically re-computes when any of its dependencies change,
+     * with built-in support for cancellation, loading state, and error handling.
+     *
+     * @template U
+     * @param {(get: <T>(cell: Cell<T>) => T, signal: AbortSignal) => Promise<U>} callback - An async function that computes the derived value.
+     *   - `get`: A function to read cell values while tracking them as dependencies.
+     *   - `signal`: An AbortSignal that is aborted when a new computation starts,
+     *     useful for cancelling in-flight requests.
+     * @returns {AsyncDerivedCell<U>} A new AsyncDerivedCell instance.
+     *
+     * @example
+     * ```javascript
+     * import { Cell } from '@adbl/cells';
+     *
+     * const userId = Cell.source(1);
+     *
+     * const userData = Cell.derivedAsync(async (get, signal) => {
+     *   const id = get(userId); // Tracks userId as a dependency
+     *   const response = await fetch(`/api/users/${id}`, { signal });
+     *   return response.json();
+     * });
+     *
+     * // Access loading and error states
+     * userData.pending.listen((loading) => console.log('Loading:', loading));
+     * userData.error.listen((err) => err && console.error(err));
+     *
+     * // Get the async value
+     * const data = await userData.get();
+     * ```
+     */
+    static derivedAsync = (callback) => new AsyncDerivedCell(callback);
+    /**
+     * Creates a new AsyncTaskCell that represents a one-time asynchronous computation.
+     * Unlike derivedAsync which re-computes automatically when dependencies change,
+     * a task only executes when explicitly called via `runWith(input)`.
+     *
+     * Tasks are ideal for:
+     * - Form submissions
+     * - One-time API calls
+     * - User-triggered actions
+     * - Operations that should not auto-execute
+     *
+     * @template Input, Output
+     * @param {(input: Input, signal: AbortSignal) => Promise<Output>} fn - An async function that performs the task.
+     *   - `input`: The input value passed when calling `runWith(input)`.
+     *   - `signal`: An AbortSignal that is aborted when a new execution starts,
+     *     useful for cancelling in-flight requests.
+     * @returns {AsyncTaskCell<Input, Output>} A new AsyncTaskCell instance.
+     *
+     * @example
+     * ```javascript
+     * // Create a task for submitting form data
+     * const submitTask = Cell.task(async (formData, signal) => {
+     *   const response = await fetch('/api/submit', {
+     *     method: 'POST',
+     *     body: formData,
+     *     signal
+     *   });
+     *   return response.json();
+     * });
+     *
+     * // Execute the task
+     * const result = await submitTask.runWith({ name: 'John' });
+     *
+     * // Access loading and error states
+     * submitTask.pending.listen((isPending) => {
+     *   console.log('Submitting:', isPending);
+     * });
+     *
+     * submitTask.error.listen((err) => {
+     *   if (err) console.error('Submission failed:', err);
+     * });
+     * ```
+     *
+     * @example
+     * ```javascript
+     * // Tasks can be used with Cell.composite for managing multiple operations
+     * const uploadTask = Cell.task(async (file) => {
+     *   // Upload logic
+     * });
+     *
+     * const deleteTask = Cell.task(async (id) => {
+     *   // Delete logic
+     * });
+     *
+     * const operations = Cell.composite({ upload: uploadTask, delete: deleteTask });
+     *
+     * // Track overall pending state
+     * operations.pending.listen((isPending) => {
+     *   console.log('Operations in progress:', isPending);
+     * });
+     * ```
+     */
+    static task = (fn) => new AsyncTaskCell(fn);
+    /**
+     * Joins multiple cells into a single “all-or-nothing” async unit.
+     *
+     * Each returned property only produces a new value after **every** input cell
+     * has settled for the current round, so reads like:
+     *
+     * ```js
+     * const u = await group.values.user.get();
+     * const n = await group.values.notifications.get();
+     * ```
+     *
+     * won’t observe partial updates.
+     *
+     * @template {Record<string, Cell<any>>} CellData
+     * @param {CellData} input Cells to join (may include async and sync cells).
+     * @returns {Composite<CellData>}
+     *
+     * @example
+     * const user = Cell.derivedAsync(async (get) => fetchUser(get(id)));
+     * const notifications = Cell.derivedAsync(async (get) => fetchNotifs(get(id)));
+     *
+     * const group = Cell.composite({ user, notifications });
+     *
+     * group.pending.listen(showSpinner);
+     * group.error.listen(showError);
+     * group.loaded.listen((isLoaded) => isLoaded && hideInitialSkeleton());
+     *
+     * const u = await group.values.user.get();
+     * const n = await group.values.notifications.get();
+     */
+    static composite = (input) => {
+        const output = /** @type {Composite<CellData>['values']} */ ({});
+        const error = Cell.derived(() => {
+            return (Object.values(input)
+                .map((cell) => (cell instanceof AsyncCell ? cell.error.get() : null))
+                .find(Boolean) || null);
+        });
+        const pending = Cell.derived(() => {
+            return Object.values(input)
+                .map((cell) => (cell instanceof AsyncCell ? cell.pending.get() : false))
+                .some(Boolean);
+        });
+        const loaded = Cell.source(!pending.peek());
+        pending.listen((isPending) => {
+            if (!isPending && !loaded.peek()) {
+                loaded.set(true);
+            }
+        });
+        const barrier = Cell.derivedAsync((get) => {
+            return Promise.all(Object.values(input).map(get));
+        });
+        const values = Object.keys(input).reduce((output, key) => {
+            const value = Cell.derivedAsync(async (get) => {
+                await get(barrier);
+                const err = error.peek();
+                if (err)
+                    throw err;
+                const nextValue = await get(input[key]);
+                await get(barrier);
+                return nextValue;
+            });
+            Reflect.set(output, key, value);
+            return output;
+        }, output);
+        return { values, pending, error, loaded };
+    };
     /**
      * Executes a function within a specific LocalContext.
      * Any effects (`.listen`) or derived cells (`Cell.derived`) created synchronously
@@ -647,27 +757,60 @@ export class Cell {
      * @returns {X} The return value of the callback.
      */
     static batch = (callback) => {
+        const currentBatchLevel = BATCH_NESTING_LEVEL;
+        const currentUpdateBuffer = UPDATE_BUFFER;
+        const wasUpdating = IS_UPDATING;
+        const currentBatchedEffects = BATCHED_EFFECTS;
+        UPDATE_BUFFER = [];
+        IS_UPDATING = true;
         BATCH_NESTING_LEVEL++;
+        BATCHED_EFFECTS = new Map();
         /** @type {X | undefined} */
         let value;
-        let error;
         try {
-            value = callback();
+            try {
+                value = callback();
+            }
+            catch (e) {
+                if (e instanceof Error)
+                    cellErrors.push(e);
+            }
+            if (!wasUpdating)
+                triggerUpdate();
         }
         catch (e) {
-            error = e;
-        }
-        BATCH_NESTING_LEVEL--;
-        if (error instanceof Error) {
-            cellErrors.push(error);
+            if (e instanceof Error)
+                cellErrors.push(e);
         }
-        if (BATCH_NESTING_LEVEL === 0) {
-            for (const [effect, args] of BATCHED_EFFECTS) {
-                effect(args);
+        finally {
+            BATCH_NESTING_LEVEL = currentBatchLevel;
+            if (BATCH_NESTING_LEVEL === 0) {
+                for (const [effect, value] of BATCHED_EFFECTS) {
+                    try {
+                        effect(value);
+                    }
+                    catch (e) {
+                        if (e instanceof Error)
+                            cellErrors.push(e);
+                    }
+                }
             }
-            if (!IS_UPDATING)
-                triggerUpdate();
-            BATCHED_EFFECTS = new Map();
+            else {
+                // Merge nested batch effects into parent batch so they're not lost
+                for (const [effect, value] of BATCHED_EFFECTS) {
+                    currentBatchedEffects.set(effect, value);
+                }
+            }
+            // Merge any cells scheduled for update into the parent buffer
+            for (const cell of UPDATE_BUFFER) {
+                if (!currentUpdateBuffer.includes(cell)) {
+                    currentUpdateBuffer.push(cell);
+                }
+            }
+            UPDATE_BUFFER = currentUpdateBuffer;
+            IS_UPDATING = wasUpdating;
+            BATCH_NESTING_LEVEL = currentBatchLevel;
+            BATCHED_EFFECTS = currentBatchedEffects;
         }
         throwAnyErrors();
         return /** @type {X} */ (value);
@@ -680,145 +823,6 @@ export class Cell {
      * @returns {value is Cell<T>} 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) => {
-        if (value instanceof Cell) {
-            if (value instanceof DerivedCell) {
-                return Cell.flatten(value.wvalue);
-            }
-            return Cell.flatten(value.wvalue);
-        }
-        if (Array.isArray(value)) {
-            // @ts-expect-error:
-            return Cell.flattenArray(value);
-        }
-        if (value instanceof Object) {
-            // @ts-expect-error:
-            return Cell.flattenObject(value);
-        }
-        return 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 {(...args: any[]) => Promise<any>} Getter - A function that performs the asynchronous operation.
-     * @template {Parameters<Getter>[0]} [X=Parameters<Getter>[0]]
-     * @template {Awaited<ReturnType<Getter>>} [Y=Awaited<ReturnType<Getter>>]
-     * @param {Getter} getter - A function that performs the asynchronous operation.
-     * @returns {AsyncRequestAtoms<Parameters<Getter>[0], Awaited<ReturnType<Getter>>, Getter>} 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;
-        /** @type {AbortController | undefined} */
-        let controller;
-        async function run(input = initialInput) {
-            if (controller)
-                controller.abort();
-            controller = new AbortController();
-            pending.set(true);
-            error.set(null);
-            data.set(null);
-            const currentController = controller;
-            try {
-                initialInput = input;
-                const _input = /** @type {X} */ (input);
-                const result = await getter.bind(currentController)(_input);
-                if (currentController?.signal.aborted)
-                    return;
-                data.set(result);
-            }
-            catch (e) {
-                if (e instanceof Error) {
-                    error.set(e);
-                }
-                else {
-                    throw e;
-                }
-            }
-            pending.set(false);
-            return data.get();
-        }
-        /**
-         * @param {X} [newInput]
-         * @param {boolean} [changeLoadingState]
-         */
-        async function reload(newInput, changeLoadingState = true) {
-            if (controller)
-                controller.abort();
-            controller = new AbortController();
-            if (changeLoadingState) {
-                pending.set(true);
-            }
-            await Cell.batch(async () => {
-                const currentController = controller;
-                try {
-                    const result = await getter.bind(currentController)(
-                    /** @type {X} */ (newInput ?? initialInput));
-                    if (currentController?.signal.aborted)
-                        return;
-                    data.set(result);
-                }
-                catch (e) {
-                    if (e instanceof Error) {
-                        error.set(e);
-                    }
-                    else {
-                        throw e;
-                    }
-                }
-                if (changeLoadingState) {
-                    pending.set(false);
-                }
-            });
-        }
-        return {
-            pending,
-            data,
-            error,
-            // @ts-expect-error
-            run,
-            reload,
-        };
-    }
 }
 /**
  * A class that represents a computed value that depends on other reactive values.
@@ -828,6 +832,7 @@ export class Cell {
  */
 export class DerivedCell extends Cell {
     [Depth] = 0;
+    [Deferred] = false;
     /**
      * @param {() => T} computedFn - A function that generates the value of the computed.
      */
@@ -839,20 +844,23 @@ export class DerivedCell extends Cell {
         // Ensures that the cell is derived every time the computing function is called.
         const derivationWrapper = () => {
             ACTIVE_DERIVED_CTX.push([this, 0]);
-            let value = this.wvalue;
             try {
-                value = computedFn();
+                return computedFn();
             }
             catch (e) {
                 if (e instanceof Error)
                     cellErrors.push(e);
+                return this.wvalue;
+            }
+            finally {
+                const i = /** @type {[this, number]} */ (ACTIVE_DERIVED_CTX.pop());
+                const [, depth] = i;
+                if (depth + 1 > this[Depth])
+                    this[Depth] = depth + 1;
             }
-            const [, depth] = /** @type {[this, number]} */ (ACTIVE_DERIVED_CTX.pop());
-            if (depth + 1 > this[Depth])
-                this[Depth] = depth + 1;
-            return value;
         };
-        this.setValue(derivationWrapper());
+        /** @protected @type {T} */
+        this.wvalue = derivationWrapper();
         this.computedFn = /** @type {() => T} */ (derivationWrapper);
         throwAnyErrors();
     }
@@ -872,21 +880,11 @@ export class DerivedCell extends Cell {
  * @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.set(43);
- * ```
  */
 export class SourceCell extends Cell {
     /**
@@ -896,9 +894,9 @@ export class SourceCell extends Cell {
      */
     constructor(value, options) {
         super();
-        if (options !== undefined)
-            this.options = options;
-        this.setValue(value);
+        /** @protected */
+        this.wvalue = value;
+        this.options = options;
     }
     peek() {
         return this.wvalue;
@@ -908,87 +906,468 @@ export class SourceCell extends Cell {
      * @returns {T} The value of the Cell.
      */
     get() {
-        return this.#proxy(this.revalued);
+        return this.revalued;
     }
     /**
      * Sets the value stored in the Cell and triggers an update.
      * @param {T} value
      */
     set(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)
             : deepEqual(oldValue, value);
         if (isEqual)
             return;
-        this.setValue(value);
+        this.wvalue = value;
         this[IsScheduled] = true;
         UPDATE_BUFFER.push(this);
         if (!IS_UPDATING)
             triggerUpdate();
     }
+}
+/**
+ * @template {*} out T - The type of the resolved async value.
+ * @extends {DerivedCell<Promise<T>>}
+ */
+export class AsyncCell extends DerivedCell {
+    /** @type {Set<Promise<any>>} */
+    #upstream = new Set();
+    /** @type {Set<AsyncCell<any>>} */
+    #consumed = new Set();
+    /** @type {undefined | (() => void)} */
+    #abandonLastComputation;
+    /** @type {AbortController | undefined} */
+    #controller;
     /**
-     * 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.
+     * @protected
+     * Aborts the current computation if one is running.
+     * @returns {void}
+     */
+    abort() {
+        this.#controller?.abort();
+    }
+    /**
+     * Gets the AbortSignal for the current computation.
+     * @protected
+     * @returns {AbortSignal}
      */
-    #proxy(value) {
-        if (typeof value !== 'object' || value === null)
+    get _signal() {
+        if (!this.#controller) {
+            this.#controller = new AbortController();
+        }
+        return this.#controller.signal;
+    }
+    /**
+     * A cell that indicates whether the async computation is currently running.
+     * @type {SourceCell<boolean>}
+     */
+    pending = Cell.source(true);
+    /**
+     * A cell that holds any error thrown during the async computation.
+     * Resets to `null` when a new computation starts.
+     * @type {SourceCell<Error | null>}
+     */
+    error = Cell.source(null);
+    /**
+     * @param {(get: <T>(cell: Cell<T>) => T, signal: AbortSignal) => Promise<T>} fn
+     */
+    constructor(fn) {
+        const initialState = /** @type {Promise<T>} */ (Promise.resolve(null));
+        super(() => initialState);
+        let lastStablePromise = initialState;
+        /** @type [this, number] */
+        let derivedCtx = [this, this[Depth]];
+        let runId = 0;
+        /**
+         * @template T
+         * @param {Cell<T>} cell
+         * @returns {T}
+         */
+        const get = (cell) => {
+            ACTIVE_DERIVED_CTX.push(derivedCtx);
+            const value = cell.get();
+            if (cell instanceof AsyncCell && value instanceof Promise) {
+                const currentRunId = runId;
+                value.then(() => {
+                    if (runId === currentRunId)
+                        this.#consumed.add(cell);
+                });
+            }
+            ACTIVE_DERIVED_CTX.pop();
             return value;
-        return new Proxy(value, {
-            get: (target, prop) => {
-                this.revalued;
-                if (this.options?.deep) {
-                    // @ts-expect-error: Direct access is faster than Reflection here.
-                    return this.#proxy(target[prop]);
+        };
+        this.computedFn = async () => {
+            const currentRunId = ++runId;
+            this.#consumed.clear();
+            derivedCtx = [this, this[Depth]];
+            Cell.batch(() => {
+                this.pending.set(true);
+                this.error.set(null);
+            });
+            this.#controller?.abort();
+            this.#controller = new AbortController();
+            /** @type {null | ((value: boolean) => void)} */
+            let resolveChangedState = null;
+            /** @type {Promise<boolean>} */
+            const valueHasChanged = new Promise((resolve) => {
+                resolveChangedState = resolve;
+            });
+            // if this cell discards this promise and starts another,
+            // we do not want to its children to be stuck waiting for the old.
+            // We are not using signal.addEventListener('abort') here because
+            // the controller aborts too early (before the next promise even starts),
+            // and we want the next promise to already be notified to the children,
+            // so they don't resolve prematurely.
+            /** @type {undefined | (() => void)} */
+            let abandonComputation;
+            /** @type {Promise<T | null>} */
+            const tripwire = new Promise((resolve) => {
+                abandonComputation = () => resolve(lastStablePromise);
+            });
+            const current = Promise.race([
+                tripwire,
+                new Promise((resolve) => resolve(fn(get, this._signal))),
+            ])
+                .catch((error) => {
+                if (currentRunId === runId) {
+                    Cell.batch(() => {
+                        this.pending.set(false);
+                        this.error.set(error);
+                    });
                 }
-                if (typeof prop === 'string') {
-                    const isMutativeMethod = (target instanceof Map && mutativeMapMethods.has(prop)) ||
-                        (target instanceof Set && mutativeSetMethods.has(prop)) ||
-                        (target instanceof Date && mutativeDateMethods.has(prop)) ||
-                        ((ArrayBuffer.isView(target) || Array.isArray(target)) &&
-                            mutativeArrayMethods.has(prop));
-                    if (isMutativeMethod) {
-                        // @ts-expect-error: Direct access is faster than Reflection here.
-                        return (...args) => {
-                            // @ts-expect-error: Direct access is faster than Reflection here.
-                            const result = target[prop](...args);
-                            UPDATE_BUFFER.push(this);
-                            this[IsScheduled] = true;
-                            if (!IS_UPDATING)
-                                triggerUpdate();
-                            return result;
-                        };
-                    }
+                return lastStablePromise;
+            })
+                .then(async (value) => {
+                if (currentRunId === runId) {
+                    this.pending.set(false);
+                    resolveChangedState?.(!deepEqual(await lastStablePromise, value));
                 }
-                // @ts-expect-error: Direct access is faster than Reflection here.
-                let value = target[prop];
-                if (typeof value === 'function') {
-                    value = value.bind(target);
+                else {
+                    resolveChangedState?.(false);
                 }
                 return value;
-            },
-            set: (target, prop, value) => {
-                // @ts-expect-error: dynamic object access.
-                const formerValue = target[prop];
-                const isEqual = deepEqual(formerValue, value);
-                if (!isEqual) {
-                    // @ts-expect-error: dynamic object access.
-                    target[prop] = value;
-                    UPDATE_BUFFER.push(this);
-                    this[IsScheduled] = true;
-                    if (!IS_UPDATING) {
+            });
+            this.wvalue = current;
+            this.#notify(current, valueHasChanged, lastStablePromise, initialState);
+            this.#abandonLastComputation?.();
+            this.#abandonLastComputation = abandonComputation;
+            current.finally(async () => {
+                if (currentRunId !== runId)
+                    return;
+                if (lastStablePromise === initialState) {
+                    // We only run update() for subsequent changes, not initial resolution.
+                    lastStablePromise = current;
+                    return;
+                }
+                lastStablePromise = current;
+                if (derivedCtx[1] + 1 > this[Depth])
+                    this[Depth] = derivedCtx[1] + 1;
+                if (await valueHasChanged)
+                    this.update();
+            });
+            return this.wvalue;
+        };
+        // First call.
+        this.computedFn();
+    }
+    /**
+     * @param {Promise<any>} promise
+     * @param {Promise<boolean>} valueHasChanged
+     * @param {Promise<any>} lastStablePromise
+     * @param {Promise<any>} initialState
+     */
+    #notify(promise, valueHasChanged, lastStablePromise, initialState) {
+        for (const child of this.derivations) {
+            if (!(child instanceof AsyncDerivedCell))
+                continue;
+            if (child.#upstream.has(promise))
+                continue;
+            // Only direct children should be scheduled based on this cell's valueHasChanged.
+            // Grandchildren will be scheduled by their direct parent when it computes.
+            promise.then(async () => {
+                child.#upstream.delete(promise);
+                if (lastStablePromise === initialState) {
+                    return;
+                }
+                // If the child is already computing and it has not tried to read the parent,
+                // it need not be restarted. When it tries to access the parent,
+                // it will receive the most recent value.
+                if (child.pending.peek() && !child.#consumed.has(this)) {
+                    return;
+                }
+                if (!child[IsScheduled] && (await valueHasChanged)) {
+                    UPDATE_BUFFER.push(child);
+                    if (!IS_UPDATING)
                         triggerUpdate();
-                    }
                 }
-                return true;
-            },
+            });
+            child.#upstream.add(promise);
+            // Propagate ONLY the upstream waiting to grandchildren (not the scheduling).
+            // This ensures grandchildren wait for this ancestor to complete,
+            // but they'll be scheduled by their direct parent's #notify, not ours.
+            child.#notifyUpstreamOnly(promise);
+        }
+    }
+    /**
+     * Propagates upstream tracking to grandchildren without scheduling them.
+     * This ensures they wait for the ancestor to complete when calling .get().
+     * @param {Promise<any>} promise
+     */
+    #notifyUpstreamOnly(promise) {
+        for (const child of this.derivations) {
+            if (!(child instanceof AsyncDerivedCell))
+                continue;
+            if (child.#upstream.has(promise))
+                continue;
+            child.#upstream.add(promise);
+            promise.finally(() => child.#upstream.delete(promise));
+            // Continue propagating upstream tracking down the chain
+            child.#notifyUpstreamOnly(promise);
+        }
+    }
+    /**
+     * Returns the current value of the async cell.
+     * @returns {Promise<T>}
+     */
+    async get() {
+        super.get(); // Forces a dependency registration in sync time.
+        while (this.#upstream.size)
+            await Promise.allSettled([...this.#upstream]);
+        return new Promise((resolve) => {
+            if (this.pending.peek()) {
+                this.pending.listen(() => resolve(this.wvalue), { once: true });
+            }
+            else
+                resolve(this.wvalue);
         });
     }
+    [DisposeAsyncCell]() {
+        this.#controller?.abort();
+        this.#abandonLastComputation?.();
+    }
+    /**
+     * Returns the current value of the async cell without registering dependencies.
+     * Like get(), this waits for upstream promises and pending state to resolve,
+     * but it does not register this cell as a dependency of the calling context.
+     * @returns {Promise<T>} A promise that resolves to the current value.
+     */
+    async peek() {
+        while (this.#upstream.size)
+            await Promise.allSettled([...this.#upstream]);
+        return new Promise((resolve) => {
+            if (this.pending.peek()) {
+                this.pending.listen(() => resolve(this.wvalue), { once: true });
+            }
+            else {
+                resolve(this.wvalue);
+            }
+        });
+    }
+}
+/**
+ * A derived cell that computes its value asynchronously.
+ *
+ * AsyncDerivedCell extends the reactive paradigm to asynchronous operations,
+ * automatically re-running the async computation when dependencies change.
+ * It provides built-in state management for loading and error states.
+ *
+ * Key features:
+ * - Automatic dependency tracking via the `get` function
+ * - Automatic cancellation of in-flight operations when dependencies change
+ * - Built-in `pending` cell for loading state
+ * - Built-in `error` cell for error handling
+ * - Race condition prevention through AbortSignal
+ *
+ * @template {*} out T - The type of the resolved async value.
+ * @extends {AsyncCell<T>}
+ *
+ * @example
+ * ```javascript
+ * const searchQuery = Cell.source('');
+ *
+ * const searchResults = Cell.derivedAsync(async (get, signal) => {
+ *   const query = get(searchQuery);
+ *   if (!query) return [];
+ *
+ *   const response = await fetch(`/api/search?q=${query}`, { signal });
+ *   return response.json();
+ * });
+ *
+ * // React to state changes
+ * searchResults.pending.listen((loading) => {
+ *   showSpinner(loading);
+ * });
+ *
+ * searchResults.error.listen((error) => {
+ *   if (error) showError(error.message);
+ * });
+ * ```
+ */
+export class AsyncDerivedCell extends AsyncCell {
+    /**
+     * Revalidates the async cell by recomputing its value.
+     * This will abort any in-flight computation and start a new one.
+     * @returns {void}
+     */
+    revalidate() {
+        this.computedFn();
+    }
+}
+/**
+ * @template I, O
+ * @typedef {(input: I, signal: AbortSignal) => Promise<O>} MutatorFn
+ */
+/**
+ * A task cell that performs one-time asynchronous computations.
+ *
+ * AsyncTaskCell is designed for operations that should only execute when explicitly
+ * triggered, unlike AsyncDerivedCell which re-computes automatically. This makes it
+ * ideal for form submissions, button actions, or any user-triggered operations.
+ *
+ * Key features:
+ * - Only executes when `runWith(input)` is called
+ * - Does not deduplicate concurrent `runWith(input)` calls; each call creates
+ *   an independent execution with no caching
+ * - Built-in `pending` cell for loading state (false until first execution)
+ * - Built-in `error` cell for error handling
+ * - Supports cancellation via AbortSignal (concurrent cancellations must be
+ *   handled in the task function)
+ * - Can be used with Cell.composite for grouping multiple tasks
+ *
+ * @template {*} out I - The input type of the task function.
+ * @template {*} out T - The type of the resolved async value.
+ * @extends {AsyncCell<T>}
+ *
+ * @example
+ * ```javascript
+ * import { Cell } from '@adbl/cells';
+ *
+ * // Create a task for user login
+ * const loginTask = Cell.task(async (credentials, signal) => {
+ *   const response = await fetch('/api/login', {
+ *     method: 'POST',
+ *     headers: { 'Content-Type': 'application/json' },
+ *     body: JSON.stringify(credentials),
+ *     signal
+ *   });
+ *
+ *   if (!response.ok) {
+ *     throw new Error('Login failed');
+ *   }
+ *
+ *   return response.json();
+ * });
+ *
+ * // Execute the task
+ * loginTask.runWith({ username: 'john', password: 'secret' });
+ *
+ * // Monitor states
+ * loginTask.pending.listen((isPending) => {
+ *   submitButton.disabled = isPending;
+ *   submitButton.textContent = isPending ? 'Logging in...' : 'Login';
+ * });
+ *
+ * loginTask.error.listen((error) => {
+ *   if (error) {
+ *     errorMessage.textContent = error.message;
+ *   }
+ * });
+ *
+ * loginTask.listen(async (promise) => {
+ *   const user = await promise;
+ *   console.log('Logged in as:', user.name);
+ * });
+ * ```
+ *
+ * @example
+ * ```javascript
+ * const fetchTask = Cell.task(async (id) => {
+ *   console.log('Fetching user', id);
+ *   await delay(1000);
+ *   return { id, name: 'User ' + id };
+ * });
+ *
+ * // Execute the task
+ * const user = await fetchTask.runWith(1);
+ * console.log(user.name);
+ *
+ * // Execute again - each call creates a new execution
+ * const anotherUser = await fetchTask.runWith(2);
+ * ```
+ */
+export class AsyncTaskCell extends AsyncCell {
+    /** @param {MutatorFn<I, T>} fn */
+    constructor(fn) {
+        let currentInput = /** @type {I} */ (null);
+        // currentInput may be null; hasInput indicates whether runWith has been called.
+        /** @type {boolean} */
+        let hasInput = false;
+        const computedFn = () => {
+            if (!hasInput)
+                return Promise.resolve(/** @type {T} */ (null));
+            const capturedInput = currentInput;
+            return fn(capturedInput, this._signal);
+        };
+        super(computedFn);
+        // AsyncTaskCell should not be pending until runWith is called
+        this.pending.set(false);
+        let hasExecuted = false;
+        this.update = this.update.bind(this);
+        /**
+         * Executes the task with the provided input.
+         *
+         * Each call to runWith creates a new execution of the task function.
+         * Concurrent calls are not deduplicated or cached. If you need to cancel
+         * work in progress, use the provided AbortSignal and handle it inside the
+         * task function.
+         *
+         * @param {I} input - The input value to pass to the task function.
+         * @returns {Promise<T | null>} A promise that resolves with the task result,
+         *   or null if the task hasn't been executed yet.
+         *
+         * @example
+         * ```javascript
+         * const task = Cell.task(async (userId) => {
+         *   const response = await fetch(`/api/users/${userId}`);
+         *   return response.json();
+         * });
+         *
+         * // Execute the task
+         * const user = await task.runWith(123);
+         * console.log(user.name);
+         *
+         * // Execute again with different input
+         * const anotherUser = await task.runWith(456);
+         * ```
+         */
+        this.runWith = async (input) => {
+            const isFirstExecution = !hasExecuted;
+            this.abort();
+            currentInput = input;
+            hasInput = true;
+            const value = this.computedFn();
+            hasExecuted = true;
+            // For the first execution, we need to manually trigger an update
+            // since AsyncCell skips update() for the initial state.
+            // We also need to schedule AsyncDerivedCell children for recomputation.
+            if (isFirstExecution) {
+                value.then(() => {
+                    this.update();
+                    // Schedule AsyncDerivedCell children for recomputation
+                    for (const child of this.derivations) {
+                        if (child instanceof AsyncDerivedCell && !child[IsScheduled]) {
+                            UPDATE_BUFFER.push(child);
+                            child[IsScheduled] = true;
+                        }
+                    }
+                    if (!IS_UPDATING)
+                        triggerUpdate();
+                });
+            }
+            return value;
+        };
+    }
 }
 /**
  * An error class that aggregates multiple errors thrown during a cell update cycle.