@ersbeth/picoflow 2.0.2 → 2.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Elisabeth Rousset
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -4,6 +4,10 @@
 
 > **Upgrading from v1.x?** See the [Upgrade Guide](https://ersbeth-web.gitlab.io/picoflow/guide/advanced/migration-v2.html) for migration instructions.
 
+## Requirements
+
+The schedulers use `Promise.withResolvers()`, so picoflow needs **Node ≥ 22**, or Chrome ≥ 119, Safari ≥ 17.4, Firefox ≥ 121 in the browser. There is no fallback: on an older runtime the failure is immediate, on the first primitive you create.
+
 ## Installation
 
 ```bash
@@ -21,6 +25,27 @@ yarn add @ersbeth/picoflow
 
 For comprehensive guides and API documentation, visit the [official website](https://ersbeth-web.gitlab.io/picoflow/)
 
+## Development
+
+```bash
+pnpm install
+pnpm playwright:install   # once — downloads Chromium for the browser tests
+pnpm test                 # watch Node tests
+pnpm test:browser         # watch browser tests
+```
+
+See [`CONTRIBUTING.md`](CONTRIBUTING.md) for the full setup, the conventions and the release procedure. Known issues and their status are tracked in [`audits/FINDINGS.md`](audits/FINDINGS.md); planned breaking changes in [`ROADMAP.md`](ROADMAP.md); vulnerability reporting in [`SECURITY.md`](SECURITY.md).
+
+## AI Coding Agents
+
+Picoflow ships a [`SKILL.md`](SKILL.md) with the npm package, matching the exact version you have
+installed. If you use an agent skill tool (e.g. [`npx skills`](https://github.com/vercel-labs/skills)),
+install it straight from `node_modules` after installing the package:
+
+```bash
+npx skills add ./node_modules/@ersbeth/picoflow
+```
+
 ## License
 
 This project is licensed under the [MIT License](LICENSE).

package/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: picoflow
+description: Use when writing, reviewing, or debugging TypeScript code that uses @ersbeth/picoflow's reactive primitives (signal, state, constant, derivation, writableDerivation, array, map, subscribe). Covers the explicit tracking model (get(t) vs pick()), disposal, and the mistakes that silently break reactivity.
+---
+
+# PicoFlow
+
+PicoFlow is a reactive dataflow library with **explicit tracking** — there is no automatic dependency
+detection like in Vue, MobX or Solid. Follow the rules below whenever you write or review code that
+imports from `@ersbeth/picoflow`.
+
+## The core rule: `.get(t)` vs `.pick()`
+
+Every primitive is read one of two ways:
+
+- **`.get(t)`** — tracked read. `t` is a `FlowTracker`, only available inside a `derivation()` callback
+  or a `subscribe()` data function. Registers the caller as a dependent.
+- **`.pick()`** — untracked async read (`Promise<T>`). Use outside reactive contexts (event handlers,
+  one-off reads) when you don't want to react to future changes.
+
+Never call `.get(t)` outside a derivation/subscribe callback — `t` isn't available there. Never use
+`.pick()` inside a derivation/subscribe when you actually want reactivity — it silently creates no
+dependency, which is a common source of "why doesn't this update" bugs.
+
+Reactive values are named with a `$` prefix (`$count`, `$user`) by convention — keep this when writing
+new code in a PicoFlow codebase, and use it to tell reactive values apart from plain ones at a glance.
+
+## Choosing a primitive
+
+| Need | Use | Not |
+|---|---|---|
+| Event with no payload (trigger a refresh, coordinate actions) | `signal()` | `state()` for a flag no one reads |
+| Mutable value that changes over time | `state(value)` | `constant` (if it truly never changes) |
+| Expensive one-time computation, never changes | `constant(() => ...)` — **always a function**, computed lazily on first access | a plain top-level `const` if nothing reactive reads it |
+| Pure computed value from other primitives | `derivation((t) => ...)` | putting side effects in it — use `subscribe` |
+| A derivation that occasionally needs manual override | `writableDerivation((t) => ...)` | — |
+| List with fine-grained mutation tracking | `array(initial?)` | `state(someArray)` if you need per-operation tracking |
+| Key-value store with fine-grained mutation tracking | `map(initial?)` | `state(someMap)` if you need per-operation tracking |
+| Running side effects (DOM, network, storage, logging) in reaction to changes | `.subscribe()` (single primitive) or `subscribe()` (multiple) | `derivation` — derivations must stay pure |
+
+Async variants exist for state/constant/derivation/writableDerivation (`stateAsync`, `constantAsync`,
+`derivationAsync`, `writableDerivationAsync`) — same rules, the held value is a `Promise<T>`, and reads
+of a still-pending value are handled automatically (surfaced via `subscribe()`'s optional `onPending`
+callback) rather than needing manual `await`/try-catch inside a derivation.
+
+## Mistakes to catch when reviewing PicoFlow code
+
+- **Side effects inside `derivation()`** (logging, API calls, mutating outside state) — derivations must
+  be pure; move the side effect into a `subscribe()`.
+- **Mutating a collection returned by `.get(t)`/`.pick()` in place**, e.g. `items.push(x)` on a picked
+  array, or `user.name = 'x'` on a picked object, then relying on it to update — this changes nothing
+  observable. Always produce a new array/object (`items.map(...)`, `{ ...user, name: 'x' }`), or use the
+  primitive's own mutation methods (`$array.push(x)`, `$map.update(k, v)`).
+- **`constant(value)` with a direct value instead of a function** — constants always take an initializer
+  function (`constant(() => value)`), enforcing lazy evaluation. A direct value is a v1 pattern (see below).
+- **Not disposing subscriptions/primitives** (`.dispose()`) when they're no longer needed — every
+  `subscribe()`/`.subscribe()` call keeps running until disposed; forgetting this in code that creates
+  subscriptions repeatedly (e.g. once per component instance, once per request) is a memory leak.
+- **Creating a subscription inside another subscription's callback** — it re-creates one on every run
+  and leaks. Combine into a single `subscribe()` whose data function reads all the needed primitives.
+- **A `subscribe()`/`.subscribe()` callback that calls `.set()` on a primitive it also reads** — infinite
+  loop.
+- **Using `add()`/`update()` on `array`/`map` without checking preconditions** — `array.update(index, x)`
+  throws if the index is out of bounds; `map.add(key, x)` throws if the key exists; `map.update(key, x)`
+  throws if it doesn't. Check first (`.pick()`) or branch on it, don't assume.
+- **Tracking the whole `array`/`map` (`.subscribe()`/`.get(t)`) when only specific operations matter** —
+  prefer `$collection.$lastAction.subscribe(...)` (a discriminated union with a `type` field) to react
+  only to the mutation kind you care about, instead of re-running on every change.
+
+## Recognizing pre-v2 (deprecated) API usage
+
+If existing code uses any of these, it predates PicoFlow v2 — flag it and suggest migrating (full guide:
+https://ersbeth-web.gitlab.io/picoflow/guide/advanced/migration-v2.html):
+
+- `effect((t) => ...)` — removed. Replace with `.subscribe()` (single primitive) or `subscribe()` (multiple).
+- `$map.$lastAdded` / `$lastUpdated` / `$lastDeleted` — replaced by a single `$map.$lastAction` signal
+  with a `type` discriminant.
+- `$array.setItem(index, value)` — renamed to `$array.update(index, value)`.
+- `constant(value)` with a direct (non-function) value.
+
+## Minimal example (the shape most PicoFlow code follows)
+
+```typescript
+import { state, derivation, subscribe } from '@ersbeth/picoflow'
+
+const $count = state(0)
+const $isEven = derivation((t) => $count.get(t) % 2 === 0)
+
+const effect = subscribe(
+  (t) => ({ count: $count.get(t), even: $isEven.get(t) }),
+  (data) => console.log(`Count is ${data.count}, which is ${data.even ? 'even' : 'odd'}`),
+)
+
+$count.set((n) => n + 1) // atomic updater form, prefer it when the new value depends on the current one
+
+// when done:
+effect.dispose()
+$count.dispose()
+```
+
+## Further reference
+
+This file covers the rules needed to write and review correct PicoFlow code. For the full generated API
+reference (every method, accessor, inherited member) or the guide with longer walkthroughs, see
+https://ersbeth-web.gitlab.io/picoflow/ (or its condensed single-file form at
+https://ersbeth-web.gitlab.io/picoflow/llms-full.txt).

package/dist/picoflow.js

@@ -7,7 +7,7 @@ function isDisposable(obj) {
 class PendingError extends Error {
   pendingPromise;
   constructor(promise) {
-    super("[PicoFlow] PendingResolver pending");
+    super("[PicoFlow] Computation is pending");
     this.name = "PendingError";
     this.pendingPromise = promise;
   }
@@ -36,8 +36,8 @@ class AsyncResolver {
     return this._finished;
   }
   compute() {
-    if (this._finished) throw new Error("[Picoflow] PendingResolver: Can't restart a settled resolver");
-    if (this._aborted) throw new Error("[Picoflow] PendingResolver: Can't restart an aborted resolver");
+    if (this._finished) throw new Error("[PicoFlow] AsyncResolver: Can't restart a settled resolver");
+    if (this._aborted) throw new Error("[PicoFlow] AsyncResolver: Can't restart an aborted resolver");
     this._iteration++;
     const currentIteration = this._iteration;
     this._compute().then((value) => {
@@ -51,8 +51,8 @@ class AsyncResolver {
     });
   }
   overwrite(promise) {
-    if (this._finished) throw new Error("[Picoflow] PendingResolver: Can't overwrite a settled resolver");
-    if (this._aborted) throw new Error("[Picoflow] PendingResolver: Can't overwrite an aborted resolver");
+    if (this._finished) throw new Error("[PicoFlow] AsyncResolver: Can't overwrite a settled resolver");
+    if (this._aborted) throw new Error("[PicoFlow] AsyncResolver: Can't overwrite an aborted resolver");
     this._iteration++;
     const currentIteration = this._iteration;
     promise.then((value) => {
@@ -81,7 +81,7 @@ class AsyncScheduler {
     this._onResolve = onResolve;
     this._onReject = onReject;
     this._resolver = new AsyncResolver(compute);
-    this._resolver.computed.then(this._onResolve).catch(this._onReject).finally(() => this._settled.resolve());
+    this._attachHandlers(this._resolver);
   }
   get settled() {
     if (this._disposed) throw new Error("[PicoFlow] ComputationScheduler is disposed");
@@ -95,7 +95,7 @@ class AsyncScheduler {
     if (this._resolver.finished) {
       this._resolver = new AsyncResolver(this._compute);
       this._settled = Promise.withResolvers();
-      this._resolver.computed.then(this._onResolve).catch(this._onReject).finally(() => this._settled.resolve());
+      this._attachHandlers(this._resolver);
     }
     this._resolver.overwrite(promise);
   }
@@ -104,10 +104,19 @@ class AsyncScheduler {
     if (this._resolver.finished) {
       this._resolver = new AsyncResolver(this._compute);
       this._settled = Promise.withResolvers();
-      this._resolver.computed.then(this._onResolve).catch(this._onReject).finally(() => this._settled.resolve());
+      this._attachHandlers(this._resolver);
     }
     this._resolver.compute();
   }
+  _attachHandlers(resolver) {
+    resolver.computed.then((value) => {
+      if (this._disposed) return;
+      this._onResolve(value);
+    }).catch((error) => {
+      if (this._disposed) return;
+      this._onReject(error);
+    }).finally(() => this._settled.resolve());
+  }
   dispose() {
     this._resolver.abort();
     this._disposed = true;
@@ -116,7 +125,6 @@ class AsyncScheduler {
 
 class SyncResolver {
   _compute;
-  _iteration = 0;
   _aborted = false;
   _finished = false;
   _onValue;
@@ -133,18 +141,16 @@ class SyncResolver {
     return this._finished;
   }
   compute() {
-    if (this._finished) throw new Error("[Picoflow] PendingResolver: Can't restart a settled resolver");
-    if (this._aborted) throw new Error("[Picoflow] PendingResolver: Can't restart an aborted resolver");
-    this._iteration++;
-    const currentIteration = this._iteration;
+    if (this._finished) throw new Error("[PicoFlow] SyncResolver: Can't restart a settled resolver");
+    if (this._aborted) throw new Error("[PicoFlow] SyncResolver: Can't restart an aborted resolver");
     try {
       const value = this._compute();
-      if (this._iteration === currentIteration && !this._aborted) {
+      if (!this._finished && !this._aborted) {
         this._finished = true;
         this._onValue(value);
       }
     } catch (error) {
-      if (this._iteration === currentIteration && !this._aborted) {
+      if (!this._finished && !this._aborted) {
         if (!(error instanceof PendingError)) {
           this._finished = true;
           this._onError(error);
@@ -153,17 +159,12 @@ class SyncResolver {
     }
   }
   overwrite(value) {
-    if (this._finished) throw new Error("[Picoflow] PendingResolver: Can't overwrite a settled resolver");
-    if (this._aborted) throw new Error("[Picoflow] PendingResolver: Can't overwrite an aborted resolver");
-    this._iteration++;
-    const currentIteration = this._iteration;
-    if (this._iteration === currentIteration && !this._aborted) {
-      this._finished = true;
-      this._onValue(value);
-    }
+    if (this._finished) throw new Error("[PicoFlow] SyncResolver: Can't overwrite a settled resolver");
+    if (this._aborted) throw new Error("[PicoFlow] SyncResolver: Can't overwrite an aborted resolver");
+    this._finished = true;
+    this._onValue(value);
   }
   abort() {
-    this._iteration++;
     this._aborted = true;
   }
 }
@@ -224,17 +225,48 @@ class Disposable {
 }
 
 class ExecutionStack {
+  static _MAX_FLUSH_STEPS = 1e4;
   static _pendingQueue = [];
   static _effectQueue = [];
   static _executionScheduled;
+  static _coalesceResetScheduled = false;
+  /**
+   * True once the current synchronous call stack has finished and microtasks have started.
+   * EffectNode uses this to treat microtask notifications (e.g. async resolve) differently
+   * from coalesced sync-batch notifications.
+   */
+  static _pastSyncTurn = false;
+  /** @internal Used by EffectNode to distinguish sync-batch from microtask notifications. */
+  static get pastSyncTurn() {
+    return ExecutionStack._pastSyncTurn;
+  }
+  /**
+   * @internal Runs after the current sync turn ends (queueMicrotask).
+   * Marks pastSyncTurn so the next coalesced effect notify can bump its epoch,
+   * and resets per-effect coalesce flags via onReset.
+   */
+  static scheduleCoalesceReset(onReset) {
+    if (ExecutionStack._coalesceResetScheduled) return;
+    ExecutionStack._coalesceResetScheduled = true;
+    queueMicrotask(() => {
+      ExecutionStack._pastSyncTurn = true;
+      ExecutionStack._coalesceResetScheduled = false;
+      onReset();
+    });
+  }
   static pushPending(node) {
+    ExecutionStack._beginSyncTurn();
     ExecutionStack._scheduleExecution();
     ExecutionStack._pendingQueue.push(node);
   }
   static pushEffect(effect) {
+    ExecutionStack._beginSyncTurn();
     ExecutionStack._scheduleExecution();
     ExecutionStack._effectQueue.push(effect);
   }
+  static _beginSyncTurn() {
+    ExecutionStack._pastSyncTurn = false;
+  }
   static _scheduleExecution() {
     if (ExecutionStack._executionScheduled) return;
     ExecutionStack._executionScheduled = new Promise((resolve) => {
@@ -245,15 +277,21 @@ class ExecutionStack {
       }, 0);
     });
   }
+  static _drain(queue) {
+    for (let i = 0; i < queue.length; i++) {
+      if (i >= ExecutionStack._MAX_FLUSH_STEPS) {
+        ExecutionStack._pendingQueue.length = 0;
+        ExecutionStack._effectQueue.length = 0;
+        throw new Error("[PicoFlow] Reactive update cycle exceeded maximum depth");
+      }
+      const node = queue[i];
+      node?.execute();
+    }
+    queue.length = 0;
+  }
   static _execute() {
-    ExecutionStack._pendingQueue.forEach((node) => {
-      node.execute();
-    });
-    ExecutionStack._pendingQueue.length = 0;
-    ExecutionStack._effectQueue.forEach((effect) => {
-      effect.execute();
-    });
-    ExecutionStack._effectQueue.length = 0;
+    ExecutionStack._drain(ExecutionStack._pendingQueue);
+    ExecutionStack._drain(ExecutionStack._effectQueue);
   }
 }
 
@@ -403,32 +441,67 @@ class EffectNode extends Observer {
   _onData;
   _onError;
   _onPending;
+  /** True while this effect is already waiting in the effect queue for the next flush. */
+  _queued = false;
+  /** Guards the single coalesced bump of _notifyEpoch while _queued during one sync turn. */
+  _coalescedWhileQueued = false;
+  /** Monotonic count of notifications that must eventually be executed. */
+  _notifyEpoch = 0;
+  /** How many notification epochs have been executed so far. */
+  _executedEpoch = 0;
   constructor(data, onData, onError, onPending) {
     super();
     this._data = data;
     this._onData = onData;
     this._onError = onError;
     this._onPending = onPending;
+    this._notifyEpoch = 1;
     this.execute();
   }
   notify() {
     if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    if (this._queued) {
+      if (!this._coalescedWhileQueued) {
+        this._coalescedWhileQueued = true;
+        if (ExecutionStack.pastSyncTurn) {
+          this._notifyEpoch++;
+        }
+      }
+      return;
+    }
+    this._notifyEpoch++;
+    this._queued = true;
+    ExecutionStack.scheduleCoalesceReset(() => {
+      this._coalescedWhileQueued = false;
+    });
     ExecutionStack.pushEffect(this);
   }
   execute() {
-    try {
-      if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-      this.clearDependencies();
-      const data = this._data(this);
-      this._onData(data);
-    } catch (error) {
-      if (error instanceof PendingError) {
-        this._onPending?.();
-      } else {
-        if (this._onError) {
-          this._onError(error instanceof Error ? error : new Error(String(error)));
+    this._queued = false;
+    if (this._disposed) {
+      this._executedEpoch = this._notifyEpoch;
+      return;
+    }
+    const targetEpoch = this._notifyEpoch;
+    while (this._executedEpoch < targetEpoch) {
+      this._executedEpoch++;
+      if (this._disposed) {
+        this._executedEpoch = this._notifyEpoch;
+        return;
+      }
+      try {
+        this.clearDependencies();
+        const data = this._data(this);
+        this._onData(data);
+      } catch (error) {
+        if (error instanceof PendingError) {
+          this._onPending?.();
         } else {
-          throw error;
+          if (this._onError) {
+            this._onError(error instanceof Error ? error : new Error(String(error)));
+          } else {
+            throw error;
+          }
         }
       }
     }
@@ -570,12 +643,14 @@ class ValueAsyncNode extends ValueNode {
     );
   }
   _onResolve(value) {
+    if (this.disposed) return;
     this.status = "resolved";
     this._value = value;
     this._error = void 0;
     this.notifyDependents();
   }
   _onReject(error) {
+    if (this.disposed) return;
     this.status = "error";
     this._error = error;
     this.notifyDependents();
@@ -724,11 +799,66 @@ class ValueSyncNode extends ValueNode {
   }
 }
 
+class ActionNode extends ValueSyncNode {
+  _slots = /* @__PURE__ */ new Set();
+  _enqueueForSubscribers(action) {
+    for (const slot of this._slots) {
+      slot.queue.push(action);
+    }
+  }
+  set(valueOrUpdater) {
+    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    if (typeof valueOrUpdater === "function") {
+      const updater = valueOrUpdater;
+      const nextValue2 = updater(this._value);
+      if (this.status === "resolved" && nextValue2 === this._value) return;
+      this._enqueueForSubscribers(nextValue2);
+      super.set(updater);
+      return;
+    }
+    const nextValue = valueOrUpdater;
+    if (this.status === "resolved" && nextValue === this._value) return;
+    this._enqueueForSubscribers(nextValue);
+    super.set(nextValue);
+  }
+  subscribe(onValue, onError, onPending) {
+    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    const slot = { queue: [] };
+    this._slots.add(slot);
+    const effect = new EffectNode(
+      (tracker) => {
+        this.watch(tracker);
+        if (slot.queue.length === 0) {
+          return [this.get(tracker)];
+        }
+        return slot.queue.splice(0);
+      },
+      (actions) => {
+        for (const action of actions) {
+          onValue(action);
+        }
+      },
+      onError,
+      onPending
+    );
+    const originalDispose = effect.dispose.bind(effect);
+    effect.dispose = () => {
+      this._slots.delete(slot);
+      originalDispose();
+    };
+    return effect;
+  }
+  dispose() {
+    this._slots.clear();
+    super.dispose();
+  }
+}
+
 class ArrayNode extends ValueSyncNode {
   $lastAction;
   constructor(value = []) {
     super(value);
-    this.$lastAction = new ValueSyncNode({
+    this.$lastAction = new ActionNode({
       type: "set",
       setItems: value,
       clearedItems: []
@@ -781,6 +911,7 @@ class ArrayNode extends ValueSyncNode {
   }
   pop() {
     if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    if (this._value.length === 0) return void 0;
     const item = this._value.pop();
     this.notifyDependents();
     this.$lastAction.set({ type: "pop", removedItem: item });
@@ -794,6 +925,7 @@ class ArrayNode extends ValueSyncNode {
   }
   shift() {
     if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    if (this._value.length === 0) return void 0;
     const item = this._value.shift();
     this.notifyDependents();
     this.$lastAction.set({ type: "shift", removedItem: item });
@@ -822,9 +954,9 @@ class ArrayNode extends ValueSyncNode {
   }
   dispose() {
     super.dispose();
-    this._value.forEach((item) => {
-      if (item instanceof Disposable) item.dispose();
-    });
+    if (!this.$lastAction.disposed) {
+      this.$lastAction.dispose();
+    }
     this._value = [];
   }
 }
@@ -837,7 +969,7 @@ class MapNode extends ValueSyncNode {
   $lastAction;
   constructor(value = /* @__PURE__ */ new Map()) {
     super(value);
-    this.$lastAction = new ValueSyncNode({
+    this.$lastAction = new ActionNode({
       type: "set",
       setMap: value,
       clearedMap: /* @__PURE__ */ new Map()
@@ -845,8 +977,7 @@ class MapNode extends ValueSyncNode {
   }
   add(key, value) {
     if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
-    const previousValue = this._value.get(key);
-    if (previousValue) {
+    if (this._value.has(key)) {
       throw new Error("[PicoFlow] Key already exists");
     }
     this._value.set(key, value);
@@ -855,8 +986,8 @@ class MapNode extends ValueSyncNode {
   }
   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");
     const previousValue = this._value.get(key);
-    if (!previousValue) throw new Error("[PicoFlow] Key does not exist");
     this._value.set(key, value);
     this.notifyDependents();
     this.$lastAction.set({
@@ -869,8 +1000,8 @@ class MapNode extends ValueSyncNode {
   }
   delete(key) {
     if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    if (!this._value.has(key)) throw new Error("[PicoFlow] Key does not exist");
     const value = this._value.get(key);
-    if (value === void 0) throw new Error("[PicoFlow] Key does not exist");
     this._value.delete(key);
     this.notifyDependents();
     this.$lastAction.set({ type: "delete", key, removedValue: value });
@@ -897,9 +1028,9 @@ class MapNode extends ValueSyncNode {
   }
   dispose() {
     super.dispose();
-    this._value.forEach((item) => {
-      if (item instanceof Disposable) item.dispose();
-    });
+    if (!this.$lastAction.disposed) {
+      this.$lastAction.dispose();
+    }
     this._value.clear();
   }
 }
@@ -943,7 +1074,15 @@ function writableDerivation(compute) {
   return new ValueSyncNode(compute);
 }
 
-function fromNode(node) {
+function describeFlowInput(value) {
+  if (value === null) return "null";
+  if (typeof value === "object") {
+    const name = value.constructor?.name;
+    return name ? `object (${name})` : "object";
+  }
+  return typeof value;
+}
+function fromNode(node, options) {
   const [resource, { refetch }] = createResource(() => node.pick());
   let fx;
   onMount(() => {
@@ -968,14 +1107,19 @@ function fromNode(node) {
     resource.error ?? resource();
     resetErrorBoundaries();
   });
-  onCleanup(() => fx.dispose());
+  onCleanup(() => {
+    fx.dispose();
+    if (options?.disposeNode && !node.disposed) {
+      node.dispose();
+    }
+  });
   return resource;
 }
 function fromGetter(getter) {
   const derivation = new ValueSyncNode((t) => {
     return getter(t);
   });
-  return fromNode(derivation);
+  return fromNode(derivation, { disposeNode: true });
 }
 function from(flow) {
   if (flow instanceof ValueAsyncNode || flow instanceof ValueSyncNode) {
@@ -984,7 +1128,7 @@ function from(flow) {
   if (typeof flow === "function") {
     return fromGetter(flow);
   }
-  throw new Error("Invalid flow type");
+  throw new Error(`[PicoFlow] from(): expected a FlowValue or getter function, received ${describeFlowInput(flow)}`);
 }
 
 export { array, constant, constantAsync, derivation, derivationAsync, from, isDisposable, map, signal, state, stateAsync, subscribe, writableDerivation, writableDerivationAsync };

package/dist/types/api/base/flowObservable.d.ts

@@ -1,6 +1,6 @@
-import { FlowDisposable } from './flowDisposable';
-import { FlowSubscribable } from './flowSubscribable';
-import { FlowTracker } from './flowTracker';
+import { FlowDisposable } from './flowDisposable.js';
+import { FlowSubscribable } from './flowSubscribable.js';
+import { FlowTracker } from './flowTracker.js';
 /**
  * Contract for reactive primitives that emit changes and notify their dependents in the reactivity graph.
  * @public

package/dist/types/api/base/flowObservable.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"flowObservable.d.ts","sourceRoot":"","sources":["../../../../src/api/base/flowObservable.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAEjD;;;GAGG;AACH,MAAM,WAAW,cAAc,CAAC,CAAC,CAAE,SAAQ,cAAc,EAAE,gBAAgB,CAAC,CAAC,CAAC;IAC1E;;;;;;;OAOG;IACH,KAAK,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,CAAC;IAElC;;;;;;OAMG;IACH,OAAO,IAAI,IAAI,CAAC;CACnB"}
+{"version":3,"file":"flowObservable.d.ts","sourceRoot":"","sources":["../../../../src/api/base/flowObservable.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD;;;GAGG;AACH,MAAM,WAAW,cAAc,CAAC,CAAC,CAAE,SAAQ,cAAc,EAAE,gBAAgB,CAAC,CAAC,CAAC;IAC1E;;;;;;;OAOG;IACH,KAAK,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,CAAC;IAElC;;;;;;OAMG;IACH,OAAO,IAAI,IAAI,CAAC;CACnB"}

package/dist/types/api/base/flowSubscribable.d.ts

@@ -1,5 +1,5 @@
-import { FlowEffect } from '../nodes/flowEffect';
-import { FlowTracker } from './flowTracker';
+import { FlowEffect } from '../nodes/flowEffect.js';
+import { FlowTracker } from './flowTracker.js';
 /**
  * Function that tracks reactive dependencies and returns data.
  *