@ersbeth/picoflow 1.0.0 → 1.1.0

package/src/flow/nodes/await/flowNodeAwait.ts

@@ -0,0 +1,508 @@
+import {
+	FlowEffect,
+	FlowGraph,
+	FlowSignal,
+	type FlowTracker,
+} from "../../base";
+
+/**
+ * A versatile reactive node that can operate as mutable state or computed derivation, with asynchronous values.
+ *
+ * @typeParam T - The type of the value held by this node (not the Promise itself).
+ *
+ * @remarks
+ * FlowNodeAwait is a flexible reactive primitive that adapts its behavior based on how it's initialized.
+ * It extends {@link FlowSignal} and provides reactive value access with automatic dependency tracking.
+ * Unlike its synchronous counterpart {@link FlowNode}, FlowNodeAwait works with `Promise<T>` values internally,
+ * but provides a synchronous-looking API by automatically awaiting Promises and caching the resolved values.
+ *
+ * **Key Difference from FlowNodeAsync:**
+ * Unlike {@link FlowNodeAsync}, which returns Promises from `get()`, FlowNodeAwait returns the resolved value
+ * directly. This makes the API more convenient for reactive code that doesn't want to deal with Promises
+ * in every access. The Promise is awaited internally and the resolved value is cached.
+ *
+ * **Operating Modes:**
+ *
+ * - **Mutable State Mode**: When constructed with a constant Promise, FlowNodeAwait acts as a mutable
+ *   reactive state. You can update its value using `set()`, and all dependents are automatically
+ *   notified when the value changes. The Promise is resolved internally and the value is cached.
+ *
+ * - **Computed Derivation Mode**: When constructed with a compute function, FlowNodeAwait acts as a
+ *   computed value that automatically tracks its dependencies. The compute function runs lazily
+ *   (only when the value is first accessed) and recomputes when any tracked dependency changes.
+ *   The compute function must return a `Promise<T>`. The computed value can be temporarily overridden
+ *   using `set()`, but the override is cleared on the next recomputation (triggered by dependency changes).
+ *
+ * **Asynchronous Nature:**
+ * FlowNodeAwait works with Promises internally, but provides a synchronous-looking API:
+ * - `get(t)` returns the resolved value synchronously (`T | undefined`). The value may be `undefined`
+ *   if the Promise hasn't resolved yet on first access.
+ * - `pick()` returns a `Promise<T>` that must be awaited. Use this when you need to ensure the value
+ *   is fully resolved before proceeding.
+ * - The Promise is awaited internally in `_computeValue()` and the resolved value is cached in `_value`.
+ *
+ * **Lazy Computation:**
+ * When using a compute function, the computation doesn't run immediately upon construction. It
+ * executes only when:
+ * - The value is first read via `get()` or `pick()`
+ * - The node is watched via `watch()`
+ *
+ * **Dirty Tracking:**
+ * When a tracked dependency changes, the node is marked as "dirty" but doesn't recompute
+ * immediately. Recomputation happens lazily on the next value access, preventing unnecessary
+ * computations when multiple dependencies change in quick succession. The resolved value is cached
+ * until dependencies change, ensuring efficient access patterns.
+ *
+ * **Dynamic Dependencies:**
+ * Dependencies are tracked dynamically during each computation. If the compute function
+ * conditionally tracks different observables, the dependency graph updates automatically.
+ *
+ * @example
+ * ```typescript
+ * // Mutable state mode
+ * const $count = new FlowNodeAwait(Promise.resolve(0));
+ * await $count.set(Promise.resolve(1)); // Updates the value
+ *
+ * // Computed derivation mode
+ * const $firstName = new FlowNodeAwait(Promise.resolve('John'));
+ * const $lastName = new FlowNodeAwait(Promise.resolve('Doe'));
+ * const $fullName = new FlowNodeAwait(async (t) => {
+ *   const first = $firstName.get(t); // Synchronous - returns resolved value
+ *   const last = $lastName.get(t);   // Synchronous - returns resolved value
+ *   return `${first} ${last}`;
+ * });
+ *
+ * // Compute function hasn't run yet (lazy)
+ * const name = await $fullName.pick(); // Now it computes: "John Doe"
+ *
+ * // Temporarily override computed value
+ * await $fullName.set(Promise.resolve('Override'));
+ * console.log(await $fullName.pick()); // "Override"
+ *
+ * // Trigger recomputation (clears override)
+ * await $firstName.set(Promise.resolve('Jane'));
+ * console.log(await $fullName.pick()); // "Jane Doe" (override cleared)
+ * ```
+ *
+ * @public
+ */
+export class FlowNodeAwait<T> extends FlowSignal {
+	// protected _promise?: Promise<T>;
+	private _dirty = true;
+	private _value?: T;
+	private _compute?: (t: FlowTracker) => Promise<T>;
+
+	/**
+	 * Creates a new FlowNodeAwait.
+	 *
+	 * @param compute - Either a constant Promise or a compute function that derives the value.
+	 *
+	 * @remarks
+	 * The constructor accepts two different initialization modes:
+	 *
+	 * - **Constant Promise**: Creates a mutable reactive node that can be updated via `set()`.
+	 *   The Promise is stored immediately and resolved internally. The resolved value is cached
+	 *   and can be accessed synchronously via `get()`. The Promise can be changed at any time via `set()`.
+	 *
+	 * - **Compute function**: Creates a computed reactive node that automatically tracks dependencies
+	 *   and recomputes when they change. The compute function receives a tracking context (`t`)
+	 *   that should be used to access dependencies via `.get(t)`. The function must return a
+	 *   `Promise<T>`. The function is not executed immediately; it runs lazily on first access.
+	 *   The Promise is awaited internally and the resolved value is cached. The computed value can
+	 *   be temporarily overridden using `set()`, but the override is cleared on the next recomputation
+	 *   (triggered by dependency changes).
+	 *
+	 * @example
+	 * ```typescript
+	 * // Mutable state with constant Promise
+	 * const $count = new FlowNodeAwait(Promise.resolve(0));
+	 * await $count.set(Promise.resolve(5));
+	 *
+	 * // Computed derivation with async function
+	 * const $a = new FlowNodeAwait(Promise.resolve(10));
+	 * const $b = new FlowNodeAwait(Promise.resolve(20));
+	 * const $sum = new FlowNodeAwait(async (t) => {
+	 *   const a = $a.get(t); // Synchronous - returns resolved value
+	 *   const b = $b.get(t); // Synchronous - returns resolved value
+	 *   return a + b;
+	 * });
+	 *
+	 * // Lazy evaluation - compute function hasn't run yet
+	 * console.log(await $sum.pick()); // Now it computes: 30
+	 * ```
+	 *
+	 * @public
+	 */
+	constructor(compute: Promise<T> | ((t: FlowTracker) => Promise<T>)) {
+		super();
+		if (typeof compute === "function") {
+			this._compute = compute as (t: FlowTracker) => Promise<T>;
+		} else {
+			this.set(compute);
+		}
+	}
+
+	override watch(tracker: FlowTracker): void {
+		if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+		this._computeValue();
+		super.watch(tracker);
+	}
+
+	/**
+	 * Gets the current value with dependency tracking.
+	 *
+	 * @param tracker - The tracking context for reactive tracking. This observable is registered
+	 * as a dependency when accessed through this method.
+	 *
+	 * @returns The current resolved value of type T, or `undefined` if the Promise hasn't resolved yet.
+	 *
+	 * @remarks
+	 * Use `get(t)` within effects and derivations to create reactive dependencies. The tracker
+	 * parameter must be provided from the reactive context (typically the `t` parameter in effect
+	 * or derivation callbacks).
+	 *
+	 * **Important:** This method returns the resolved value synchronously (`T | undefined`), not a Promise.
+	 * The Promise is awaited internally and the resolved value is cached. This provides a convenient
+	 * synchronous-looking API while working with asynchronous data sources.
+	 *
+	 * **Undefined Value:**
+	 * On the first access before the Promise has resolved, this method may return `undefined`. Once
+	 * the Promise resolves, subsequent calls will return the cached value. If you need to ensure the
+	 * value is fully resolved, use `pick()` instead, which returns a Promise that you can await.
+	 *
+	 * To read a value without creating a dependency, use `pick()` instead.
+	 *
+	 * @example
+	 * ```typescript
+	 * effect((t) => {
+	 *   const tracked = $state.get(t);        // Synchronous - returns resolved value, creates dependency
+	 *   const untracked = await $other.pick(); // Async - no dependency
+	 * });
+	 * ```
+	 *
+	 * @throws Error if the node has been disposed.
+	 *
+	 * @public
+	 */
+	get(tracker: FlowTracker): T | undefined {
+		if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+		this.watch(tracker);
+		return this._value;
+	}
+
+	/**
+	 * Updates the node with a new value.
+	 *
+	 * @param value - A new Promise or a callback function that computes a new Promise based on the current value.
+	 *
+	 * @returns A promise that resolves after the update is processed and all dependent effects have been notified.
+	 *
+	 * @remarks
+	 * This method can be used in two ways:
+	 *
+	 * **For mutable state nodes** (constructed with a constant Promise):
+	 * - Updates the stored Promise directly
+	 * - All dependents are notified of the change
+	 *
+	 * **For computed nodes** (constructed with a compute function):
+	 * - Temporarily overrides the computed value
+	 * - The override persists until the next recomputation, which occurs when:
+	 *   - A tracked dependency changes, or
+	 *   - The node is refreshed
+	 * - This allows temporarily overriding computed values for testing or manual control
+	 *
+	 * **Value Comparison:**
+	 * The Promises are resolved and their values are compared. If the resolved new value is strictly
+	 * equal (`===`) to the current resolved value, no update occurs and subscribers are not notified.
+	 * This prevents unnecessary re-renders and effect executions.
+	 *
+	 * **Asynchronous Processing:**
+	 * The update is processed asynchronously through the reactive graph, ensuring proper
+	 * ordering of updates and effect execution. The method returns a Promise that resolves
+	 * after the update is complete.
+	 *
+	 * @throws Error if the node has been disposed.
+	 *
+	 * @example
+	 * ```typescript
+	 * // Mutable state usage
+	 * const $count = new FlowNodeAwait(Promise.resolve(0));
+	 * await $count.set(Promise.resolve(5));
+	 * await $count.set(async (current) => Promise.resolve(current + 1)); // 6
+	 *
+	 * // Temporary override of computed value
+	 * const $source = new FlowNodeAwait(Promise.resolve(10));
+	 * const $doubled = new FlowNodeAwait(async (t) => {
+	 *   const val = $source.get(t); // Synchronous - returns resolved value
+	 *   return val * 2;
+	 * });
+	 *
+	 * console.log(await $doubled.pick()); // 20
+	 *
+	 * // Temporarily override
+	 * await $doubled.set(Promise.resolve(50));
+	 * console.log(await $doubled.pick()); // 50 (override active)
+	 *
+	 * // Dependency change clears override
+	 * await $source.set(Promise.resolve(15));
+	 * console.log(await $doubled.pick()); // 30 (recomputed, override cleared)
+	 * ```
+	 *
+	 * @public
+	 */
+	async set(
+		value: T | Promise<T> | ((current: T) => Promise<T>),
+	): Promise<void> {
+		if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+
+		const update = async () => {
+			this._dirty = false;
+
+			// compute current value
+			const currentValue = this._value as T;
+
+			// compute new value
+			let nextValue: T;
+			switch (true) {
+				case value instanceof Promise: {
+					nextValue = await value;
+					break;
+				}
+				case typeof value === "function": {
+					nextValue = await (value as (current: T) => Promise<T>)(currentValue);
+					break;
+				}
+				default: {
+					nextValue = value as T;
+					break;
+				}
+			}
+
+			// assign new value
+			this._value = nextValue;
+
+			// return value changed check
+			return nextValue !== currentValue;
+		};
+
+		const notify = () => {
+			// call super method to avoid setting dirty flag back to true
+			super._notify();
+		};
+
+		return FlowGraph.requestWrite(notify, update);
+	}
+
+	/**
+	 * Forces recomputation of the value, even if it's not marked as dirty.
+	 *
+	 * @returns A promise that resolves after the recomputation is complete and all
+	 * dependent effects have been notified.
+	 *
+	 * @remarks
+	 * This method is useful when you need to force a recomputation of a computed value,
+	 * for example when the computation depends on external data that has changed outside
+	 * the reactive system.
+	 *
+	 * **Behavior:**
+	 * - For nodes with a compute function: Forces the compute function to run again,
+	 *   even if no dependencies have changed. This effectively clears any temporary
+	 *   override that was set using `set()`.
+	 * - For nodes without a compute function (mutable state): Recomputes the current
+	 *   value (which is just the stored value), useful for consistency but typically
+	 *   not necessary.
+	 *
+	 * The recomputation happens asynchronously through the reactive graph, ensuring
+	 * proper ordering of updates and effect execution.
+	 *
+	 * @throws Error if the node has been disposed.
+	 *
+	 * @example
+	 * ```typescript
+	 * const $externalData = new FlowNodeAwait(async () => fetchExternalData());
+	 *
+	 * // Some external event occurs that changes the data source
+	 * externalDataChanged();
+	 *
+	 * // Force recomputation to get the new value
+	 * await $externalData.refresh();
+	 *
+	 * // For computed nodes with temporary overrides
+	 * const $source = new FlowNodeAwait(Promise.resolve(10));
+	 * const $computed = new FlowNodeAwait(async (t) => {
+	 *   const val = $source.get(t); // Synchronous - returns resolved value
+	 *   return val * 2;
+	 * });
+	 * await $computed.set(Promise.resolve(100)); // Temporary override
+	 * await $computed.refresh(); // Clears override, recomputes from source
+	 * ```
+	 *
+	 * @public
+	 */
+	async refresh(): Promise<void> {
+		if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+
+		const update = async () => {
+			// compute current value
+			await this._computeValue();
+			const currentValue = this._value as T;
+
+			// compute new value
+			await this._computeValue({ force: true });
+			const nextValue = this._value as T;
+
+			// return value changed check
+			return nextValue !== currentValue;
+		};
+
+		const notify = () => {
+			// call super method to avoid setting dirty flag back to true
+			super._notify();
+		};
+
+		return await FlowGraph.requestWrite(notify, update);
+	}
+
+	/**
+	 * Gets the current value without any dependency tracking.
+	 *
+	 * @returns A promise that resolves with the current value of type T.
+	 *
+	 * @remarks
+	 * This method reads the value asynchronously through the reactive graph, ensuring proper ordering of
+	 * read operations. Unlike `get(t)`, this method does not create a reactive dependency.
+	 *
+	 * **Important:** This is an async method that returns `Promise<T>`. Always use `await` when calling it.
+	 * This ensures the Promise is fully resolved before returning the value. This is different from `get()`,
+	 * which returns the cached resolved value synchronously (or `undefined` if not yet resolved).
+	 *
+	 * Use `pick()` when you want to read a snapshot of the current value without creating a reactive
+	 * dependency. This is useful for:
+	 * - Reading initial values outside reactive contexts
+	 * - Accessing configuration that shouldn't trigger updates
+	 * - Ensuring the value is fully resolved before using it
+	 * - Mixing tracked and untracked reads in the same effect
+	 *
+	 * @example
+	 * ```typescript
+	 * // Read a snapshot outside reactive context
+	 * const currentValue = await $state.pick();
+	 *
+	 * // Mix tracked and untracked reads
+	 * effect(async (t) => {
+	 *   const tracked = $reactive.get(t);         // Synchronous - triggers re-runs
+	 *   const snapshot = await $config.pick();    // Async - doesn't trigger re-runs
+	 *   processData(tracked, snapshot);
+	 * });
+	 * ```
+	 *
+	 * @throws Error if the node has been disposed.
+	 *
+	 * @public
+	 */
+	async pick(): Promise<T> {
+		if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+		await FlowGraph.requestRead(() => this._computeValue());
+		return this._value as T;
+	}
+
+	/**
+	 * Subscribes a listener function to changes of this node.
+	 *
+	 * @param listener - A callback function that receives the new resolved value whenever it changes.
+	 *
+	 * @returns A disposer function that cancels the subscription when called.
+	 *
+	 * @remarks
+	 * This method creates a reactive subscription that automatically tracks this node as a dependency.
+	 * The listener is executed:
+	 * - Immediately with the current resolved value when the subscription is created
+	 * - Automatically whenever the value changes
+	 *
+	 * **Important:** The listener receives the resolved value directly (`T | undefined`), not a Promise.
+	 * The value may be `undefined` if the Promise hasn't resolved yet on the first call. The Promise
+	 * is awaited internally and the resolved value is cached, so the listener receives the same value
+	 * that would be returned by `get()`.
+	 *
+	 * The subscription uses a {@link FlowEffect} internally to manage the reactive tracking and
+	 * automatic re-execution. When the value changes, the listener is called with the new resolved
+	 * value after the update is processed through the reactive graph.
+	 *
+	 * **Cleanup:**
+	 * Always call the returned disposer function when you no longer need the subscription to
+	 * prevent memory leaks and unnecessary computations.
+	 *
+	 * @example
+	 * ```typescript
+	 * const $count = new FlowNodeAwait(Promise.resolve(0));
+	 *
+	 * // Subscribe to changes
+	 * const unsubscribe = $count.subscribe((value) => {
+	 *   console.log(`Count is now: ${value}`); // value is T | undefined
+	 * });
+	 * // Logs immediately: "Count is now: 0"
+	 *
+	 * await $count.set(Promise.resolve(5));
+	 * // Logs: "Count is now: 5"
+	 *
+	 * // Clean up when done
+	 * unsubscribe();
+	 * ```
+	 *
+	 * @throws Error if the node has been disposed.
+	 *
+	 * @public
+	 */
+	subscribe(listener: (value: T | undefined) => void): () => void {
+		if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+		const effect = new FlowEffect((t) => {
+			listener(this.get(t));
+		});
+		return () => effect.dispose();
+	}
+
+	/* INTERNAL --------------------------------------------------------- */
+
+	/* @internal */ override _notify(): void {
+		if (this._dirty) {
+			return;
+		}
+		this._dirty = true;
+		super._notify();
+	}
+
+	private async _computeValue(options?: { force?: boolean }): Promise<void> {
+		if (!this._dirty && !options?.force) return;
+
+		if (!this._compute) {
+			this._dirty = false;
+			return;
+		}
+
+		this._dirty = false;
+
+		// Store current dependencies
+		const dependencies = [...this._dependencies];
+
+		// Clear current dependencies, compute and retrack dependencies
+		this._dependencies.clear();
+
+		// Compute the value and wait until all dependencies are computed
+		const previousValue = this._value;
+		this._value = await this._compute(this);
+
+		// Unsubscribe from dependencies that are no longer needed
+		const dependenciesToRemove = dependencies.filter(
+			(dependency) => !this._dependencies.has(dependency),
+		);
+		dependenciesToRemove.forEach((dependency) => {
+			dependency._unregisterDependency(this);
+		});
+
+		// Notify dependencies
+		// use super method to avoid setting dirty flag back to true
+		if (!options?.force && previousValue !== this._value) {
+			FlowGraph.requestTrigger(() => super._notify());
+		}
+	}
+}

