@ersbeth/picoflow 1.0.1 → 1.1.1

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

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

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

package/src/flow/nodes/index.ts

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

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

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

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