@ersbeth/picoflow 1.0.0 → 1.1.0

package/src/basic/observable.ts

@@ -1,109 +0,0 @@
-import { FlowEffect } from "./effect";
-import { FlowSignal } from "./signal";
-import type { TrackingContext } from "./trackingContext";
-
-/**
- * Represents a reactive observable that holds and tracks a value.
- *
- * @remarks
- * FlowObservable is the base class for all reactive values in PicoFlow. It provides two ways
- * to access the current value:
- *
- * 1. **Tracked access** via `get(context)`: Registers the observable as a dependency in the
- *    tracking context, so changes trigger re-execution of the effect or derivation.
- *
- * 2. **Untracked access** via `pick()` or `get(null)`: Reads the current value without registering
- *    a dependency, useful for reading values within effects that shouldn't trigger re-runs.
- *
- * Subclasses must implement the {@link FlowObservable._getRaw} method to provide the actual value.
- *
- * @typeParam T - The type of the value held by the observable.
- * @public
- */
-export abstract class FlowObservable<T> extends FlowSignal {
-	/**
-	 * Gets the current value with optional dependency tracking.
-	 *
-	 * @param context - The tracking context for reactive tracking, or null for untracked access.
-	 * When a context is provided, this observable is registered as a dependency. When null,
-	 * the value is read without any tracking.
-	 *
-	 * @returns The current value of type T.
-	 *
-	 * @remarks
-	 * Use `get(t)` within effects and derivations to create reactive dependencies.
-	 * Use `get(null)` when you need to read a value without tracking (though `pick()` is more idiomatic).
-	 *
-	 * @example
-	 * ```typescript
-	 * effect((t) => {
-	 *   const tracked = $state.get(t);     // Dependency registered
-	 *   const untracked = $other.get(null); // No dependency
-	 * });
-	 * ```
-	 *
-	 * @public
-	 */
-	get(context: TrackingContext | null): T {
-		if (context) {
-			this.watch(context);
-		}
-		return this._getRaw();
-	}
-
-	/**
-	 * Gets the current value without any dependency tracking.
-	 *
-	 * @returns The current value of type T.
-	 *
-	 * @remarks
-	 * This method is equivalent to calling `get(null)` but provides a more semantic and readable API.
-	 * Use `pick()` when you want to read a snapshot of the current value without creating a reactive
-	 * dependency. This is useful for:
-	 * - Reading initial values
-	 * - Accessing configuration that shouldn't trigger updates
-	 * - Mixing tracked and untracked reads in the same effect
-	 *
-	 * @example
-	 * ```typescript
-	 * // Read a snapshot outside reactive context
-	 * const currentValue = $state.pick();
-	 *
-	 * // Mix tracked and untracked reads
-	 * effect((t) => {
-	 *   const tracked = $reactive.get(t);    // Triggers re-runs
-	 *   const snapshot = $config.pick();     // Doesn't trigger re-runs
-	 *   processData(tracked, snapshot);
-	 * });
-	 * ```
-	 *
-	 * @public
-	 */
-	pick(): T {
-		return this._getRaw();
-	}
-
-	/**
-	 * Internal method to retrieve the raw value.
-	 * Subclasses must override this method to provide the current value.
-	 * @internal
-	 */
-	protected abstract _getRaw(): T;
-
-	/* INTERNAL -------------------------------------------*/
-
-	/** @internal */ protected _value!: T;
-
-	/**
-	 * Subscribes a listener function to changes of the observable.
-	 * The listener is executed immediately with the current value and on subsequent updates.
-	 * @param listener - A callback function that receives the new value.
-	 * @returns A disposer function to cancel the subscription.
-	 */
-	subscribe(listener: (value: T) => void): () => void {
-		const effect = new FlowEffect((t) => {
-			listener(this.get(t));
-		});
-		return () => effect.dispose();
-	}
-}

package/src/basic/signal.ts

