@ersbeth/picoflow 1.0.0 → 1.1.0

package/src/{advanced → flow/nodes/await/advanced}/resource.ts

@@ -1,4 +1,4 @@
-import { FlowObservable } from "../basic";
+import { FlowObservableAsync } from "../async";
 
 /**
  * Represents a reactive resource that asynchronously fetches its value and returns `T | undefined`.
@@ -53,7 +53,7 @@ import { FlowObservable } from "../basic";
  *
  * @public
  */
-export class FlowResource<T> extends FlowObservable<T | undefined> {
+export class FlowResource<T> extends FlowObservableAsync<T | undefined> {
 	/**
 	 * Creates a new FlowResource.
 	 *
@@ -91,10 +91,44 @@ export class FlowResource<T> extends FlowObservable<T | undefined> {
 		const value = await this._fetch();
 		if (value === this._value) return;
 		this._value = value;
-		this._notify();
+		this.trigger();
 	}
 
 	/* INTERNAL ------------------------------------------------ */
 
 	private _fetch: () => Promise<T>;
 }
+
+/**
+ * Creates a new reactive resource that asynchronously fetches its value, returning `T | undefined`.
+ *
+ * @typeParam T - The type of the resource value.
+ * @param fn - An asynchronous function that fetches the resource value.
+ * @returns A new instance of {@link FlowResource}.
+ *
+ * @remarks
+ * A resource manages async data fetching with reactive updates. Unlike {@link resourceAsync},
+ * this returns the resolved value directly (or `undefined` if not fetched yet), making it
+ * easier to work with in synchronous contexts. Call `fetch()` to trigger the async operation.
+ *
+ * @example
+ * ```typescript
+ * const $user = resource(() => fetch('/api/user').then(r => r.json()));
+ *
+ * // Trigger fetch
+ * await $user.fetch();
+ *
+ * // Use in effect
+ * effect((t) => {
+ *   const user = $user.get(t);
+ *   if (user) {
+ *     console.log(user.name);
+ *   }
+ * });
+ * ```
+ *
+ * @public
+ */
+export function resource<T>(fn: () => Promise<T>): FlowResource<T> {
+	return new FlowResource(fn);
+}

package/src/{advanced → flow/nodes/await/advanced}/resourceAsync.ts

@@ -1,4 +1,4 @@
-import { FlowObservable } from "../basic/";
+import { FlowObservableAsync } from "../async";
 
 /**
  * Represents a reactive resource that asynchronously fetches its value and always returns a Promise.
@@ -35,7 +35,7 @@ import { FlowObservable } from "../basic/";
  *
  * @public
  */
-export class FlowResourceAsync<T> extends FlowObservable<Promise<T>> {
+export class FlowResourceAsync<T> extends FlowObservableAsync<Promise<T>> {
 	/**
 	 * Creates a new FlowResource.
 	 * @param fetch - An asynchronous function that retrieves the resource's value.
@@ -68,10 +68,42 @@ export class FlowResourceAsync<T> extends FlowObservable<Promise<T>> {
 	public async fetch(): Promise<void> {
 		if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
 		this._value = this._fetch();
-		this._notify();
+		this.trigger();
 	}
 
 	/* INTERNAL ------------------------------------------------ */
 
 	private _fetch: () => Promise<T>;
 }
+
+/**
+ * Creates a new reactive asynchronous resource that always returns a Promise.
+ *
+ * @typeParam T - The type of the resource value.
+ * @param fn - An asynchronous function that fetches the resource value.
+ * @returns A new instance of {@link FlowResourceAsync}.
+ *
+ * @remarks
+ * An async resource manages async data fetching and always returns a Promise, making it
+ * ideal for async/await patterns. Unlike {@link resource}, the Promise is created lazily
+ * on first access and cached. Call `fetch()` to create a new Promise and trigger a refetch.
+ *
+ * @example
+ * ```typescript
+ * const $data = resourceAsync(() => fetch('/api/data').then(r => r.json()));
+ *
+ * // Use with async/await
+ * effect(async (t) => {
+ *   const data = await $data.get(t);
+ *   console.log(data);
+ * });
+ *
+ * // Refetch
+ * await $data.fetch();
+ * ```
+ *
+ * @public
+ */
+export function resourceAsync<T>(fn: () => Promise<T>): FlowResourceAsync<T> {
+	return new FlowResourceAsync(fn);
+}

package/src/{advanced → flow/nodes/await/advanced}/stream.ts

@@ -1,4 +1,4 @@
-import { FlowObservable } from "../basic/";
+import { FlowObservable } from "../sync";
 
 /**
  * A function type that sets a new value for the reactive stream.
@@ -145,6 +145,44 @@ export class FlowStream<T> extends FlowObservable<T | undefined> {
 		if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
 		if (value === this._value) return;
 		this._value = value;
-		this._notify();
+		this.trigger();
 	}
 }
+
+/**
+ * Creates a new reactive stream that bridges external event sources with PicoFlow's reactive system.
+ *
+ * @typeParam T - The type of the stream value.
+ * @param updater - A function that receives a setter to update the stream's value.
+ * It should return a disposer function to clean up resources.
+ * @returns A new instance of {@link FlowStream}.
+ *
+ * @remarks
+ * Streams are ideal for integrating push-based data sources like WebSockets, DOM events,
+ * timers, or any event emitter. The updater sets up subscriptions and calls the setter
+ * when new data arrives. The returned disposer is called on cleanup.
+ *
+ * @example
+ * ```typescript
+ * // WebSocket stream
+ * const $messages = stream<string>((set) => {
+ *   const ws = new WebSocket('ws://example.com');
+ *   ws.onmessage = (e) => set(e.data);
+ *   return () => ws.close();
+ * });
+ *
+ * // Timer stream
+ * const $tick = stream<number>((set) => {
+ *   let count = 0;
+ *   const id = setInterval(() => set(count++), 1000);
+ *   return () => clearInterval(id);
+ * });
+ * ```
+ *
+ * @public
+ */
+export function stream<T>(
+	updater: (set: (value: T) => void) => () => void,
+): FlowStream<T> {
+	return new FlowStream(updater);
+}

package/src/{advanced → flow/nodes/await/advanced}/streamAsync.ts

@@ -1,4 +1,4 @@
-import { FlowObservable } from "../basic";
+import { FlowObservable } from "../sync";
 import type { FlowStreamDisposer, FlowStreamUpdater } from "./stream";
 
 /**
@@ -128,7 +128,7 @@ export class FlowStreamAsync<T> extends FlowObservable<Promise<T>> {
 			this._resolve(value);
 			this._initialized = true;
 			this._awaitedValue = value;
-			this._notify();
+			this.trigger();
 			return;
 		}
 
@@ -136,6 +136,41 @@ export class FlowStreamAsync<T> extends FlowObservable<Promise<T>> {
 
 		this._value = Promise.resolve(value);
 		this._awaitedValue = value;
-		this._notify();
+		this.trigger();
 	}
 }
+
+/**
+ * Creates a new reactive asynchronous stream that always returns a Promise.
+ *
+ * @typeParam T - The type of the stream value.
+ * @param updater - A function that receives a setter to update the stream's value.
+ * It should return a disposer function to clean up resources.
+ * @returns A new instance of {@link FlowStreamAsync}.
+ *
+ * @remarks
+ * Async streams are ideal for push-based async data sources where you want to use async/await.
+ * Unlike {@link stream}, this always returns a Promise that resolves to the value. The initial
+ * Promise is created on construction and resolves when the setter is first called.
+ *
+ * @example
+ * ```typescript
+ * const $asyncMessages = streamAsync<string>((set) => {
+ *   const ws = new WebSocket('ws://example.com');
+ *   ws.onmessage = (e) => set(e.data);
+ *   return () => ws.close();
+ * });
+ *
+ * effect(async (t) => {
+ *   const message = await $asyncMessages.get(t);
+ *   console.log('Received:', message);
+ * });
+ * ```
+ *
+ * @public
+ */
+export function streamAsync<T>(
+	updater: (set: (value: T) => void) => () => void,
+): FlowStreamAsync<T> {
+	return new FlowStreamAsync(updater);
+}

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

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

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