@ersbeth/picoflow 0.2.4 → 1.0.1

package/dist/types/basic/constant.d.ts

@@ -1,11 +1,47 @@
 import { FlowObservable } from './observable';
 /**
- * Represents a reactive and immutable constant value computed lazily upon first access.
+ * Represents a reactive and immutable constant value that can be computed lazily upon first access.
  *
- * @remarks This class extends FlowObservable and supports initializing the constant using either a direct value
- * or a lazy initializer function. Once computed, the value is cached for all subsequent accesses.
+ * @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.
  *
- * @typeparam T - The type of the constant value.
+ * **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
  */
@@ -13,20 +49,12 @@ export declare 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 for lazy initialization.
-     * @public
-     */
-    constructor(value: T | (() => T));
-    /**
-     * Retrieves the constant value, computing it lazily if needed.
-     *
-     * Accessing this method will initialize the value if it has not been computed already.
-     * Throws an error if the instance has been disposed or if lazy initialization fails.
+     * @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.
      *
-     * @returns The cached constant value.
-     * @throws Error if the constant is disposed or cannot be initialized.
      * @public
      */
-    get(): T;
+    constructor(value: T | (() => T));
 }
 //# sourceMappingURL=constant.d.ts.map

package/dist/types/basic/constant.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constant.d.ts","sourceRoot":"","sources":["../../../src/basic/constant.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE9C;;;;;;;;;GASG;AACH,qBAAa,YAAY,CAAC,CAAC,CAAE,SAAQ,cAAc,CAAC,CAAC,CAAC;IAClD;;;;;OAKG;gBACS,KAAK,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAKhC;;;;;;;;;OASG;IACH,GAAG,IAAI,CAAC;CA6BX"}
+{"version":3,"file":"constant.d.ts","sourceRoot":"","sources":["../../../src/basic/constant.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,qBAAa,YAAY,CAAC,CAAC,CAAE,SAAQ,cAAc,CAAC,CAAC,CAAC;IACrD;;;;;;;;OAQG;gBACS,KAAK,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;CAsChC"}

package/dist/types/basic/derivation.d.ts

@@ -1,40 +1,89 @@
-import { FlowGetter, FlowObservable } from './observable';
-import { 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 declare 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.
+     *
+     * @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: (get: FlowGetter, watch: FlowWatcher) => T);
+    constructor(compute: (t: TrackingContext) => T);
+    private _initialized;
+    private _dirty;
+    private _compute;
+    private _trackedContext;
+    private _initLazy;
     /**
-     * Gets the current derived value.
-     * @returns The current computed value.
+     * 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 lazily initializes and updates the derivation if it is marked as dirty. It throws an error
-     * if the derivation has been disposed.
+     * 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
      */
-    get(): T;
-    private _initialized;
-    private _dirty;
-    private _trackedGet;
-    private _trackedWatch;
-    private _untrackedGet;
-    private _untrackedWatch;
-    private _trackedCompute;
-    private _untrackedCompute;
-    private _initEager;
-    private _initLazy;
+    watch(context: TrackingContext): void;
 }
 //# sourceMappingURL=derivation.d.ts.map

