@ersbeth/picoflow 1.0.1 → 1.1.0

package/dist/picoflow.js

@@ -1,45 +1,228 @@
-import { createMemo, createResource, createSignal, onMount, onCleanup } from 'solid-js';
+function isDisposable(obj) {
+  return obj !== null && obj !== void 0 && typeof obj.dispose === "function";
+}
 
-class TrackingContext {
-  /** @internal */
-  constructor(_owner) {
-    this._owner = _owner;
+class FlowGraph {
+  static _effectsQueue = [];
+  static _actionQueue = [];
+  static _processingActionQueue = false;
+  /**
+   * Resets all internal queues and processing state.
+   *
+   * @remarks
+   * Use this method primarily for testing scenarios where you need to ensure
+   * a clean state between test runs. It clears pending effects and queued
+   * operations.
+   *
+   * @example
+   * ```typescript
+   * beforeEach(() => {
+   *   FlowGraph.clear();
+   * });
+   * ```
+   *
+   * @public
+   */
+  static clear() {
+    FlowGraph._effectsQueue = [];
+    FlowGraph._actionQueue = [];
+    FlowGraph._processingActionQueue = false;
   }
   /**
-   * Registers a dependency on the given signal.
-   * @internal
+   * Queues a trigger notification for processing.
+   *
+   * @param notify - Function to call when the trigger is processed.
+   * @returns A promise that resolves after the trigger is processed.
+   *
+   * @remarks
+   * This method is used internally by reactive primitives to coordinate
+   * signal triggers. The promise resolves after all associated effects
+   * have been executed.
+   *
+   * @public
    */
-  /** @internal */
-  _registerDependency(signal) {
-    this._owner._registerDependency(signal);
+  static requestTrigger(notify) {
+    const promiseWithResolvers = Promise.withResolvers();
+    FlowGraph._actionQueue.push({
+      ...promiseWithResolvers,
+      type: "trigger",
+      notify
+    });
+    FlowGraph._processActionQueue();
+    return promiseWithResolvers.promise;
+  }
+  /**
+   * Queues a read operation for processing.
+   *
+   * @param read - Function that performs the read operation.
+   * @returns A promise that resolves with the read value.
+   *
+   * @remarks
+   * This method is used internally by reactive primitives to coordinate
+   * read operations. The read function is executed and its result (or promise)
+   * is returned.
+   *
+   * @public
+   */
+  static requestRead(read) {
+    const promiseWithResolvers = Promise.withResolvers();
+    FlowGraph._actionQueue.push({
+      ...promiseWithResolvers,
+      type: "read",
+      read
+    });
+    FlowGraph._processActionQueue();
+    return promiseWithResolvers.promise;
   }
+  /**
+   * Queues a write operation with update logic for processing.
+   *
+   * @param notify - Function to call if the update succeeds.
+   * @param update - Function that performs the update and returns whether
+   * it changed the value.
+   * @returns A promise that resolves after the write is processed.
+   *
+   * @remarks
+   * This method is used internally by reactive primitives to coordinate
+   * write operations. The update function is executed, and if it returns true
+   * (or a promise resolving to true), the notify function is called to
+   * trigger dependent effects.
+   *
+   * @public
+   */
+  static requestWrite(notify, update) {
+    const promiseWithResolvers = Promise.withResolvers();
+    FlowGraph._actionQueue.push({
+      ...promiseWithResolvers,
+      type: "write",
+      notify,
+      update
+    });
+    FlowGraph._processActionQueue();
+    return promiseWithResolvers.promise;
+  }
+  /**
+   * Queues effects for execution after the current operation completes.
+   *
+   * @param effects - Array of effects to queue for execution.
+   *
+   * @remarks
+   * This method is used internally by reactive primitives to schedule effect
+   * execution. Effects are executed after the current read/write/trigger
+   * operation completes, ensuring proper ordering of reactive updates.
+   *
+   * @public
+   */
+  static pushEffects(effects) {
+    FlowGraph._effectsQueue.push(...effects);
+  }
+  /** @internal */
+  static _processActionQueue = async () => {
+    if (FlowGraph._processingActionQueue) return;
+    FlowGraph._processingActionQueue = true;
+    while (FlowGraph._actionQueue.length > 0) {
+      const actionRequest = FlowGraph._actionQueue.shift();
+      if (!actionRequest) break;
+      if (actionRequest.type === "read") {
+        try {
+          const read = actionRequest.read();
+          let value;
+          if (read instanceof Promise) {
+            value = await read;
+          } else {
+            value = read;
+          }
+          actionRequest.resolve(value);
+        } catch (error) {
+          const safeError = error instanceof Error ? error : new Error(String(error));
+          actionRequest.reject(safeError);
+        }
+        continue;
+      }
+      if (actionRequest.type === "write") {
+        try {
+          const updateResult = actionRequest.update();
+          let updated = false;
+          if (updateResult instanceof Promise) {
+            updated = await updateResult;
+          } else {
+            updated = updateResult;
+          }
+          if (!updated) {
+            actionRequest.resolve();
+            continue;
+          }
+          actionRequest.notify();
+        } catch (error) {
+          const safeError = error instanceof Error ? error : new Error(String(error));
+          actionRequest.reject(safeError);
+          continue;
+        }
+      }
+      if (actionRequest.type === "trigger") {
+        actionRequest.notify();
+      }
+      let effectError = null;
+      for (const effect of FlowGraph._effectsQueue) {
+        try {
+          await effect._requestExec();
+        } catch (error) {
+          effectError = error instanceof Error ? error : new Error(String(error));
+          break;
+        }
+      }
+      FlowGraph._effectsQueue = [];
+      if (effectError) {
+        actionRequest.reject(effectError);
+      } else {
+        actionRequest.resolve();
+      }
+    }
+    FlowGraph._processingActionQueue = false;
+  };
 }
 
 class FlowEffect {
+  _disposed = false;
+  _dependencies = /* @__PURE__ */ new Set();
+  _apply;
+  settled;
   /**
-   * Creates a new FlowEffect.
+   * Creates a new effect and runs it once immediately.
    *
-   * @param apply - A side-effect function that receives a tracking context to
-   * access and register dependencies on reactive observables and signals.
+   * @param apply - Side-effect function receiving the tracking context (`t`).
+   * It can be sync or async (returning `Promise<void>`).
    *
    * @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.
+   * Use `t` to opt-in to reactive tracking:
+   * - `observable.get(t)` / `signal.watch(t)` to re-run when they change
+   * - `observable.pick()` for reads that should not re-run the effect
+   *
+   * The effect schedules its first run during construction. Each subsequent
+   * change to a tracked dependency queues another run.
    *
    * @public
    */
   constructor(apply) {
-    this._trackedContext = new TrackingContext(this);
     this._apply = apply;
-    this._exec();
+    this.settled = FlowGraph.requestRead(() => this._exec());
   }
   /**
-   * Disposes the effect, unregistering all its tracked dependencies.
+   * Stops the effect and detaches it from all 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.
+   * Call this when the effect's work is no longer needed (e.g., component
+   * unmount, teardown of a feature). After disposal:
+   * - The effect will not re-run.
+   * - All dependency links are removed.
+   * - Calling `dispose()` again throws an error.
+   *
+   * @example
+   * ```typescript
+   * const fx = effect((t) => $signal.watch(t));
+   * // ... later
+   * fx.dispose();
+   * ```
    *
    * @public
    */
@@ -51,25 +234,19 @@ class FlowEffect {
     this._disposed = true;
   }
   /**
-   * Indicates whether this effect has been disposed.
+   * Whether the effect has been disposed.
    *
-   * @returns A boolean value that is true if the effect is disposed, false otherwise.
+   * @returns `true` once disposal has run; `false` while the effect is active.
    *
    * @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);
+  async _requestExec() {
+    this.settled = this._exec();
+    return this.settled;
   }
   /** @internal */
   _registerDependency(dependency) {
@@ -81,61 +258,95 @@ class FlowEffect {
     this._dependencies.delete(dependency);
     dependency._unregisterEffect(this);
   }
+  async _exec() {
+    if (this._disposed)
+      throw new Error("[PicoFlow] Effect is disposed");
+    const result = this._apply(this);
+    if (result instanceof Promise) {
+      await result;
+    }
+  }
+}
+function effect(fn) {
+  return new FlowEffect(fn);
 }
 
 class FlowSignal {
   /**
-   * Triggers the FlowSignal.
-   * Notifies all registered listeners and schedules execution of associated effects.
-   * @throws If the FlowSignal has already been disposed.
+   * Triggers the signal and notifies all dependents.
+   *
+   * @remarks
+   * Any effect/derivation that called `watch(t)` on this signal will re-run.
+   * Returns a promise that settles after notifications complete.
+   *
+   * @throws Error if the signal is disposed.
+   *
+   * @example
+   * ```typescript
+   * const $tick = signal();
+   *
+   * effect((t) => {
+   *   $tick.watch(t);
+   *   console.log("tick");
+   * });
+   *
+   * $tick.trigger(); // logs "tick"
+   * ```
+   *
    * @public
    */
-  trigger() {
+  async trigger() {
     if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-    this._notify();
+    return FlowGraph.requestTrigger(() => this._notify());
   }
   /**
-   * Watches the signal, registering it as a dependency in the tracking context.
+   * Registers this signal as a dependency in the current tracking context.
    *
-   * @param context - The tracking context in which to register this signal as a dependency.
+   * @param context - The tracking context (`t`) provided to effects/derivations.
    *
    * @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.
+   * Signals have no value to read; calling `watch(t)` simply means “re-run me
+   * when this signal is triggered.” Call this inside an effect/derivation
+   * callback where a tracking context is available.
    *
    * @throws Error if the signal has been disposed.
    *
    * @example
    * ```typescript
-   * const $signal = signal();
+   * const $refresh = signal();
    *
    * effect((t) => {
-   *   $signal.watch(t);  // Track the signal
-   *   console.log('Signal triggered!');
+   *   $refresh.watch(t);
+   *   console.log("refresh triggered");
    * });
    *
-   * $signal.trigger(); // Logs: "Signal triggered!"
+   * $refresh.trigger(); // logs "refresh triggered"
    * ```
    *
    * @public
    */
-  watch(context) {
+  watch(caller) {
     if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-    context._registerDependency(this);
+    caller._registerDependency(this);
   }
   /**
-   * Disposes the FlowSignal.
-   * Cleans up all registered effects, listeners, and dependencies.
-   * Once disposed, further usage of the signal will throw an error.
-   * @throws If the FlowSignal is already disposed.
+   * Disposes the signal and cleans up its dependencies/listeners.
+   *
+   * @remarks
+   * After disposal the signal must not be used; calling `trigger` or `watch`
+   * will throw. If `options?.self` is true, only this signal is disposed; when
+   * false or omitted, dependents may also be disposed depending on the
+   * implementation.
+   *
+   * @throws Error if the signal is already disposed.
+   *
+   * @example
+   * ```typescript
+   * const $refresh = signal();
+   * // ... use it
+   * $refresh.dispose();
+   * ```
+   *
    * @public
    */
   dispose(options) {
@@ -161,30 +372,27 @@ class FlowSignal {
     this._disposed = true;
   }
   /**
-   * Indicates whether the FlowSignal has been disposed.
-   * @remarks Once disposed, the signal should not be used.
+   * Whether the signal has been disposed.
+   *
+   * @returns `true` if disposed; `false` while active.
+   *
+   * @remarks Use to guard operations or avoid double disposal.
+   *
    * @public
    */
   get disposed() {
     return this._disposed;
   }
   /* INTERNAL ------------------------------------------------------------- */
-  /** @internal */
   _disposed = false;
-  /** @internal */
   _dependencies = /* @__PURE__ */ new Set();
-  /** @internal */
   _listeners = /* @__PURE__ */ new Set();
-  /** @internal */
   _effects = /* @__PURE__ */ new Set();
-  /** @internal */
   _notify() {
+    FlowGraph.pushEffects(Array.from(this._effects));
     this._listeners.forEach((listener) => {
       listener._notify();
     });
-    this._effects.forEach((effect) => {
-      effect._exec();
-    });
   }
   /** @internal */
   _registerDependency(dependency) {
@@ -197,12 +405,12 @@ class FlowSignal {
     dependency._unregisterListener(this);
   }
   /** @internal */
-  _registerListener(signal) {
-    this._listeners.add(signal);
+  _registerListener(signal2) {
+    this._listeners.add(signal2);
   }
   /** @internal */
-  _unregisterListener(signal) {
-    this._listeners.delete(signal);
+  _unregisterListener(signal2) {
+    this._listeners.delete(signal2);
   }
   /** @internal */
   _registerEffect(effect) {
@@ -213,285 +421,715 @@ class FlowSignal {
     this._effects.delete(effect);
   }
 }
+function signal() {
+  return new FlowSignal();
+}
 
-class FlowObservable extends FlowSignal {
+class FlowNodeAsync extends FlowSignal {
+  _promise;
+  _dirty = true;
+  _compute;
   /**
-   * 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.
+   * Creates a new FlowNodeAsync.
    *
-   * @returns The current value of type T.
+   * @param compute - Either a constant Promise or a compute function that derives the value.
    *
    * @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).
+   * The constructor accepts two different initialization modes:
+   *
+   * - **Constant Promise**: Creates a mutable reactive node that can be updated via `set()`.
+   *   The Promise is stored immediately and can be changed at any time. The Promise resolves
+   *   to the value of type T.
+   *
+   * - **Compute function**: Creates a computed reactive node that automatically tracks dependencies
+   *   and recomputes when they change. The compute function receives a tracking context (`t`)
+   *   that should be used to access dependencies via `.get(t)`. The function must return a
+   *   `Promise<T>`. The function is not executed immediately; it runs lazily on first access.
+   *   The computed value can be temporarily overridden using `set()`, but the override is cleared
+   *   on the next recomputation (triggered by dependency changes).
    *
    * @example
    * ```typescript
-   * effect((t) => {
-   *   const tracked = $state.get(t);     // Dependency registered
-   *   const untracked = $other.get(null); // No dependency
+   * // Mutable state with constant Promise
+   * const $count = new FlowNodeAsync(Promise.resolve(0));
+   * await $count.set(Promise.resolve(5));
+   *
+   * // Computed derivation with async function
+   * const $a = new FlowNodeAsync(Promise.resolve(10));
+   * const $b = new FlowNodeAsync(Promise.resolve(20));
+   * const $sum = new FlowNodeAsync(async (t) => {
+   *   const a = await $a.get(t);
+   *   const b = await $b.get(t);
+   *   return a + b;
    * });
+   *
+   * // Lazy evaluation - compute function hasn't run yet
+   * console.log(await $sum.pick()); // Now it computes: 30
    * ```
    *
    * @public
    */
-  get(context) {
-    if (context) {
-      this.watch(context);
+  constructor(compute) {
+    super();
+    if (typeof compute === "function") {
+      this._compute = compute;
+    } else {
+      this._promise = compute;
+      this._dirty = false;
     }
-    return this._getRaw();
+  }
+  get settled() {
+    return this._promise;
+  }
+  async watch(tracker) {
+    if (this._disposed)
+      return Promise.reject(new Error("[PicoFlow] Primitive is disposed"));
+    super.watch(tracker);
+    return this._computeValue();
+  }
+  /**
+   * Gets the current value with dependency tracking.
+   *
+   * @param tracker - The tracking context for reactive tracking. This observable is registered
+   * as a dependency when accessed through this method.
+   *
+   * @returns A Promise that resolves to the current value of type T.
+   *
+   * @remarks
+   * Use `get(t)` within effects and derivations to create reactive dependencies. The tracker
+   * parameter must be provided from the reactive context (typically the `t` parameter in effect
+   * or derivation callbacks).
+   *
+   * **Important:** This method returns a `Promise<T>`, not `T`. You must await the Promise to
+   * get the actual value. The Promise is cached until dependencies change, ensuring efficient
+   * access patterns.
+   *
+   * To read a value without creating a dependency, use `pick()` instead.
+   *
+   * @example
+   * ```typescript
+   * effect(async (t) => {
+   *   const tracked = await $state.get(t);     // Dependency registered, await the Promise
+   *   const untracked = await $other.pick();   // No dependency
+   * });
+   * ```
+   *
+   * @throws Error if the node has been disposed.
+   *
+   * @public
+   */
+  async get(tracker) {
+    if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    await this._computeValue();
+    if (tracker) super.watch(tracker);
+    return this._promise;
+  }
+  /**
+   * Updates the node with a new value.
+   *
+   * @param value - A new Promise or a callback function that computes a new Promise based on the current value.
+   *
+   * @returns A promise that resolves after the update is processed and all dependent effects have been notified.
+   *
+   * @remarks
+   * This method can be used in two ways:
+   *
+   * **For mutable state nodes** (constructed with a constant Promise):
+   * - Updates the stored Promise directly
+   * - All dependents are notified of the change
+   *
+   * **For computed nodes** (constructed with a compute function):
+   * - Temporarily overrides the computed value
+   * - The override persists until the next recomputation, which occurs when:
+   *   - A tracked dependency changes, or
+   *   - The node is refreshed
+   * - This allows temporarily overriding computed values for testing or manual control
+   *
+   * **Value Comparison:**
+   * The Promises are resolved and their values are compared. If the resolved new value is strictly
+   * equal (`===`) to the current resolved value, no update occurs and subscribers are not notified.
+   * This prevents unnecessary re-renders and effect executions.
+   *
+   * **Asynchronous Processing:**
+   * The update is processed asynchronously through the reactive graph, ensuring proper
+   * ordering of updates and effect execution. The method returns a Promise that resolves
+   * after the update is complete.
+   *
+   * @throws Error if the node has been disposed.
+   *
+   * @example
+   * ```typescript
+   * // Mutable state usage
+   * const $count = new FlowNodeAsync(Promise.resolve(0));
+   * await $count.set(Promise.resolve(5));
+   * await $count.set(async (current) => Promise.resolve(current + 1)); // 6
+   *
+   * // Temporary override of computed value
+   * const $source = new FlowNodeAsync(Promise.resolve(10));
+   * const $doubled = new FlowNodeAsync(async (t) => {
+   *   const val = await $source.get(t);
+   *   return val * 2;
+   * });
+   *
+   * console.log(await $doubled.pick()); // 20
+   *
+   * // Temporarily override
+   * await $doubled.set(Promise.resolve(50));
+   * console.log(await $doubled.pick()); // 50 (override active)
+   *
+   * // Dependency change clears override
+   * await $source.set(Promise.resolve(15));
+   * console.log(await $doubled.pick()); // 30 (recomputed, override cleared)
+   * ```
+   *
+   * @public
+   */
+  async set(value) {
+    if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    const update = async () => {
+      await this._computeValue();
+      const currentValue = await this._promise;
+      const nextPromise = typeof value === "function" ? value(currentValue) : value;
+      const nextValue = await nextPromise;
+      this._promise = nextPromise;
+      return nextValue !== currentValue;
+    };
+    const notify = () => {
+      super._notify();
+    };
+    return FlowGraph.requestWrite(notify, update);
+  }
+  /**
+   * Forces recomputation of the value, even if it's not marked as dirty.
+   *
+   * @returns A promise that resolves after the recomputation is complete and all
+   * dependent effects have been notified.
+   *
+   * @remarks
+   * This method is useful when you need to force a recomputation of a computed value,
+   * for example when the computation depends on external data that has changed outside
+   * the reactive system.
+   *
+   * **Behavior:**
+   * - For nodes with a compute function: Forces the compute function to run again,
+   *   even if no dependencies have changed. This effectively clears any temporary
+   *   override that was set using `set()`.
+   * - For nodes without a compute function (mutable state): Recomputes the current
+   *   value (which is just the stored value), useful for consistency but typically
+   *   not necessary.
+   *
+   * The recomputation happens asynchronously through the reactive graph, ensuring
+   * proper ordering of updates and effect execution.
+   *
+   * @throws Error if the node has been disposed.
+   *
+   * @example
+   * ```typescript
+   * const $externalData = new FlowNode(() => fetchExternalData());
+   *
+   * // Some external event occurs that changes the data source
+   * externalDataChanged();
+   *
+   * // Force recomputation to get the new value
+   * await $externalData.refresh();
+   *
+   * // For computed nodes with temporary overrides
+   * const $computed = new FlowNode((t) => $source.get(t) * 2);
+   * $computed.set(100); // Temporary override
+   * await $computed.refresh(); // Clears override, recomputes from source
+   * ```
+   *
+   * @public
+   */
+  async refresh() {
+    if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    const update = async () => {
+      await this._computeValue();
+      const currentValue = await this._promise;
+      await this._computeValue({ force: true });
+      const nextValue = await this._promise;
+      return nextValue !== currentValue;
+    };
+    const notify = () => {
+      super._notify();
+    };
+    return await FlowGraph.requestWrite(notify, update);
   }
   /**
    * Gets the current value without any dependency tracking.
    *
-   * @returns The current value of type T.
+   * @returns A promise that resolves with the current value of type T.
    *
    * @remarks
-   * This method is equivalent to calling `get(null)` but provides a more semantic and readable API.
+   * This method reads the value asynchronously through the reactive graph, ensuring proper ordering of
+   * read operations. Unlike `get(t)`, this method does not create a reactive dependency.
+   *
+   * **Important:** This is an async method that returns `Promise<T>`. Always use `await` when calling it.
+   *
    * 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
+   * - Reading initial values outside reactive contexts
    * - 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();
+   * const currentValue = await $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
+   * effect(async (t) => {
+   *   const tracked = await $reactive.get(t);    // Triggers re-runs
+   *   const snapshot = await $config.pick();    // Doesn't trigger re-runs
    *   processData(tracked, snapshot);
    * });
    * ```
    *
+   * @throws Error if the node has been disposed.
+   *
    * @public
    */
-  pick() {
-    return this._getRaw();
+  async pick() {
+    if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    await FlowGraph.requestRead(() => this._computeValue());
+    return this._promise;
   }
-  /* INTERNAL -------------------------------------------*/
-  /** @internal */
-  _value;
   /**
-   * Subscribes a listener function to changes of the observable.
-   * The listener is executed immediately with the current value and on subsequent updates.
-   * @param listener - A callback function that receives the new value.
-   * @returns A disposer function to cancel the subscription.
+   * Subscribes a listener function to changes of this node.
+   *
+   * @param listener - A callback function that receives the new value whenever it changes.
+   *
+   * @returns A disposer function that cancels the subscription when called.
+   *
+   * @remarks
+   * This method creates a reactive subscription that automatically tracks this node as a dependency.
+   * The listener is executed:
+   * - Immediately with the current value when the subscription is created
+   * - Automatically whenever the value changes
+   *
+   * **Important:** The listener receives a `Promise<T>`, not `T`. You must await the Promise
+   * within the listener to access the actual value. The Promise is the same one returned by `get()`,
+   * so it's cached until dependencies change.
+   *
+   * The subscription uses a {@link FlowEffect} internally to manage the reactive tracking and
+   * automatic re-execution. When the value changes, the listener is called with the new Promise
+   * after the update is processed through the reactive graph.
+   *
+   * **Cleanup:**
+   * Always call the returned disposer function when you no longer need the subscription to
+   * prevent memory leaks and unnecessary computations.
+   *
+   * @example
+   * ```typescript
+   * const $count = new FlowNodeAsync(Promise.resolve(0));
+   *
+   * // Subscribe to changes
+   * const unsubscribe = $count.subscribe(async (valuePromise) => {
+   *   const value = await valuePromise;
+   *   console.log(`Count is now: ${value}`);
+   * });
+   * // Logs immediately: "Count is now: 0"
+   *
+   * await $count.set(Promise.resolve(5));
+   * // Logs: "Count is now: 5"
+   *
+   * // Clean up when done
+   * unsubscribe();
+   * ```
+   *
+   * @throws Error if the node has been disposed.
+   *
+   * @public
    */
   subscribe(listener) {
+    if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
     const effect = new FlowEffect((t) => {
       listener(this.get(t));
     });
     return () => effect.dispose();
   }
+  /* INTERNAL --------------------------------------------------------- */
+  /* @internal */
+  _notify() {
+    if (this._dirty) {
+      return;
+    }
+    this._dirty = true;
+    super._notify();
+  }
+  async _computeValue(options) {
+    if (!this._dirty && !options?.force) return;
+    if (!this._compute) {
+      this._dirty = false;
+      return;
+    }
+    this._dirty = false;
+    const dependencies = [...this._dependencies];
+    this._dependencies.clear();
+    this._promise = this._compute(this);
+    await this._promise;
+    const dependenciesToRemove = dependencies.filter(
+      (dependency) => !this._dependencies.has(dependency)
+    );
+    dependenciesToRemove.forEach((dependency) => {
+      dependency._unregisterDependency(this);
+    });
+  }
+}
+
+function constantAsync(value) {
+  return new FlowNodeAsync(value);
+}
+
+function derivationAsync(fn) {
+  return new FlowNodeAsync(fn);
+}
+
+function stateAsync(value) {
+  return new FlowNodeAsync(value);
 }
 
-class FlowConstant extends FlowObservable {
+class FlowNode extends FlowSignal {
+  _value;
+  _dirty = true;
+  _compute;
   /**
-   * Creates a new FlowConstant instance.
+   * Creates a new FlowNode.
+   *
+   * @param compute - Either a constant value or a compute function that derives the value.
+   *
+   * @remarks
+   * The constructor accepts two different initialization modes:
+   *
+   * - **Constant value**: Creates a mutable reactive node that can be updated via `set()`.
+   *   The value is stored immediately and can be changed at any time.
+   *
+   * - **Compute function**: Creates a computed reactive node that automatically tracks dependencies
+   *   and recomputes when they change. The compute function receives a tracking context (`t`)
+   *   that should be used to access dependencies via `.get(t)`. The function is not executed
+   *   immediately; it runs lazily on first access. The computed value can be temporarily
+   *   overridden using `set()`, but the override is cleared on the next recomputation
+   *   (triggered by dependency changes or `refresh()`).
+   *
+   * @example
+   * ```typescript
+   * // Mutable state with constant value
+   * const $count = new FlowNode(0);
+   * $count.set(5);
    *
-   * @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.
+   * // Computed derivation with function
+   * const $a = new FlowNode(10);
+   * const $b = new FlowNode(20);
+   * const $sum = new FlowNode((t) => $a.get(t) + $b.get(t));
+   *
+   * // Lazy evaluation - compute function hasn't run yet
+   * console.log(await $sum.pick()); // Now it computes: 30
+   * ```
    *
    * @public
    */
-  constructor(value) {
+  constructor(compute) {
     super();
-    this._initEager(value);
-  }
-  /**
-   * Internal method to get the raw value.
-   * @internal
-   */
-  _getRaw() {
-    if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-    this._initLazy();
-    return this._value;
-  }
-  /* INTERNAL --------------------------------------------------------- */
-  /** @internal */
-  _initialized = false;
-  /** @internal */
-  _init;
-  /** @internal */
-  _initEager(value) {
-    if (typeof value === "function") {
-      this._init = value;
+    if (typeof compute === "function") {
+      this._compute = compute;
     } else {
-      this._value = value;
-      this._initialized = true;
+      this._value = compute;
+      this._dirty = false;
     }
   }
-  /** @internal */
-  _initLazy() {
-    if (!this._initialized && this._init) {
-      this._value = this._init();
-      this._initialized = true;
-    }
-    if (!this._initialized)
-      throw new Error("[PicoFlow] Primitive can't be initialized");
+  watch(tracker) {
+    if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    this._computeValue();
+    super.watch(tracker);
   }
-}
-
-class FlowDerivation extends FlowObservable {
   /**
-   * Creates a new FlowDerivation.
+   * Gets the current value with dependency tracking.
+   *
+   * @param tracker - The tracking context for reactive tracking. This observable is registered
+   * as a dependency when accessed through this method.
+   *
+   * @returns The current value of type T.
+   *
+   * @remarks
+   * Use `get(t)` within effects and derivations to create reactive dependencies. The tracker
+   * parameter must be provided from the reactive context (typically the `t` parameter in effect
+   * or derivation callbacks).
    *
-   * @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.
+   * To read a value without creating a dependency, use `pick()` instead.
+   *
+   * @example
+   * ```typescript
+   * effect((t) => {
+   *   const tracked = $state.get(t);     // Dependency registered
+   *   const untracked = await $other.pick(); // No dependency
+   * });
+   * ```
+   *
+   * @throws Error if the node has been disposed.
    *
    * @public
    */
-  constructor(compute) {
-    super();
-    this._compute = compute;
-    this._trackedContext = new TrackingContext(this);
+  get(tracker) {
+    if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    this._computeValue();
+    if (tracker) super.watch(tracker);
+    return this._value;
   }
   /**
-   * Internal method to get the raw value.
-   * @internal
+   * Updates the node with a new value.
+   *
+   * @param value - A new value or a callback function that computes a new value based on the current value.
+   *
+   * @returns A promise that resolves after the update is processed and all dependent effects have been notified.
+   *
+   * @remarks
+   * This method can be used in two ways:
+   *
+   * **For mutable state nodes** (constructed with a constant value):
+   * - Updates the stored value directly
+   * - All dependents are notified of the change
+   *
+   * **For computed nodes** (constructed with a compute function):
+   * - Temporarily overrides the computed value
+   * - The override persists until the next recomputation, which occurs when:
+   *   - A tracked dependency changes, or
+   *   - `refresh()` is called
+   * - This allows temporarily overriding computed values for testing or manual control
+   *
+   * **Value Comparison:**
+   * If the new value is strictly equal (`===`) to the current value, no update occurs
+   * and subscribers are not notified. This prevents unnecessary re-renders and effect
+   * executions.
+   *
+   * **Asynchronous Processing:**
+   * The update is processed asynchronously through the reactive graph, ensuring proper
+   * ordering of updates and effect execution.
+   *
+   * @throws Error if the node has been disposed.
+   *
+   * @example
+   * ```typescript
+   * // Mutable state usage
+   * const $count = new FlowNode(0);
+   * await $count.set(5);
+   * await $count.set(current => current + 1); // 6
+   *
+   * // Temporary override of computed value
+   * const $source = new FlowNode(10);
+   * const $doubled = new FlowNode((t) => $source.get(t) * 2);
+   *
+   * console.log(await $doubled.pick()); // 20
+   *
+   * // Temporarily override
+   * await $doubled.set(50);
+   * console.log(await $doubled.pick()); // 50 (override active)
+   *
+   * // Dependency change clears override
+   * await $source.set(15);
+   * console.log(await $doubled.pick()); // 30 (recomputed, override cleared)
+   * ```
+   *
+   * @public
    */
-  _getRaw() {
+  set(value) {
     if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-    this._initLazy();
-    this._update();
-    return this._value;
-  }
-  /* INTERNAL --------------------------------------------------------- */
-  _initialized = false;
-  _dirty = false;
-  _compute;
-  _trackedContext;
-  _initLazy() {
-    if (!this._initialized) {
-      this._value = this._compute(this._trackedContext);
-      this._initialized = true;
-    }
+    const update = () => {
+      this._computeValue();
+      const currentValue = this._value;
+      const next = typeof value === "function" ? value(currentValue) : value;
+      this._value = next;
+      return next !== currentValue;
+    };
+    const notify = () => {
+      super._notify();
+    };
+    return FlowGraph.requestWrite(notify, update);
   }
-  /* @internal */
-  _update() {
-    if (this._dirty) {
-      const dependencies = [...this._dependencies];
-      this._dependencies.clear();
-      this._value = this._compute(this._trackedContext);
-      const dependenciesToRemove = dependencies.filter(
-        (dependency) => !this._dependencies.has(dependency)
-      );
-      dependenciesToRemove.forEach((dependency) => {
-        dependency._unregisterDependency(this);
-      });
-      this._dirty = false;
-    }
-  }
-  /* @internal */
-  _notify() {
-    this._dirty = true;
-    super._notify();
+  /**
+   * Forces recomputation of the value, even if it's not marked as dirty.
+   *
+   * @returns A promise that resolves after the recomputation is complete and all
+   * dependent effects have been notified.
+   *
+   * @remarks
+   * This method is useful when you need to force a recomputation of a computed value,
+   * for example when the computation depends on external data that has changed outside
+   * the reactive system.
+   *
+   * **Behavior:**
+   * - For nodes with a compute function: Forces the compute function to run again,
+   *   even if no dependencies have changed. This effectively clears any temporary
+   *   override that was set using `set()`.
+   * - For nodes without a compute function (mutable state): Recomputes the current
+   *   value (which is just the stored value), useful for consistency but typically
+   *   not necessary.
+   *
+   * The recomputation happens asynchronously through the reactive graph, ensuring
+   * proper ordering of updates and effect execution.
+   *
+   * @throws Error if the node has been disposed.
+   *
+   * @example
+   * ```typescript
+   * const $externalData = new FlowNode(() => fetchExternalData());
+   *
+   * // Some external event occurs that changes the data source
+   * externalDataChanged();
+   *
+   * // Force recomputation to get the new value
+   * await $externalData.refresh();
+   *
+   * // For computed nodes with temporary overrides
+   * const $computed = new FlowNode((t) => $source.get(t) * 2);
+   * $computed.set(100); // Temporary override
+   * await $computed.refresh(); // Clears override, recomputes from source
+   * ```
+   *
+   * @public
+   */
+  async refresh() {
+    if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    const update = () => {
+      this._computeValue();
+      const currentValue = this._value;
+      this._computeValue({ force: true });
+      const nextValue = this._value;
+      return nextValue !== currentValue;
+    };
+    const notify = () => {
+      super._notify();
+    };
+    return await FlowGraph.requestWrite(notify, update);
   }
   /**
-   * Watches the derivation, registering it as a dependency in the given context.
+   * Gets the current value without any dependency tracking.
    *
-   * @param context - The tracking context in which to register this derivation.
+   * @returns A promise that resolves with the current value of type T.
    *
    * @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 method reads the value asynchronously through the reactive graph, ensuring proper ordering of
+   * read operations. Unlike `get(t)`, this method does not create a reactive dependency.
+   *
+   * 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 outside reactive contexts
+   * - Accessing configuration that shouldn't trigger updates
+   * - Mixing tracked and untracked reads in the same effect
    *
-   * 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
+   * **Note:** This is an async method. Always use `await` when calling it.
    *
    * @example
    * ```typescript
-   * const $derived = derivation((t) => $state.get(t) * 2);
+   * // Read a snapshot outside reactive context
+   * const currentValue = await $state.pick();
    *
-   * effect((t) => {
-   *   $derived.watch(t); // Derivation computes even without reading value
-   *   doSomething();     // Effect re-runs when $derived's dependencies change
+   * // Mix tracked and untracked reads
+   * effect(async (t) => {
+   *   const tracked = $reactive.get(t);        // Triggers re-runs
+   *   const snapshot = await $config.pick();    // Doesn't trigger re-runs
+   *   processData(tracked, snapshot);
    * });
    * ```
    *
+   * @throws Error if the node has been disposed.
+   *
    * @public
    */
-  watch(context) {
-    super.watch(context);
-    this._initLazy();
-    this._update();
+  async pick() {
+    if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    await FlowGraph.requestRead(() => this._computeValue());
+    return this._value;
   }
-}
-
-function isDisposable(obj) {
-  return obj !== null && obj !== void 0 && typeof obj.dispose === "function";
-}
-
-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.
+   * Subscribes a listener function to changes of this node.
+   *
+   * @param listener - A callback function that receives the new value whenever it changes.
+   *
+   * @returns A disposer function that cancels the subscription when called.
+   *
    * @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.
+   * This method creates a reactive subscription that automatically tracks this node as a dependency.
+   * The listener is executed:
+   * - Immediately with the current value when the subscription is created
+   * - Automatically whenever the value changes
+   *
+   * The subscription uses a {@link FlowEffect} internally to manage the reactive tracking and
+   * automatic re-execution. When the value changes, the listener is called with the new value
+   * after the update is processed through the reactive graph.
+   *
+   * **Cleanup:**
+   * Always call the returned disposer function when you no longer need the subscription to
+   * prevent memory leaks and unnecessary computations.
+   *
+   * @example
+   * ```typescript
+   * const $count = new FlowNode(0);
+   *
+   * // Subscribe to changes
+   * const unsubscribe = $count.subscribe((value) => {
+   *   console.log(`Count is now: ${value}`);
+   * });
+   * // Logs immediately: "Count is now: 0"
+   *
+   * await $count.set(5);
+   * // Logs: "Count is now: 5"
+   *
+   * // Clean up when done
+   * unsubscribe();
+   * ```
+   *
+   * @throws Error if the node has been disposed.
+   *
    * @public
    */
-  set(value) {
+  subscribe(listener) {
     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();
+    const effect = new FlowEffect((t) => {
+      listener(this.get(t));
+    });
+    return () => effect.dispose();
+  }
+  /* INTERNAL --------------------------------------------------------- */
+  /* @internal */
+  _notify() {
+    if (this._dirty) {
+      return;
+    }
+    this._dirty = true;
+    super._notify();
+  }
+  _computeValue(options) {
+    if (!this._dirty && !options?.force) return;
+    if (!this._compute) {
+      this._dirty = false;
+      return;
+    }
+    this._dirty = false;
+    const dependencies = [...this._dependencies];
+    this._dependencies.clear();
+    this._value = this._compute(this);
+    const dependenciesToRemove = dependencies.filter(
+      (dependency) => !this._dependencies.has(dependency)
+    );
+    dependenciesToRemove.forEach((dependency) => {
+      dependency._unregisterDependency(this);
+    });
   }
 }
 
-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);
+  return new FlowNode(value);
 }
+
 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) : [])
-  );
+  return new FlowNode(fn);
 }
-function array(initial) {
-  return new FlowArray(initial);
+
+function state(value) {
+  return new FlowNode(value);
 }
 
-class FlowArray extends FlowObservable {
+class FlowArray extends FlowNode {
   /**
    * Last action performed on the FlowArray.
    * @public
@@ -503,8 +1141,7 @@ class FlowArray extends FlowObservable {
    * @public
    */
   constructor(value = []) {
-    super();
-    this._value = value;
+    super(value);
     this.$lastAction = state({
       type: "set",
       items: value
@@ -532,14 +1169,23 @@ class FlowArray extends FlowObservable {
    * @param items - The new array of items.
    * @public
    */
-  set(items) {
+  async set(items) {
     if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-    this._value.forEach((item) => {
-      if (isDisposable(item)) item.dispose({ self: true });
-    });
-    this._value = items;
-    this._notify();
-    this.$lastAction.set({ type: "set", items });
+    const update = () => {
+      const currentValue = this._value;
+      if (currentValue !== items) {
+        currentValue.forEach((item) => {
+          if (isDisposable(item)) item.dispose({ self: true });
+        });
+        this._value = items;
+        this.$lastAction.set({ type: "set", items });
+      }
+      return currentValue !== items;
+    };
+    const notify = () => {
+      super._notify();
+    };
+    return FlowGraph.requestWrite(notify, update);
   }
   /**
    * Replaces an item at a specific index.
@@ -547,62 +1193,104 @@ class FlowArray extends FlowObservable {
    * @param item - The new item.
    * @public
    */
-  setItem(index, item) {
+  async update(index, item) {
     if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-    if (index < 0 || index >= this._value.length) {
-      throw new Error("[PicoFlow] Index out of bounds");
-    }
-    this._value[index] = item;
-    this._notify();
-    this.$lastAction.set({ type: "setItem", index, item });
+    const update = () => {
+      if (index < 0 || index >= this._value.length) {
+        throw new Error("[PicoFlow] Index out of bounds");
+      }
+      const currentValue = this._value[index];
+      if (currentValue !== item) {
+        if (isDisposable(currentValue)) {
+          currentValue.dispose({ self: true });
+        }
+        this._value[index] = item;
+        this.$lastAction.set({ type: "update", index, item });
+      }
+      return currentValue !== item;
+    };
+    const notify = () => {
+      super._notify();
+    };
+    return FlowGraph.requestWrite(notify, update);
   }
   /**
    * Appends an item to the end of the array.
    * @param item - The item to append.
    * @public
    */
-  push(item) {
+  async push(item) {
     if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-    this._value.push(item);
-    this._notify();
-    this.$lastAction.set({ type: "push", item });
+    const update = () => {
+      this._value.push(item);
+      this.$lastAction.set({ type: "push", item });
+      return true;
+    };
+    const notify = () => {
+      super._notify();
+    };
+    return FlowGraph.requestWrite(notify, update);
   }
   /**
    * Removes the last item from the array.
    * @public
    */
-  pop() {
+  async pop() {
     if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-    const item = this._value.pop();
-    if (isDisposable(item)) {
-      item.dispose({ self: true });
-    }
-    this._notify();
-    this.$lastAction.set({ type: "pop" });
+    const update = () => {
+      const item = this._value.pop();
+      if (item !== void 0) {
+        if (isDisposable(item)) {
+          item.dispose({ self: true });
+        }
+        this.$lastAction.set({ type: "pop" });
+        return true;
+      }
+      return false;
+    };
+    const notify = () => {
+      super._notify();
+    };
+    return FlowGraph.requestWrite(notify, update);
   }
   /**
    * Inserts an item at the beginning of the array.
    * @param item - The item to insert.
    * @public
    */
-  unshift(item) {
+  async unshift(item) {
     if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-    this._value.unshift(item);
-    this._notify();
-    this.$lastAction.set({ type: "unshift", item });
+    const update = () => {
+      this._value.unshift(item);
+      this.$lastAction.set({ type: "unshift", item });
+      return true;
+    };
+    const notify = () => {
+      super._notify();
+    };
+    return FlowGraph.requestWrite(notify, update);
   }
   /**
    * Removes the first item from the array.
    * @public
    */
-  shift() {
+  async shift() {
     if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-    const item = this._value.shift();
-    if (isDisposable(item)) {
-      item.dispose({ self: true });
-    }
-    this._notify();
-    this.$lastAction.set({ type: "shift" });
+    const update = () => {
+      const item = this._value.shift();
+      if (item !== void 0) {
+        if (isDisposable(item)) {
+          item.dispose({ self: true });
+        }
+        this.$lastAction.set({ type: "shift" });
+        return true;
+      }
+      return false;
+    };
+    const notify = () => {
+      super._notify();
+    };
+    return FlowGraph.requestWrite(notify, update);
   }
   /**
    * Changes the content of the array.
@@ -611,33 +1299,45 @@ class FlowArray extends FlowObservable {
    * @param newItems - New items to add.
    * @public
    */
-  splice(start, deleteCount, ...newItems) {
+  async splice(start, deleteCount, ...newItems) {
     if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-    const items = this._value.splice(start, deleteCount, ...newItems);
-    items.forEach((item) => {
-      if (isDisposable(item)) item.dispose({ self: true });
-    });
-    this._notify();
-    this.$lastAction.set({
-      type: "splice",
-      start,
-      deleteCount,
-      items: newItems
-    });
+    const update = () => {
+      const items = this._value.splice(start, deleteCount, ...newItems);
+      items.forEach((item) => {
+        if (isDisposable(item)) item.dispose({ self: true });
+      });
+      this.$lastAction.set({
+        type: "splice",
+        start,
+        deleteCount,
+        items: newItems
+      });
+      return true;
+    };
+    const notify = () => {
+      super._notify();
+    };
+    return FlowGraph.requestWrite(notify, update);
   }
   /**
    * Clears all items from the array.
    * @public
    */
-  clear() {
+  async clear() {
     if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-    const items = [...this._value];
-    items.forEach((item) => {
-      if (isDisposable(item)) item.dispose({ self: true });
-    });
-    this._value = [];
-    this._notify();
-    this.$lastAction.set({ type: "clear" });
+    const update = () => {
+      const items = [...this._value];
+      items.forEach((item) => {
+        if (isDisposable(item)) item.dispose({ self: true });
+      });
+      this._value = [];
+      this.$lastAction.set({ type: "clear" });
+      return true;
+    };
+    const notify = () => {
+      super._notify();
+    };
+    return FlowGraph.requestWrite(notify, update);
   }
   /**
    * Disposes the FlowArray and its items.
@@ -652,41 +1352,29 @@ class FlowArray extends FlowObservable {
     this._value = [];
   }
   /* INTERNAL */
-  /** @internal */
-  _value = [];
+}
+function array(initial) {
+  return new FlowArray(initial);
 }
 
-class FlowMap extends FlowState {
+class FlowMap extends FlowNode {
   /**
-   * 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.
-   *
+   * Last action performed on the FlowMap.
    * @public
    */
-  $lastUpdated = new FlowState(null);
+  $lastAction;
   /**
-   * 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.
-   *
+   * Creates an instance of FlowMap.
+   * @param value - Initial map value.
    * @public
    */
-  $lastDeleted = new FlowState(null);
+  constructor(value = /* @__PURE__ */ new Map()) {
+    super(value);
+    this.$lastAction = state({
+      type: "set",
+      map: value
+    });
+  }
   /**
    * Adds a new key-value pair to the map.
    *
@@ -696,19 +1384,26 @@ class FlowMap extends FlowState {
    * @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},
+   * Adds a new entry to the internal map, emits the key-value pair via {@link FlowMap.$lastAction},
    * and notifies all subscribers of the change.
    *
    * @public
    */
-  add(key, value) {
+  async 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();
+    const update = () => {
+      const currentValue = this._value.get(key);
+      if (currentValue) {
+        throw new Error("[PicoFlow] Key already exists");
+      }
+      this._value.set(key, value);
+      this.$lastAction.set({ type: "add", key, value });
+      return true;
+    };
+    const notify = () => {
+      super._notify();
+    };
+    return FlowGraph.requestWrite(notify, update);
   }
   /**
    * Updates an existing key-value pair in the map.
@@ -719,19 +1414,28 @@ class FlowMap extends FlowState {
    * @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},
+   * Updates an existing entry in the internal map, emits the key-value pair via {@link FlowMap.$lastAction},
    * and notifies all subscribers of the change.
    *
    * @public
    */
-  update(key, value) {
+  async 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();
+    const update = () => {
+      const currentValue = this._value.get(key);
+      if (!currentValue) throw new Error("[PicoFlow] Key does not exist");
+      if (currentValue !== value) {
+        if (isDisposable(currentValue)) currentValue.dispose({ self: true });
+        this._value.set(key, value);
+        this.$lastAction.set({ type: "update", key, value });
+        return true;
+      }
+      return false;
+    };
+    const notify = () => {
+      super._notify();
+    };
+    return FlowGraph.requestWrite(notify, update);
   }
   /**
    * Deletes the value at the specified key from the underlying map.
@@ -740,341 +1444,105 @@ class FlowMap extends FlowState {
    * @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},
+   * Removes the key from the internal map, emits the deleted key and its value via {@link FlowMap.$lastAction},
    * 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);
-  }
-}
-
-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;
-}
-
-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() {
+  async delete(key) {
     if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-    this._value = this._fetch();
-    this._notify();
+    const update = () => {
+      const value = this._value.get(key);
+      if (value === void 0) throw new Error("[PicoFlow] Key does not exist");
+      if (isDisposable(value)) value.dispose({ self: true });
+      this._value.delete(key);
+      this.$lastAction.set({ type: "delete", key, value });
+      return true;
+    };
+    const notify = () => {
+      super._notify();
+    };
+    return FlowGraph.requestWrite(notify, update);
   }
-  /* INTERNAL ------------------------------------------------ */
-  _fetch;
-}
-
-class FlowStream extends FlowObservable {
   /**
-   * Creates a new FlowStream.
+   * Replaces the entire map with new entries.
    *
-   * @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.
+   * @param map - The new map of entries.
+   * @throws If the FlowMap instance is disposed.
    *
    * @remarks
-   * The updater is invoked immediately during construction. Make sure to return a proper
-   * cleanup function to avoid resource leaks.
+   * Replaces all entries in the internal map, disposes the old values (if they are disposable),
+   * emits the new map via {@link FlowMap.$lastAction}, and notifies all subscribers of the change.
    *
    * @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) {
+  async set(map2) {
     if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-    if (value === this._value) return;
-    this._value = value;
-    this._notify();
+    const update = () => {
+      const currentValue = this._value;
+      if (currentValue !== map2) {
+        currentValue.forEach((item) => {
+          if (isDisposable(item)) item.dispose({ self: true });
+        });
+      }
+      this._value = map2;
+      if (currentValue !== map2) {
+        this.$lastAction.set({ type: "set", map: map2 });
+      }
+      return currentValue !== map2;
+    };
+    const notify = () => {
+      super._notify();
+    };
+    return FlowGraph.requestWrite(notify, update);
   }
-}
-
-class FlowStreamAsync extends FlowObservable {
   /**
-   * Creates a new asynchronous FlowStream.
+   * Clears all entries from the map.
    *
-   * @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.
+   * @throws If the FlowMap instance is disposed.
    *
    * @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.
+   * Removes all entries from the internal map, disposes the removed values (if they are disposable),
+   * emits a clear action via {@link FlowMap.$lastAction}, and notifies all subscribers of the change.
    *
    * @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() {
+  async clear() {
     if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-    return this._value;
+    const update = () => {
+      const items = [...this._value.values()];
+      items.forEach((item) => {
+        if (isDisposable(item)) item.dispose({ self: true });
+      });
+      this._value.clear();
+      this.$lastAction.set({ type: "clear" });
+      return true;
+    };
+    const notify = () => {
+      super._notify();
+    };
+    return FlowGraph.requestWrite(notify, update);
   }
   /**
-   * Disposes the stream, releasing all resources.
-   * @remarks In addition to disposing the underlying observable, this method calls the disposer
-   * returned by the updater.
+   * Disposes the FlowMap and its values.
+   * @param options - Disposal options.
    * @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 {
-  /**
-   * Returns the current value.
-   */
-  get;
-  /**
-   * Sets the value or updates it using a getter function.
-   */
-  set;
-  /**
-   * Creates a new SolidState with the given initial value.
-   * @param initialValue - The initial value.
-   */
-  constructor(initialValue) {
-    const [get, set] = createSignal(initialValue);
-    this.get = get;
-    this.set = set;
-  }
-}
-class SolidDerivation {
-  /**
-   * Returns the current derived value.
-   */
-  get;
-  /**
-   * Creates a new SolidDerivation from a getter function or value.
-   * @param calculator - The getter function or value.
-   */
-  constructor(calculator) {
-    const get = createMemo(calculator);
-    this.get = get;
-  }
-}
-class SolidResource {
-  /**
-   * Returns the current value (or undefined if not yet loaded).
-   */
-  get;
-  /**
-   * Returns the current resource state.
-   */
-  state;
-  /**
-   * Returns the latest successfully loaded value (or undefined).
-   */
-  latest;
-  /**
-   * Triggers a refetch of the resource.
-   */
-  refetch;
-  /**
-   * Creates a new SolidResource from a fetcher function.
-   * @param fetcher - The async fetcher function.
-   */
-  constructor(fetcher) {
-    const [get, set] = createResource(fetcher);
-    this.get = get;
-    this.state = () => get.state;
-    this.latest = () => get.latest;
-    this.refetch = () => set.refetch();
-  }
-}
-
-function fromSync(state) {
-  const solidState = new SolidState(state.pick());
-  let fx;
-  onMount(() => {
-    fx = new FlowEffect((t) => {
-      const value = state.get(t);
-      solidState.set(() => value);
-    });
-  });
-  onCleanup(() => fx.dispose());
-  return solidState;
-}
-function fromAsync(derivation) {
-  const solidResource = new SolidResource(async () => {
-    const value = await derivation.pick();
-    return value;
-  });
-  let fx;
-  onMount(() => {
-    fx = new FlowEffect(async (t) => {
-      await derivation.get(t);
-      solidResource.refetch();
+  dispose(options) {
+    super.dispose(options);
+    this._value.forEach((item) => {
+      if (isDisposable(item)) item.dispose(options);
     });
-  });
-  onCleanup(() => fx.dispose());
-  return solidResource;
-}
-function shallowFrom(flow) {
-  const initialValue = flow.pick();
-  const isAsync = initialValue instanceof Promise;
-  if (isAsync) {
-    return fromAsync(flow);
-  }
-  return fromSync(flow);
-}
-function deepFrom(getter) {
-  const derivation = new FlowDerivation((t) => {
-    return getter(t);
-  });
-  const initialValue = derivation.pick();
-  const isAsync = initialValue instanceof Promise;
-  if (isAsync) {
-    return fromAsync(derivation);
+    this._value.clear();
   }
-  return fromSync(derivation);
 }
-function from(flow) {
-  if (flow instanceof FlowObservable) {
-    return shallowFrom(flow);
+function map(initial) {
+  if (initial instanceof Map) {
+    return new FlowMap(initial);
   }
-  return deepFrom(flow);
+  return new FlowMap(
+    new Map(initial ? Object.entries(initial) : [])
+  );
 }
 
-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 };
+export { FlowArray, FlowEffect, FlowGraph, FlowMap, FlowNode, FlowNodeAsync, FlowSignal, array, constant, constantAsync, derivation, derivationAsync, effect, isDisposable, map, signal, state, stateAsync };