@ersbeth/picoflow 1.1.1 → 2.0.0

package/src/flow/base/flowSignal.ts

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

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

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

package/src/flow/base/utils.ts

@@ -1,19 +0,0 @@
-/**
- * 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;

package/src/flow/collections/flowArray.ts

@@ -1,409 +0,0 @@
-import { FlowGraph, isDisposable } from "../base";
-import { FlowNode, type FlowState, state } from "../nodes";
-
-/**
- * Represents the actions that can be performed on a FlowArray.
- * @public
- */
-export type FlowArrayAction<T> =
-	| {
-			type: "set";
-			items: T[];
-	  }
-	| {
-			type: "update";
-			index: number;
-			item: T;
-	  }
-	| {
-			type: "push";
-			item: T;
-	  }
-	| {
-			type: "pop";
-	  }
-	| {
-			type: "unshift";
-			item: T;
-	  }
-	| {
-			type: "shift";
-	  }
-	| {
-			type: "splice";
-			start: number;
-			deleteCount: number;
-			items: T[];
-	  }
-	| {
-			type: "clear";
-	  };
-
-/**
- * Represents a reactive array.
- * @public
- */
-export class FlowArray<T> extends FlowNode<T[]> {
-	/**
-	 * Last action performed on the FlowArray.
-	 * @public
-	 */
-	$lastAction: FlowState<FlowArrayAction<T>>;
-	protected declare _value: T[];
-
-	/**
-	 * Creates an instance of FlowArray.
-	 * @param value - Initial array value.
-	 * @public
-	 */
-	constructor(value: T[] = []) {
-		super(value);
-		this.$lastAction = state<FlowArrayAction<T>>({
-			type: "set",
-			items: value,
-		});
-	}
-
-	/**
-	 * Gets the current length of the array.
-	 * @returns The length of the array.
-	 * @public
-	 */
-	get length(): number {
-		if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-		return this._value.length;
-	}
-
-	/**
-	 * Internal method to get the raw value.
-	 * @internal
-	 */
-	protected _getRaw(): T[] {
-		if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-		return [...this._value]; // Ensure nobody can modify the original array
-	}
-
-	/**
-	 * Replaces the entire array with new items.
-	 * @param items - The new array of items.
-	 * @public
-	 */
-	override async set(items: T[]): Promise<void> {
-		if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-		const update = () => {
-			// compute current value
-			const currentValue = this._value;
-
-			if (currentValue !== items) {
-				// dispose old items
-				currentValue.forEach((item) => {
-					if (isDisposable(item)) item.dispose({ self: true });
-				});
-
-				// assign new items
-				this._value = items;
-
-				// emit last action
-				this.$lastAction.set({ type: "set", items: items });
-			}
-
-			// return value changed check
-			return currentValue !== items;
-		};
-
-		const notify = () => {
-			// call super method to avoid setting dirty flag back to true
-			super._notify();
-		};
-
-		return FlowGraph.requestWrite(notify, update);
-	}
-
-	/**
-	 * Replaces an item at a specific index.
-	 * @param index - The index of the item to replace.
-	 * @param item - The new item.
-	 * @public
-	 */
-	async update(index: number, item: T): Promise<void> {
-		if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-		const update = () => {
-			if (index < 0 || index >= this._value.length) {
-				throw new Error("[PicoFlow] Index out of bounds");
-			}
-
-			// compute current value
-			const currentValue = this._value[index];
-
-			if (currentValue !== item) {
-				// dispose item
-				if (isDisposable(currentValue)) {
-					currentValue.dispose({ self: true });
-				}
-
-				// update item
-				this._value[index] = item;
-
-				// emit last action
-				this.$lastAction.set({ type: "update", index: index, item: item });
-			}
-
-			// return value changed check
-			return currentValue !== item;
-		};
-
-		const notify = () => {
-			// call super method to avoid setting dirty flag back to true
-			super._notify();
-		};
-
-		return FlowGraph.requestWrite(notify, update);
-	}
-
-	/**
-	 * Appends an item to the end of the array.
-	 * @param item - The item to append.
-	 * @public
-	 */
-	async push(item: T): Promise<void> {
-		if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-		const update = () => {
-			// push item
-			this._value.push(item);
-
-			// emit last action
-			this.$lastAction.set({ type: "push", item: item });
-
-			// return value changed check
-			return true;
-		};
-
-		const notify = () => {
-			// call super method to avoid setting dirty flag back to true
-			super._notify();
-		};
-
-		return FlowGraph.requestWrite(notify, update);
-	}
-
-	/**
-	 * Removes the last item from the array.
-	 * @public
-	 */
-	async pop(): Promise<void> {
-		if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-
-		const update = () => {
-			// pop item
-			const item = this._value.pop();
-
-			if (item !== undefined) {
-				// dispose item
-				if (isDisposable(item)) {
-					item.dispose({ self: true });
-				}
-
-				// emit last action
-				this.$lastAction.set({ type: "pop" });
-
-				// return value changed check
-				return true;
-			}
-			return false;
-		};
-
-		const notify = () => {
-			// call super method to avoid setting dirty flag back to true
-			super._notify();
-		};
-
-		return FlowGraph.requestWrite(notify, update);
-	}
-
-	/**
-	 * Inserts an item at the beginning of the array.
-	 * @param item - The item to insert.
-	 * @public
-	 */
-	async unshift(item: T): Promise<void> {
-		if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-		const update = () => {
-			// unshift item
-			this._value.unshift(item);
-
-			// emit last action
-			this.$lastAction.set({ type: "unshift", item: item });
-
-			// return value changed check
-			return true;
-		};
-
-		const notify = () => {
-			// call super method to avoid setting dirty flag back to true
-			super._notify();
-		};
-
-		return FlowGraph.requestWrite(notify, update);
-	}
-
-	/**
-	 * Removes the first item from the array.
-	 * @public
-	 */
-	async shift(): Promise<void> {
-		if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-		const update = () => {
-			// shift item
-			const item = this._value.shift();
-
-			if (item !== undefined) {
-				// dispose item
-				if (isDisposable(item)) {
-					item.dispose({ self: true });
-				}
-				// emit last action
-				this.$lastAction.set({ type: "shift" });
-
-				// return value changed check
-				return true;
-			}
-
-			return false;
-		};
-
-		const notify = () => {
-			// call super method to avoid setting dirty flag back to true
-			super._notify();
-		};
-
-		return FlowGraph.requestWrite(notify, update);
-	}
-
-	/**
-	 * Changes the content of the array.
-	 * @param start - The starting index.
-	 * @param deleteCount - Number of items to remove.
-	 * @param newItems - New items to add.
-	 * @public
-	 */
-	async splice(
-		start: number,
-		deleteCount: number,
-		...newItems: T[]
-	): Promise<void> {
-		if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-		const update = () => {
-			// splice items
-			const items = this._value.splice(start, deleteCount, ...newItems);
-
-			// dispose items
-			items.forEach((item) => {
-				if (isDisposable(item)) item.dispose({ self: true });
-			});
-
-			// emit last action
-			this.$lastAction.set({
-				type: "splice",
-				start: start,
-				deleteCount: deleteCount,
-				items: newItems,
-			});
-
-			// return value changed check
-			return true;
-		};
-
-		const notify = () => {
-			// call super method to avoid setting dirty flag back to true
-			super._notify();
-		};
-
-		return FlowGraph.requestWrite(notify, update);
-	}
-
-	/**
-	 * Clears all items from the array.
-	 * @public
-	 */
-	async clear(): Promise<void> {
-		if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-		const update = () => {
-			// dispose old items
-			const items = [...this._value];
-			items.forEach((item) => {
-				if (isDisposable(item)) item.dispose({ self: true });
-			});
-
-			// clear array
-			this._value = [];
-
-			// emit last action
-			this.$lastAction.set({ type: "clear" });
-
-			// return value changed check
-			return true;
-		};
-
-		const notify = () => {
-			// call super method to avoid setting dirty flag back to true
-			super._notify();
-		};
-
-		return FlowGraph.requestWrite(notify, update);
-	}
-
-	/**
-	 * Disposes the FlowArray and its items.
-	 * @param options - Disposal options.
-	 * @public
-	 */
-	override dispose(options?: { self: boolean }): void {
-		super.dispose(options);
-		this._value.forEach((item) => {
-			if (isDisposable(item)) item.dispose(options);
-		});
-		this._value = [];
-	}
-
-	/* INTERNAL */
-}
-
-/**
- * Creates a new reactive array with mutation methods and fine-grained action tracking.
- *
- * @typeParam T - The type of the array elements.
- * @param initial - An optional array of initial values.
- * @returns A new instance of {@link FlowArray}.
- *
- * @remarks
- * A reactive array provides array-like mutation methods (push, pop, shift, unshift, splice)
- * and tracks the last operation performed via `$lastAction`. This enables both whole-array
- * reactivity and fine-grained tracking of specific mutations.
- *
- * The array automatically disposes disposable items when they are removed (if they implement
- * the FlowDisposable interface).
- *
- * @example
- * ```typescript
- * const $items = array([1, 2, 3]);
- *
- * // Track the whole array
- * effect((t) => {
- *   console.log('Items:', $items.get(t));
- * });
- *
- * // Track the last action
- * effect((t) => {
- *   const action = $items.$lastAction.get(t);
- *   console.log('Action:', action.type);
- * });
- *
- * $items.push(4); // Logs action: "push"
- * $items.pop();   // Logs action: "pop"
- * ```
- *
- * @public
- */
-export function array<T>(initial?: T[]): FlowArray<T> {
-	return new FlowArray<T>(initial);
-}