@ersbeth/picoflow 1.0.1 → 1.1.0

package/dist/types/flow/nodes/async/flowNodeAsync.d.ts

@@ -0,0 +1,343 @@
+import { FlowSignal, FlowTracker } from '../../base';
+/**
+ * A versatile reactive node that can operate as mutable state or computed derivation, with asynchronous values.
+ *
+ * @typeParam T - The type of the value held by this node (not the Promise itself).
+ *
+ * @remarks
+ * FlowNodeAsync is a flexible reactive primitive that adapts its behavior based on how it's initialized.
+ * It extends {@link FlowSignal} and provides reactive value access with automatic dependency tracking.
+ * Unlike its synchronous counterpart {@link FlowNode}, FlowNodeAsync always works with `Promise<T>` values,
+ * making it suitable for asynchronous computations and data fetching.
+ *
+ * **Operating Modes:**
+ *
+ * - **Mutable State Mode**: When constructed with a constant Promise, FlowNodeAsync acts as a mutable
+ *   reactive state. You can update its value using `set()`, and all dependents are automatically
+ *   notified when the value changes. The value is always a Promise that resolves to type T.
+ *
+ * - **Computed Derivation Mode**: When constructed with a compute function, FlowNodeAsync acts as a
+ *   computed value that automatically tracks its dependencies. The compute function runs lazily
+ *   (only when the value is first accessed) and recomputes when any tracked dependency changes.
+ *   The compute function must return a `Promise<T>`. The computed value can be temporarily overridden
+ *   using `set()`, but the override is cleared on the next recomputation (triggered by dependency changes).
+ *
+ * **Asynchronous Nature:**
+ * All values in FlowNodeAsync 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:**
+ * When using a compute function, the computation doesn't run immediately upon construction. It
+ * executes only when:
+ * - The value is first read via `get()` or `pick()`
+ * - The node is watched via `watch()`
+ *
+ * **Dirty Tracking:**
+ * When a tracked dependency changes, the node is marked as "dirty" but doesn't recompute
+ * immediately. Recomputation happens lazily on the next value access, preventing unnecessary
+ * computations when multiple dependencies change in quick succession. The Promise is cached until
+ * dependencies change, ensuring efficient access patterns.
+ *
+ * **Dynamic Dependencies:**
+ * Dependencies are tracked dynamically during each computation. If the compute function
+ * conditionally tracks different observables, the dependency graph updates automatically.
+ *
+ * @example
+ * ```typescript
+ * // Mutable state mode
+ * const $count = new FlowNodeAsync(Promise.resolve(0));
+ * await $count.set(Promise.resolve(1)); // Updates the value
+ *
+ * // Computed derivation mode
+ * const $firstName = new FlowNodeAsync(Promise.resolve('John'));
+ * const $lastName = new FlowNodeAsync(Promise.resolve('Doe'));
+ * const $fullName = new FlowNodeAsync(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"
+ *
+ * // Temporarily override computed value
+ * await $fullName.set(Promise.resolve('Override'));
+ * console.log(await $fullName.pick()); // "Override"
+ *
+ * // Trigger recomputation (clears override)
+ * await $firstName.set(Promise.resolve('Jane'));
+ * console.log(await $fullName.pick()); // "Jane Doe" (override cleared)
+ * ```
+ *
+ * @public
+ */
+export declare class FlowNodeAsync<T> extends FlowSignal {
+    protected _promise?: Promise<T>;
+    private _dirty;
+    private _compute?;
+    /**
+     * Creates a new FlowNodeAsync.
+     *
+     * @param compute - Either a constant Promise or a compute function that derives the value.
+     *
+     * @remarks
+     * The constructor accepts two different initialization modes:
+     *
+     * - **Constant Promise**: Creates a mutable reactive node that can be updated via `set()`.
+     *   The Promise is stored immediately and can be changed at any time. The Promise resolves
+     *   to the value of type T.
+     *
+     * - **Compute function**: Creates a computed reactive node that automatically tracks dependencies
+     *   and recomputes when they change. The compute 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.
+     *   The computed value can be temporarily overridden using `set()`, but the override is cleared
+     *   on the next recomputation (triggered by dependency changes).
+     *
+     * @example
+     * ```typescript
+     * // Mutable state with constant Promise
+     * const $count = new FlowNodeAsync(Promise.resolve(0));
+     * await $count.set(Promise.resolve(5));
+     *
+     * // Computed derivation with async function
+     * const $a = new FlowNodeAsync(Promise.resolve(10));
+     * const $b = new FlowNodeAsync(Promise.resolve(20));
+     * const $sum = new FlowNodeAsync(async (t) => {
+     *   const a = await $a.get(t);
+     *   const b = await $b.get(t);
+     *   return a + b;
+     * });
+     *
+     * // Lazy evaluation - compute function hasn't run yet
+     * console.log(await $sum.pick()); // Now it computes: 30
+     * ```
+     *
+     * @public
+     */
+    constructor(compute: Promise<T> | ((t: FlowTracker) => Promise<T>));
+    get settled(): Promise<T> | undefined;
+    watch(tracker: FlowTracker): Promise<void>;
+    /**
+     * Gets the current value with dependency tracking.
+     *
+     * @param tracker - The tracking context for reactive tracking. This observable is registered
+     * as a dependency when accessed through this method.
+     *
+     * @returns A Promise that resolves to the current value of type T.
+     *
+     * @remarks
+     * Use `get(t)` within effects and derivations to create reactive dependencies. The tracker
+     * parameter must be provided from the reactive context (typically the `t` parameter in effect
+     * or derivation callbacks).
+     *
+     * **Important:** This method returns a `Promise<T>`, not `T`. You must await the Promise to
+     * get the actual value. The Promise is cached until dependencies change, ensuring efficient
+     * access patterns.
+     *
+     * To read a value without creating a dependency, use `pick()` instead.
+     *
+     * @example
+     * ```typescript
+     * effect(async (t) => {
+     *   const tracked = await $state.get(t);     // Dependency registered, await the Promise
+     *   const untracked = await $other.pick();   // No dependency
+     * });
+     * ```
+     *
+     * @throws Error if the node has been disposed.
+     *
+     * @public
+     */
+    get(tracker: FlowTracker | null): Promise<T>;
+    /**
+     * Updates the node with a new value.
+     *
+     * @param value - A new Promise or a callback function that computes a new Promise based on the current value.
+     *
+     * @returns A promise that resolves after the update is processed and all dependent effects have been notified.
+     *
+     * @remarks
+     * This method can be used in two ways:
+     *
+     * **For mutable state nodes** (constructed with a constant Promise):
+     * - Updates the stored Promise directly
+     * - All dependents are notified of the change
+     *
+     * **For computed nodes** (constructed with a compute function):
+     * - Temporarily overrides the computed value
+     * - The override persists until the next recomputation, which occurs when:
+     *   - A tracked dependency changes, or
+     *   - The node is refreshed
+     * - This allows temporarily overriding computed values for testing or manual control
+     *
+     * **Value Comparison:**
+     * The Promises are resolved and their values are compared. If the resolved new value is strictly
+     * equal (`===`) to the current resolved value, no update occurs and subscribers are not notified.
+     * This prevents unnecessary re-renders and effect executions.
+     *
+     * **Asynchronous Processing:**
+     * The update is processed asynchronously through the reactive graph, ensuring proper
+     * ordering of updates and effect execution. The method returns a Promise that resolves
+     * after the update is complete.
+     *
+     * @throws Error if the node has been disposed.
+     *
+     * @example
+     * ```typescript
+     * // Mutable state usage
+     * const $count = new FlowNodeAsync(Promise.resolve(0));
+     * await $count.set(Promise.resolve(5));
+     * await $count.set(async (current) => Promise.resolve(current + 1)); // 6
+     *
+     * // Temporary override of computed value
+     * const $source = new FlowNodeAsync(Promise.resolve(10));
+     * const $doubled = new FlowNodeAsync(async (t) => {
+     *   const val = await $source.get(t);
+     *   return val * 2;
+     * });
+     *
+     * console.log(await $doubled.pick()); // 20
+     *
+     * // Temporarily override
+     * await $doubled.set(Promise.resolve(50));
+     * console.log(await $doubled.pick()); // 50 (override active)
+     *
+     * // Dependency change clears override
+     * await $source.set(Promise.resolve(15));
+     * console.log(await $doubled.pick()); // 30 (recomputed, override cleared)
+     * ```
+     *
+     * @public
+     */
+    set(value: Promise<T> | ((current: T) => Promise<T>)): Promise<void>;
+    /**
+     * Forces recomputation of the value, even if it's not marked as dirty.
+     *
+     * @returns A promise that resolves after the recomputation is complete and all
+     * dependent effects have been notified.
+     *
+     * @remarks
+     * This method is useful when you need to force a recomputation of a computed value,
+     * for example when the computation depends on external data that has changed outside
+     * the reactive system.
+     *
+     * **Behavior:**
+     * - For nodes with a compute function: Forces the compute function to run again,
+     *   even if no dependencies have changed. This effectively clears any temporary
+     *   override that was set using `set()`.
+     * - For nodes without a compute function (mutable state): Recomputes the current
+     *   value (which is just the stored value), useful for consistency but typically
+     *   not necessary.
+     *
+     * The recomputation happens asynchronously through the reactive graph, ensuring
+     * proper ordering of updates and effect execution.
+     *
+     * @throws Error if the node has been disposed.
+     *
+     * @example
+     * ```typescript
+     * const $externalData = new FlowNode(() => fetchExternalData());
+     *
+     * // Some external event occurs that changes the data source
+     * externalDataChanged();
+     *
+     * // Force recomputation to get the new value
+     * await $externalData.refresh();
+     *
+     * // For computed nodes with temporary overrides
+     * const $computed = new FlowNode((t) => $source.get(t) * 2);
+     * $computed.set(100); // Temporary override
+     * await $computed.refresh(); // Clears override, recomputes from source
+     * ```
+     *
+     * @public
+     */
+    refresh(): Promise<void>;
+    /**
+     * Gets the current value without any dependency tracking.
+     *
+     * @returns A promise that resolves with the current value of type T.
+     *
+     * @remarks
+     * This method reads the value asynchronously through the reactive graph, ensuring proper ordering of
+     * read operations. Unlike `get(t)`, this method does not create a reactive dependency.
+     *
+     * **Important:** This is an async method that returns `Promise<T>`. Always use `await` when calling it.
+     *
+     * Use `pick()` when you want to read a snapshot of the current value without creating a reactive
+     * dependency. This is useful for:
+     * - Reading initial values outside reactive contexts
+     * - Accessing configuration that shouldn't trigger updates
+     * - Mixing tracked and untracked reads in the same effect
+     *
+     * @example
+     * ```typescript
+     * // Read a snapshot outside reactive context
+     * const currentValue = await $state.pick();
+     *
+     * // Mix tracked and untracked reads
+     * effect(async (t) => {
+     *   const tracked = await $reactive.get(t);    // Triggers re-runs
+     *   const snapshot = await $config.pick();    // Doesn't trigger re-runs
+     *   processData(tracked, snapshot);
+     * });
+     * ```
+     *
+     * @throws Error if the node has been disposed.
+     *
+     * @public
+     */
+    pick(): Promise<T>;
+    /**
+     * Subscribes a listener function to changes of this node.
+     *
+     * @param listener - A callback function that receives the new value whenever it changes.
+     *
+     * @returns A disposer function that cancels the subscription when called.
+     *
+     * @remarks
+     * This method creates a reactive subscription that automatically tracks this node as a dependency.
+     * The listener is executed:
+     * - Immediately with the current value when the subscription is created
+     * - Automatically whenever the value changes
+     *
+     * **Important:** The listener receives a `Promise<T>`, not `T`. You must await the Promise
+     * within the listener to access the actual value. The Promise is the same one returned by `get()`,
+     * so it's cached until dependencies change.
+     *
+     * The subscription uses a {@link FlowEffect} internally to manage the reactive tracking and
+     * automatic re-execution. When the value changes, the listener is called with the new Promise
+     * after the update is processed through the reactive graph.
+     *
+     * **Cleanup:**
+     * Always call the returned disposer function when you no longer need the subscription to
+     * prevent memory leaks and unnecessary computations.
+     *
+     * @example
+     * ```typescript
+     * const $count = new FlowNodeAsync(Promise.resolve(0));
+     *
+     * // Subscribe to changes
+     * const unsubscribe = $count.subscribe(async (valuePromise) => {
+     *   const value = await valuePromise;
+     *   console.log(`Count is now: ${value}`);
+     * });
+     * // Logs immediately: "Count is now: 0"
+     *
+     * await $count.set(Promise.resolve(5));
+     * // Logs: "Count is now: 5"
+     *
+     * // Clean up when done
+     * unsubscribe();
+     * ```
+     *
+     * @throws Error if the node has been disposed.
+     *
+     * @public
+     */
+    subscribe(listener: (value: Promise<T>) => void): () => void;
+    private _computeValue;
+}
+//# sourceMappingURL=flowNodeAsync.d.ts.map

