@ersbeth/picoflow 1.0.0 → 1.1.0

package/src/flow/collections/flowMap.ts

@@ -0,0 +1,398 @@
+import { FlowGraph, isDisposable } from "../base";
+import { FlowNode, type FlowState, state } from "../nodes";
+
+/**
+ * Represents the actions that can be performed on a FlowMap.
+ * @public
+ */
+export type FlowMapAction<K, V> =
+	| {
+			type: "set";
+			map: Map<K, V>;
+	  }
+	| {
+			type: "add";
+			key: K;
+			value: V;
+	  }
+	| {
+			type: "update";
+			key: K;
+			value: V;
+	  }
+	| {
+			type: "delete";
+			key: K;
+			value: V;
+	  }
+	| {
+			type: "clear";
+	  };
+
+/**
+ * Represents a reactive map that extends {@link FlowState} for tracking key-value pairs.
+ *
+ * @remarks
+ * FlowMap wraps a native JavaScript Map and provides reactive tracking at multiple granularity levels.
+ * Unlike plain reactive state, FlowMap offers fine-grained reactivity that lets you track:
+ *
+ * 1. **Whole map changes**: Via `get(t)` or `pick()` on the FlowMap itself
+ * 2. **Last action**: Via the `$lastAction` signal, track the most recent operation performed on the map
+ *
+ * **Reactive Signals:**
+ * - **$lastAction**: A FlowState containing a {@link FlowMapAction} that describes the most recent operation
+ *   (set, add, update, delete, or clear) performed on the map
+ *
+ * These signals enable fine-grained reactivity patterns where effects can respond to specific
+ * map operations without re-processing the entire map.
+ *
+ * **Use Cases:**
+ * - Entity stores where you want to track additions/removals separately
+ * - Cache implementations with granular invalidation
+ * - Collections where operations on individual keys matter
+ * - UI state where you want to animate specific additions or removals
+ *
+ * @example
+ * ```typescript
+ * const $users = map<string, User>();
+ *
+ * // Track the whole map
+ * effect((t) => {
+ *   const users = $users.get(t);
+ *   console.log(`Total users: ${users.size}`);
+ * });
+ *
+ * // Track last action
+ * effect((t) => {
+ *   const action = $users.$lastAction.get(t);
+ *   switch (action.type) {
+ *     case 'add':
+ *       console.log(`User ${action.key} was added:`, action.value);
+ *       break;
+ *     case 'update':
+ *       console.log(`User ${action.key} was updated:`, action.value);
+ *       break;
+ *     case 'delete':
+ *       console.log(`User ${action.key} was deleted:`, action.value);
+ *       break;
+ *     case 'set':
+ *       console.log('Map was replaced');
+ *       break;
+ *     case 'clear':
+ *       console.log('Map was cleared');
+ *       break;
+ *   }
+ * });
+ *
+ * // Modify the map
+ * $users.add('user1', { name: 'John', age: 30 });
+ * $users.add('user2', { name: 'Jane', age: 25 });
+ * $users.update('user1', { name: 'John', age: 31 });
+ * $users.delete('user1');
+ * $users.clear();
+ * ```
+ *
+ * @typeParam K - The type of the map keys.
+ * @typeParam V - The type of the map values.
+ *
+ * @public
+ */
+export class FlowMap<K, V> extends FlowNode<Map<K, V>> {
+	/**
+	 * Last action performed on the FlowMap.
+	 * @public
+	 */
+	public $lastAction: FlowState<FlowMapAction<K, V>>;
+	protected declare _value: Map<K, V>;
+
+	/**
+	 * Creates an instance of FlowMap.
+	 * @param value - Initial map value.
+	 * @public
+	 */
+	constructor(value: Map<K, V> = new Map()) {
+		super(value);
+		this.$lastAction = state<FlowMapAction<K, V>>({
+			type: "set",
+			map: value,
+		});
+	}
+
+	/**
+	 * Adds a new key-value pair to the map.
+	 *
+	 * @param key - The key to add.
+	 * @param value - The value to associate with the key.
+	 * @throws If the FlowMap instance is disposed.
+	 * @throws If the key already exists in the map.
+	 *
+	 * @remarks
+	 * Adds a new entry to the internal map, emits the key-value pair via {@link FlowMap.$lastAction},
+	 * and notifies all subscribers of the change.
+	 *
+	 * @public
+	 */
+	public async add(key: K, value: V): Promise<void> {
+		if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+
+		const update = () => {
+			// get value
+			const currentValue = this._value.get(key);
+			if (currentValue) {
+				throw new Error("[PicoFlow] Key already exists");
+			}
+
+			// add key
+			this._value.set(key, value);
+
+			// emit last action
+			this.$lastAction.set({ type: "add", key, value });
+
+			// return value changed check
+			return true;
+		};
+
+		const notify = () => {
+			// call super method to avoid setting dirty flag back to true
+			super._notify();
+		};
+
+		return FlowGraph.requestWrite(notify, update);
+	}
+
+	/**
+	 * Updates an existing key-value pair in the map.
+	 *
+	 * @param key - The key to update.
+	 * @param value - The new value to associate with the key.
+	 * @throws If the FlowMap instance is disposed.
+	 * @throws If the key does not exist in the map.
+	 *
+	 * @remarks
+	 * Updates an existing entry in the internal map, emits the key-value pair via {@link FlowMap.$lastAction},
+	 * and notifies all subscribers of the change.
+	 *
+	 * @public
+	 */
+	public async update(key: K, value: V): Promise<void> {
+		if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+
+		const update = () => {
+			// get value
+			const currentValue = this._value.get(key);
+			if (!currentValue) throw new Error("[PicoFlow] Key does not exist");
+
+			if (currentValue !== value) {
+				// dispose value
+				if (isDisposable(currentValue)) currentValue.dispose({ self: true });
+
+				// update key
+				this._value.set(key, value);
+
+				// emit last action
+				this.$lastAction.set({ type: "update", key, value });
+
+				// return value changed check
+				return true;
+			}
+			return false;
+		};
+
+		const notify = () => {
+			// call super method to avoid setting dirty flag back to true
+			super._notify();
+		};
+
+		return FlowGraph.requestWrite(notify, update);
+	}
+
+	/**
+	 * Deletes the value at the specified key from the underlying map.
+	 *
+	 * @param key - The key to delete.
+	 * @throws If the FlowMap instance is disposed.
+	 *
+	 * @remarks
+	 * Removes the key from the internal map, emits the deleted key and its value via {@link FlowMap.$lastAction},
+	 * and notifies all subscribers of the change.
+	 *
+	 * @public
+	 */
+	public async delete(key: K): Promise<void> {
+		if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+
+		const update = () => {
+			// get value
+			const value = this._value.get(key);
+			if (value === undefined) throw new Error("[PicoFlow] Key does not exist");
+
+			// dispose value
+			if (isDisposable(value)) value.dispose({ self: true });
+
+			// delete key
+			this._value.delete(key);
+
+			// emit last action
+			this.$lastAction.set({ type: "delete", key, value });
+
+			// return value changed check
+			return true;
+		};
+
+		const notify = () => {
+			// call super method to avoid setting dirty flag back to true
+			super._notify();
+		};
+
+		return FlowGraph.requestWrite(notify, update);
+	}
+
+	/**
+	 * Replaces the entire map with new entries.
+	 *
+	 * @param map - The new map of entries.
+	 * @throws If the FlowMap instance is disposed.
+	 *
+	 * @remarks
+	 * Replaces all entries in the internal map, disposes the old values (if they are disposable),
+	 * emits the new map via {@link FlowMap.$lastAction}, and notifies all subscribers of the change.
+	 *
+	 * @public
+	 */
+	override async set(map: Map<K, V>): Promise<void> {
+		if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+		const update = () => {
+			// compute current value
+			const currentValue = this._value;
+
+			// dispose old values
+			if (currentValue !== map) {
+				currentValue.forEach((item) => {
+					if (isDisposable(item)) item.dispose({ self: true });
+				});
+			}
+
+			// assign new map
+			this._value = map;
+
+			// emit last action
+			if (currentValue !== map) {
+				this.$lastAction.set({ type: "set", map: map });
+			}
+
+			// return value changed check
+			return currentValue !== map;
+		};
+
+		const notify = () => {
+			// call super method to avoid setting dirty flag back to true
+			super._notify();
+		};
+
+		return FlowGraph.requestWrite(notify, update);
+	}
+
+	/**
+	 * Clears all entries from the map.
+	 *
+	 * @throws If the FlowMap instance is disposed.
+	 *
+	 * @remarks
+	 * Removes all entries from the internal map, disposes the removed values (if they are disposable),
+	 * emits a clear action via {@link FlowMap.$lastAction}, and notifies all subscribers of the change.
+	 *
+	 * @public
+	 */
+	public async clear(): Promise<void> {
+		if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+
+		const update = () => {
+			// dispose old values
+			const items = [...this._value.values()];
+			items.forEach((item) => {
+				if (isDisposable(item)) item.dispose({ self: true });
+			});
+
+			// clear map
+			this._value.clear();
+
+			// emit last action
+			this.$lastAction.set({ type: "clear" });
+
+			// return value changed check
+			return true;
+		};
+
+		const notify = () => {
+			// call super method to avoid setting dirty flag back to true
+			super._notify();
+		};
+
+		return FlowGraph.requestWrite(notify, update);
+	}
+
+	/**
+	 * Disposes the FlowMap and its values.
+	 * @param options - Disposal options.
+	 * @public
+	 */
+	override dispose(options?: { self: boolean }): void {
+		super.dispose(options);
+		this._value.forEach((item) => {
+			if (isDisposable(item)) item.dispose(options);
+		});
+		this._value.clear();
+	}
+}
+
+/**
+ * Creates a new reactive map state with fine-grained tracking of operations.
+ *
+ * @typeParam K - The type of the keys.
+ * @typeParam V - The type of the values.
+ * @param initial - An optional record of key-value pairs or a Map to initialize the map.
+ * @returns A new instance of {@link FlowMap}.
+ *
+ * @remarks
+ * A reactive map wraps a native JavaScript Map and provides multiple levels of reactivity:
+ * tracking the entire map, tracking individual set operations, and tracking individual
+ * delete operations. The initial record (if provided) is converted to a native Map.
+ * If a Map is provided, it is used directly.
+ *
+ * @example
+ * ```typescript
+ * const $users = map<string, User>({
+ *   'user1': { name: 'John', age: 30 }
+ * });
+ *
+ * // Or with a Map
+ * const $users2 = map<string, User>(new Map([['user1', { name: 'John', age: 30 }]]));
+ *
+ * // Track the whole map
+ * effect((t) => {
+ *   console.log('Users:', $users.get(t).size);
+ * });
+ *
+ * // Track last action
+ * effect((t) => {
+ *   const action = $users.$lastAction.get(t);
+ *   if (action.type === 'add') {
+ *     console.log(`Added: ${action.key}`);
+ *   }
+ * });
+ *
+ * $users.add('user2', { name: 'Jane', age: 25 });
+ * ```
+ *
+ * @public
+ */
+export function map<K extends string | number | symbol, V>(
+	initial?: Record<K, V> | Map<K, V>,
+): FlowMap<K, V> {
+	if (initial instanceof Map) {
+		return new FlowMap<K, V>(initial);
+	}
+	return new FlowMap<K, V>(
+		new Map<K, V>(initial ? (Object.entries(initial) as [K, V][]) : []),
+	);
+}

