@ersbeth/picoflow 1.1.2 → 2.0.0

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

@@ -1,130 +0,0 @@
-import { FlowNodeAwait } from "./flowNodeAwait";
-
-/**
- * Represents a reactive state that holds a mutable value, with asynchronous values.
- *
- * @typeParam T - The type of the state value (not the Promise itself).
- *
- * @remarks
- * `FlowStateAwait` is a type alias of {@link FlowNodeAwait}, providing a mutable reactive state that can be
- * updated using the `set()` method. It provides all the reactive capabilities of `FlowNodeAwait`
- * (lazy computation, caching) with the ability to mutate the value.
- *
- * Unlike {@link FlowConstantAwait}, which is immutable and computes once, states can be updated at any
- * time. Unlike {@link FlowDerivationAwait}, which recomputes when dependencies change, states are
- * updated explicitly via `set()`.
- *
- * **Key Difference from FlowStateAsync:**
- * Unlike {@link FlowStateAsync}, which returns Promises from `get()`, FlowStateAwait 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:**
- * FlowStateAwait 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 the state is updated.
- * - The `set()` method returns `Promise<void>` and must be awaited.
- *
- * **Reading Values:**
- * You can read the state value using `get(t)` for tracked access (creates reactive dependency)
- * or `pick()` for untracked access (reads without creating dependency):
- * - `get(t)` returns the resolved value synchronously (`T | undefined`)
- * - `pick()` returns a `Promise<T>` that must be awaited
- *
- * **Updating Values:**
- * When the state is updated with a new value that differs from the current value (strict equality),
- * all dependent effects and derivations are automatically notified and re-executed. If the new value
- * is strictly equal to the current value, no notification occurs. The `set()` method accepts either
- * a `Promise<T>` or a function `(current: T) => Promise<T>` and returns `Promise<void>`.
- *
- * @example
- * ```typescript
- * const $count = stateAwait(Promise.resolve(0));
- *
- * // Read with tracking
- * effect((t) => {
- *   const value = $count.get(t); // Synchronous - returns resolved value, effect re-runs when $count changes
- *   console.log(value);
- * });
- *
- * // Read without tracking
- * const snapshot = await $count.pick(); // Async - returns Promise
- *
- * // Update the value
- * await $count.set(Promise.resolve(1));
- * await $count.set(async (current) => Promise.resolve(current + 1));
- * ```
- *
- * @public
- */
-export type FlowStateAwait<T> = Omit<FlowNodeAwait<T>, "refresh">;
-
-/**
- * Creates a new reactive state holding a mutable value.
- *
- * @typeParam T - The type of the state value (not the Promise itself).
- *
- * @param value - The initial value for the state, or a function that returns the initial value.
- * If a function is provided, it is called lazily only when the value is first accessed via
- * `get()` or `pick()`. If a direct Promise is provided, it is stored immediately and resolved internally.
- *
- * @returns A new instance of {@link FlowStateAwait} that provides reactive access to the mutable value.
- *
- * @remarks
- * State is the most common reactive primitive - a mutable container that notifies dependents
- * when its value changes. Use `set()` to update the value (returns `Promise<void>`) and `get(t)`
- * or `pick()` to read it:
- * - `get(t)` returns the resolved value synchronously (`T | undefined`)
- * - `pick()` returns a `Promise<T>` that must be awaited
- *
- * **Asynchronous Nature:**
- * FlowStateAwait 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 the state is updated.
- * - The `set()` method returns `Promise<void>` and must be awaited.
- *
- * **Lazy Initialization:**
- * When a function is provided, the initialization is lazy - the function is not called immediately
- * upon creation. It executes only when:
- * - The value is first read via `get(t)` or `pick()`
- * - The state is watched via `watch()`
- *
- * This is useful for expensive async initializations that may not be needed immediately.
- *
- * **When to Use States:**
- * - Use `stateAwait()` for mutable values that can be updated directly
- * - Use `constantAwait()` for values that compute once and never change
- * - Use `derivationAwait()` for values that recompute when dependencies change
- *
- * @example
- * ```typescript
- * // Direct Promise - initialized immediately
- * const $count = stateAwait(Promise.resolve(0));
- *
- * // Lazy initialization - computed on first access
- * const $config = stateAwait(async () => {
- *   return await loadConfiguration();
- * });
- *
- * effect((t) => {
- *   const value = $count.get(t); // Synchronous - returns resolved value
- *   console.log(value);
- * });
- *
- * await $count.set(Promise.resolve(1)); // Logs: 1
- * await $count.set(async (current) => Promise.resolve(current + 1)); // Logs: 2
- * ```
- *
- * @public
- */
-export function stateAwait<T>(
-	value: Promise<T> | (() => Promise<T>),
-): FlowStateAwait<T> {
-	return new FlowNodeAwait(value);
-}

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

@@ -1,5 +0,0 @@
-export * from "./flowConstantAwait";
-export * from "./flowDerivationAwait";
-export * from "./flowNodeAwait";
-export * from "./flowReadonlyAwait";
-export * from "./flowStateAwait";

package/src/flow/nodes/index.ts

@@ -1,3 +0,0 @@
-export * from "./async";
-export * from "./sync";
-// export * from "./await";

package/src/flow/nodes/sync/flowConstant.ts

