@ersbeth/picoflow 0.2.4 → 1.0.0

package/dist/picoflow.js

@@ -1,4 +1,87 @@
-import { createSignal, createResource, createMemo, onMount, onCleanup } from 'solid-js';
+import { createMemo, createResource, createSignal, onMount, onCleanup } from 'solid-js';
+
+class TrackingContext {
+  /** @internal */
+  constructor(_owner) {
+    this._owner = _owner;
+  }
+  /**
+   * Registers a dependency on the given signal.
+   * @internal
+   */
+  /** @internal */
+  _registerDependency(signal) {
+    this._owner._registerDependency(signal);
+  }
+}
+
+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) {
+    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
+   */
+  dispose() {
+    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
+   */
+  get disposed() {
+    return this._disposed;
+  }
+  /* INTERNAL ------------------------------------------------------------ */
+  _disposed = false;
+  _dependencies = /* @__PURE__ */ new Set();
+  _trackedContext;
+  _apply;
+  /** @internal */
+  _exec() {
+    if (this._disposed)
+      throw new Error("[PicoFlow] Effect is disposed");
+    this._apply(this._trackedContext);
+  }
+  /** @internal */
+  _registerDependency(dependency) {
+    this._dependencies.add(dependency);
+    dependency._registerEffect(this);
+  }
+  /** @internal */
+  _unregisterDependency(dependency) {
+    this._dependencies.delete(dependency);
+    dependency._unregisterEffect(this);
+  }
+}
 
 class FlowSignal {
   /**
@@ -11,6 +94,43 @@ class FlowSignal {
     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
+   */
+  watch(context) {
+    if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    context._registerDependency(this);
+  }
   /**
    * Disposes the FlowSignal.
    * Cleans up all registered effects, listeners, and dependencies.
@@ -21,17 +141,19 @@ class FlowSignal {
   dispose(options) {
     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)
-      );
+      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._effects).forEach((effect) => {
+        effect.dispose();
+      });
+      Array.from(this._listeners).forEach((listener) => {
+        listener.dispose();
+      });
     }
     Array.from(this._dependencies).forEach((dependency) => {
       this._unregisterDependency(dependency);
@@ -47,141 +169,115 @@ class FlowSignal {
     return this._disposed;
   }
   /* INTERNAL ------------------------------------------------------------- */
-  /*@internal*/
+  /** @internal */
   _disposed = false;
-  /*@internal*/
+  /** @internal */
   _dependencies = /* @__PURE__ */ new Set();
-  /*@internal*/
+  /** @internal */
   _listeners = /* @__PURE__ */ new Set();
-  /*@internal*/
+  /** @internal */
   _effects = /* @__PURE__ */ new Set();
-  /*@internal*/
-  _watch() {
-    if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-  }
-  /*@internal*/
+  /** @internal */
   _notify() {
-    this._listeners.forEach((listener) => listener._notify());
-    this._effects.forEach((effect) => effect._exec());
-  }
-  /*@internal*/
-  _watchFrom(listener) {
-    listener._registerDependency(this);
-    this._watch();
+    this._listeners.forEach((listener) => {
+      listener._notify();
+    });
+    this._effects.forEach((effect) => {
+      effect._exec();
+    });
   }
-  /*@internal*/
+  /** @internal */
   _registerDependency(dependency) {
     this._dependencies.add(dependency);
     dependency._registerListener(this);
   }
-  /*@internal*/
+  /** @internal */
   _unregisterDependency(dependency) {
     this._dependencies.delete(dependency);
     dependency._unregisterListener(this);
   }
-  /*@internal*/
+  /** @internal */
   _registerListener(signal) {
     this._listeners.add(signal);
   }
-  /*@internal*/
+  /** @internal */
   _unregisterListener(signal) {
     this._listeners.delete(signal);
   }
-  /*@internal*/
+  /** @internal */
   _registerEffect(effect) {
     this._effects.add(effect);
   }
-  /*@internal*/
+  /** @internal */
   _unregisterEffect(effect) {
     this._effects.delete(effect);
   }
 }
 
-class FlowEffect {
+class FlowObservable extends FlowSignal {
   /**
-   * Creates a new FlowEffect.
+   * Gets the current value with optional dependency tracking.
    *
-   * @param apply - A side-effect function that receives a getter and a watcher to
-   * access and register dependencies on reactive observables and signals.
+   * @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
-   * The provided function is executed immediately in a tracked mode to collect dependencies.
-   * On subsequent executions, it runs in an untracked mode.
+   * 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
    */
-  constructor(apply) {
-    this._trackedExec = () => apply(this._trackedGet, this._trackedWatch);
-    this._untrackedExec = () => apply(this._untrackedGet, this._untrackedWatch);
-    this._exec();
+  get(context) {
+    if (context) {
+      this.watch(context);
+    }
+    return this._getRaw();
   }
   /**
-   * Disposes the effect, unregistering all its tracked dependencies.
+   * Gets the current value without any dependency tracking.
+   *
+   * @returns The current value of type T.
    *
    * @remarks
-   * Once disposed, the effect must no longer be used. Trying to dispose an effect
-   * that is already disposed will throw an error.
+   * 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
    *
-   * @public
-   */
-  dispose() {
-    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.
+   * @example
+   * ```typescript
+   * // Read a snapshot outside reactive context
+   * const currentValue = $state.pick();
    *
-   * @returns A boolean value that is true if the effect is disposed, false otherwise.
+   * // 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
    */
-  get disposed() {
-    return this._disposed;
-  }
-  /* INTERNAL ------------------------------------------------------------ */
-  _disposed = false;
-  _initialized = false;
-  _dependencies = /* @__PURE__ */ new Set();
-  _trackedGet = (observable) => observable._getFrom(this);
-  _trackedWatch = (signal) => signal._watchFrom(this);
-  _untrackedGet = (observable) => observable.get();
-  _untrackedWatch = (signal) => signal._watch();
-  _trackedExec;
-  _untrackedExec;
-  /*@internal*/
-  _exec() {
-    if (this._disposed)
-      throw new Error("[PicoFlow] Effect is disposed");
-    if (this._initialized) this._untrackedExec();
-    else {
-      this._trackedExec();
-      this._initialized = true;
-    }
-  }
-  /*@internal*/
-  _registerDependency(dependency) {
-    this._dependencies.add(dependency);
-    dependency._registerEffect(this);
-  }
-  /*@internal*/
-  _unregisterDependency(dependency) {
-    this._dependencies.delete(dependency);
-    dependency._unregisterEffect(this);
+  pick() {
+    return this._getRaw();
   }
-}
-
-class FlowObservable extends FlowSignal {
   /* INTERNAL -------------------------------------------*/
-  /*@internal*/
+  /** @internal */
   _value;
-  /*@internal*/
-  _getFrom(listener) {
-    listener._registerDependency(this);
-    return this.get();
-  }
   /**
    * Subscribes a listener function to changes of the observable.
    * The listener is executed immediately with the current value and on subsequent updates.
@@ -189,8 +285,8 @@ class FlowObservable extends FlowSignal {
    * @returns A disposer function to cancel the subscription.
    */
   subscribe(listener) {
-    const effect = new FlowEffect((get) => {
-      listener(get(this));
+    const effect = new FlowEffect((t) => {
+      listener(this.get(t));
     });
     return () => effect.dispose();
   }
@@ -200,7 +296,10 @@ class FlowConstant extends FlowObservable {
   /**
    * 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.
+   * @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) {
@@ -208,26 +307,20 @@ class FlowConstant extends FlowObservable {
     this._initEager(value);
   }
   /**
-   * 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.
-   *
-   * @returns The cached constant value.
-   * @throws Error if the constant is disposed or cannot be initialized.
-   * @public
+   * Internal method to get the raw value.
+   * @internal
    */
-  get() {
+  _getRaw() {
     if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
     this._initLazy();
     return this._value;
   }
   /* INTERNAL --------------------------------------------------------- */
-  /*@internal*/
+  /** @internal */
   _initialized = false;
-  /*@internal*/
+  /** @internal */
   _init;
-  /*@internal*/
+  /** @internal */
   _initEager(value) {
     if (typeof value === "function") {
       this._init = value;
@@ -236,7 +329,7 @@ class FlowConstant extends FlowObservable {
       this._initialized = true;
     }
   }
-  /*@internal*/
+  /** @internal */
   _initLazy() {
     if (!this._initialized && this._init) {
       this._value = this._init();
@@ -247,81 +340,54 @@ class FlowConstant extends FlowObservable {
   }
 }
 
-class FlowState extends FlowConstant {
-  /**
-   * 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) {
-    if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-    const next = typeof value === "function" ? value(this._value) : value;
-    if (next === this._value) return;
-    this._value = next;
-    this._notify();
-  }
-}
-
 class FlowDerivation extends FlowObservable {
   /**
    * 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) {
     super();
-    this._initEager(compute);
+    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
+   * Internal method to get the raw value.
+   * @internal
    */
-  get() {
+  _getRaw() {
     if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
     this._initLazy();
-    this._compute();
+    this._update();
     return this._value;
   }
   /* INTERNAL --------------------------------------------------------- */
   _initialized = false;
   _dirty = false;
-  _trackedGet = (observable) => observable._getFrom(this);
-  _trackedWatch = (signal) => signal._watchFrom(this);
-  _untrackedGet = (observable) => observable.get();
-  _untrackedWatch = (signal) => signal._watch();
-  _trackedCompute;
-  _untrackedCompute;
-  _initEager(compute) {
-    this._trackedCompute = () => compute(this._trackedGet, this._trackedWatch);
-    this._untrackedCompute = () => compute(this._untrackedGet, this._untrackedWatch);
-  }
+  _compute;
+  _trackedContext;
   _initLazy() {
     if (!this._initialized) {
-      this._value = this._trackedCompute();
+      this._value = this._compute(this._trackedContext);
       this._initialized = true;
     }
   }
   /* @internal */
-  _compute() {
+  _update() {
     if (this._dirty) {
       const dependencies = [...this._dependencies];
       this._dependencies.clear();
-      this._value = this._trackedCompute();
+      this._value = this._compute(this._trackedContext);
       const dependenciesToRemove = dependencies.filter(
         (dependency) => !this._dependencies.has(dependency)
       );
-      dependenciesToRemove.forEach(
-        (dependency) => dependency._unregisterDependency(this)
-      );
+      dependenciesToRemove.forEach((dependency) => {
+        dependency._unregisterDependency(this);
+      });
       this._dirty = false;
     }
   }
@@ -330,259 +396,99 @@ class FlowDerivation extends FlowObservable {
     this._dirty = true;
     super._notify();
   }
-  /* @internal */
-  _watch() {
-    if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-    this._initLazy();
-    this._compute();
-  }
-}
-
-function isDisposable(obj) {
-  return obj !== null && obj !== void 0 && typeof obj.dispose === "function";
-}
-
-class FlowMap extends FlowState {
-  /**
-   * A reactive state that holds the most recent key and value that were set.
-   *
-   * @remarks
-   * When a key is set via {@link FlowMap.setAt}, this state is updated with
-   * the corresponding key and value.
-   *
-   * @public
-   */
-  $lastSet = new FlowState({});
-  /**
-   * 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
-   */
-  $lastDeleted = new FlowState({});
   /**
-   * Sets a value at the specified key in the underlying map.
+   * Watches the derivation, registering it as a dependency in the given context.
    *
-   * @param key - The key at which to set the value.
-   * @param value - The value to set.
-   * @throws If the FlowMap instance is disposed.
+   * @param context - The tracking context in which to register this derivation.
    *
    * @remarks
-   * Updates the internal map, emits the key-value pair via {@link FlowMap.$lastSet},
-   * and notifies all subscribers of the change.
+   * 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.
    *
-   * @public
-   */
-  setAt(key, value) {
-    if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-    this._value.set(key, value);
-    this.$lastSet.set({ key, value });
-    this._notify();
-  }
-  /**
-   * Deletes the value at the specified key from the underlying map.
+   * 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
    *
-   * @param key - The key to delete.
-   * @throws If the FlowMap instance is disposed.
+   * @example
+   * ```typescript
+   * const $derived = derivation((t) => $state.get(t) * 2);
    *
-   * @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.
+   * effect((t) => {
+   *   $derived.watch(t); // Derivation computes even without reading value
+   *   doSomething();     // Effect re-runs when $derived's dependencies change
+   * });
+   * ```
    *
    * @public
    */
-  delete(key) {
-    if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-    const value = this._value.get(key);
-    this._value.delete(key);
-    this.$lastDeleted.set({ key, value });
-    this._notify();
+  watch(context) {
+    super.watch(context);
+    this._initLazy();
+    this._update();
   }
 }
 
-class FlowStream extends FlowObservable {
-  /**
-   * Creates a new FlowStream.
-   * @param updater - A function that receives a setter to update the stream's value.
-   * It should return a disposer function that will be called upon disposal.
-   * @public
-   */
-  constructor(updater) {
-    super();
-    this._disposer = updater((value) => {
-      this._set(value);
-    });
-  }
-  /**
-   * Retrieves the current value of the stream.
-   * @returns The current value, or undefined if no value has been set yet.
-   * @throws Error if the stream is disposed.
-   * @public
-   */
-  get() {
-    if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-    return this._value;
-  }
+function isDisposable(obj) {
+  return obj !== null && obj !== void 0 && typeof obj.dispose === "function";
+}
+
+class FlowState extends FlowConstant {
   /**
-   * Disposes the stream, releasing all resources.
+   * 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
-   * In addition to disposing the underlying observable, this method calls the disposer
-   * returned by the updater.
+   * 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
    */
-  dispose() {
-    super.dispose();
-    this._disposer();
-  }
-  /* INTERNAL ------------------------------------------------------ */
-  _disposer;
-  _set(value) {
+  set(value) {
     if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-    if (value === this._value) return;
-    this._value = value;
+    const next = typeof value === "function" ? value(this._value) : value;
+    if (next === this._value) return;
+    this._value = next;
     this._notify();
   }
 }
 
-class FlowStreamAsync extends FlowObservable {
-  /**
-   * Creates a new asynchronous FlowStream.
-   * @param updater - A function that receives a setter to update the stream's value.
-   * It should return a disposer function that will be called upon disposal.
-   * @remarks The updater function can invoke the setter asynchronously to update the stream.
-   * @public
-   */
-  constructor(updater) {
-    super();
-    this._disposer = updater((value) => {
-      this._set(value);
-    });
-    this._value = new Promise((resolve) => {
-      this._resolve = resolve;
-    });
-  }
-  /**
-   * Retrieves the current value of the stream as a Promise.
-   * @returns A Promise that resolves to the current value.
-   * @throws Error if the stream is disposed.
-   * @public
-   */
-  get() {
-    if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-    return this._value;
-  }
-  /**
-   * Disposes the stream, releasing all resources.
-   * @remarks In addition to disposing the underlying observable, this method calls the disposer
-   * returned by the updater.
-   * @public
-   */
-  dispose() {
-    super.dispose();
-    this._disposer();
-  }
-  /* INTERNAL ------------------------------------------------------ */
-  _initialized = false;
-  _awaitedValue;
-  _resolve;
-  _disposer;
-  _set(value) {
-    if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-    if (!this._initialized) {
-      this._resolve(value);
-      this._initialized = true;
-      this._awaitedValue = value;
-      this._notify();
-      return;
-    }
-    if (value === this._awaitedValue) return;
-    this._value = Promise.resolve(value);
-    this._awaitedValue = value;
-    this._notify();
-  }
+function signal() {
+  return new FlowSignal();
 }
-
-class FlowResource extends FlowObservable {
-  /**
-   * Creates a new FlowResource.
-   * @param fetch - An asynchronous function that retrieves the resource's value.
-   *
-   * @public
-   */
-  constructor(fetch) {
-    super();
-    this._fetch = fetch;
-  }
-  /**
-   * Retrieves the current resource value.
-   * @returns The current value, or undefined if the resource has not been fetched yet.
-   * @throws Error if the resource is disposed.
-   * @public
-   */
-  get() {
-    if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-    return this._value;
-  }
-  /**
-   * Asynchronously fetches a new value for the resource.
-   * @remarks
-   * Executes the internal fetch function. If the fetched value differs from the current one,
-   * updates the resource's value and notifies subscribers.
-   * @returns A Promise that resolves when the fetch operation is complete.
-   * @throws Error if the resource is disposed.
-   * @public
-   */
-  async fetch() {
-    if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-    const value = await this._fetch();
-    if (value === this._value) return;
-    this._value = value;
-    this._notify();
-  }
-  /* INTERNAL ------------------------------------------------ */
-  _fetch;
+function constant(value) {
+  return new FlowConstant(value);
 }
-
-class FlowResourceAsync extends FlowObservable {
-  /**
-   * Creates a new FlowResource.
-   * @param fetch - An asynchronous function that retrieves the resource's value.
-   * @public
-   */
-  constructor(fetch) {
-    super();
-    this._fetch = fetch;
-  }
-  /**
-   * Retrieves the current resource value.
-   * @returns The current value, or undefined if the resource has not been fetched yet.
-   * @throws Error if the resource is disposed.
-   * @public
-   */
-  get() {
-    if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-    if (!this._value) this._value = this._fetch();
-    return this._value;
-  }
-  /**
-   * Asynchronously fetches a new value for the resource.
-   * @remarks
-   * Executes the internal fetch function. If the fetched value differs from the current one,
-   * updates the resource's value and notifies subscribers.
-   * @returns A Promise that resolves when the fetch operation is complete.
-   * @throws Error if the resource is disposed.
-   * @public
-   */
-  async fetch() {
-    if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-    this._value = this._fetch();
-    this._notify();
-  }
-  /* INTERNAL ------------------------------------------------ */
-  _fetch;
+function state(value) {
+  return new FlowState(value);
+}
+function resource(fn) {
+  return new FlowResource(fn);
+}
+function resourceAsync(fn) {
+  return new FlowResourceAsync(fn);
+}
+function stream(updater) {
+  return new FlowStream(updater);
+}
+function streamAsync(updater) {
+  return new FlowStreamAsync(updater);
+}
+function derivation(fn) {
+  return new FlowDerivation(fn);
+}
+function effect(fn) {
+  return new FlowEffect(fn);
+}
+function map(initial) {
+  return new FlowMap(
+    new Map(initial ? Object.entries(initial) : [])
+  );
+}
+function array(initial) {
+  return new FlowArray(initial);
 }
 
 class FlowArray extends FlowObservable {
@@ -614,11 +520,10 @@ class FlowArray extends FlowObservable {
     return this._value.length;
   }
   /**
-   * Returns a copy of the internal array.
-   * @returns A copy of the array.
-   * @public
+   * Internal method to get the raw value.
+   * @internal
    */
-  get() {
+  _getRaw() {
     if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
     return [...this._value];
   }
@@ -747,44 +652,313 @@ class FlowArray extends FlowObservable {
     this._value = [];
   }
   /* INTERNAL */
-  /*@internal*/
+  /** @internal */
   _value = [];
 }
 
-function signal() {
-  return new FlowSignal();
-}
-function constant(value) {
-  return new FlowConstant(value);
-}
-function state(value) {
-  return new FlowState(value);
-}
-function resource(fn) {
-  return new FlowResource(fn);
-}
-function resourceAsync(fn) {
-  return new FlowResourceAsync(fn);
-}
-function stream(updater) {
-  return new FlowStream(updater);
-}
-function streamAsync(updater) {
-  return new FlowStreamAsync(updater);
+class FlowMap extends FlowState {
+  /**
+   * 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
+   */
+  $lastAdded = new FlowState(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
+   */
+  $lastUpdated = new FlowState(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
+   */
+  $lastDeleted = new FlowState(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
+   */
+  add(key, value) {
+    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
+   */
+  update(key, value) {
+    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
+   */
+  delete(key) {
+    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
+   */
+  dispose(options) {
+    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);
+  }
 }
-function derivation(fn) {
-  return new FlowDerivation(fn);
+
+class FlowResource extends FlowObservable {
+  /**
+   * Creates a new FlowResource.
+   *
+   * @param fetch - An asynchronous function that retrieves the resource's value.
+   * This function is not invoked on construction; you must call the `fetch()` method
+   * to execute it.
+   *
+   * @public
+   */
+  constructor(fetch) {
+    super();
+    this._fetch = fetch;
+  }
+  /**
+   * Internal method to get the raw value.
+   * @internal
+   */
+  _getRaw() {
+    if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    return this._value;
+  }
+  /**
+   * Asynchronously fetches a new value for the resource.
+   * @remarks
+   * Executes the internal fetch function. If the fetched value differs from the current one,
+   * updates the resource's value and notifies subscribers.
+   * @returns A Promise that resolves when the fetch operation is complete.
+   * @throws Error if the resource is disposed.
+   * @public
+   */
+  async fetch() {
+    if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    const value = await this._fetch();
+    if (value === this._value) return;
+    this._value = value;
+    this._notify();
+  }
+  /* INTERNAL ------------------------------------------------ */
+  _fetch;
 }
-function effect(fn) {
-  return new FlowEffect(fn);
+
+class FlowResourceAsync extends FlowObservable {
+  /**
+   * Creates a new FlowResource.
+   * @param fetch - An asynchronous function that retrieves the resource's value.
+   * @public
+   */
+  constructor(fetch) {
+    super();
+    this._fetch = fetch;
+  }
+  /**
+   * Internal method to get the raw value.
+   * @internal
+   */
+  _getRaw() {
+    if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    if (!this._value) this._value = this._fetch();
+    return this._value;
+  }
+  /**
+   * Asynchronously fetches a new value for the resource.
+   * @remarks
+   * Executes the internal fetch function. If the fetched value differs from the current one,
+   * updates the resource's value and notifies subscribers.
+   * @returns A Promise that resolves when the fetch operation is complete.
+   * @throws Error if the resource is disposed.
+   * @public
+   */
+  async fetch() {
+    if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    this._value = this._fetch();
+    this._notify();
+  }
+  /* INTERNAL ------------------------------------------------ */
+  _fetch;
 }
-function map(initial) {
-  return new FlowMap(
-    new Map(initial ? Object.entries(initial) : [])
-  );
+
+class FlowStream extends FlowObservable {
+  /**
+   * Creates a new FlowStream.
+   *
+   * @param updater - A function that receives a setter callback and returns a disposer.
+   * The setter should be called whenever new data is available. The disposer will be
+   * invoked when the stream is disposed to clean up resources.
+   *
+   * @remarks
+   * The updater is invoked immediately during construction. Make sure to return a proper
+   * cleanup function to avoid resource leaks.
+   *
+   * @public
+   */
+  constructor(updater) {
+    super();
+    this._disposer = updater((value) => {
+      this._set(value);
+    });
+  }
+  /**
+   * Internal method to get the raw value.
+   * @internal
+   */
+  _getRaw() {
+    if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    return this._value;
+  }
+  /**
+   * Disposes the stream, releasing all resources.
+   * @remarks
+   * In addition to disposing the underlying observable, this method calls the disposer
+   * returned by the updater.
+   * @public
+   */
+  dispose() {
+    super.dispose();
+    this._disposer();
+  }
+  /* INTERNAL ------------------------------------------------------ */
+  _disposer;
+  _set(value) {
+    if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    if (value === this._value) return;
+    this._value = value;
+    this._notify();
+  }
 }
-function array(initial) {
-  return new FlowArray(initial);
+
+class FlowStreamAsync extends FlowObservable {
+  /**
+   * Creates a new asynchronous FlowStream.
+   *
+   * @param updater - A function that receives a setter callback and returns a disposer.
+   * The setter should be called whenever new data is available (can be called asynchronously).
+   * The disposer will be invoked when the stream is disposed to clean up resources.
+   *
+   * @remarks
+   * The updater is invoked immediately during construction. An initial Promise is created
+   * that will resolve when the setter is first called. Make sure to return a proper cleanup
+   * function to avoid resource leaks.
+   *
+   * @public
+   */
+  constructor(updater) {
+    super();
+    this._disposer = updater((value) => {
+      this._set(value);
+    });
+    this._value = new Promise((resolve) => {
+      this._resolve = resolve;
+    });
+  }
+  /**
+   * Internal method to get the raw value.
+   * @internal
+   */
+  _getRaw() {
+    if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    return this._value;
+  }
+  /**
+   * Disposes the stream, releasing all resources.
+   * @remarks In addition to disposing the underlying observable, this method calls the disposer
+   * returned by the updater.
+   * @public
+   */
+  dispose() {
+    super.dispose();
+    this._disposer();
+  }
+  /* INTERNAL ------------------------------------------------------ */
+  _initialized = false;
+  _awaitedValue;
+  _resolve;
+  _disposer;
+  _set(value) {
+    if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    if (!this._initialized) {
+      this._resolve(value);
+      this._initialized = true;
+      this._awaitedValue = value;
+      this._notify();
+      return;
+    }
+    if (value === this._awaitedValue) return;
+    this._value = Promise.resolve(value);
+    this._awaitedValue = value;
+    this._notify();
+  }
 }
 
 class SolidState {
@@ -851,11 +1025,11 @@ class SolidResource {
 }
 
 function fromSync(state) {
-  const solidState = new SolidState(state.get());
+  const solidState = new SolidState(state.pick());
   let fx;
   onMount(() => {
-    fx = new FlowEffect((get) => {
-      const value = get(state);
+    fx = new FlowEffect((t) => {
+      const value = state.get(t);
       solidState.set(() => value);
     });
   });
@@ -864,13 +1038,13 @@ function fromSync(state) {
 }
 function fromAsync(derivation) {
   const solidResource = new SolidResource(async () => {
-    const value = await derivation.get();
+    const value = await derivation.pick();
     return value;
   });
   let fx;
   onMount(() => {
-    fx = new FlowEffect(async (get) => {
-      await get(derivation);
+    fx = new FlowEffect(async (t) => {
+      await derivation.get(t);
       solidResource.refetch();
     });
   });
@@ -878,7 +1052,7 @@ function fromAsync(derivation) {
   return solidResource;
 }
 function shallowFrom(flow) {
-  const initialValue = flow.get();
+  const initialValue = flow.pick();
   const isAsync = initialValue instanceof Promise;
   if (isAsync) {
     return fromAsync(flow);
@@ -886,10 +1060,10 @@ function shallowFrom(flow) {
   return fromSync(flow);
 }
 function deepFrom(getter) {
-  const derivation = new FlowDerivation((get) => {
-    return getter(get);
+  const derivation = new FlowDerivation((t) => {
+    return getter(t);
   });
-  const initialValue = derivation.get();
+  const initialValue = derivation.pick();
   const isAsync = initialValue instanceof Promise;
   if (isAsync) {
     return fromAsync(derivation);
@@ -903,4 +1077,4 @@ function from(flow) {
   return deepFrom(flow);
 }
 
-export { FlowArray, FlowConstant, FlowDerivation, FlowEffect, FlowMap, FlowObservable, FlowResource, FlowResourceAsync, FlowSignal, FlowState, FlowStream, FlowStreamAsync, SolidDerivation, SolidResource, SolidState, array, constant, derivation, effect, from, isDisposable, map, resource, resourceAsync, signal, state, stream, streamAsync };
+export { FlowArray, FlowConstant, FlowDerivation, FlowEffect, FlowMap, FlowObservable, FlowResource, FlowResourceAsync, FlowSignal, FlowState, FlowStream, FlowStreamAsync, SolidDerivation, SolidResource, SolidState, TrackingContext, array, constant, derivation, effect, from, isDisposable, map, resource, resourceAsync, signal, state, stream, streamAsync };