package/dist/types/flow/nodes/async/flowNodeAsync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flowNodeAsync.d.ts","sourceRoot":"","sources":["../../../../../src/flow/nodes/async/flowNodeAsync.ts"],"names":[],"mappings":"AAAA,OAAO,EAGN,UAAU,EACV,KAAK,WAAW,EAChB,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwEG;AACH,qBAAa,aAAa,CAAC,CAAC,CAAE,SAAQ,UAAU;IAC/C,SAAS,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IAChC,OAAO,CAAC,MAAM,CAAQ;IACtB,OAAO,CAAC,QAAQ,CAAC,CAAiC;IAElD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAuCG;gBACS,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IAUlE,IAAI,OAAO,2BAEV;IAEc,KAAK,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAOzD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACG,GAAG,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,GAAG,OAAO,CAAC,CAAC,CAAC;IAOlD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2DG;IACG,GAAG,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IA4B1E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAyCG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAwB9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACG,IAAI,IAAI,OAAO,CAAC,CAAC,CAAC;IAMxB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8CG;IACH,SAAS,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,MAAM,IAAI;YAkB9C,aAAa;CA8B3B"}

package/dist/types/flow/nodes/async/flowReadonlyAsync.d.ts

@@ -0,0 +1,81 @@
+import { FlowNodeAsync } from './flowNodeAsync';
+/**
+ * A generic utility type for creating read-only views of reactive nodes, with asynchronous values.
+ *
+ * @typeParam T - The type of the value held by the reactive node (not the Promise itself).
+ *
+ * @remarks
+ * `FlowReadonlyAsync` is a type alias based on {@link FlowNodeAsync} with the `set()` and `refresh()`
+ * methods removed, making it a read-only view. It provides all the reactive capabilities of `FlowNodeAsync`
+ * (dependency tracking, lazy computation, caching, reading values) but prevents mutation.
+ *
+ * **Asynchronous Nature:**
+ * All values in FlowReadonlyAsync 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.
+ *
+ * **Difference from FlowConstantAsync and FlowDerivationAsync:**
+ * - {@link FlowConstantAsync}: Specialized type for immutable constants that compute once and never change
+ * - {@link FlowDerivationAsync}: Specialized type for computed values that automatically recompute when dependencies change
+ * - `FlowReadonlyAsync`: Generic utility type that can be used with any `FlowNodeAsync` to create a read-only view
+ *
+ * **Use Cases:**
+ * - **Type Safety**: Ensure functions don't accidentally mutate state by accepting `FlowReadonlyAsync` instead of `FlowStateAsync`
+ * - **API Design**: Expose read-only views of internal state to prevent external mutation
+ * - **Function Parameters**: Accept any reactive node (state, derivation, constant) but prevent mutation
+ * - **Composition**: Create read-only wrappers around mutable states for safer sharing
+ *
+ * @example
+ * ```typescript
+ * // Type safety: Function that only reads state
+ * function displayCount(count: FlowReadonlyAsync<number>) {
+ *   // count.set(Promise.resolve(100)); // TypeScript error: Property 'set' does not exist
+ *   effect(async (t) => {
+ *     const value = await count.get(t); // OK: Reading is allowed
+ *     console.log(value);
+ *   });
+ * }
+ *
+ * const $count = stateAsync(Promise.resolve(0));
+ * displayCount($count); // OK: FlowStateAsync is assignable to FlowReadonlyAsync
+ *
+ * // API design: Expose read-only view
+ * class Counter {
+ *   private _count = stateAsync(Promise.resolve(0));
+ *
+ *   get count(): FlowReadonlyAsync<number> {
+ *     return this._count; // FlowStateAsync is assignable to FlowReadonlyAsync
+ *   }
+ *
+ *   async increment() {
+ *     await this._count.set(async (current) => Promise.resolve(current + 1)); // Internal mutation allowed
+ *   }
+ * }
+ *
+ * const counter = new Counter();
+ * // counter.count.set(Promise.resolve(100)); // TypeScript error: Cannot mutate read-only view
+ * const current = await counter.count.pick(); // OK: Reading is allowed
+ *
+ * // Works with derivations too
+ * 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}`;
+ * });
+ *
+ * function displayName(name: FlowReadonlyAsync<string>) {
+ *   effect(async (t) => {
+ *     const fullName = await name.get(t);
+ *     console.log(fullName);
+ *   });
+ * }
+ *
+ * displayName($fullName); // OK: FlowDerivationAsync is assignable to FlowReadonlyAsync
+ * ```
+ *
+ * @public
+ */
+export type FlowReadonlyAsync<T> = Omit<FlowNodeAsync<T>, "set" | "refresh">;
+//# sourceMappingURL=flowReadonlyAsync.d.ts.map

