@ersbeth/picoflow 1.0.0 → 1.1.0

package/src/flow/base/flowGraph.ts

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

package/src/flow/base/flowSignal.ts

@@ -0,0 +1,207 @@
+import type { FlowDisposable } from "./flowDisposable";
+import type { FlowEffect } from "./flowEffect";
+import { FlowGraph } from "./flowGraph";
+import type { FlowTracker } from "./flowTracker";
+
+/**
+ * Event-like reactive primitive with no payload.
+ *
+ * @remarks
+ * A signal is used to broadcast that “something happened” (refresh, invalidate,
+ * notify). It does not carry data; it only notifies dependents that they should
+ * react. Track it with `watch(t)` inside an effect or derivation to re-run when
+ * the signal is triggered.
+ *
+ * Signals can be triggered and disposed. Once disposed, further interaction
+ * throws an error.
+ *
+ * @public
+ */
+export class FlowSignal implements FlowDisposable, FlowTracker {
+	/**
+	 * Triggers the signal and notifies all dependents.
+	 *
+	 * @remarks
+	 * Any effect/derivation that called `watch(t)` on this signal will re-run.
+	 * Returns a promise that settles after notifications complete.
+	 *
+	 * @throws Error if the signal is disposed.
+	 *
+	 * @example
+	 * ```typescript
+	 * const $tick = signal();
+	 *
+	 * effect((t) => {
+	 *   $tick.watch(t);
+	 *   console.log("tick");
+	 * });
+	 *
+	 * $tick.trigger(); // logs "tick"
+	 * ```
+	 *
+	 * @public
+	 */
+	public async trigger() {
+		if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+		return FlowGraph.requestTrigger(() => this._notify());
+	}
+
+	/**
+	 * Registers this signal as a dependency in the current tracking context.
+	 *
+	 * @param context - The tracking context (`t`) provided to effects/derivations.
+	 *
+	 * @remarks
+	 * Signals have no value to read; calling `watch(t)` simply means “re-run me
+	 * when this signal is triggered.” Call this inside an effect/derivation
+	 * callback where a tracking context is available.
+	 *
+	 * @throws Error if the signal has been disposed.
+	 *
+	 * @example
+	 * ```typescript
+	 * const $refresh = signal();
+	 *
+	 * effect((t) => {
+	 *   $refresh.watch(t);
+	 *   console.log("refresh triggered");
+	 * });
+	 *
+	 * $refresh.trigger(); // logs "refresh triggered"
+	 * ```
+	 *
+	 * @public
+	 */
+	public watch(caller: FlowTracker): void {
+		if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+		caller._registerDependency(this);
+	}
+
+	/**
+	 * Disposes the signal and cleans up its dependencies/listeners.
+	 *
+	 * @remarks
+	 * After disposal the signal must not be used; calling `trigger` or `watch`
+	 * will throw. If `options?.self` is true, only this signal is disposed; when
+	 * false or omitted, dependents may also be disposed depending on the
+	 * implementation.
+	 *
+	 * @throws Error if the signal is already disposed.
+	 *
+	 * @example
+	 * ```typescript
+	 * const $refresh = signal();
+	 * // ... use it
+	 * $refresh.dispose();
+	 * ```
+	 *
+	 * @public
+	 */
+	public dispose(options?: { self: boolean }): void {
+		if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+		if (options?.self) {
+			Array.from(this._effects).forEach((effect) => {
+				effect._unregisterDependency(this);
+			});
+			Array.from(this._listeners).forEach((listener) => {
+				listener._unregisterDependency(this);
+			});
+		} else {
+			Array.from(this._effects).forEach((effect) => {
+				effect.dispose();
+			});
+			Array.from(this._listeners).forEach((listener) => {
+				listener.dispose();
+			});
+		}
+		Array.from(this._dependencies).forEach((dependency) => {
+			this._unregisterDependency(dependency);
+		});
+		this._disposed = true;
+	}
+
+	/**
+	 * Whether the signal has been disposed.
+	 *
+	 * @returns `true` if disposed; `false` while active.
+	 *
+	 * @remarks Use to guard operations or avoid double disposal.
+	 *
+	 * @public
+	 */
+	public get disposed(): boolean {
+		return this._disposed;
+	}
+
+	/* INTERNAL ------------------------------------------------------------- */
+
+	protected _disposed = false;
+
+	protected _dependencies = new Set<FlowSignal>();
+
+	protected _listeners = new Set<FlowSignal>();
+
+	protected _effects = new Set<FlowEffect>();
+
+	protected _notify(): void {
+		FlowGraph.pushEffects(Array.from(this._effects));
+
+		this._listeners.forEach((listener) => {
+			listener._notify();
+		});
+	}
+
+	/** @internal */ _registerDependency(dependency: FlowSignal): void {
+		this._dependencies.add(dependency);
+		dependency._registerListener(this);
+	}
+
+	/** @internal */ _unregisterDependency(dependency: FlowSignal): void {
+		this._dependencies.delete(dependency);
+		dependency._unregisterListener(this);
+	}
+
+	/** @internal */ _registerListener(signal: FlowSignal): void {
+		this._listeners.add(signal);
+	}
+
+	/** @internal */ _unregisterListener(signal: FlowSignal): void {
+		this._listeners.delete(signal);
+	}
+
+	/** @internal */ _registerEffect(effect: FlowEffect): void {
+		this._effects.add(effect);
+	}
+
+	/** @internal */ _unregisterEffect(effect: FlowEffect): void {
+		this._effects.delete(effect);
+	}
+}
+
+/**
+ * Creates a new signal for event-like notifications.
+ *
+ * @returns A new instance of {@link FlowSignal}.
+ *
+ * @remarks
+ * Use signals to announce “something happened” when no payload is needed. Track
+ * them with `watch(t)` inside effects/derivations and trigger them to re-run
+ * dependents.
+ *
+ * @example
+ * ```typescript
+ * const $ready = signal();
+ *
+ * effect((t) => {
+ *   $ready.watch(t);
+ *   console.log("ready!");
+ * });
+ *
+ * $ready.trigger(); // logs "ready!"
+ * ```
+ *
+ * @public
+ */
+export function signal(): FlowSignal {
+	return new FlowSignal();
+}