@@ -1,145 +0,0 @@
-import type { FlowDisposable } from "./disposable";
-import type { FlowEffect } from "./effect";
-import type { TrackingContext } from "./trackingContext";
-
-/**
- * Represents a reactive signal.
- *
- * @remarks Use FlowSignal to create reactive streams that notify listeners and execute associated effects.
- * Signals can be triggered and disposed. Once disposed, interactions with the signal will throw errors.
- * @public
- */
-export class FlowSignal implements FlowDisposable {
-	/**
-	 * Triggers the FlowSignal.
-	 * Notifies all registered listeners and schedules execution of associated effects.
-	 * @throws If the FlowSignal has already been disposed.
-	 * @public
-	 */
-	public trigger(): void {
-		if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-		this._notify();
-	}
-
-	/**
-	 * Watches the signal, registering it as a dependency in the tracking context.
-	 *
-	 * @param context - The tracking context in which to register this signal as a dependency.
-	 *
-	 * @remarks
-	 * Use `watch()` when you want to track a signal without reading its value (signals don't
-	 * have values to read). This is useful for triggering effects based on signal events
-	 * without needing associated data.
-	 *
-	 * When the signal is triggered via `trigger()`, any effects or derivations that have
-	 * watched this signal will automatically re-execute.
-	 *
-	 * This method must be called within an effect or derivation context where a TrackingContext
-	 * is available. For observables (which hold values), use `.get(t)` instead, which both
-	 * reads the value and watches for changes.
-	 *
-	 * @throws Error if the signal has been disposed.
-	 *
-	 * @example
-	 * ```typescript
-	 * const $signal = signal();
-	 *
-	 * effect((t) => {
-	 *   $signal.watch(t);  // Track the signal
-	 *   console.log('Signal triggered!');
-	 * });
-	 *
-	 * $signal.trigger(); // Logs: "Signal triggered!"
-	 * ```
-	 *
-	 * @public
-	 */
-	public watch(context: TrackingContext): void {
-		if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-		context._registerDependency(this);
-	}
-
-	/**
-	 * Disposes the FlowSignal.
-	 * Cleans up all registered effects, listeners, and dependencies.
-	 * Once disposed, further usage of the signal will throw an error.
-	 * @throws If the FlowSignal is already disposed.
-	 * @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;
-	}
-
-	/**
-	 * Indicates whether the FlowSignal has been disposed.
-	 * @remarks Once disposed, the signal should not be used.
-	 * @public
-	 */
-	public get disposed(): boolean {
-		return this._disposed;
-	}
-
-	/* INTERNAL ------------------------------------------------------------- */
-
-	/** @internal */ protected _disposed = false;
-
-	/** @internal */ protected _dependencies = new Set<FlowSignal>();
-
-	/** @internal */ protected _listeners = new Set<FlowSignal>();
-
-	/** @internal */ protected _effects = new Set<FlowEffect>();
-
-	/** @internal */ _notify(): void {
-		this._listeners.forEach((listener) => {
-			listener._notify();
-		});
-		this._effects.forEach((effect) => {
-			effect._exec();
-		});
-	}
-
-	/** @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);
-	}
-}

package/src/basic/state.ts

@@ -1,60 +0,0 @@
-import { FlowConstant } from "./constant";
-
-/**
- * Represents a reactive state that holds a mutable value.
- *
- * @typeParam T - The type of the state value.
- *
- * @remarks
- * FlowState extends FlowConstant and inherits reactive value access methods from FlowObservable.
- * You can read the state value using `get(context)` for tracked access or `pick()` for untracked access.
- * Use the {@link FlowState.set} method to update the state value.
- *
- * When the state is updated with a new value that differs from the current value, all dependent
- * effects and derivations are automatically notified and re-executed. If the new value is strictly
- * equal to the current value, no notification occurs.
- *
- * @example
- * ```typescript
- * const $count = state(0);
- *
- * // Read with tracking
- * effect((t) => {
- *   console.log($count.get(t)); // Effect re-runs when $count changes
- * });
- *
- * // Read without tracking
- * const snapshot = $count.pick();
- *
- * // Update the value
- * $count.set(1);
- * $count.set(current => current + 1);
- * ```
- *
- * @public
- */
-export class FlowState<T> extends FlowConstant<T> {
-	/**
-	 * Updates the state with a new value.
-	 * @param value - A new value or a callback function that computes a new value based on the current state.
-	 * @remarks
-	 * If the computed new value is strictly equal to the current state value, no change is made and subscribers
-	 * will not be notified. Otherwise, the state is updated and all subscribers are informed of the change.
-	 * @throws Error if the state has been disposed.
-	 * @public
-	 */
-	set(value: T | ((current: T) => T)): void {
-		if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-
-		// compute new value
-		const next =
-			typeof value === "function"
-				? (value as (current: T) => T)(this._value)
-				: value;
-
-		// apply new value
-		if (next === this._value) return;
-		this._value = next;
-		this._notify();
-	}
-}

package/src/basic/trackingContext.ts

@@ -1,45 +0,0 @@
-import type { FlowDerivation } from "./derivation";
-import type { FlowEffect } from "./effect";
-import type { FlowSignal } from "./signal";
-
-/**
- * Represents a tracking context used to register dependencies during reactive computations.
- *
- * @remarks
- * TrackingContext is the core mechanism that enables automatic dependency tracking in PicoFlow's
- * reactive system. When you create an effect or derivation, PicoFlow automatically creates and
- * manages a TrackingContext instance for you. This context is passed as a parameter (typically
- * named `t`) to your computation functions.
- *
- * You use the tracking context to explicitly mark which observables should be tracked as dependencies:
- * - Call `observable.get(t)` to read a value AND register it as a dependency
- * - Call `observable.pick()` to read a value WITHOUT registering it as a dependency
- * - Call `signal.watch(t)` to register a signal as a dependency without reading a value
- *
- * End-users typically don't instantiate TrackingContext directly; instead, they receive it as
- * a parameter in effect and derivation callbacks.
- *
- * @example
- * ```typescript
- * // TrackingContext passed as parameter 't'
- * effect((t) => {
- *   const value = $state.get(t);  // Tracked dependency
- *   const snapshot = $other.pick(); // Not tracked
- *   console.log(value, snapshot);
- * });
- * ```
- *
- * @public
- */
-export class TrackingContext {
-	/** @internal */
-	constructor(private _owner: FlowEffect | FlowDerivation<unknown>) {}
-
-	/**
-	 * Registers a dependency on the given signal.
-	 * @internal
-	 */
-	/** @internal */ _registerDependency(signal: FlowSignal): void {
-		this._owner._registerDependency(signal);
-	}
-}