package/src/flow/collections/index.ts

@@ -0,0 +1,2 @@
+export * from "./flowArray";
+export * from "./flowMap";

package/src/flow/index.ts

@@ -0,0 +1,3 @@
+export * from "./base";
+export * from "./collections";
+export * from "./nodes";

package/src/flow/nodes/async/flowConstantAsync.ts

@@ -0,0 +1,142 @@
+import { FlowNodeAsync } from "./flowNodeAsync";
+
+/**
+ * Represents a constant value that can be computed lazily upon first access, with asynchronous values.
+ *
+ * @typeParam T - The type of the constant value (not the Promise itself).
+ *
+ * @remarks
+ * `FlowConstantAsync` is a type alias based on {@link FlowNodeAsync} with the `set()` and `refresh()`
+ * methods removed, making it immutable. It provides all the reactive capabilities of `FlowNodeAsync`
+ * (lazy computation, caching, dependency tracking) but prevents value mutation after initialization.
+ *
+ * Unlike {@link FlowStateAsync}, which is mutable via the `set()` method, a constant's value never
+ * changes after it's computed. This makes it ideal for values that should remain stable throughout
+ * the application lifecycle.
+ *
+ * **Asynchronous Nature:**
+ * All values in FlowConstantAsync are Promises. When you call `get()` or `pick()`, you receive a
+ * `Promise<T>` that you must await to get the actual value. This allows for seamless integration
+ * with async/await patterns and asynchronous data sources.
+ *
+ * **Lazy Computation:**
+ * Constants are created using the `constantAsync()` factory function, which accepts either a
+ * `Promise<T>` or a function returning `Promise<T>`. The computation doesn't run immediately
+ * upon creation when using a function. It executes only when:
+ * - The value is first read via `get()` or `pick()`
+ * - The constant is watched via `watch()`
+ * This allows you to defer expensive async computations until they're actually needed.
+ *
+ * **Initialization Patterns:**
+ * - **Constant Promise**: Pass a `Promise<T>` directly; it's stored immediately and can be accessed
+ *   right away. The Promise resolves to the value of type T.
+ * - **Lazy initialization**: Pass a function `() => Promise<T>`; it's called only when the value
+ *   is first accessed via `get()` or `pick()`. This is useful for expensive async operations that
+ *   may not be needed immediately.
+ *
+ * **Caching:**
+ * Once computed (either immediately or lazily), the Promise is cached permanently. All subsequent
+ * accesses return the cached Promise without re-computation, ensuring the value remains constant
+ * and the computation runs only once.
+ *
+ * **Use Cases:**
+ * - Configuration values loaded asynchronously that don't change
+ * - Expensive async computations that should only run once
+ * - Initialization values for other reactive primitives
+ * - Values derived from external async sources that shouldn't be modified
+ *
+ * @example
+ * ```typescript
+ * // Constant Promise - initialized immediately
+ * const $config = constantAsync(Promise.resolve({ apiUrl: 'https://api.example.com' }));
+ * const config = await $config.pick(); // Resolves immediately
+ *
+ * // Lazy initialization - computed on first access
+ * const $expensiveValue = constantAsync(async () => {
+ *   console.log('Computing...');
+ *   return await performExpensiveAsyncCalculation();
+ * });
+ *
+ * // First access triggers computation
+ * const value1 = await $expensiveValue.pick(); // Logs: "Computing..."
+ *
+ * // Subsequent accesses return cached Promise
+ * const value2 = await $expensiveValue.pick(); // No log - returns cached value
+ *
+ * // Value cannot be changed (set() method is not available)
+ * // $expensiveValue.set(Promise.resolve(100)); // TypeScript error: Property 'set' does not exist
+ * ```
+ *
+ * @public
+ */
+export type FlowConstantAsync<T> = Omit<FlowNodeAsync<T>, "set" | "refresh">;
+
+/**
+ * Creates a new reactive constant with lazy initialization support.
+ *
+ * @typeParam T - The type of the constant value (not the Promise itself).
+ *
+ * @param value - Either a `Promise<T>` for immediate initialization, or a function `() => Promise<T>`
+ * for lazy initialization. The function will be called only when the value is first accessed.
+ *
+ * @returns A new instance of {@link FlowConstantAsync} that provides reactive access to the computed value.
+ *
+ * @remarks
+ * Constants are immutable reactive values that are computed once and cached permanently. Unlike
+ * states (created with `stateAsync()`), constants cannot be modified after initialization - they don't
+ * have a `set()` method.
+ *
+ * **Asynchronous Nature:**
+ * All values are Promises. When you access the constant via `get(t)` or `pick()`, you receive a
+ * `Promise<T>` that you must await to get the actual value. This allows for seamless integration
+ * with async/await patterns and asynchronous data sources.
+ *
+ * **Lazy Computation:**
+ * When you provide a function, the computation is not executed immediately upon creation. It runs only when:
+ * - The value is first read via `get(t)` or `pick()`
+ * - The constant is watched via `watch()`
+ *
+ * This lazy computation is useful for:
+ * - Expensive async computations that may not be needed immediately
+ * - Values that depend on resources not available at construction time
+ * - Deferring async operations until the value is actually needed
+ *
+ * **When to Use Constants:**
+ * - Use `constantAsync()` for values that should never change after initialization
+ * - Use `stateAsync()` for mutable values that can be updated
+ * - Use `derivationAsync()` for values that recompute when dependencies change
+ *
+ * @example
+ * ```typescript
+ * // Eager initialization with Promise
+ * const $config = constantAsync(Promise.resolve({
+ *   apiUrl: 'https://api.example.com'
+ * }));
+ * const config = await $config.pick();
+ *
+ * // Lazy initialization with async function
+ * const $expensiveValue = constantAsync(async () => {
+ *   return await loadConfigurationFromFile();
+ * });
+ *
+ * // Computation hasn't run yet
+ * // First access triggers it
+ * const value = await $expensiveValue.pick();
+ *
+ * // Subsequent accesses return cached Promise
+ * const value2 = await $expensiveValue.pick();
+ *
+ * // Use in reactive context
+ * effect(async (t) => {
+ *   const cfg = await $config.get(t);
+ *   console.log(`API URL: ${cfg.apiUrl}`);
+ * });
+ * ```
+ *
+ * @public
+ */
+export function constantAsync<T>(
+	value: Promise<T> | (() => Promise<T>),
+): FlowConstantAsync<T> {
+	return new FlowNodeAsync(value);
+}

