@ersbeth/picoflow 1.1.1 → 2.0.0

package/src/flow/nodes/await/advanced/resource.ts

@@ -1,134 +0,0 @@
-import { FlowObservableAsync } from "../async";
-
-/**
- * Represents a reactive resource that asynchronously fetches its value and returns `T | undefined`.
- *
- * @remarks
- * FlowResource extends FlowObservable to manage asynchronous data fetching with reactive updates.
- * Unlike {@link FlowResourceAsync} which always returns a Promise, FlowResource returns the resolved
- * value directly (or `undefined` if not yet fetched), making it more convenient for synchronous access
- * patterns in effects and derivations.
- *
- * **Key Characteristics:**
- * - The value is `undefined` initially, before the first fetch
- * - Call `fetch()` to trigger the asynchronous fetch operation
- * - When fetched, the value is compared to the current value; only different values trigger updates
- * - Reading via `get(t)` or `pick()` returns the current value (possibly `undefined`) without triggering a fetch
- *
- * **Fetch Behavior:**
- * The fetch function is NOT called automatically on construction. You must explicitly call the
- * `fetch()` method to retrieve the resource. This gives you control over when network requests
- * or expensive async operations occur.
- *
- * **Use Cases:**
- * - API data fetching where you want synchronous access to the cached value
- * - Lazy-loaded data that shouldn't fetch on construction
- * - Resources that need manual refresh control
- * - Data that may or may not be available (hence `T | undefined`)
- *
- * @example
- * ```typescript
- * const $user = resource(() => fetchUserFromAPI());
- *
- * // Initially undefined
- * console.log($user.pick()); // undefined
- *
- * // Trigger the fetch
- * await $user.fetch();
- * console.log($user.pick()); // { id: 1, name: 'John' }
- *
- * // Use in an effect
- * effect((t) => {
- *   const user = $user.get(t);
- *   if (user) {
- *     console.log(`Hello, ${user.name}`);
- *   }
- * });
- *
- * // Refetch to update
- * await $user.fetch();
- * ```
- *
- * @typeParam T - The type of the resource value (not including the undefined case).
- *
- * @public
- */
-export class FlowResource<T> extends FlowObservableAsync<T | undefined> {
-	/**
-	 * Creates a new FlowResource.
-	 *
-	 * @param fetch - An asynchronous function that retrieves the resource's value.
-	 * This function is not invoked on construction; you must call the `fetch()` method
-	 * to execute it.
-	 *
-	 * @public
-	 */
-	constructor(fetch: () => Promise<T>) {
-		super();
-		this._fetch = fetch;
-	}
-
-	/**
-	 * Internal method to get the raw value.
-	 * @internal
-	 */
-	protected _getRaw(): T | undefined {
-		if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-		return this._value;
-	}
-
-	/**
-	 * Asynchronously fetches a new value for the resource.
-	 * @remarks
-	 * Executes the internal fetch function. If the fetched value differs from the current one,
-	 * updates the resource's value and notifies subscribers.
-	 * @returns A Promise that resolves when the fetch operation is complete.
-	 * @throws Error if the resource is disposed.
-	 * @public
-	 */
-	public async fetch(): Promise<void> {
-		if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-		const value = await this._fetch();
-		if (value === this._value) return;
-		this._value = value;
-		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/flow/nodes/await/advanced/resourceAsync.ts

@@ -1,109 +0,0 @@
-import { FlowObservableAsync } from "../async";
-
-/**
- * Represents a reactive resource that asynchronously fetches its value and always returns a Promise.
- *
- * @remarks
- * FlowResourceAsync extends FlowObservable and encapsulates an asynchronous fetch function.
- * Unlike {@link FlowResource} which returns `T | undefined`, FlowResourceAsync always returns
- * a `Promise<T>`, making it suitable for async/await patterns.
- *
- * **Key Characteristics:**
- * - The first call to `get()` or `pick()` creates and caches a Promise
- * - Subsequent calls return the same Promise until `fetch()` is called
- * - Calling `fetch()` creates a new Promise and notifies subscribers
- * - The Promise resolves to the fetched value of type T
- *
- * **Lazy Promise Creation:**
- * The fetch function doesn't execute until the resource's value is first accessed.
- * This allows you to define resources without immediately triggering network requests.
- *
- * @example
- * ```typescript
- * const $user = resourceAsync(() => fetchUserFromAPI());
- *
- * effect(async (t) => {
- *   const user = await $user.get(t);  // Tracked, effect re-runs on fetch()
- *   console.log(user.name);
- * });
- *
- * // Trigger a refetch
- * await $user.fetch();
- * ```
- *
- * @typeParam T - The type of the resource value (not the Promise itself).
- *
- * @public
- */
-export class FlowResourceAsync<T> extends FlowObservableAsync<Promise<T>> {
-	/**
-	 * Creates a new FlowResource.
-	 * @param fetch - An asynchronous function that retrieves the resource's value.
-	 * @public
-	 */
-	constructor(fetch: () => Promise<T>) {
-		super();
-		this._fetch = fetch;
-	}
-
-	/**
-	 * Internal method to get the raw value.
-	 * @internal
-	 */
-	protected _getRaw(): Promise<T> {
-		if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-		if (!this._value) this._value = this._fetch();
-		return this._value;
-	}
-
-	/**
-	 * Asynchronously fetches a new value for the resource.
-	 * @remarks
-	 * Executes the internal fetch function. If the fetched value differs from the current one,
-	 * updates the resource's value and notifies subscribers.
-	 * @returns A Promise that resolves when the fetch operation is complete.
-	 * @throws Error if the resource is disposed.
-	 * @public
-	 */
-	public async fetch(): Promise<void> {
-		if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-		this._value = this._fetch();
-		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/flow/nodes/await/advanced/stream.ts

@@ -1,188 +0,0 @@
-import { FlowObservable } from "../sync";
-
-/**
- * A function type that sets a new value for the reactive stream.
- * @typeParam T - The type of the value.
- * @public
- */
-export type FlowStreamSetter<T> = (value: T) => void;
-
-/**
- * A function type that disposes of a resource.
- * @public
- */
-export type FlowStreamDisposer = () => void;
-
-/**
- * A function type that updates a stream and returns a disposer for cleanup.
- * @remarks
- * The updater receives a setter function to update the stream's value.
- * It should return a disposer function to release any resources or subscriptions.
- * @typeParam T - The type of the stream value.
- * @public
- */
-export type FlowStreamUpdater<T> = (
-	set: FlowStreamSetter<T>,
-) => FlowStreamDisposer;
-
-/**
- * Represents a reactive stream that updates its value based on an external updater function.
- *
- * @remarks
- * FlowStream extends FlowObservable to bridge external event sources with PicoFlow's reactive
- * system. It's designed for integrating with event emitters, WebSocket connections, timers,
- * or any push-based data source that sends updates over time.
- *
- * **How It Works:**
- * 1. You provide an updater function that receives a setter callback
- * 2. The updater sets up subscriptions to external events and calls the setter with new values
- * 3. When the setter is called, the stream notifies all dependent effects and derivations
- * 4. The updater returns a disposer function for cleanup
- *
- * **Initial Value:**
- * The stream's value is `undefined` until the first time the setter is called. This allows
- * you to check if any data has been received yet.
- *
- * **Change Detection:**
- * The stream only notifies subscribers when the new value differs from the current value
- * (using strict equality `===`). This prevents unnecessary updates for duplicate values.
- *
- * **Resource Management:**
- * The disposer function returned by your updater is automatically called when the stream
- * is disposed. Use it to clean up subscriptions, close connections, or clear timers.
- *
- * **Use Cases:**
- * - WebSocket message streams
- * - DOM event listeners
- * - setInterval/setTimeout timers
- * - Server-sent events (SSE)
- * - Observable subscriptions from other libraries
- * - Any push-based data source
- *
- * @example
- * ```typescript
- * // WebSocket stream
- * const $messages = stream<string>((set) => {
- *   const ws = new WebSocket('ws://example.com');
- *   ws.onmessage = (event) => set(event.data);
- *   return () => ws.close();
- * });
- *
- * // Timer stream
- * const $tick = stream<number>((set) => {
- *   let count = 0;
- *   const id = setInterval(() => set(count++), 1000);
- *   return () => clearInterval(id);
- * });
- *
- * // DOM event stream
- * const $clicks = stream<MouseEvent>((set) => {
- *   const handler = (e: MouseEvent) => set(e);
- *   document.addEventListener('click', handler);
- *   return () => document.removeEventListener('click', handler);
- * });
- *
- * // Use in an effect
- * effect((t) => {
- *   const message = $messages.get(t);
- *   if (message) {
- *     console.log('Received:', message);
- *   }
- * });
- * ```
- *
- * @typeParam T - The type of the values emitted by the stream.
- * @public
- */
-export class FlowStream<T> extends FlowObservable<T | undefined> {
-	/**
-	 * Creates a new FlowStream.
-	 *
-	 * @param updater - A function that receives a setter callback and returns a disposer.
-	 * The setter should be called whenever new data is available. The disposer will be
-	 * invoked when the stream is disposed to clean up resources.
-	 *
-	 * @remarks
-	 * The updater is invoked immediately during construction. Make sure to return a proper
-	 * cleanup function to avoid resource leaks.
-	 *
-	 * @public
-	 */
-	constructor(updater: FlowStreamUpdater<T>) {
-		super();
-		this._disposer = updater((value: T) => {
-			this._set(value);
-		});
-	}
-
-	/**
-	 * Internal method to get the raw value.
-	 * @internal
-	 */
-	protected _getRaw(): T | undefined {
-		if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-		return this._value;
-	}
-
-	/**
-	 * Disposes the stream, releasing all resources.
-	 * @remarks
-	 * In addition to disposing the underlying observable, this method calls the disposer
-	 * returned by the updater.
-	 * @public
-	 */
-	public override dispose(): void {
-		super.dispose();
-		this._disposer();
-	}
-
-	/* INTERNAL ------------------------------------------------------ */
-
-	private _disposer: FlowStreamDisposer;
-
-	private _set(value: T): void {
-		/* v8 ignore next */
-		if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-		if (value === this._value) return;
-		this._value = value;
-		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/flow/nodes/await/advanced/streamAsync.ts

@@ -1,176 +0,0 @@
-import { FlowObservable } from "../sync";
-import type { FlowStreamDisposer, FlowStreamUpdater } from "./stream";
-
-/**
- * Represents an asynchronous reactive stream that always returns a Promise and updates based on an updater function.
- *
- * @remarks
- * FlowStreamAsync extends FlowObservable to bridge external async event sources with PicoFlow's
- * reactive system. Unlike {@link FlowStream} which returns `T | undefined`, FlowStreamAsync always
- * returns a `Promise<T>`, making it suitable for use with async/await patterns.
- *
- * **How It Works:**
- * 1. On construction, creates an initial Promise that resolves when the first value arrives
- * 2. Your updater function receives a setter callback and sets up event subscriptions
- * 3. When the setter is called with a value, the Promise resolves (first call) or a new Promise is created (subsequent calls)
- * 4. The updater returns a disposer function for cleanup
- *
- * **Promise Behavior:**
- * - **First call to setter**: Resolves the initial Promise created at construction
- * - **Subsequent calls**: Creates a new `Promise.resolve(value)` for immediate resolution
- * - **Reading the value**: Always returns a Promise, either pending (initial) or resolved
- *
- * **Change Detection:**
- * After the first value is set, the stream only notifies subscribers when the new value
- * differs from the previous value (using strict equality `===`). This prevents unnecessary
- * updates for duplicate values.
- *
- * **Resource Management:**
- * The disposer function returned by your updater is automatically called when the stream
- * is disposed. Use it to clean up subscriptions, close connections, or clear timers.
- *
- * **Use Cases:**
- * - Async WebSocket message streams
- * - Server-sent events that you want to await
- * - Async event handlers
- * - Integration with async iterators
- * - Any push-based async data source
- *
- * @example
- * ```typescript
- * // Async WebSocket stream
- * const $messages = streamAsync<string>((set) => {
- *   const ws = new WebSocket('ws://example.com');
- *   ws.onmessage = (event) => set(event.data);
- *   return () => ws.close();
- * });
- *
- * // Use with async/await
- * effect(async (t) => {
- *   const message = await $messages.get(t);
- *   console.log('Received:', message);
- * });
- *
- * // Wait for the first message
- * const firstMessage = await $messages.pick();
- * console.log('First message:', firstMessage);
- *
- * // Async timer stream
- * const $asyncTick = streamAsync<number>((set) => {
- *   let count = 0;
- *   const id = setInterval(() => set(count++), 1000);
- *   return () => clearInterval(id);
- * });
- * ```
- *
- * @typeParam T - The type of the values emitted by the stream (not the Promise itself).
- * @public
- */
-export class FlowStreamAsync<T> extends FlowObservable<Promise<T>> {
-	/**
-	 * Creates a new asynchronous FlowStream.
-	 *
-	 * @param updater - A function that receives a setter callback and returns a disposer.
-	 * The setter should be called whenever new data is available (can be called asynchronously).
-	 * The disposer will be invoked when the stream is disposed to clean up resources.
-	 *
-	 * @remarks
-	 * The updater is invoked immediately during construction. An initial Promise is created
-	 * that will resolve when the setter is first called. Make sure to return a proper cleanup
-	 * function to avoid resource leaks.
-	 *
-	 * @public
-	 */
-	constructor(updater: FlowStreamUpdater<T>) {
-		super();
-		this._disposer = updater((value: T) => {
-			this._set(value);
-		});
-
-		this._value = new Promise((resolve) => {
-			this._resolve = resolve;
-		});
-	}
-
-	/**
-	 * Internal method to get the raw value.
-	 * @internal
-	 */
-	protected _getRaw(): Promise<T> {
-		if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-		return this._value;
-	}
-
-	/**
-	 * Disposes the stream, releasing all resources.
-	 * @remarks In addition to disposing the underlying observable, this method calls the disposer
-	 * returned by the updater.
-	 * @public
-	 */
-	public override dispose(): void {
-		super.dispose();
-		this._disposer();
-	}
-
-	/* INTERNAL ------------------------------------------------------ */
-
-	private _initialized = false;
-	private _awaitedValue?: T;
-
-	private _resolve!: (value: T) => void;
-	private _disposer: FlowStreamDisposer;
-
-	private _set(value: T): void {
-		/* v8 ignore next */
-		if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-
-		if (!this._initialized) {
-			this._resolve(value);
-			this._initialized = true;
-			this._awaitedValue = value;
-			this.trigger();
-			return;
-		}
-
-		if (value === this._awaitedValue) return;
-
-		this._value = Promise.resolve(value);
-		this._awaitedValue = value;
-		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);
-}