@@ -1,111 +0,0 @@
-import type { NotPromise } from "../../base";
-import { FlowNode } from "./flowNode";
-
-/**
- * Represents a constant value that can be computed lazily upon first access.
- *
- * @typeParam T - The type of the constant value.
- *
- * @remarks
- * `FlowConstant` is a type alias based on {@link FlowNode} with the `set()` method removed,
- * making it immutable. It provides all the reactive capabilities of `FlowNode` (
- * lazy computation, caching) but prevents value mutation after initialization.
- *
- * Unlike {@link FlowState}, 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.
- *
- * **Lazy Computation:**
- * Constants are created using the `constant()` factory function, which accepts a compute function.
- * The computation doesn't run immediately upon creation. 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 computations until they're actually needed.
- *
- * **Caching:**
- * Once computed, the value is cached permanently. All subsequent accesses return the cached value
- * without re-computation, ensuring the value remains constant and the computation runs only once.
- *
- * **Use Cases:**
- * - Configuration values that don't change
- * - Expensive computations that should only run once
- * - Initialization values for other reactive primitives
- * - Values derived from external sources that shouldn't be modified
- *
- * @example
- * ```typescript
- * // Lazy initialization - computed on first access
- * const $expensiveValue = constant(() => {
- *   return performExpensiveCalculation();
- * });
- *
- * // First access triggers computation
- * const value1 = await $expensiveValue.pick();
- *
- * // Subsequent accesses return cached value
- * const value2 = await $expensiveValue.pick();
- *
- * // Value cannot be changed (set() method is not available)
- * // $expensiveValue.set(100); // TypeScript error: Property 'set' does not exist
- * ```
- *
- * @public
- */
-export type FlowConstant<T> = Omit<FlowNode<T>, "set" | "refresh">;
-
-/**
- * Creates a new reactive constant with lazy initialization.
- *
- * @typeParam T - The type of the constant value.
- *
- * @param value - A function that computes the constant value. This function is called lazily
- * only when the value is first accessed via `get()` or `pick()`.
- *
- * @returns A new instance of {@link FlowConstant} 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 `state()`), constants cannot be modified after initialization - they don't
- * have a `set()` method.
- *
- * **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 constant is watched via `watch()`
- *
- * This lazy computation is useful for:
- * - Expensive computations that may not be needed immediately
- * - Values that depend on resources not available at construction time
- * - Deferring computation until the value is actually needed
- *
- * **When to Use Constants:**
- * - Use `constant()` for values that should never change after initialization
- * - Use `state()` for mutable values that can be updated
- * - Use `derivation()` for values that recompute when dependencies change
- *
- * @example
- * ```typescript
- * // Expensive computation that runs only once
- * const $config = constant(() => {
- *   return loadConfigurationFromFile();
- * });
- *
- * // Computation hasn't run yet
- * // First access triggers it
- * const config = await $config.pick();
- *
- * // Subsequent accesses return cached value
- * const config2 = await $config.pick();
- *
- * // Use in reactive context
- * effect((t) => {
- *   const cfg = $config.get(t);
- *   console.log(`API URL: ${cfg.apiUrl}`);
- * });
- * ```
- *
- * @public
- */
-export function constant<T>(value: () => NotPromise<T>): FlowConstant<T> {
-	return new FlowNode(value);
-}

package/src/flow/nodes/sync/flowDerivation.ts

@@ -1,105 +0,0 @@
-import type { FlowTracker, NotPromise } from "../../base";
-import { FlowNode } from "./flowNode";
-
-/**
- * Represents a reactive derivation whose value is computed based on other reactive signals.
- *
- * @typeParam T - The type of the computed value.
- *
- * @remarks
- * `FlowDerivation` is a type alias based on {@link FlowNode} with the `set()` method removed,
- * making it immutable. It provides all the reactive capabilities of `FlowNode` (dependency tracking,
- * lazy computation, caching) but prevents value mutation after initialization.
- *
- * Unlike {@link FlowConstant}, 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.
- *
- * **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()`
- *
- * **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. 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.
- *
- * @example
- * ```typescript
- * const $firstName = state('John');
- * const $lastName = state('Doe');
- *
- * const $fullName = derivation((t) => {
- *   return `${$firstName.get(t)} ${$lastName.get(t)}`;
- * });
- *
- * // 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('Jane');
- * const newName = await $fullName.pick(); // "Jane Doe" (recomputed)
- * ```
- *
- * @public
- */
-export type FlowDerivation<T> = Omit<FlowNode<T>, "set">;
-
-/**
- * Creates a new reactive derivation whose value is computed based on other reactive signals.
- *
- * @typeParam T - The type of the derived value.
- *
- * @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 is not executed immediately; it runs lazily on first access.
- *
- * @returns A new instance of {@link FlowDerivation} 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.
- *
- * **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()`
- *
- * **When to Use Derivations:**
- * - Use `derivation()` for values that should recompute when dependencies change
- * - Use `constant()` for values that compute once and never change
- * - Use `state()` for mutable values that can be updated directly
- *
- * @example
- * ```typescript
- * const $firstName = state('John');
- * const $lastName = state('Doe');
- *
- * const $fullName = derivation((t) => {
- *   return `${$firstName.get(t)} ${$lastName.get(t)}`;
- * });
- *
- * // Use in reactive context
- * effect((t) => {
- *   console.log($fullName.get(t)); // Logs: "John Doe"
- * });
- *
- * // When dependencies change, derivation recomputes automatically
- * await $firstName.set('Jane'); // Logs: "Jane Doe"
- * ```
- *
- * @public
- */
-export function derivation<T>(
-	fn: (t: FlowTracker) => NotPromise<T>,
-): FlowDerivation<T> {
-	return new FlowNode(fn);
-}