@ersbeth/picoflow 0.2.4 → 1.0.0

package/src/basic/observable.ts

@@ -1,51 +1,109 @@
 import { FlowEffect } from "./effect";
 import { FlowSignal } from "./signal";
-
-/**
- * A function that retrieves the current value from a FlowObservable.
- * @typeparam T - The type of the value held by the observable.
- * @param observable - The FlowObservable instance to retrieve the value from.
- * @returns The current value of the observable.
- * @public
- */
-export type FlowGetter = <T>(observable: FlowObservable<T>) => T;
+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:
  *
- * @remarks Subclasses must implement the {@link FlowObservable.get} method to return the current value.
- * @typeparam T - The type of the value held by the observable.
+ * 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 {
-    /**
-     * Retrieves the current value stored in the observable.
-     * Subclasses must override this method to provide the current value.
-     * @returns The current value of type T.
-     * @public
-     */
-    abstract get(): T;
+	/**
+	 * 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 -------------------------------------------*/
+	/**
+	 * Internal method to retrieve the raw value.
+	 * Subclasses must override this method to provide the current value.
+	 * @internal
+	 */
+	protected abstract _getRaw(): T;
 
-    /*@internal*/ protected _value!: T;
+	/* INTERNAL -------------------------------------------*/
 
-    /*@internal*/ _getFrom(listener: FlowObservable<unknown> | FlowEffect): T {
-        listener._registerDependency(this);
-        return this.get();
-    }
+	/** @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((get) => {
-            listener(get(this));
-        });
-        return () => effect.dispose();
-    }
+	/**
+	 * 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,12 +1,6 @@
 import type { FlowDisposable } from "./disposable";
 import type { FlowEffect } from "./effect";
-
-/**
- * A function for watching a FlowSignal.
- * @param signal - The FlowSignal that is being observed.
- * @public
- */
-export type FlowWatcher = (signal: FlowSignal) => void;
+import type { TrackingContext } from "./trackingContext";
 
 /**
  * Represents a reactive signal.
@@ -16,102 +10,136 @@ export type FlowWatcher = (signal: FlowSignal) => void;
  * @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();
-    }
-
-    /**
-     * 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*/ _watch(): void {
-        /* v8 ignore next 1 */
-        if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-    }
-
-    /*@internal*/ _notify(): void {
-        this._listeners.forEach((listener) => listener._notify());
-        this._effects.forEach((effect) => effect._exec());
-    }
-
-    /*@internal*/ _watchFrom(listener: FlowSignal | FlowEffect): void {
-        listener._registerDependency(this);
-        this._watch();
-    }
-
-    /*@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);
-    }
+	/**
+	 * 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

@@ -3,37 +3,58 @@ import { FlowConstant } from "./constant";
 /**
  * Represents a reactive state that holds a mutable value.
  *
- * @typeparam T - The type of the state value.
+ * @typeParam T - The type of the state value.
  *
  * @remarks
- * FlowState extends FlowConstant, which provides the {@link FlowConstant.get} method to read
- * the current state. Use the {@link FlowState.set} method to update the state. When the state is updated,
- * subscribers are notified automatically. This class notifies subscribers only when the value changes.
+ * 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");
+	/**
+	 * 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;
+		// 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();
-    }
+		// apply new value
+		if (next === this._value) return;
+		this._value = next;
+		this._notify();
+	}
 }

package/src/basic/trackingContext.ts

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