package/dist/types/basic/derivation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"derivation.d.ts","sourceRoot":"","sources":["../../../src/basic/derivation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,UAAU,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC/D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAE5C;;;;;;;;GAQG;AACH,qBAAa,cAAc,CAAC,CAAC,CAAE,SAAQ,cAAc,CAAC,CAAC,CAAC;IACpD;;;;;OAKG;gBACS,OAAO,EAAE,CAAC,GAAG,EAAE,UAAU,EAAE,KAAK,EAAE,WAAW,KAAK,CAAC;IAK/D;;;;;;;OAOG;IACI,GAAG,IAAI,CAAC;IASf,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,MAAM,CAAS;IAEvB,OAAO,CAAC,WAAW,CAAyD;IAC5E,OAAO,CAAC,aAAa,CAAoD;IACzE,OAAO,CAAC,aAAa,CAAgD;IACrE,OAAO,CAAC,eAAe,CAA4C;IACnE,OAAO,CAAC,eAAe,CAAW;IAClC,OAAO,CAAC,iBAAiB,CAAW;IAEpC,OAAO,CAAC,UAAU;IASlB,OAAO,CAAC,SAAS;CA0CpB"}
+{"version":3,"file":"derivation.d.ts","sourceRoot":"","sources":["../../../src/basic/derivation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,qBAAa,cAAc,CAAC,CAAC,CAAE,SAAQ,cAAc,CAAC,CAAC,CAAC;IACvD;;;;;;;;OAQG;gBACS,OAAO,EAAE,CAAC,CAAC,EAAE,eAAe,KAAK,CAAC;IAmB9C,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,QAAQ,CAA4B;IAC5C,OAAO,CAAC,eAAe,CAAkB;IAEzC,OAAO,CAAC,SAAS;IAiCjB;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACa,KAAK,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI;CAQrD"}

package/dist/types/basic/disposable.d.ts

@@ -1,22 +1,81 @@
 /**
- * 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.
+     *
+     * @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 declare function isDisposable(obj: unknown): obj is FlowDisposable;

package/dist/types/basic/disposable.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"disposable.d.ts","sourceRoot":"","sources":["../../../src/basic/disposable.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC3B;;;OAGG;IACH,OAAO,CAAC,OAAO,CAAC,EAAE;QAAE,IAAI,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;CAC9C;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,cAAc,CAMhE"}
+{"version":3,"file":"disposable.d.ts","sourceRoot":"","sources":["../../../src/basic/disposable.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,WAAW,cAAc;IAC9B;;;;;;;;OAQG;IACH,OAAO,CAAC,OAAO,CAAC,EAAE;QAAE,IAAI,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;CAC3C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,cAAc,CAMhE"}

package/dist/types/basic/effect.d.ts

@@ -1,13 +1,28 @@
-import { FlowGetter } from './observable';
-import { FlowWatcher } 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
  */
@@ -15,16 +30,17 @@ export declare class FlowEffect {
     /**
      * Creates a new FlowEffect.
      *
-     * @param apply - A side-effect function that receives a getter and a watcher to
+     * @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 in a tracked mode to collect dependencies.
-     * On subsequent executions, it runs in an untracked mode.
+     * 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: (get: FlowGetter, watch: FlowWatcher) => void);
+    constructor(apply: (t: TrackingContext) => void);
     /**
      * Disposes the effect, unregistering all its tracked dependencies.
      *
@@ -44,13 +60,8 @@ export declare class FlowEffect {
      */
     get disposed(): boolean;
     private _disposed;
-    private _initialized;
     private _dependencies;
-    private _trackedGet;
-    private _trackedWatch;
-    private _untrackedGet;
-    private _untrackedWatch;
-    private _trackedExec;
-    private _untrackedExec;
+    private _trackedContext;
+    private _apply;
 }
 //# sourceMappingURL=effect.d.ts.map

package/dist/types/basic/effect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"effect.d.ts","sourceRoot":"","sources":["../../../src/basic/effect.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,KAAK,EAAc,WAAW,EAAE,MAAM,UAAU,CAAC;AAExD;;;;;;;;;;GAUG;AACH,qBAAa,UAAU;IACnB;;;;;;;;;;;OAWG;gBACS,KAAK,EAAE,CAAC,GAAG,EAAE,UAAU,EAAE,KAAK,EAAE,WAAW,KAAK,IAAI;IAOhE;;;;;;;;OAQG;IACI,OAAO,IAAI,IAAI;IAQtB;;;;;;OAMG;IACH,IAAW,QAAQ,IAAI,OAAO,CAE7B;IAID,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,aAAa,CAAyB;IAE9C,OAAO,CAAC,WAAW,CAAyD;IAC5E,OAAO,CAAC,aAAa,CAAoD;IACzE,OAAO,CAAC,aAAa,CAAgD;IACrE,OAAO,CAAC,eAAe,CAA4C;IACnE,OAAO,CAAC,YAAY,CAAa;IACjC,OAAO,CAAC,cAAc,CAAa;CAsBtC"}
+{"version":3,"file":"effect.d.ts","sourceRoot":"","sources":["../../../src/basic/effect.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,UAAU;IACtB;;;;;;;;;;;;OAYG;gBACS,KAAK,EAAE,CAAC,CAAC,EAAE,eAAe,KAAK,IAAI;IAM/C;;;;;;;;OAQG;IACI,OAAO,IAAI,IAAI;IAQtB;;;;;;OAMG;IACH,IAAW,QAAQ,IAAI,OAAO,CAE7B;IAID,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,aAAa,CAAyB;IAC9C,OAAO,CAAC,eAAe,CAAkB;IACzC,OAAO,CAAC,MAAM,CAA+B;CAoB7C"}

package/dist/types/basic/index.d.ts

@@ -1,11 +1,10 @@
-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';
 //# sourceMappingURL=index.d.ts.map

package/dist/types/basic/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/basic/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACtC,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACtC,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,YAAY,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,YAAY,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAC5C,YAAY,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/basic/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,YAAY,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACtC,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACtC,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/types/basic/observable.d.ts

@@ -1,28 +1,77 @@
 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 { 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.
  *
- * @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.
+ * 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 declare abstract class FlowObservable<T> extends FlowSignal {
     /**
-     * Retrieves the current value stored in the observable.
-     * Subclasses must override this method to provide the current value.
+     * 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;
+    /**
+     * 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
      */
-    abstract get(): T;
+    pick(): T;
     /**
      * Subscribes a listener function to changes of the observable.
      * The listener is executed immediately with the current value and on subsequent updates.

package/dist/types/basic/observable.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"observable.d.ts","sourceRoot":"","sources":["../../../src/basic/observable.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAEtC;;;;;;GAMG;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,EAAE,UAAU,EAAE,cAAc,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;AAEjE;;;;;;;GAOG;AACH,8BAAsB,cAAc,CAAC,CAAC,CAAE,SAAQ,UAAU;IACtD;;;;;OAKG;IACH,QAAQ,CAAC,GAAG,IAAI,CAAC;IAWjB;;;;;OAKG;IACH,SAAS,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,GAAG,MAAM,IAAI;CAMtD"}
+{"version":3,"file":"observable.d.ts","sourceRoot":"","sources":["../../../src/basic/observable.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACtC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEzD;;;;;;;;;;;;;;;;;GAiBG;AACH,8BAAsB,cAAc,CAAC,CAAC,CAAE,SAAQ,UAAU;IACzD;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,GAAG,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI,GAAG,CAAC;IAOvC;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,IAAI,IAAI,CAAC;IAeT;;;;;OAKG;IACH,SAAS,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,GAAG,MAAM,IAAI;CAMnD"}

package/dist/types/basic/signal.d.ts

@@ -1,10 +1,5 @@
 import { FlowDisposable } from './disposable';
-/**
- * A function for watching a FlowSignal.
- * @param signal - The FlowSignal that is being observed.
- * @public
- */
-export type FlowWatcher = (signal: FlowSignal) => void;
+import { TrackingContext } from './trackingContext';
 /**
  * Represents a reactive signal.
  *
@@ -20,6 +15,40 @@ export declare class FlowSignal implements FlowDisposable {
      * @public
      */
     trigger(): void;
+    /**
+     * 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
+     */
+    watch(context: TrackingContext): void;
     /**
      * Disposes the FlowSignal.
      * Cleans up all registered effects, listeners, and dependencies.

package/dist/types/basic/signal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"signal.d.ts","sourceRoot":"","sources":["../../../src/basic/signal.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAGnD;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,MAAM,EAAE,UAAU,KAAK,IAAI,CAAC;AAEvD;;;;;;GAMG;AACH,qBAAa,UAAW,YAAW,cAAc;IAC7C;;;;;OAKG;IACI,OAAO,IAAI,IAAI;IAKtB;;;;;;OAMG;IACI,OAAO,CAAC,OAAO,CAAC,EAAE;QAAE,IAAI,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI;IAqBjD;;;;OAIG;IACH,IAAW,QAAQ,IAAI,OAAO,CAE7B;CAoDJ"}
+{"version":3,"file":"signal.d.ts","sourceRoot":"","sources":["../../../src/basic/signal.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEnD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEzD;;;;;;GAMG;AACH,qBAAa,UAAW,YAAW,cAAc;IAChD;;;;;OAKG;IACI,OAAO,IAAI,IAAI;IAKtB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;IACI,KAAK,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI;IAK5C;;;;;;OAMG;IACI,OAAO,CAAC,OAAO,CAAC,EAAE;QAAE,IAAI,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI;IAuBjD;;;;OAIG;IACH,IAAW,QAAQ,IAAI,OAAO,CAE7B;CA8CD"}

package/dist/types/basic/state.d.ts

@@ -2,12 +2,33 @@ 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
  */

package/dist/types/basic/state.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../../src/basic/state.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE1C;;;;;;;;;;;GAWG;AACH,qBAAa,SAAS,CAAC,CAAC,CAAE,SAAQ,YAAY,CAAC,CAAC,CAAC;IAC7C;;;;;;;;OAQG;IACH,GAAG,CAAC,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,IAAI;CAc5C"}
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../../src/basic/state.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,qBAAa,SAAS,CAAC,CAAC,CAAE,SAAQ,YAAY,CAAC,CAAC,CAAC;IAChD;;;;;;;;OAQG;IACH,GAAG,CAAC,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,IAAI;CAczC"}

package/dist/types/basic/trackingContext.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 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 declare class TrackingContext {
+    private _owner;
+}
+//# sourceMappingURL=trackingContext.d.ts.map

package/dist/types/basic/trackingContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trackingContext.d.ts","sourceRoot":"","sources":["../../../src/basic/trackingContext.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBAAa,eAAe;IAEf,OAAO,CAAC,MAAM;CAS1B"}