@ersbeth/picoflow 0.2.4 → 1.0.1

package/src/basic/derivation.ts

@@ -1,103 +1,147 @@
-import { type FlowGetter, FlowObservable } from "./observable";
-import type { FlowWatcher } from "./signal";
+import { FlowObservable } from "./observable";
+import { TrackingContext } from "./trackingContext";
 
 /**
  * Represents a reactive derivation whose value is computed based on other reactive signals.
+ *
  * @remarks
- * It tracks dependencies automatically and recomputes its value when any dependency changes.
- * Use FlowDerivation to create derived values in a reactive manner. It lazily initializes the computed value,
- * ensuring that computations only occur when necessary.
- * @typeparam T - The type of the computed value.
+ * FlowDerivation creates a computed value that automatically tracks its dependencies and
+ * recomputes when any dependency changes. The computation is lazy: it doesn't execute until
+ * the value is first accessed (via `get()` or `pick()`), and subsequent accesses return the
+ * cached value until a dependency changes.
+ *
+ * **Lazy Initialization:**
+ * The compute function doesn't run immediately upon creation. It runs only when:
+ * - The value is first read via `get()` or `pick()`
+ * - The derivation is watched via `watch()`
+ *
+ * **Dirty Checking and Recomputation:**
+ * When a tracked dependency changes, the derivation is marked as "dirty" but doesn't recompute
+ * immediately. Recomputation happens lazily on the next value access. This prevents unnecessary
+ * computations when multiple dependencies change in quick succession.
+ *
+ * **Dynamic Dependencies:**
+ * Dependencies are tracked dynamically during each computation. If the compute function
+ * conditionally tracks different observables, the dependency graph updates automatically.
+ *
+ * @example
+ * ```typescript
+ * const $firstName = state('John');
+ * const $lastName = state('Doe');
+ *
+ * const $fullName = derivation((t) => {
+ *   return `${$firstName.get(t)} ${$lastName.get(t)}`;
+ * });
+ *
+ * // Compute function hasn't run yet (lazy)
+ * const name = $fullName.pick(); // Now it computes
+ * ```
+ *
+ * @typeParam T - The type of the computed value.
  * @public
  */
 export class FlowDerivation<T> extends FlowObservable<T> {
-    /**
-     * Creates a new FlowDerivation.
-     * @param compute - A function that computes the derived value. It is provided with two parameters:
-     * a getter and a watcher that respect dependency tracking.
-     * @public
-     */
-    constructor(compute: (get: FlowGetter, watch: FlowWatcher) => T) {
-        super();
-        this._initEager(compute);
-    }
+	/**
+	 * Creates a new FlowDerivation.
+	 *
+	 * @param compute - A function that computes the derived value using a tracking context.
+	 * The function receives a TrackingContext and should use it to access dependencies via
+	 * `.get(t)`. The function is not executed immediately; it runs lazily on first access.
+	 *
+	 * @public
+	 */
+	constructor(compute: (t: TrackingContext) => T) {
+		super();
+		this._compute = compute;
+		this._trackedContext = new TrackingContext(this);
+	}
 
-    /**
-     * Gets the current derived value.
-     * @returns The current computed value.
-     * @remarks
-     * This method lazily initializes and updates the derivation if it is marked as dirty. It throws an error
-     * if the derivation has been disposed.
-     * @public
-     */
-    public get(): T {
-        if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-        this._initLazy();
-        this._compute();
-        return this._value;
-    }
+	/**
+	 * Internal method to get the raw value.
+	 * @internal
+	 */
+	protected _getRaw(): T {
+		if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+		this._initLazy();
+		this._update();
+		return this._value;
+	}
 
-    /* INTERNAL --------------------------------------------------------- */
+	/* INTERNAL --------------------------------------------------------- */
 
-    private _initialized = false;
-    private _dirty = false;
+	private _initialized = false;
+	private _dirty = false;
+	private _compute: (t: TrackingContext) => T;
+	private _trackedContext: TrackingContext;
 
-    private _trackedGet: FlowGetter = (observable) => observable._getFrom(this);
-    private _trackedWatch: FlowWatcher = (signal) => signal._watchFrom(this);
-    private _untrackedGet: FlowGetter = (observable) => observable.get();
-    private _untrackedWatch: FlowWatcher = (signal) => signal._watch();
-    private _trackedCompute!: () => T;
-    private _untrackedCompute!: () => T;
+	private _initLazy(): void {
+		if (!this._initialized) {
+			this._value = this._compute(this._trackedContext);
+			this._initialized = true;
+		}
+	}
 
-    private _initEager(
-        compute: (get: FlowGetter, watch: FlowWatcher) => T,
-    ): void {
-        this._trackedCompute = () =>
-            compute(this._trackedGet, this._trackedWatch);
-        this._untrackedCompute = () =>
-            compute(this._untrackedGet, this._untrackedWatch);
-    }
+	/* @internal */ private _update(): void {
+		if (this._dirty) {
+			// Store current dependencies
+			const dependencies = [...this._dependencies];
 
-    private _initLazy(): void {
-        if (!this._initialized) {
-            this._value = this._trackedCompute();
-            this._initialized = true;
-        }
-    }
+			// Clear current dependencies, compute and retrack dependencies
+			this._dependencies.clear();
+			this._value = this._compute(this._trackedContext);
 
-    /* @internal */ _compute(): void {
-        if (this._dirty) {
-            // we cant use untrackedCompute because it will not track dependencies
-            // that changed dynamically
+			// Unsubscribe from dependencies that are no longer needed
+			const dependenciesToRemove = dependencies.filter(
+				(dependency) => !this._dependencies.has(dependency),
+			);
+			dependenciesToRemove.forEach((dependency) => {
+				dependency._unregisterDependency(this);
+			});
 
-            // store current dependencies
-            const dependencies = [...this._dependencies];
+			this._dirty = false;
+		}
+	}
 
-            // clear current dependencies, compute and retrack dependencies
-            this._dependencies.clear();
-            this._value = this._trackedCompute();
+	/* @internal */ override _notify(): void {
+		this._dirty = true;
+		super._notify();
+	}
 
-            // unsubscribe from dependencies that are no longer needed
-            const dependenciesToRemove = dependencies.filter(
-                (dependency) => !this._dependencies.has(dependency),
-            );
-            dependenciesToRemove.forEach((dependency) =>
-                dependency._unregisterDependency(this),
-            );
+	/**
+	 * Watches the derivation, registering it as a dependency in the given context.
+	 *
+	 * @param context - The tracking context in which to register this derivation.
+	 *
+	 * @remarks
+	 * This method overrides the base `watch()` to handle a special case: when a derivation
+	 * is watched without having its value read (e.g., `$derivation.watch(t)` instead of
+	 * `$derivation.get(t)`), the derivation still needs to compute its value to establish
+	 * its own dependencies. Otherwise, the derivation would be tracked but wouldn't track
+	 * its own dependencies, breaking the reactive chain.
+	 *
+	 * This override ensures that:
+	 * 1. The derivation is registered as a dependency in the provided context
+	 * 2. The derivation computes its value (if not already computed)
+	 * 3. The derivation tracks its own dependencies during computation
+	 *
+	 * @example
+	 * ```typescript
+	 * const $derived = derivation((t) => $state.get(t) * 2);
+	 *
+	 * effect((t) => {
+	 *   $derived.watch(t); // Derivation computes even without reading value
+	 *   doSomething();     // Effect re-runs when $derived's dependencies change
+	 * });
+	 * ```
+	 *
+	 * @public
+	 */
+	public override watch(context: TrackingContext): void {
+		super.watch(context); // Register this derivation as a dependency
 
-            this._dirty = false;
-        }
-    }
-
-    /* @internal */ override _notify(): void {
-        this._dirty = true;
-        super._notify();
-    }
-
-    /* @internal */ override _watch(): void {
-        /* v8 ignore next 1 */
-        if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-        this._initLazy();
-        this._compute();
-    }
+		// Ensure the derivation is initialized and up-to-date
+		// This is needed when watching a derivation without reading its value
+		this._initLazy();
+		this._update();
+	}
 }