package/dist/types/flow/nodes/async/flowReadonlyAsync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flowReadonlyAsync.d.ts","sourceRoot":"","sources":["../../../../../src/flow/nodes/async/flowReadonlyAsync.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6EG;AACH,MAAM,MAAM,iBAAiB,CAAC,CAAC,IAAI,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,KAAK,GAAG,SAAS,CAAC,CAAC"}

package/dist/types/flow/nodes/async/flowStateAsync.d.ts

@@ -0,0 +1,111 @@
+import { FlowNodeAsync } from './flowNodeAsync';
+/**
+ * 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
+ * `FlowStateAsync` is a type alias of {@link FlowNodeAsync}, providing a mutable reactive state that can be
+ * updated using the `set()` method. It provides all the reactive capabilities of `FlowNodeAsync`
+ * (lazy computation, caching) with the ability to mutate the value.
+ *
+ * Unlike {@link FlowConstantAsync}, which is immutable and computes once, states can be updated at any
+ * time. Unlike {@link FlowDerivationAsync}, which recomputes when dependencies change, states are
+ * updated explicitly via `set()`.
+ *
+ * **Asynchronous Nature:**
+ * All values in FlowStateAsync are Promises. When you call `get()` or `pick()`, you receive a
+ * `Promise<T>` that you must await to get the actual value. The `set()` method returns `Promise<void>`
+ * and must be awaited. This allows for seamless integration with async/await patterns and asynchronous
+ * data sources.
+ *
+ * **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). Both methods return `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 = stateAsync(Promise.resolve(0));
+ *
+ * // Read with tracking
+ * effect(async (t) => {
+ *   const value = await $count.get(t); // Effect re-runs when $count changes
+ *   console.log(value);
+ * });
+ *
+ * // Read without tracking
+ * const snapshot = await $count.pick();
+ *
+ * // Update the value
+ * await $count.set(Promise.resolve(1));
+ * await $count.set(async (current) => Promise.resolve(current + 1));
+ * ```
+ *
+ * @public
+ */
+export type FlowStateAsync<T> = Omit<FlowNodeAsync<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.
+ *
+ * @returns A new instance of {@link FlowStateAsync} 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 (both return `Promise<T>`).
+ *
+ * **Asynchronous Nature:**
+ * All values are Promises. When you access the state via `get(t)` or `pick()`, you receive a
+ * `Promise<T>` that you must await to get the actual value. The `set()` method also returns
+ * `Promise<void>` and must be awaited. This allows for seamless integration with async/await
+ * patterns and asynchronous data sources.
+ *
+ * **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 `stateAsync()` for mutable values that can be updated directly
+ * - Use `constantAsync()` for values that compute once and never change
+ * - Use `derivationAsync()` for values that recompute when dependencies change
+ *
+ * @example
+ * ```typescript
+ * // Direct Promise - initialized immediately
+ * const $count = stateAsync(Promise.resolve(0));
+ *
+ * // Lazy initialization - computed on first access
+ * const $config = stateAsync(async () => {
+ *   return await loadConfiguration();
+ * });
+ *
+ * effect(async (t) => {
+ *   const value = await $count.get(t);
+ *   console.log(value);
+ * });
+ *
+ * await $count.set(Promise.resolve(1)); // Logs: 1
+ * await $count.set(async (current) => Promise.resolve(current + 1)); // Logs: 2
+ * ```
+ *
+ * @public
+ */
+export declare function stateAsync<T>(value: Promise<T> | (() => Promise<T>)): FlowStateAsync<T>;
+//# sourceMappingURL=flowStateAsync.d.ts.map

