@ersbeth/picoflow 1.0.1 → 1.1.0

package/src/advanced/map.ts

@@ -1,193 +0,0 @@
-import { FlowState, isDisposable } from "../basic/";
-
-/**
- * Represents a reactive map that extends {@link FlowState} for tracking key-value pairs.
- *
- * @remarks
- * FlowMap wraps a native JavaScript Map and provides reactive tracking at multiple granularity levels.
- * Unlike plain reactive state, FlowMap offers fine-grained reactivity that lets you track:
- *
- * 1. **Whole map changes**: Via `get(t)` or `pick()` on the FlowMap itself
- * 2. **Last add operation**: Via the `$lastAdded` signal, track which key-value pair was most recently added
- * 3. **Last update operation**: Via the `$lastUpdated` signal, track which key-value pair was most recently updated
- * 4. **Last delete operation**: Via the `$lastDeleted` signal, track which key-value pair was most recently removed
- *
- * **Reactive Signals:**
- * - **$lastAdded**: A FlowState containing `{ key?: K, value?: V }` updated on each `add()` call
- * - **$lastUpdated**: A FlowState containing `{ key?: K, value?: V }` updated on each `update()` call
- * - **$lastDeleted**: A FlowState containing `{ key?: K, value?: V }` updated on each `delete()` call
- *
- * These signals enable fine-grained reactivity patterns where effects can respond to specific
- * map operations without re-processing the entire map.
- *
- * **Use Cases:**
- * - Entity stores where you want to track additions/removals separately
- * - Cache implementations with granular invalidation
- * - Collections where operations on individual keys matter
- * - UI state where you want to animate specific additions or removals
- *
- * @example
- * ```typescript
- * const $users = map<string, User>();
- *
- * // Track the whole map
- * effect((t) => {
- *   const users = $users.get(t);
- *   console.log(`Total users: ${users.size}`);
- * });
- *
- * // Track only additions
- * effect((t) => {
- *   const { key, value } = $users.$lastAdded.get(t);
- *   if (key && value) {
- *     console.log(`User ${key} was added:`, value);
- *   }
- * });
- *
- * // Track only updates
- * effect((t) => {
- *   const { key, value } = $users.$lastUpdated.get(t);
- *   if (key && value) {
- *     console.log(`User ${key} was updated:`, value);
- *   }
- * });
- *
- * // Track only deletions
- * effect((t) => {
- *   const { key, value } = $users.$lastDeleted.get(t);
- *   if (key && value) {
- *     console.log(`User ${key} was deleted:`, value);
- *   }
- * });
- *
- * // Modify the map
- * $users.add('user1', { name: 'John', age: 30 });
- * $users.add('user2', { name: 'Jane', age: 25 });
- * $users.update('user1', { name: 'John', age: 31 });
- * $users.delete('user1');
- * ```
- *
- * @typeParam K - The type of the map keys.
- * @typeParam V - The type of the map values.
- *
- * @public
- */
-export class FlowMap<K, V> extends FlowState<Map<K, V>> {
-	/**
-	 * A reactive state that holds the most recent key and value that were added.
-	 *
-	 * @remarks
-	 * When a key is added via {@link FlowMap.add}, this state is updated with
-	 * the corresponding key and value.
-	 *
-	 * @public
-	 */
-	public $lastAdded = new FlowState<{ key: K; value: V } | null>(null);
-
-	/**
-	 * A reactive state that holds the most recent key and value that were updated.
-	 *
-	 * @remarks
-	 * When a key is updated via {@link FlowMap.update}, this state is updated with
-	 * the corresponding key and value.
-	 *
-	 * @public
-	 */
-	public $lastUpdated = new FlowState<{ key: K; value: V } | null>(null);
-
-	/**
-	 * A reactive state that holds the most recent key and value that were deleted.
-	 *
-	 * @remarks
-	 * When a key is deleted via {@link FlowMap.delete}, this state is updated with
-	 * the corresponding key and its last known value.
-	 *
-	 * @public
-	 */
-	public $lastDeleted = new FlowState<{ key: K; value: V } | null>(null);
-
-	/**
-	 * Adds a new key-value pair to the map.
-	 *
-	 * @param key - The key to add.
-	 * @param value - The value to associate with the key.
-	 * @throws If the FlowMap instance is disposed.
-	 * @throws If the key already exists in the map.
-	 *
-	 * @remarks
-	 * Adds a new entry to the internal map, emits the key-value pair via {@link FlowMap.$lastAdded},
-	 * and notifies all subscribers of the change.
-	 *
-	 * @public
-	 */
-	public add(key: K, value: V): void {
-		if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-		if (this._value.has(key)) {
-			throw new Error("[PicoFlow] Key already exists");
-		}
-		this._value.set(key, value);
-		this.$lastAdded.set({ key, value });
-		this._notify();
-	}
-
-	/**
-	 * Updates an existing key-value pair in the map.
-	 *
-	 * @param key - The key to update.
-	 * @param value - The new value to associate with the key.
-	 * @throws If the FlowMap instance is disposed.
-	 * @throws If the key does not exist in the map.
-	 *
-	 * @remarks
-	 * Updates an existing entry in the internal map, emits the key-value pair via {@link FlowMap.$lastUpdated},
-	 * and notifies all subscribers of the change.
-	 *
-	 * @public
-	 */
-	public update(key: K, value: V): void {
-		if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-		if (!this._value.has(key)) {
-			throw new Error("[PicoFlow] Key does not exist");
-		}
-		this._value.set(key, value);
-		this.$lastUpdated.set({ key, value });
-		this._notify();
-	}
-
-	/**
-	 * Deletes the value at the specified key from the underlying map.
-	 *
-	 * @param key - The key to delete.
-	 * @throws If the FlowMap instance is disposed.
-	 *
-	 * @remarks
-	 * Removes the key from the internal map, emits the deleted key and its value via {@link FlowMap.$lastDeleted},
-	 * and notifies all subscribers of the change.
-	 *
-	 * @public
-	 */
-	public delete(key: K): void {
-		if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-		const value = this._value.get(key);
-		if (!value) throw new Error("[PicoFlow] Key does not exist");
-		this._value.delete(key);
-		this.$lastDeleted.set({ key, value });
-		this._notify();
-	}
-
-	/**
-	 * Disposes the FlowMap and its values.
-	 * @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.clear();
-		this.$lastAdded.dispose(options);
-		this.$lastUpdated.dispose(options);
-		this.$lastDeleted.dispose(options);
-	}
-}

package/src/basic/constant.ts

@@ -1,97 +0,0 @@
-import { FlowObservable } from "./observable";
-
-/**
- * Represents a reactive and immutable constant value that can be computed lazily upon first access.
- *
- * @remarks
- * FlowConstant extends FlowObservable to provide an immutable reactive value. Unlike {@link FlowState},
- * which is mutable via the `set()` method, a constant's value never changes after initialization.
- *
- * **Initialization Patterns:**
- * - **Direct value**: Pass a value directly; it's stored immediately.
- * - **Lazy initialization**: Pass a function; it's called only when the value is first accessed
- *   via `get()` or `pick()`.
- *
- * **Lazy Evaluation Benefits:**
- * Lazy initialization is useful when:
- * - The computation is expensive and may not be needed immediately
- * - The value depends on resources that aren't available at construction time
- * - You want to defer computation until the value is actually needed
- *
- * **Caching:**
- * Once computed (either immediately or lazily), the value is cached permanently. All subsequent
- * accesses return the cached value without re-computation.
- *
- * **Use Cases:**
- * - Configuration values that don't change
- * - Expensive computations that should only run once
- * - Initialization values for other reactive primitives
- *
- * @example
- * ```typescript
- * // Direct value - initialized immediately
- * const $config = constant({ apiUrl: 'https://api.example.com' });
- *
- * // Lazy initialization - computed on first access
- * const $expensiveValue = constant(() => {
- *   console.log('Computing...');
- *   return performExpensiveCalculation();
- * });
- *
- * $expensiveValue.pick(); // Logs: "Computing..."
- * $expensiveValue.pick(); // No log - returns cached value
- * ```
- *
- * @typeParam T - The type of the constant value.
- *
- * @public
- */
-export class FlowConstant<T> extends FlowObservable<T> {
-	/**
-	 * Creates a new FlowConstant instance.
-	 *
-	 * @param value - Either a direct value of type T or a function returning a value of type T.
-	 * If a function is provided, it will be invoked lazily on the first value access.
-	 * If a direct value is provided, it is stored immediately.
-	 *
-	 * @public
-	 */
-	constructor(value: T | (() => T)) {
-		super();
-		this._initEager(value);
-	}
-
-	/**
-	 * Internal method to get the raw value.
-	 * @internal
-	 */
-	protected _getRaw(): T {
-		if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-		this._initLazy();
-		return this._value;
-	}
-
-	/* INTERNAL --------------------------------------------------------- */
-
-	/** @internal */ protected _initialized = false;
-	/** @internal */ protected _init?: () => T;
-
-	/** @internal */ protected _initEager(value: T | (() => T)): void {
-		if (typeof value === "function") {
-			this._init = value as () => T;
-		} else {
-			this._value = value;
-			this._initialized = true;
-		}
-	}
-
-	/** @internal */ protected _initLazy(): void {
-		if (!this._initialized && this._init) {
-			this._value = this._init();
-			this._initialized = true;
-		}
-		/* v8 ignore next 2 */
-		if (!this._initialized)
-			throw new Error("[PicoFlow] Primitive can't be initialized");
-	}
-}

package/src/basic/derivation.ts

@@ -1,147 +0,0 @@
-import { FlowObservable } from "./observable";
-import { TrackingContext } from "./trackingContext";
-
-/**
- * Represents a reactive derivation whose value is computed based on other reactive signals.
- *
- * @remarks
- * 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 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);
-	}
-
-	/**
-	 * 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 --------------------------------------------------------- */
-
-	private _initialized = false;
-	private _dirty = false;
-	private _compute: (t: TrackingContext) => T;
-	private _trackedContext: TrackingContext;
-
-	private _initLazy(): void {
-		if (!this._initialized) {
-			this._value = this._compute(this._trackedContext);
-			this._initialized = true;
-		}
-	}
-
-	/* @internal */ private _update(): void {
-		if (this._dirty) {
-			// Store current dependencies
-			const dependencies = [...this._dependencies];
-
-			// Clear current dependencies, compute and retrack dependencies
-			this._dependencies.clear();
-			this._value = this._compute(this._trackedContext);
-
-			// Unsubscribe from dependencies that are no longer needed
-			const dependenciesToRemove = dependencies.filter(
-				(dependency) => !this._dependencies.has(dependency),
-			);
-			dependenciesToRemove.forEach((dependency) => {
-				dependency._unregisterDependency(this);
-			});
-
-			this._dirty = false;
-		}
-	}
-
-	/* @internal */ override _notify(): void {
-		this._dirty = true;
-		super._notify();
-	}
-
-	/**
-	 * 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
-
-		// 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,86 +0,0 @@
-/**
- * Represents an object with a disposable lifecycle that manages resources requiring cleanup.
- *
- * @remarks
- * 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 - 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;
-}
-
-/**
- * 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"
-	);
-}

package/src/basic/effect.ts

@@ -1,104 +0,0 @@
-import type { FlowSignal } from "./signal";
-import { TrackingContext } from "./trackingContext";
-
-/**
- * Represents a reactive effect that executes side-effect functions based
- * on its tracked dependencies.
- *
- * @remarks
- * 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 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;
-	}
-
-	/**
-	 * 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 ------------------------------------------------------------ */
-
-	private _disposed = false;
-	private _dependencies = new Set<FlowSignal>();
-	private _trackedContext: TrackingContext;
-	private _apply: (t: TrackingContext) => void;
-
-	/** @internal */ _exec(): void {
-		if (this._disposed)
-			/* v8 ignore next 1 */
-			throw new Error("[PicoFlow] Effect is disposed");
-
-		// Always execute with tracking context
-		this._apply(this._trackedContext);
-	}
-
-	/** @internal */ _registerDependency(dependency: FlowSignal): void {
-		this._dependencies.add(dependency);
-		dependency._registerEffect(this);
-	}
-
-	/** @internal */ _unregisterDependency(dependency: FlowSignal): void {
-		this._dependencies.delete(dependency);
-		dependency._unregisterEffect(this);
-	}
-}

package/src/basic/index.ts

@@ -1,9 +0,0 @@
-export { FlowConstant } from "./constant";
-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";