@ersbeth/picoflow 1.1.2 → 2.0.0

package/src/flow/collections/flowMap.ts

@@ -1,398 +0,0 @@
-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/nodes/async/flowConstantAsync.ts

@@ -1,142 +0,0 @@
-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

@@ -1,143 +0,0 @@
-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);
-}