package/dist/types/flow/nodes/async/flowStateAsync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flowStateAsync.d.ts","sourceRoot":"","sources":["../../../../../src/flow/nodes/async/flowStateAsync.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,MAAM,MAAM,cAAc,CAAC,CAAC,IAAI,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;AAElE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAC3B,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,OAAO,CAAC,CAAC,CAAC,CAAC,GACpC,cAAc,CAAC,CAAC,CAAC,CAEnB"}

package/dist/types/flow/nodes/async/index.d.ts

@@ -0,0 +1,6 @@
+export * from './flowConstantAsync';
+export * from './flowDerivationAsync';
+export * from './flowNodeAsync';
+export * from './flowReadonlyAsync';
+export * from './flowStateAsync';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/flow/nodes/async/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/flow/nodes/async/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC;AACpC,cAAc,kBAAkB,CAAC"}

package/dist/types/flow/nodes/index.d.ts

@@ -0,0 +1,3 @@
+export * from './async';
+export * from './sync';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/flow/nodes/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/flow/nodes/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,QAAQ,CAAC"}

package/dist/types/flow/nodes/sync/flowConstant.d.ts

@@ -0,0 +1,108 @@
+import { 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 declare function constant<T>(value: () => NotPromise<T>): FlowConstant<T>;
+//# sourceMappingURL=flowConstant.d.ts.map

package/dist/types/flow/nodes/sync/flowConstant.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flowConstant.d.ts","sourceRoot":"","sources":["../../../../../src/flow/nodes/sync/flowConstant.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEtC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,KAAK,GAAG,SAAS,CAAC,CAAC;AAEnE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC,CAAC,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC,CAEvE"}