package/src/basic/disposable.ts

@@ -1,27 +1,86 @@
 /**
- * Represents an object with a disposable lifecycle.
+ * Represents an object with a disposable lifecycle that manages resources requiring cleanup.
+ *
  * @remarks
- * Objects implementing this interface require explicit resource disposal.
+ * FlowDisposable is the interface for PicoFlow primitives that hold resources needing
+ * explicit cleanup. Implementing this interface ensures that objects can properly release
+ * resources such as subscriptions, event listeners, and dependent effects.
+ *
+ * **Disposal Behavior:**
+ * All PicoFlow reactive primitives (signals, states, effects, derivations, etc.) implement
+ * this interface. When disposed:
+ * - The primitive becomes unusable and throws errors on further access
+ * - All subscriptions and dependencies are cleaned up
+ * - Memory is freed for garbage collection
+ *
+ * **Options:**
+ * The optional `options` parameter controls disposal behavior:
+ * - `{ self: true }`: Dispose only this object, leaving dependent effects/listeners active
+ * - `{ self: false }` or omitted: Dispose this object AND all dependent effects/listeners (cascade)
+ *
+ * @example
+ * ```typescript
+ * const $state = state(0);
+ * const fx = effect((t) => console.log($state.get(t)));
+ *
+ * // Cascade disposal - disposes $state and all its effects
+ * $state.dispose();
+ *
+ * // Self-only disposal - disposes $state but leaves effects intact
+ * $state.dispose({ self: true });
+ * ```
+ *
  * @public
  */
 export interface FlowDisposable {
-    /**
-     * Disposes resources held by this object.
-     * @param options - Options to specify disposal behavior.
-     */
-    dispose(options?: { self: boolean }): void;
+	/**
+	 * Disposes resources held by this object.
+	 *
+	 * @param options - Optional configuration for disposal behavior.
+	 * @param options.self - When true, disposes only this object without cascading to dependents.
+	 * When false or omitted, disposes this object and all its dependent effects and listeners.
+	 *
+	 * @throws Error if the object has already been disposed (behavior may vary by implementation).
+	 */
+	dispose(options?: { self: boolean }): void;
 }
 
 /**
- * Checks whether an object implements the FlowDisposable interface.
- * @param obj - The object to test.
- * @returns True if the object has a dispose method, otherwise false.
+ * Type guard that checks whether an object implements the FlowDisposable interface.
+ *
+ * @param obj - The object to test for disposability.
+ * @returns True if the object has a `dispose` method and is therefore disposable, false otherwise.
+ *
+ * @remarks
+ * This utility function is useful for safely checking if an object needs disposal before
+ * attempting cleanup operations. It performs a runtime check for the presence of a `dispose`
+ * method, making it safe to use with unknown types.
+ *
+ * **Common Use Cases:**
+ * - Conditionally disposing items in collections (arrays, maps)
+ * - Generic cleanup functions that handle both disposable and non-disposable objects
+ * - Defensive programming when working with mixed types
+ *
+ * @example
+ * ```typescript
+ * function cleanupArray<T>(items: T[]) {
+ *   items.forEach(item => {
+ *     if (isDisposable(item)) {
+ *       item.dispose();
+ *     }
+ *   });
+ * }
+ *
+ * const mixed = [state(1), "string", signal(), 42];
+ * cleanupArray(mixed); // Only disposes the state and signal
+ * ```
+ *
  * @public
  */
 export function isDisposable(obj: unknown): obj is FlowDisposable {
-    return (
-        obj !== null &&
-        obj !== undefined &&
-        typeof (obj as FlowDisposable).dispose === "function"
-    );
+	return (
+		obj !== null &&
+		obj !== undefined &&
+		typeof (obj as FlowDisposable).dispose === "function"
+	);
 }

