@ersbeth/picoflow 1.1.1 → 2.0.0

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

@@ -1,154 +0,0 @@
-import { FlowNodeAwait } from "./flowNodeAwait";
-
-/**
- * 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
- * `FlowConstantAwait` is a type alias based on {@link FlowNodeAwait} with the `set()` and `refresh()`
- * methods removed, making it immutable. It provides all the reactive capabilities of `FlowNodeAwait`
- * (lazy computation, caching, dependency tracking) but prevents value mutation after initialization.
- *
- * Unlike {@link FlowStateAwait}, 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.
- *
- * **Key Difference from FlowConstantAsync:**
- * Unlike {@link FlowConstantAsync}, which returns Promises from `get()`, FlowConstantAwait 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:**
- * FlowConstantAwait 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 permanently.
- *
- * **Lazy Computation:**
- * Constants are created using the `constantAwait()` 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 resolved internally.
- *   The resolved value is cached and can be accessed synchronously via `get()`.
- * - **Lazy initialization**: Pass a function `() => Promise<T>`; it's called only when the value
- *   is first accessed via `get()` or `pick()`. The Promise is awaited internally and the resolved
- *   value is cached. This is useful for expensive async operations that may not be needed immediately.
- *
- * **Caching:**
- * Once computed (either immediately or lazily), the resolved 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 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 = constantAwait(Promise.resolve({ apiUrl: 'https://api.example.com' }));
- * const config = await $config.pick(); // Async - returns Promise
- * const configValue = $config.get(t); // Synchronous - returns resolved value
- *
- * // Lazy initialization - computed on first access
- * const $expensiveValue = constantAwait(async () => {
- *   console.log('Computing...');
- *   return await performExpensiveAsyncCalculation();
- * });
- *
- * // First access triggers computation
- * const value1 = await $expensiveValue.pick(); // Logs: "Computing..."
- *
- * // Subsequent accesses return cached value
- * const value2 = $expensiveValue.get(t); // Synchronous - returns cached value, no log
- *
- * // Value cannot be changed (set() method is not available)
- * // $expensiveValue.set(Promise.resolve(100)); // TypeScript error: Property 'set' does not exist
- * ```
- *
- * @public
- */
-export type FlowConstantAwait<T> = Omit<FlowNodeAwait<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 FlowConstantAwait} 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 `stateAwait()`), constants cannot be modified after initialization - they don't
- * have a `set()` method.
- *
- * **Asynchronous Nature:**
- * FlowConstantAwait 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 permanently.
- *
- * **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 `constantAwait()` for values that should never change after initialization
- * - Use `stateAwait()` for mutable values that can be updated
- * - Use `derivationAwait()` for values that recompute when dependencies change
- *
- * @example
- * ```typescript
- * // Eager initialization with Promise
- * const $config = constantAwait(Promise.resolve({
- *   apiUrl: 'https://api.example.com'
- * }));
- * const config = await $config.pick(); // Async - returns Promise
- *
- * // Lazy initialization with async function
- * const $expensiveValue = constantAwait(async () => {
- *   return await loadConfigurationFromFile();
- * });
- *
- * // Computation hasn't run yet
- * // First access triggers it
- * const value = await $expensiveValue.pick(); // Async - ensures value is resolved
- *
- * // Subsequent accesses return cached value
- * const value2 = $expensiveValue.get(t); // Synchronous - returns cached value
- *
- * // Use in reactive context
- * effect((t) => {
- *   const cfg = $config.get(t); // Synchronous - returns resolved value
- *   console.log(`API URL: ${cfg.apiUrl}`);
- * });
- * ```
- *
- * @public
- */
-export function constantAwait<T>(
-	value: Promise<T> | (() => Promise<T>),
-): FlowConstantAwait<T> {
-	return new FlowNodeAwait(value);
-}

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

@@ -1,154 +0,0 @@
-import type { FlowTracker } from "../../base";
-import { FlowNodeAwait } from "./flowNodeAwait";
-/**
- * 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
- * `FlowDerivationAwait` is a type alias based on {@link FlowNodeAwait} with the `set()` method removed,
- * making it immutable. It provides all the reactive capabilities of `FlowNodeAwait` (dependency tracking,
- * lazy computation, caching) but prevents value mutation after initialization.
- *
- * Unlike {@link FlowConstantAwait}, 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.
- *
- * **Key Difference from FlowDerivationAsync:**
- * Unlike {@link FlowDerivationAsync}, which returns Promises from `get()`, FlowDerivationAwait 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:**
- * FlowDerivationAwait 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.
- *
- * **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 resolved value 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 await node dependencies via `.get(t)`, the value is returned synchronously (no await needed).
- * The compute function must return a `Promise<T>` which is awaited internally.
- *
- * @example
- * ```typescript
- * 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}`;
- * });
- *
- * // 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 FlowDerivationAwait<T> = Omit<FlowNodeAwait<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 FlowDerivationAwait} 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:**
- * FlowDerivationAwait 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.
- * - Within the compute function, when accessing await node dependencies via `.get(t)`, the value
- *   is returned synchronously (no await needed). This makes the code cleaner and easier to read.
- * - The compute function must return a `Promise<T>` which is awaited internally.
- *
- * **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 `derivationAwait()` for values that should recompute when dependencies change
- * - Use `constantAwait()` for values that compute once and never change
- * - Use `stateAwait()` for mutable values that can be updated directly
- *
- * @example
- * ```typescript
- * 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}`;
- * });
- *
- * // Use in reactive context
- * effect((t) => {
- *   const name = $fullName.get(t); // Synchronous - returns resolved value
- *   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 = stateAwait(Promise.resolve(1));
- * const $user = derivationAwait(async (t) => {
- *   const id = $userId.get(t); // Synchronous - returns resolved value
- *   return await fetchUser(id); // Still need await for external async operations
- * });
- * ```
- *
- * @public
- */
-export function derivationAwait<T>(
-	fn: (t: FlowTracker) => Promise<T>,
-): FlowDerivationAwait<T> {
-	return new FlowNodeAwait(fn);
-}