@ersbeth/picoflow 1.1.2 → 2.0.0

package/src/flow/base/flowDisposable.ts

@@ -1,71 +0,0 @@
-/**
- * Contract for objects that own resources and must be cleaned up explicitly.
- *
- * @remarks
- * Many PicoFlow primitives expose `dispose()` so you can tear down subscriptions,
- * listeners, or reactive links when they are no longer needed (e.g., component
- * unmount, feature teardown, test cleanup).
- *
- * Typical options:
- * - `{ self: true }` — dispose only this instance (dependents decide their own lifecycle).
- * - `{ self: false }` or omitted — also dispose dependents, if the implementation supports it.
- *
- * The exact cascade behavior depends on the concrete primitive; consult its docs.
- *
- * @example
- * ```typescript
- * const $state = state(0);
- * const fx = effect((t) => console.log($state.get(t)));
- *
- * $state.dispose();          // Common teardown path
- * $state.dispose({ self: true }); // Dispose only this instance if you want dependents to persist
- * ```
- *
- * @public
- */
-export interface FlowDisposable {
-	/**
-	 * Disposes resources held by this object.
-	 *
-	 * @param options - Optional disposal behavior.
-	 * @param options.self - When true, dispose only this object. When false or
-	 * omitted, the implementation may also dispose dependents.
-	 *
-	 * @remarks
-	 * Use `dispose()` during teardown (unmount, test cleanup, feature shutdown).
-	 * Calling `dispose()` more than once may throw; behavior is defined by the
-	 * concrete implementation.
-	 *
-	 * @throws Error if the object has already been disposed (implementation-specific).
-	 */
-	dispose(options?: { self: boolean }): void;
-}
-
-/**
- * Runtime type guard that checks whether an object is disposable.
- *
- * @param obj - Value to test.
- * @returns `true` if `obj` exposes a callable `dispose`; otherwise `false`.
- *
- * @remarks
- * Use this for defensive cleanup in mixed collections or optional resources.
- * It performs a runtime shape check; no assumptions about specific types are made.
- *
- * @example
- * ```typescript
- * function cleanup(items: unknown[]) {
- *   for (const item of items) {
- *     if (isDisposable(item)) item.dispose();
- *   }
- * }
- * ```
- *
- * @public
- */
-export function isDisposable(obj: unknown): obj is FlowDisposable {
-	return (
-		obj !== null &&
-		obj !== undefined &&
-		typeof (obj as FlowDisposable).dispose === "function"
-	);
-}

package/src/flow/base/flowEffect.ts

