@ersbeth/picoflow 0.2.3 → 1.0.0

package/src/advanced/stream.ts

@@ -2,7 +2,7 @@ import { FlowObservable } from "../basic/";
 
 /**
  * A function type that sets a new value for the reactive stream.
- * @typeparam T - The type of the value.
+ * @typeParam T - The type of the value.
  * @public
  */
 export type FlowStreamSetter<T> = (value: T) => void;
@@ -18,70 +18,133 @@ export type FlowStreamDisposer = () => void;
  * @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.
+ * @typeParam T - The type of the stream value.
  * @public
  */
 export type FlowStreamUpdater<T> = (
-    set: FlowStreamSetter<T>,
+	set: FlowStreamSetter<T>,
 ) => FlowStreamDisposer;
 
 /**
- * Represents a reactive stream that updates its value based on an updater function.
+ * Represents a reactive stream that updates its value based on an external updater function.
  *
  * @remarks
- * FlowStream extends FlowObservable to encapsulate an update mechanism provided by an external updater function.
- * The updater is invoked during construction with a setter, and it returns a disposer to be called upon disposal.
- * Note: The stream's current value may be undefined until explicitly set.
+ * 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.
  *
- * @typeparam T - The type of the stream's value.
+ * **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 to update the stream's value.
-     * It should return a disposer function that will be called upon disposal.
-     * @public
-     */
-    constructor(updater: FlowStreamUpdater<T>) {
-        super();
-        this._disposer = updater((value: T) => {
-            this._set(value);
-        });
-    }
+	/**
+	 * 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);
+		});
+	}
 
-    /**
-     * Retrieves the current value of the stream.
-     * @returns The current value, or undefined if no value has been set yet.
-     * @throws Error if the stream is disposed.
-     * @public
-     */
-    public get(): T | undefined {
-        if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-        return this._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();
-    }
+	/**
+	 * 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 ------------------------------------------------------ */
+	/* INTERNAL ------------------------------------------------------ */
 
-    private _disposer: FlowStreamDisposer;
+	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._notify();
-    }
+	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._notify();
+	}
 }

package/src/advanced/streamAsync.ts

@@ -2,81 +2,140 @@ import { FlowObservable } from "../basic";
 import type { FlowStreamDisposer, FlowStreamUpdater } from "./stream";
 
 /**
- * Represents an asynchronous reactive stream that updates its value based on an updater function.
+ * Represents an asynchronous reactive stream that always returns a Promise and updates based on an updater function.
  *
  * @remarks
- * A FlowStreamAsync extends FlowObservable and encapsulates a mechanism for asynchronously updating its value.
- * The updater is invoked during construction with a setter, and its returned disposer is called upon disposal.
- * Note: The stream's current value may be undefined until it is set.
+ * 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.
  *
- * @typeparam T - The type of the stream's value.
+ * **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 to update the stream's value.
-     * It should return a disposer function that will be called upon disposal.
-     * @remarks The updater function can invoke the setter asynchronously to update the stream.
-     * @public
-     */
-    constructor(updater: FlowStreamUpdater<T>) {
-        super();
-        this._disposer = updater((value: T) => {
-            this._set(value);
-        });
+	/**
+	 * 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;
-        });
-    }
+		this._value = new Promise((resolve) => {
+			this._resolve = resolve;
+		});
+	}
 
-    /**
-     * Retrieves the current value of the stream as a Promise.
-     * @returns A Promise that resolves to the current value.
-     * @throws Error if the stream is disposed.
-     * @public
-     */
-    public get(): Promise<T> {
-        if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-        return this._value;
-    }
+	/**
+	 * 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();
-    }
+	/**
+	 * 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 ------------------------------------------------------ */
+	/* INTERNAL ------------------------------------------------------ */
 
-    private _initialized = false;
-    private _awaitedValue?: T;
+	private _initialized = false;
+	private _awaitedValue?: T;
 
-    private _resolve!: (value: T) => void;
-    private _disposer: FlowStreamDisposer;
+	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");
+	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._notify();
-            return;
-        }
+		if (!this._initialized) {
+			this._resolve(value);
+			this._initialized = true;
+			this._awaitedValue = value;
+			this._notify();
+			return;
+		}
 
-        if (value === this._awaitedValue) return;
+		if (value === this._awaitedValue) return;
 
-        this._value = Promise.resolve(value);
-        this._awaitedValue = value;
-        this._notify();
-    }
+		this._value = Promise.resolve(value);
+		this._awaitedValue = value;
+		this._notify();
+	}
 }

package/src/basic/constant.ts