package/src/flow/nodes/async/flowDerivationAsync.ts

@@ -0,0 +1,143 @@
+import type { FlowTracker } from "../../base";
+import { FlowNodeAsync } from "./flowNodeAsync";
+
+/**
+ * Represents a reactive derivation whose value is computed based on other reactive signals, with asynchronous values.
+ *
+ * @typeParam T - The type of the computed value (not the Promise itself).
+ *
+ * @remarks
+ * `FlowDerivationAsync` is a type alias based on {@link FlowNodeAsync} with the `set()` method removed,
+ * making it immutable. It provides all the reactive capabilities of `FlowNodeAsync` (dependency tracking,
+ * lazy computation, caching) but prevents value mutation after initialization.
+ *
+ * Unlike {@link FlowConstantAsync}, which computes its value once and never changes, derivations
+ * automatically recompute when any tracked dependency changes. This makes them ideal for
+ * creating derived state that stays in sync with its sources.
+ *
+ * **Asynchronous Nature:**
+ * All values in FlowDerivationAsync are Promises. When you call `get()` or `pick()`, you receive a
+ * `Promise<T>` that you must await to get the actual value. The compute function must return a
+ * `Promise<T>`. This allows for seamless integration with async/await patterns and asynchronous
+ * data sources.
+ *
+ * **Lazy Computation:**
+ * The compute function doesn't run immediately upon creation. It executes only when:
+ * - The value is first read via `get()` or `pick()`
+ * - The derivation is watched via `watch()`
+ * This allows you to defer expensive async computations until they're actually needed.
+ *
+ * **Automatic Recomputation:**
+ * When a tracked dependency changes, the derivation is marked as "dirty" but doesn't recompute
+ * immediately. Recomputation happens lazily on the next value access. This prevents unnecessary
+ * computations when multiple dependencies change in quick succession. The Promise is cached until
+ * dependencies change, ensuring efficient access patterns. You can also force recomputation using
+ * the `refresh()` method.
+ *
+ * **Dynamic Dependencies:**
+ * Dependencies are tracked dynamically during each computation. If the compute function
+ * conditionally tracks different observables, the dependency graph updates automatically.
+ * When accessing async dependencies via `.get(t)`, you must await the returned Promise.
+ *
+ * @example
+ * ```typescript
+ * const $firstName = stateAsync(Promise.resolve('John'));
+ * const $lastName = stateAsync(Promise.resolve('Doe'));
+ *
+ * const $fullName = derivationAsync(async (t) => {
+ *   const first = await $firstName.get(t);
+ *   const last = await $lastName.get(t);
+ *   return `${first} ${last}`;
+ * });
+ *
+ * // Compute function hasn't run yet (lazy)
+ * const name = await $fullName.pick(); // Now it computes: "John Doe"
+ *
+ * // When dependencies change, derivation recomputes automatically
+ * await $firstName.set(Promise.resolve('Jane'));
+ * const newName = await $fullName.pick(); // "Jane Doe" (recomputed)
+ * ```
+ *
+ * @public
+ */
+
+export type FlowDerivationAsync<T> = Omit<FlowNodeAsync<T>, "set">;
+
+/**
+ * Creates a new reactive derivation whose value is computed based on other reactive signals.
+ *
+ * @typeParam T - The type of the derived value (not the Promise itself).
+ *
+ * @param fn - A function that computes the derived value using a tracking context. The 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.
+ *
+ * @returns A new instance of {@link FlowDerivationAsync} that provides reactive access to the computed value.
+ *
+ * @remarks
+ * A derivation is a computed reactive value that automatically tracks its dependencies and
+ * recomputes when they change. The computation is lazy - it runs only when the value is
+ * accessed, not on construction. Use derivations to create derived state without manual
+ * dependency management.
+ *
+ * **Asynchronous Nature:**
+ * All values are Promises. When you access the derivation via `get(t)` or `pick()`, you receive a
+ * `Promise<T>` that you must await to get the actual value. The compute function must return a
+ * `Promise<T>`. When accessing async dependencies within the compute function, you must await
+ * the Promises returned by `.get(t)`.
+ *
+ * **Lazy Computation:**
+ * The compute function is not executed immediately upon creation. It runs only when:
+ * - The value is first read via `get(t)` or `pick()`
+ * - The derivation is watched via `watch()`
+ *
+ * This lazy computation is useful for:
+ * - Expensive async computations that may not be needed immediately
+ * - Values that depend on async resources
+ * - Deferring async operations until the value is actually needed
+ *
+ * **Automatic Recomputation:**
+ * When any tracked dependency changes, the derivation automatically recomputes on the next access.
+ * This ensures the derived value always stays in sync with its sources.
+ *
+ * **When to Use Derivations:**
+ * - Use `derivationAsync()` for values that should recompute when dependencies change
+ * - Use `constantAsync()` for values that compute once and never change
+ * - Use `stateAsync()` for mutable values that can be updated directly
+ *
+ * @example
+ * ```typescript
+ * const $firstName = stateAsync(Promise.resolve('John'));
+ * const $lastName = stateAsync(Promise.resolve('Doe'));
+ *
+ * const $fullName = derivationAsync(async (t) => {
+ *   const first = await $firstName.get(t);
+ *   const last = await $lastName.get(t);
+ *   return `${first} ${last}`;
+ * });
+ *
+ * // Use in reactive context
+ * effect(async (t) => {
+ *   const name = await $fullName.get(t);
+ *   console.log(name); // Logs: "John Doe"
+ * });
+ *
+ * // When dependencies change, derivation recomputes automatically
+ * await $firstName.set(Promise.resolve('Jane')); // Logs: "Jane Doe"
+ *
+ * // Async data fetching example
+ * const $userId = stateAsync(Promise.resolve(1));
+ * const $user = derivationAsync(async (t) => {
+ *   const id = await $userId.get(t);
+ *   return await fetchUser(id);
+ * });
+ * ```
+ *
+ * @public
+ */
+export function derivationAsync<T>(
+	fn: (t: FlowTracker) => Promise<T>,
+): FlowDerivationAsync<T> {
+	return new FlowNodeAsync(fn);
+}