@@ -1,171 +0,0 @@
-import { FlowGraph } from "./flowGraph";
-import type { FlowSignal } from "./flowSignal";
-import type { FlowTracker } from "./flowTracker";
-
-/**
- * Runs side-effect code in response to reactive state changes.
- *
- * @remarks
- * A `FlowEffect` is the bridge between reactive data and the outside world
- * (UI updates, logging, network calls, timers, etc.). It executes a callback
- * with a tracking context so you can choose which observables/signals should
- * re-trigger the effect:
- *
- * - Use `observable.get(t)` or `signal.watch(t)` to create dependencies.
- * - Use `observable.pick()` for untracked reads that should not re-run the effect.
- *
- * The callback runs immediately when the effect is created and re-runs whenever
- * any tracked dependency changes. The effect itself is the tracking context
- * (it implements `FlowTracker`), so `t` in your callback is the effect instance.
- *
- * Async callbacks are supported: if the callback returns a promise, the effect
- * awaits it before finishing the current run. A later change can re-run the
- * effect even if a previous async run is still pending, so write idempotent
- * side effects when working with async flows.
- *
- * @example
- * ```typescript
- * // Mixed tracked/untracked reads
- * const fx = effect((t) => {
- *   const tracked = $stateA.get(t);   // tracked -> re-runs when $stateA changes
- *   const snapshot = $config.pick();  // untracked -> does not re-run on changes
- *   console.log(tracked, snapshot);
- * });
- *
- * // Async work
- * const fxAsync = effect(async (t) => {
- *   const userId = $userId.get(t);
- *   const profile = await fetchProfile(userId);
- *   renderProfile(profile);
- * });
- * ```
- *
- * @public
- */
-export class FlowEffect {
-	private _disposed = false;
-	private _dependencies = new Set<FlowSignal>();
-	private _apply: (t: FlowTracker) => void | Promise<void>;
-	settled: Promise<void>;
-
-	/**
-	 * Creates a new effect and runs it once immediately.
-	 *
-	 * @param apply - Side-effect function receiving the tracking context (`t`).
-	 * It can be sync or async (returning `Promise<void>`).
-	 *
-	 * @remarks
-	 * Use `t` to opt-in to reactive tracking:
-	 * - `observable.get(t)` / `signal.watch(t)` to re-run when they change
-	 * - `observable.pick()` for reads that should not re-run the effect
-	 *
-	 * The effect schedules its first run during construction. Each subsequent
-	 * change to a tracked dependency queues another run.
-	 *
-	 * @public
-	 */
-	constructor(apply: (t: FlowTracker) => void | Promise<void>) {
-		this._apply = apply;
-		this.settled = FlowGraph.requestRead(() => this._exec());
-	}
-
-	/**
-	 * Stops the effect and detaches it from all tracked dependencies.
-	 *
-	 * @remarks
-	 * Call this when the effect's work is no longer needed (e.g., component
-	 * unmount, teardown of a feature). After disposal:
-	 * - The effect will not re-run.
-	 * - All dependency links are removed.
-	 * - Calling `dispose()` again throws an error.
-	 *
-	 * @example
-	 * ```typescript
-	 * const fx = effect((t) => $signal.watch(t));
-	 * // ... later
-	 * fx.dispose();
-	 * ```
-	 *
-	 * @public
-	 */
-	public dispose(): void {
-		if (this._disposed) throw new Error("[PicoFlow] Effect is disposed");
-		Array.from(this._dependencies).forEach((dependency) => {
-			this._unregisterDependency(dependency);
-		});
-		this._disposed = true;
-	}
-
-	/**
-	 * Whether the effect has been disposed.
-	 *
-	 * @returns `true` once disposal has run; `false` while the effect is active.
-	 *
-	 * @public
-	 */
-	public get disposed(): boolean {
-		return this._disposed;
-	}
-
-	/** @internal */ async _requestExec(): Promise<void> {
-		this.settled = this._exec();
-		return this.settled;
-	}
-
-	/** @internal */ _registerDependency(dependency: FlowSignal): void {
-		this._dependencies.add(dependency);
-		dependency._registerEffect(this);
-	}
-
-	/** @internal */ _unregisterDependency(dependency: FlowSignal): void {
-		this._dependencies.delete(dependency);
-		dependency._unregisterEffect(this);
-	}
-
-	private async _exec(): Promise<void> {
-		if (this._disposed)
-			/* v8 ignore next 1 */
-			throw new Error("[PicoFlow] Effect is disposed");
-
-		const result = this._apply(this);
-		if (result instanceof Promise) {
-			await result;
-		}
-	}
-}
-
-/**
- * Creates a reactive effect that runs now and re-runs when its tracked
- * dependencies change.
- *
- * @param fn - Side-effect function that receives the tracking context (`t`).
- * @returns A new {@link FlowEffect}.
- *
- * @remarks
- * Use an effect when you need to react to state changes with side effects
- * (UI updates, logging, network calls, timers). For computing derived values,
- * prefer derivations; for one-off work, use a normal function.
- *
- * - Track dependencies with `observable.get(t)` or `signal.watch(t)`.
- * - Read without tracking using `observable.pick()`.
- * - Async callbacks are supported; return a promise if you `await` inside.
- *
- * @example
- * ```typescript
- * const $count = state(0);
- *
- * const fx = effect((t) => {
- *   console.log("Count is:", $count.get(t));
- * });
- *
- * $count.set(1); // Logs "Count is: 1"
- * $count.set(2); // Logs "Count is: 2"
- *
- * fx.dispose();  // Stop reacting
- * ```
- *
- * @public
- */
-export function effect(fn: (t: FlowTracker) => void): FlowEffect {
-	return new FlowEffect(fn);
-}

