@adbl/cells 0.0.21 → 0.0.23

package/dist/library/classes.d.ts

@@ -70,6 +70,133 @@ export class Cell<out T extends unknown> {
      * @returns {LocalContext} A new LocalContext instance.
      */
     static context: () => 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: (get: <T_1>(cell: Cell<T_1>) => T_1, signal: AbortSignal) => Promise<U>) => AsyncDerivedCell<U>;
+    /**
+     * 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: (input: Input, signal: AbortSignal) => Promise<Output>) => AsyncTaskCell<Input, Output>;
+    /**
+     * 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: CellData) => Composite<CellData>;
     /**
      * Executes a function within a specific LocalContext.
      * Any effects (`.listen`) or derived cells (`Cell.derived`) created synchronously
@@ -96,46 +223,6 @@ export class Cell<out T extends unknown> {
      * @returns {value is Cell<T>} True if the value is an instance of Cell, false otherwise.
      */
     static isCell: (value: Cell<T_1> | U) => value is Cell<T_1>;
-    /**
-     * @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: T_1 | Cell<T_1>) => T_1;
-    /**
-     * 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<T_1 | Cell<T_1>>) => Array<T_1>;
-    /**
-     * 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: T_1) => { [K in keyof T_1]: T_1[K] extends Cell<infer U> ? U : T_1[K]; };
-    /**
-     * 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 extends (...args: any[]) => Promise<any>, X extends Parameters<Getter>[0] = Parameters<Getter>[0], Y extends Awaited<ReturnType<Getter>> = Awaited<ReturnType<Getter>>>(getter: Getter): AsyncRequestAtoms<Parameters<Getter>[0], Awaited<ReturnType<Getter>>, Getter>;
     /** @type {WeakRef<this> | null} */
     ref: WeakRef<this> | null;
     /**
@@ -146,11 +233,6 @@ export class Cell<out T extends unknown> {
      * @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.
@@ -190,17 +272,6 @@ export class Cell<out T extends unknown> {
      * @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;
-    /**
-     * Removes the watcher with the specified name from the list of effects for this cell.
-     * @param {string} name - The name of the watcher to stop listening to.
-     */
-    stopListeningTo(name: string): void;
     /**
      * @protected
      * Updates the root object and notifies any registered watchers and computed dependents.
@@ -232,27 +303,18 @@ export class DerivedCell<out T extends unknown> extends Cell<T> {
     /** @type {() => T} */
     computedFn: () => T;
     [Depth]: any;
+    [Deferred]: boolean;
 }
 /**
  * @template {*} out 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.set(43);
- * ```
  */
 export class SourceCell<out T extends unknown> extends Cell<T> {
     /**
@@ -267,8 +329,203 @@ export class SourceCell<out T extends unknown> extends Cell<T> {
      * @param {T} value
      */
     set(value: T): void;
+}
+/**
+ * @template {*} out T - The type of the resolved async value.
+ * @extends {DerivedCell<Promise<T>>}
+ */
+export class AsyncCell<out T extends unknown> extends DerivedCell<Promise<T>> {
+    /**
+     * @param {(get: <T>(cell: Cell<T>) => T, signal: AbortSignal) => Promise<T>} fn
+     */
+    constructor(fn: (get: <T_1>(cell: Cell<T_1>) => T_1, signal: AbortSignal) => Promise<T>);
+    /**
+     * @protected
+     * Aborts the current computation if one is running.
+     * @returns {void}
+     */
+    protected abort(): void;
+    /**
+     * Gets the AbortSignal for the current computation.
+     * @protected
+     * @returns {AbortSignal}
+     */
+    protected get _signal(): AbortSignal;
+    /**
+     * A cell that indicates whether the async computation is currently running.
+     * @type {SourceCell<boolean>}
+     */
+    pending: SourceCell<boolean>;
+    /**
+     * A cell that holds any error thrown during the async computation.
+     * Resets to `null` when a new computation starts.
+     * @type {SourceCell<Error | null>}
+     */
+    error: SourceCell<Error | null>;
+    [DisposeAsyncCell](): void;
     #private;
 }