package/src/basic/effect.ts

@@ -1,96 +1,104 @@
-import type { FlowGetter } from "./observable";
-import type { FlowSignal, FlowWatcher } from "./signal";
+import type { FlowSignal } from "./signal";
+import { TrackingContext } from "./trackingContext";
 
 /**
  * Represents a reactive effect that executes side-effect functions based
  * on its tracked dependencies.
  *
  * @remarks
- * The FlowEffect executes an apply function that performs side effects,
- * running initially in a tracked mode to register dependencies and then in
- * an untracked mode to re-execute the effect on updates.
+ * FlowEffect executes an apply function that performs side effects. The effect always runs
+ * with a tracking context, allowing you to explicitly control which observables and signals
+ * become dependencies using `.get(t)` for tracked reads or `.pick()` for untracked reads.
+ *
+ * When any tracked dependency changes, the effect automatically re-executes. The effect
+ * runs immediately upon creation and whenever its dependencies trigger updates.
+ *
+ * Unlike the old API, effects in the new TrackingContext-based system always execute with
+ * a tracking context available. You control reactivity by choosing which observables to track
+ * within the effect body.
+ *
+ * @example
+ * ```typescript
+ * const fx = effect((t) => {
+ *   const reactive = $stateA.get(t);    // Tracked - effect re-runs when $stateA changes
+ *   const snapshot = $stateB.pick();    // Not tracked - changes don't trigger re-runs
+ *   console.log(reactive, snapshot);
+ * });
+ * ```
  *
  * @public
  */
 export class FlowEffect {
-    /**
-     * Creates a new FlowEffect.
-     *
-     * @param apply - A side-effect function that receives a getter and a watcher to
-     * access and register dependencies on reactive observables and signals.
-     *
-     * @remarks
-     * The provided function is executed immediately in a tracked mode to collect dependencies.
-     * On subsequent executions, it runs in an untracked mode.
-     *
-     * @public
-     */
-    constructor(apply: (get: FlowGetter, watch: FlowWatcher) => void) {
-        this._trackedExec = () => apply(this._trackedGet, this._trackedWatch);
-        this._untrackedExec = () =>
-            apply(this._untrackedGet, this._untrackedWatch);
-        this._exec();
-    }
+	/**
+	 * Creates a new FlowEffect.
+	 *
+	 * @param apply - A side-effect function that receives a tracking context to
+	 * access and register dependencies on reactive observables and signals.
+	 *
+	 * @remarks
+	 * The provided function is executed immediately upon construction with a tracking context.
+	 * Use the context parameter to call `.get(t)` on observables you want to track, or `.pick()`
+	 * on observables you want to read without creating dependencies.
+	 *
+	 * @public
+	 */
+	constructor(apply: (t: TrackingContext) => void) {
+		this._trackedContext = new TrackingContext(this);
+		this._apply = apply;
+		this._exec();
+	}
 
-    /**
-     * Disposes the effect, unregistering all its tracked dependencies.
-     *
-     * @remarks
-     * Once disposed, the effect must no longer be used. Trying to dispose an effect
-     * that is already disposed will throw an error.
-     *
-     * @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;
-    }
+	/**
+	 * Disposes the effect, unregistering all its tracked dependencies.
+	 *
+	 * @remarks
+	 * Once disposed, the effect must no longer be used. Trying to dispose an effect
+	 * that is already disposed will throw an error.
+	 *
+	 * @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;
+	}
 
-    /**
-     * Indicates whether this effect has been disposed.
-     *
-     * @returns A boolean value that is true if the effect is disposed, false otherwise.
-     *
-     * @public
-     */
-    public get disposed(): boolean {
-        return this._disposed;
-    }
+	/**
+	 * Indicates whether this effect has been disposed.
+	 *
+	 * @returns A boolean value that is true if the effect is disposed, false otherwise.
+	 *
+	 * @public
+	 */
+	public get disposed(): boolean {
+		return this._disposed;
+	}
 
-    /* INTERNAL ------------------------------------------------------------ */
+	/* INTERNAL ------------------------------------------------------------ */
 
-    private _disposed = false;
-    private _initialized = false;
-    private _dependencies = new Set<FlowSignal>();
+	private _disposed = false;
+	private _dependencies = new Set<FlowSignal>();
+	private _trackedContext: TrackingContext;
+	private _apply: (t: TrackingContext) => void;
 
-    private _trackedGet: FlowGetter = (observable) => observable._getFrom(this);
-    private _trackedWatch: FlowWatcher = (signal) => signal._watchFrom(this);
-    private _untrackedGet: FlowGetter = (observable) => observable.get();
-    private _untrackedWatch: FlowWatcher = (signal) => signal._watch();
-    private _trackedExec: () => void;
-    private _untrackedExec: () => void;
+	/** @internal */ _exec(): void {
+		if (this._disposed)
+			/* v8 ignore next 1 */
+			throw new Error("[PicoFlow] Effect is disposed");
 
-    /*@internal*/ _exec(): void {
-        if (this._disposed)
-            /* v8 ignore next 1 */
-            throw new Error("[PicoFlow] Effect is disposed");
-        if (this._initialized) this._untrackedExec();
-        else {
-            this._trackedExec();
-            this._initialized = true;
-        }
-    }
+		// Always execute with tracking context
+		this._apply(this._trackedContext);
+	}
 
-    /*@internal*/ _registerDependency(dependency: FlowSignal): void {
-        this._dependencies.add(dependency);
-        dependency._registerEffect(this);
-    }
+	/** @internal */ _registerDependency(dependency: FlowSignal): void {
+		this._dependencies.add(dependency);
+		dependency._registerEffect(this);
+	}
 
-    /*@internal*/ _unregisterDependency(dependency: FlowSignal): void {
-        this._dependencies.delete(dependency);
-        dependency._unregisterEffect(this);
-    }
+	/** @internal */ _unregisterDependency(dependency: FlowSignal): void {
+		this._dependencies.delete(dependency);
+		dependency._unregisterEffect(this);
+	}
 }

package/src/basic/index.ts

@@ -1,10 +1,9 @@
-export { FlowSignal } from "./signal";
-export { FlowState } from "./state";
-export { FlowObservable } from "./observable";
-export { FlowDerivation } from "./derivation";
-export { FlowEffect } from "./effect";
 export { FlowConstant } from "./constant";
-export { isDisposable } from "./disposable";
-export type { FlowGetter } from "./observable";
-export type { FlowWatcher } from "./signal";
+export { FlowDerivation } from "./derivation";
 export type { FlowDisposable } from "./disposable";
+export { isDisposable } from "./disposable";
+export { FlowEffect } from "./effect";
+export { FlowObservable } from "./observable";
+export { FlowSignal } from "./signal";
+export { FlowState } from "./state";
+export { TrackingContext } from "./trackingContext";