package/src/flow/base/flowGraph.ts

@@ -1,288 +0,0 @@
-import type { FlowEffect } from "./flowEffect";
-
-/**
- * Represents a queued read operation in the reactive system.
- *
- * @remarks
- * This interface is used internally to coordinate read operations. Most users
- * will not interact with it directly.
- *
- * @internal
- */
-export interface ReadRequest<T> {
-	type: "read";
-	promise: Promise<T>;
-	resolve: (value: T) => void;
-	reject: (error: Error) => void;
-	read: () => T;
-}
-
-/**
- * Represents a queued trigger notification in the reactive system.
- *
- * @remarks
- * This interface is used internally to coordinate signal triggers. Most users
- * will not interact with it directly.
- *
- * @internal
- */
-export interface TriggerRequest {
-	type: "trigger";
-	promise: Promise<void>;
-	resolve: () => void;
-	reject: (error: Error) => void;
-	notify: () => void;
-}
-
-/**
- * Represents a queued write operation in the reactive system.
- *
- * @remarks
- * This interface is used internally to coordinate write operations with update
- * logic. Most users will not interact with it directly.
- *
- * @internal
- */
-export interface WriteRequest {
-	type: "write";
-	promise: Promise<void>;
-	resolve: () => void;
-	reject: (error: Error) => void;
-	notify: () => void;
-	update: () => boolean | Promise<boolean>;
-}
-
-/**
- * Union type representing any queued operation in the reactive system.
- *
- * @remarks
- * This type is used internally to coordinate different types of reactive
- * operations (reads, writes, triggers). Most users will not interact with it
- * directly.
- *
- * @internal
- */
-// biome-ignore lint/suspicious/noExplicitAny: we don't need to know the type of the value
-export type ActionRequest = ReadRequest<any> | TriggerRequest | WriteRequest;
-
-/**
- * Coordinates reactive operations (reads, writes, triggers, effects).
- *
- * @remarks
- * FlowGraph manages the execution order of reactive operations to ensure
- * consistent state updates. It queues operations and processes them in a
- * controlled sequence, executing effects after state changes complete.
- *
- * Most users will not interact with FlowGraph directly; reactive primitives
- * use it internally. The `clear()` method may be useful for testing scenarios
- * where you need to reset the internal state between tests.
- *
- * @public
- */
-export class FlowGraph {
-	private static _effectsQueue: FlowEffect[] = [];
-	private static _actionQueue: ActionRequest[] = [];
-	private static _processingActionQueue = false;
-
-	/**
-	 * Resets all internal queues and processing state.
-	 *
-	 * @remarks
-	 * Use this method primarily for testing scenarios where you need to ensure
-	 * a clean state between test runs. It clears pending effects and queued
-	 * operations.
-	 *
-	 * @example
-	 * ```typescript
-	 * beforeEach(() => {
-	 *   FlowGraph.clear();
-	 * });
-	 * ```
-	 *
-	 * @public
-	 */
-	static clear(): void {
-		FlowGraph._effectsQueue = [];
-		FlowGraph._actionQueue = [];
-		FlowGraph._processingActionQueue = false;
-	}
-
-	/**
-	 * Queues a trigger notification for processing.
-	 *
-	 * @param notify - Function to call when the trigger is processed.
-	 * @returns A promise that resolves after the trigger is processed.
-	 *
-	 * @remarks
-	 * This method is used internally by reactive primitives to coordinate
-	 * signal triggers. The promise resolves after all associated effects
-	 * have been executed.
-	 *
-	 * @public
-	 */
-	static requestTrigger(notify: () => void): Promise<void> {
-		const promiseWithResolvers = Promise.withResolvers<void>();
-		FlowGraph._actionQueue.push({
-			...promiseWithResolvers,
-			type: "trigger",
-			notify,
-		});
-		FlowGraph._processActionQueue();
-		return promiseWithResolvers.promise;
-	}
-
-	/**
-	 * Queues a read operation for processing.
-	 *
-	 * @param read - Function that performs the read operation.
-	 * @returns A promise that resolves with the read value.
-	 *
-	 * @remarks
-	 * This method is used internally by reactive primitives to coordinate
-	 * read operations. The read function is executed and its result (or promise)
-	 * is returned.
-	 *
-	 * @public
-	 */
-	static requestRead<T>(read: () => T | Promise<T>): Promise<T> {
-		const promiseWithResolvers = Promise.withResolvers<T>();
-		FlowGraph._actionQueue.push({
-			...promiseWithResolvers,
-			type: "read",
-			read,
-		});
-		FlowGraph._processActionQueue();
-		return promiseWithResolvers.promise;
-	}
-
-	/**
-	 * Queues a write operation with update logic for processing.
-	 *
-	 * @param notify - Function to call if the update succeeds.
-	 * @param update - Function that performs the update and returns whether
-	 * it changed the value.
-	 * @returns A promise that resolves after the write is processed.
-	 *
-	 * @remarks
-	 * This method is used internally by reactive primitives to coordinate
-	 * write operations. The update function is executed, and if it returns true
-	 * (or a promise resolving to true), the notify function is called to
-	 * trigger dependent effects.
-	 *
-	 * @public
-	 */
-	static requestWrite(
-		notify: () => void,
-		update: () => boolean | Promise<boolean>,
-	): Promise<void> {
-		const promiseWithResolvers = Promise.withResolvers<void>();
-		FlowGraph._actionQueue.push({
-			...promiseWithResolvers,
-			type: "write",
-			notify,
-			update,
-		});
-		FlowGraph._processActionQueue();
-		return promiseWithResolvers.promise;
-	}
-
-	/**
-	 * Queues effects for execution after the current operation completes.
-	 *
-	 * @param effects - Array of effects to queue for execution.
-	 *
-	 * @remarks
-	 * This method is used internally by reactive primitives to schedule effect
-	 * execution. Effects are executed after the current read/write/trigger
-	 * operation completes, ensuring proper ordering of reactive updates.
-	 *
-	 * @public
-	 */
-	static pushEffects(effects: FlowEffect[]): void {
-		FlowGraph._effectsQueue.push(...effects);
-	}
-
-	/** @internal */
-	private static _processActionQueue = async () => {
-		if (FlowGraph._processingActionQueue) return;
-		FlowGraph._processingActionQueue = true;
-
-		while (FlowGraph._actionQueue.length > 0) {
-			const actionRequest = FlowGraph._actionQueue.shift();
-			if (!actionRequest) break;
-
-			// Process read operation
-			if (actionRequest.type === "read") {
-				try {
-					const read = actionRequest.read();
-
-					let value: unknown;
-					if (read instanceof Promise) {
-						value = await read;
-					} else {
-						value = read;
-					}
-					actionRequest.resolve(value);
-				} catch (error: unknown) {
-					const safeError =
-						error instanceof Error ? error : new Error(String(error));
-					actionRequest.reject(safeError);
-				}
-				continue; // stop here
-			}
-
-			// Process write operation
-			if (actionRequest.type === "write") {
-				try {
-					const updateResult = actionRequest.update();
-
-					let updated = false;
-					if (updateResult instanceof Promise) {
-						updated = await updateResult;
-					} else {
-						updated = updateResult;
-					}
-
-					if (!updated) {
-						actionRequest.resolve();
-						continue;
-					}
-
-					actionRequest.notify();
-				} catch (error: unknown) {
-					const safeError =
-						error instanceof Error ? error : new Error(String(error));
-					actionRequest.reject(safeError);
-					continue;
-				}
-			}
-
-			// Process trigger operation
-			if (actionRequest.type === "trigger") {
-				actionRequest.notify();
-			}
-
-			// Process effects
-			let effectError: Error | null = null;
-			for (const effect of FlowGraph._effectsQueue) {
-				try {
-					await effect._requestExec();
-				} catch (error: unknown) {
-					effectError =
-						error instanceof Error ? error : new Error(String(error));
-					break;
-				}
-			}
-
-			FlowGraph._effectsQueue = [];
-
-			if (effectError) {
-				actionRequest.reject(effectError);
-			} else {
-				actionRequest.resolve();
-			}
-		}
-
-		FlowGraph._processingActionQueue = false;
-	};
-}