+/**
+ * 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<out T extends unknown> extends AsyncCell<T> {
+    /**
+     * Revalidates the async cell by recomputing its value.
+     * This will abort any in-flight computation and start a new one.
+     * @returns {void}
+     */
+    revalidate(): void;
+}
+/**
+ * @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<out I extends unknown, out T extends unknown> extends AsyncCell<T> {
+    /** @param {MutatorFn<I, T>} fn */
+    constructor(fn: MutatorFn<I, T>);
+    /**
+     * 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);
+     * ```
+     */
+    runWith: (input: I) => Promise<T | null>;
+}
 /**
  * An error class that aggregates multiple errors thrown during a cell update cycle.
  *
@@ -290,30 +547,20 @@ export class CellUpdateError extends Error {
     constructor(errors: Error[]);
     errors: Error[];
 }
-export type AsyncRequestAtoms<Input, Output, Getter> = {
-    /**
-     * 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: Getter extends (...args: infer P) => any ? P["length"] extends 0 ? SimplePromiseFn<Output> : PromiseFnWithArgs<P, Output> : SimplePromiseFn<Output>;
+export type ComputedFn<T> = (track: <T_1>(cell: Cell<T_1>) => T_1) => T;
+/**
+ * An object of barrier-synchronized async derived cells. Each member waits for
+ * *all* inputs to settle before yielding.
+ */
+export type Composite<CellData extends Record<string, Cell<any>>> = {
+    values: { [key in keyof CellData]: CellData[key] extends AsyncDerivedCell<infer T> ? AsyncDerivedCell<T> : CellData[key] extends Cell<infer X> ? AsyncDerivedCell<X> : never; };
+    pending: Cell<boolean>;
+    error: Cell<Error | null>;
     /**
-     * Triggers the asynchronous request again with an optional new input and optionally changes the loading state.
+     * Whether the composite has completed its initial load.
      */
-    reload: (newInput?: Input, changeLoadingState?: boolean) => Promise<void>;
+    loaded: Cell<boolean>;
 };
-export type SimplePromiseFn<Output> = () => Promise<Output | null>;
-export type PromiseFnWithArgs<Args extends Array<any>, Output> = (...args: Args) => Promise<Output | null>;
 export type EffectOptions = {
     /**
      * Whether the effect should be removed after the first run.
@@ -323,10 +570,6 @@ export type EffectOptions = {
      * 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;
     /**
      * Whether the effect should be weakly referenced. This means that the effect will be garbage collected if there are no other references to it.
      */
@@ -337,14 +580,6 @@ export type EffectOptions = {
     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 should watch for changes deep into the given value. By default the cell only reacts to changes at the top level.
-     */
-    deep?: boolean | undefined;
     /**
      * A function that determines whether two values are equal. If not provided, the default equality function will be used.
      */
@@ -356,8 +591,9 @@ export type SetLike<Value extends WeakKey & {
 export type MapLike<Key extends WeakKey & {
     ref: WeakRef<any> | null;
 }, Value> = Map<Key, Value> | WeakMap<Key, Value>;
-/** @template T */
-declare class Effect<T> {
+export type MutatorFn<I, O> = (input: I, signal: AbortSignal) => Promise<O>;
+/** @template {*} out T */
+declare class Effect<out T extends unknown> {
     /**
      * @param {(newValue: T) => void} callback
      * @param {EffectOptions} [options]
@@ -376,6 +612,8 @@ declare class Effect<T> {
 }
 declare const IsScheduled: unique symbol;
 declare const Depth: unique symbol;
+declare const Deferred: unique symbol;
+declare const DisposeAsyncCell: unique symbol;
 /**
  * @template {WeakKey & { ref: WeakRef<any> | null }} Value
  * @extends {Set<Value>}