package/src/flow/base/flowTracker.ts

@@ -0,0 +1,17 @@
+import type { FlowSignal } from "./flowSignal";
+
+/**
+ * Tracking context passed to reactive callbacks.
+ *
+ * @remarks
+ * Effects and derivations receive an instance of `FlowTracker` as the `t`
+ * parameter. Use it inside your callback to register dependencies (for example
+ * via APIs that accept `t`) so the callback can re-run when those dependencies
+ * change. Typical users do not implement this interface directly; it is
+ * implemented by the reactive primitives themselves.
+ *
+ * @public
+ */
+export interface FlowTracker {
+	/** @internal */ _registerDependency(signal: FlowSignal): void;
+}

package/src/flow/base/index.ts

@@ -0,0 +1,6 @@
+export * from "./flowDisposable";
+export * from "./flowEffect";
+export * from "./flowGraph";
+export * from "./flowSignal";
+export * from "./flowTracker";
+export * from "./utils";

package/src/flow/base/utils.ts

@@ -0,0 +1,19 @@
+/**
+ * Excludes `Promise` types from `T`, returning `never` if `T` is a promise.
+ *
+ * @remarks
+ * Use `NotPromise<T>` to constrain generics to synchronous values. It is helpful
+ * when an API must reject promise inputs while accepting other types unchanged.
+ *
+ * @example
+ * ```typescript
+ * function useSync<T>(value: NotPromise<T>) {
+ *   // value cannot be a Promise
+ *   return value;
+ * }
+ *
+ * useSync(123);           // ok
+ * // useSync(Promise.resolve(1)); // type error
+ * ```
+ */
+export type NotPromise<T> = T extends Promise<unknown> ? never : T;