package/src/flow/nodes/await/flowReadonlyAwait.ts

@@ -0,0 +1,89 @@
+import type { FlowNodeAwait } from "./flowNodeAwait";
+
+/**
+ * A generic utility type for creating read-only views of reactive nodes, with asynchronous values.
+ *
+ * @typeParam T - The type of the value held by the reactive node (not the Promise itself).
+ *
+ * @remarks
+ * `FlowReadonlyAwait` is a type alias based on {@link FlowNodeAwait} with the `set()` and `refresh()`
+ * methods removed, making it a read-only view. It provides all the reactive capabilities of `FlowNodeAwait`
+ * (dependency tracking, lazy computation, caching, reading values) but prevents mutation.
+ *
+ * **Key Difference from FlowReadonlyAsync:**
+ * Unlike {@link FlowReadonlyAsync}, which returns Promises from `get()`, FlowReadonlyAwait returns
+ * the resolved value directly. This makes the API more convenient for reactive code that doesn't want
+ * to deal with Promises in every access. The Promise is awaited internally and the resolved value is cached.
+ *
+ * **Asynchronous Nature:**
+ * FlowReadonlyAwait works with Promises internally, but provides a synchronous-looking API:
+ * - `get(t)` returns the resolved value synchronously (`T | undefined`). The value may be `undefined`
+ *   if the Promise hasn't resolved yet on first access.
+ * - `pick()` returns a `Promise<T>` that must be awaited. Use this when you need to ensure the value
+ *   is fully resolved before proceeding.
+ * - The Promise is awaited internally and the resolved value is cached until dependencies change.
+ *
+ * **Difference from FlowConstantAwait and FlowDerivationAwait:**
+ * - {@link FlowConstantAwait}: Specialized type for immutable constants that compute once and never change
+ * - {@link FlowDerivationAwait}: Specialized type for computed values that automatically recompute when dependencies change
+ * - `FlowReadonlyAwait`: Generic utility type that can be used with any `FlowNodeAwait` to create a read-only view
+ *
+ * **Use Cases:**
+ * - **Type Safety**: Ensure functions don't accidentally mutate state by accepting `FlowReadonlyAwait` instead of `FlowStateAwait`
+ * - **API Design**: Expose read-only views of internal state to prevent external mutation
+ * - **Function Parameters**: Accept any reactive node (state, derivation, constant) but prevent mutation
+ * - **Composition**: Create read-only wrappers around mutable states for safer sharing
+ *
+ * @example
+ * ```typescript
+ * // Type safety: Function that only reads state
+ * function displayCount(count: FlowReadonlyAwait<number>) {
+ *   // count.set(Promise.resolve(100)); // TypeScript error: Property 'set' does not exist
+ *   effect((t) => {
+ *     const value = count.get(t); // Synchronous - returns resolved value
+ *     console.log(value);
+ *   });
+ * }
+ *
+ * const $count = stateAwait(Promise.resolve(0));
+ * displayCount($count); // OK: FlowStateAwait is assignable to FlowReadonlyAwait
+ *
+ * // API design: Expose read-only view
+ * class Counter {
+ *   private _count = stateAwait(Promise.resolve(0));
+ *
+ *   get count(): FlowReadonlyAwait<number> {
+ *     return this._count; // FlowStateAwait is assignable to FlowReadonlyAwait
+ *   }
+ *
+ *   async increment() {
+ *     await this._count.set(async (current) => Promise.resolve(current + 1)); // Internal mutation allowed
+ *   }
+ * }
+ *
+ * const counter = new Counter();
+ * // counter.count.set(Promise.resolve(100)); // TypeScript error: Cannot mutate read-only view
+ * const current = await counter.count.pick(); // Async - returns Promise
+ *
+ * // Works with derivations too
+ * const $firstName = stateAwait(Promise.resolve('John'));
+ * const $lastName = stateAwait(Promise.resolve('Doe'));
+ * const $fullName = derivationAwait(async (t) => {
+ *   const first = $firstName.get(t); // Synchronous - returns resolved value
+ *   const last = $lastName.get(t);   // Synchronous - returns resolved value
+ *   return `${first} ${last}`;
+ * });
+ *
+ * function displayName(name: FlowReadonlyAwait<string>) {
+ *   effect((t) => {
+ *     const fullName = name.get(t); // Synchronous - returns resolved value
+ *     console.log(fullName);
+ *   });
+ * }
+ *
+ * displayName($fullName); // OK: FlowDerivationAwait is assignable to FlowReadonlyAwait
+ * ```
+ *
+ * @public
+ */
+export type FlowReadonlyAwait<T> = Omit<FlowNodeAwait<T>, "set" | "refresh">;