@@ -1,64 +1,97 @@
 import { FlowObservable } from "./observable";
 
 /**
- * Represents a reactive and immutable constant value computed lazily upon first access.
+ * Represents a reactive and immutable constant value that can be computed lazily upon first access.
  *
- * @remarks This class extends FlowObservable and supports initializing the constant using either a direct value
- * or a lazy initializer function. Once computed, the value is cached for all subsequent accesses.
+ * @remarks
+ * FlowConstant extends FlowObservable to provide an immutable reactive value. Unlike {@link FlowState},
+ * which is mutable via the `set()` method, a constant's value never changes after initialization.
  *
- * @typeparam T - The type of the constant value.
+ * **Initialization Patterns:**
+ * - **Direct value**: Pass a value directly; it's stored immediately.
+ * - **Lazy initialization**: Pass a function; it's called only when the value is first accessed
+ *   via `get()` or `pick()`.
+ *
+ * **Lazy Evaluation Benefits:**
+ * Lazy initialization is useful when:
+ * - The computation is expensive and may not be needed immediately
+ * - The value depends on resources that aren't available at construction time
+ * - You want to defer computation until the value is actually needed
+ *
+ * **Caching:**
+ * Once computed (either immediately or lazily), the value is cached permanently. All subsequent
+ * accesses return the cached value without re-computation.
+ *
+ * **Use Cases:**
+ * - Configuration values that don't change
+ * - Expensive computations that should only run once
+ * - Initialization values for other reactive primitives
+ *
+ * @example
+ * ```typescript
+ * // Direct value - initialized immediately
+ * const $config = constant({ apiUrl: 'https://api.example.com' });
+ *
+ * // Lazy initialization - computed on first access
+ * const $expensiveValue = constant(() => {
+ *   console.log('Computing...');
+ *   return performExpensiveCalculation();
+ * });
+ *
+ * $expensiveValue.pick(); // Logs: "Computing..."
+ * $expensiveValue.pick(); // No log - returns cached value
+ * ```
+ *
+ * @typeParam T - The type of the constant value.
  *
  * @public
  */
 export class FlowConstant<T> extends FlowObservable<T> {
-    /**
-     * Creates a new FlowConstant instance.
-     *
-     * @param value - Either a direct value of type T or a function returning a value of type T for lazy initialization.
-     * @public
-     */
-    constructor(value: T | (() => T)) {
-        super();
-        this._initEager(value);
-    }
+	/**
+	 * Creates a new FlowConstant instance.
+	 *
+	 * @param value - Either a direct value of type T or a function returning a value of type T.
+	 * If a function is provided, it will be invoked lazily on the first value access.
+	 * If a direct value is provided, it is stored immediately.
+	 *
+	 * @public
+	 */
+	constructor(value: T | (() => T)) {
+		super();
+		this._initEager(value);
+	}
 
-    /**
-     * Retrieves the constant value, computing it lazily if needed.
-     *
-     * Accessing this method will initialize the value if it has not been computed already.
-     * Throws an error if the instance has been disposed or if lazy initialization fails.
-     *
-     * @returns The cached constant value.
-     * @throws Error if the constant is disposed or cannot be initialized.
-     * @public
-     */
-    get(): T {
-        if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-        this._initLazy();
-        return this._value;
-    }
+	/**
+	 * Internal method to get the raw value.
+	 * @internal
+	 */
+	protected _getRaw(): T {
+		if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+		this._initLazy();
+		return this._value;
+	}
 
-    /* INTERNAL --------------------------------------------------------- */
+	/* INTERNAL --------------------------------------------------------- */
 
-    /*@internal*/ protected _initialized = false;
-    /*@internal*/ protected _init?: () => T;
+	/** @internal */ protected _initialized = false;
+	/** @internal */ protected _init?: () => T;
 
-    /*@internal*/ protected _initEager(value: T | (() => T)): void {
-        if (typeof value === "function") {
-            this._init = value as () => T;
-        } else {
-            this._value = value;
-            this._initialized = true;
-        }
-    }
+	/** @internal */ protected _initEager(value: T | (() => T)): void {
+		if (typeof value === "function") {
+			this._init = value as () => T;
+		} else {
+			this._value = value;
+			this._initialized = true;
+		}
+	}
 
-    /*@internal*/ protected _initLazy(): void {
-        if (!this._initialized && this._init) {
-            this._value = this._init();
-            this._initialized = true;
-        }
-        /* v8 ignore next 2 */
-        if (!this._initialized)
-            throw new Error("[PicoFlow] Primitive can't be initialized");
-    }
+	/** @internal */ protected _initLazy(): void {
+		if (!this._initialized && this._init) {
+			this._value = this._init();
+			this._initialized = true;
+		}
+		/* v8 ignore next 2 */
+		if (!this._initialized)
+			throw new Error("[PicoFlow] Primitive can't be initialized");
+	}
 }