@ersbeth/picoflow 2.2.0 → 2.3.0

package/dist/picoflow.js

@@ -1,10 +1,84 @@
 import { createResource, onMount, createEffect, resetErrorBoundaries, onCleanup } from 'solid-js';
 
+class DependenciesRegistry {
+  _dependencies = /* @__PURE__ */ new Set();
+  register(dependency, dependent) {
+    this._dependencies.add(dependency);
+    dependency.registerDependent(dependent);
+  }
+  unregister(dependency, dependent) {
+    this._dependencies.delete(dependency);
+    dependency.unregisterDependent(dependent);
+  }
+  clear(dependent) {
+    this._dependencies.forEach((dependency) => {
+      dependency.unregisterDependent(dependent);
+    });
+    this._dependencies.clear();
+  }
+  forEach(fn) {
+    Array.from(this._dependencies).forEach(fn);
+  }
+}
+
+class DependentsRegistry {
+  _dependents = /* @__PURE__ */ new Set();
+  register(dependent) {
+    this._dependents.add(dependent);
+  }
+  unregister(dependent) {
+    this._dependents.delete(dependent);
+  }
+  notifyAll() {
+    this._dependents.forEach((dependent) => {
+      dependent.notify();
+    });
+  }
+  forEach(fn) {
+    Array.from(this._dependents).forEach(fn);
+  }
+}
+
+class PicoFlowError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "PicoFlowError";
+  }
+}
+class PicoFlowDisposedError extends PicoFlowError {
+  constructor(message) {
+    super(message);
+    this.name = "PicoFlowDisposedError";
+  }
+}
+class PicoFlowCycleError extends PicoFlowError {
+  constructor(message) {
+    super(message);
+    this.name = "PicoFlowCycleError";
+  }
+}
+class PicoFlowInternalError extends PicoFlowError {
+  constructor(message) {
+    super(message);
+    this.name = "PicoFlowInternalError";
+  }
+}
+
 class Disposable {
   _disposed = false;
+  _name;
+  constructor(name) {
+    this._name = name;
+  }
   get disposed() {
     return this._disposed;
   }
+  /** Builds the disposed-primitive error, naming the primitive when a `name` was given at creation. */
+  _disposedError() {
+    return new PicoFlowDisposedError(
+      this._name ? `[PicoFlow] Primitive "${this._name}" is disposed` : "[PicoFlow] Primitive is disposed"
+    );
+  }
 }
 
 class ExecutionStack {
@@ -13,6 +87,9 @@ class ExecutionStack {
   static _effectQueue = [];
   static _executionScheduled;
   static _coalesceResetScheduled = false;
+  /** Per-effect resets accumulated for the microtask scheduled below, so notifying more than one
+   * effect in the same sync turn doesn't discard every reset after the first (A2-SEM-5). */
+  static _coalesceResets = /* @__PURE__ */ new Set();
   /** Routes any error escaping the flush loop; defaults to logging rather than crashing (A2-SEM-2, A2-SEC-1). */
   static _onFlushError = (error) => console.error(error);
   /**
@@ -31,12 +108,17 @@ class ExecutionStack {
    * and resets per-effect coalesce flags via onReset.
    */
   static scheduleCoalesceReset(onReset) {
+    ExecutionStack._coalesceResets.add(onReset);
     if (ExecutionStack._coalesceResetScheduled) return;
     ExecutionStack._coalesceResetScheduled = true;
     queueMicrotask(() => {
       ExecutionStack._pastSyncTurn = true;
       ExecutionStack._coalesceResetScheduled = false;
-      onReset();
+      const resets = ExecutionStack._coalesceResets;
+      ExecutionStack._coalesceResets = /* @__PURE__ */ new Set();
+      resets.forEach((reset) => {
+        reset();
+      });
     });
   }
   /** @internal Wired to the public `onFlushError()` API in `src/api/base/flowConfig.ts`. */
@@ -71,7 +153,9 @@ class ExecutionStack {
       if (i >= ExecutionStack._MAX_FLUSH_STEPS) {
         ExecutionStack._pendingQueue.length = 0;
         ExecutionStack._effectQueue.length = 0;
-        ExecutionStack._onFlushError(new Error("[PicoFlow] Reactive update cycle exceeded maximum depth"));
+        ExecutionStack._onFlushError(
+          new PicoFlowCycleError("[PicoFlow] Reactive update cycle exceeded maximum depth")
+        );
         return;
       }
       const node = queue[i];
@@ -90,66 +174,59 @@ class ExecutionStack {
 }
 
 class Node extends Disposable {
-  _dependencies = /* @__PURE__ */ new Set();
-  _dependents = /* @__PURE__ */ new Set();
+  _dependenciesRegistry = new DependenciesRegistry();
+  _dependentsRegistry = new DependentsRegistry();
   _status = "resolved";
   get status() {
-    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    if (this.disposed) throw this._disposedError();
     return this._status;
   }
   set status(status) {
-    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    if (this.disposed) throw this._disposedError();
     this._status = status;
   }
   registerDependency(dependency) {
-    if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-    this._dependencies.add(dependency);
-    dependency.registerDependent(this);
+    if (this._disposed) throw this._disposedError();
+    this._dependenciesRegistry.register(dependency, this);
   }
   unregisterDependency(dependency) {
-    if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-    this._dependencies.delete(dependency);
-    dependency.unregisterDependent(this);
+    if (this._disposed) throw this._disposedError();
+    this._dependenciesRegistry.unregister(dependency, this);
   }
   clearDependencies() {
-    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
-    this._dependencies.forEach((dependency) => {
-      dependency.unregisterDependent(this);
-    });
-    this._dependencies.clear();
+    if (this.disposed) throw this._disposedError();
+    this._dependenciesRegistry.clear(this);
   }
   registerDependent(dependent) {
-    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
-    this._dependents.add(dependent);
+    if (this.disposed) throw this._disposedError();
+    this._dependentsRegistry.register(dependent);
   }
   unregisterDependent(dependent) {
-    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
-    this._dependents.delete(dependent);
+    if (this.disposed) throw this._disposedError();
+    this._dependentsRegistry.unregister(dependent);
   }
   markDependencyDisposed() {
   }
   notifyDependents() {
     if (this.disposed) return;
-    this._dependents.forEach((dependent) => {
-      dependent.notify();
-    });
+    this._dependentsRegistry.notifyAll();
   }
   watch(tracker) {
-    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    if (this.disposed) throw this._disposedError();
     tracker.registerDependency(this);
   }
   trigger() {
-    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    if (this.disposed) throw this._disposedError();
     this.notifyDependents();
   }
   dispose() {
     if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-    Array.from(this._dependents).forEach((dependant) => {
+    this._dependentsRegistry.forEach((dependant) => {
       dependant.markDependencyDisposed();
       dependant.unregisterDependency(this);
       this.unregisterDependent(dependant);
     });
-    Array.from(this._dependencies).forEach((dependency) => {
+    this._dependenciesRegistry.forEach((dependency) => {
       this.unregisterDependency(dependency);
     });
     this._disposed = true;
@@ -157,41 +234,39 @@ class Node extends Disposable {
 }
 
 class Observable extends Disposable {
-  _dependents = /* @__PURE__ */ new Set();
+  _dependentsRegistry = new DependentsRegistry();
   _status = "resolved";
   get status() {
-    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    if (this.disposed) throw this._disposedError();
     return this._status;
   }
   set status(status) {
-    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    if (this.disposed) throw this._disposedError();
     this._status = status;
   }
   registerDependent(dependent) {
-    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
-    this._dependents.add(dependent);
+    if (this.disposed) throw this._disposedError();
+    this._dependentsRegistry.register(dependent);
   }
   unregisterDependent(dependent) {
-    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
-    this._dependents.delete(dependent);
+    if (this.disposed) throw this._disposedError();
+    this._dependentsRegistry.unregister(dependent);
   }
   notifyDependents() {
     if (this.disposed) return;
-    this._dependents.forEach((dependent) => {
-      dependent.notify();
-    });
+    this._dependentsRegistry.notifyAll();
   }
   watch(tracker) {
-    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    if (this.disposed) throw this._disposedError();
     tracker.registerDependency(this);
   }
   trigger() {
-    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    if (this.disposed) throw this._disposedError();
     this.notifyDependents();
   }
   dispose() {
-    if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-    Array.from(this._dependents).forEach((dependant) => {
+    if (this._disposed) throw this._disposedError();
+    this._dependentsRegistry.forEach((dependant) => {
       dependant.markDependencyDisposed();
       dependant.unregisterDependency(this);
       this.unregisterDependent(dependant);
@@ -201,34 +276,27 @@ class Observable extends Disposable {
 }
 
 class Observer extends Disposable {
-  _dependencies = /* @__PURE__ */ new Set();
+  _dependenciesRegistry = new DependenciesRegistry();
   /** Set when a dependency disposed while this observer was queued; consumed by the next execute(). */
   _dependencyDisposed = false;
   markDependencyDisposed() {
     this._dependencyDisposed = true;
   }
   registerDependency(dependency) {
-    if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-    this._dependencies.add(dependency);
-    dependency.registerDependent(this);
+    if (this._disposed) throw this._disposedError();
+    this._dependenciesRegistry.register(dependency, this);
   }
   unregisterDependency(dependency) {
-    if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-    this._dependencies.delete(dependency);
-    dependency.unregisterDependent(this);
+    if (this._disposed) throw this._disposedError();
+    this._dependenciesRegistry.unregister(dependency, this);
   }
   clearDependencies() {
     if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
-    this._dependencies.forEach((dependency) => {
-      dependency.unregisterDependent(this);
-    });
-    this._dependencies.clear();
+    this._dependenciesRegistry.clear(this);
   }
   dispose() {
-    if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-    Array.from(this._dependencies).forEach((dependency) => {
-      this.unregisterDependency(dependency);
-    });
+    if (this._disposed) throw this._disposedError();
+    this._dependenciesRegistry.clear(this);
     this._disposed = true;
   }
 }
@@ -321,14 +389,14 @@ class AsyncScheduler {
     this._attachHandlers(this._resolver);
   }
   get settled() {
-    if (this._disposed) throw new Error("[PicoFlow] ComputationScheduler is disposed");
+    if (this._disposed) throw new PicoFlowDisposedError("[PicoFlow] ComputationScheduler is disposed");
     return this._settled.promise;
   }
   get disposed() {
     return this._disposed;
   }
   overwrite(promise) {
-    if (this._disposed) throw new Error("[PicoFlow] ComputationScheduler is disposed");
+    if (this._disposed) throw new PicoFlowDisposedError("[PicoFlow] ComputationScheduler is disposed");
     if (this._resolver.finished) {
       this._resolver = new AsyncResolver(this._compute);
       this._settled = Promise.withResolvers();
@@ -337,7 +405,7 @@ class AsyncScheduler {
     this._resolver.overwrite(promise);
   }
   compute() {
-    if (this._disposed) throw new Error("[PicoFlow] ComputationScheduler is disposed");
+    if (this._disposed) throw new PicoFlowDisposedError("[PicoFlow] ComputationScheduler is disposed");
     if (this._resolver.finished) {
       this._resolver = new AsyncResolver(this._compute);
       this._settled = Promise.withResolvers();
@@ -429,7 +497,7 @@ class SyncScheduler {
     return this._settled.promise;
   }
   overwrite(value) {
-    if (this._disposed) throw new Error("[PicoFlow] ComputationScheduler is disposed");
+    if (this._disposed) throw new PicoFlowDisposedError("[PicoFlow] ComputationScheduler is disposed");
     if (this._resolver.finished) {
       this._settled = Promise.withResolvers();
       this._resolver = new SyncResolver(this._compute, this._onResolve, this._onReject);
@@ -437,7 +505,7 @@ class SyncScheduler {
     this._resolver.overwrite(value);
   }
   compute() {
-    if (this._disposed) throw new Error("[PicoFlow] ComputationScheduler is disposed");
+    if (this._disposed) throw new PicoFlowDisposedError("[PicoFlow] ComputationScheduler is disposed");
     if (this._resolver.finished) {
       this._settled = Promise.withResolvers();
       this._resolver = new SyncResolver(this._compute, this._onResolve, this._onReject);
@@ -463,6 +531,8 @@ class EffectNode extends Observer {
   _notifyEpoch = 0;
   /** How many notification epochs have been executed so far. */
   _executedEpoch = 0;
+  /** Callbacks registered via {@link onDispose}, run once after dispose() tears down the graph edges. */
+  _disposeListeners = [];
   constructor(data, onData, onError, onPending) {
     super();
     this._data = data;
@@ -472,8 +542,23 @@ class EffectNode extends Observer {
     this._notifyEpoch = 1;
     this.execute();
   }
+  /**
+   * Registers a callback to run once this effect is disposed, after the graph edges are torn
+   * down. Lets a caller that wraps an effect (e.g. {@link ActionNode.subscribe}) attach its own
+   * teardown without patching `dispose` on the returned instance (A2-ARCH-8).
+   * @internal
+   */
+  onDispose(fn) {
+    this._disposeListeners.push(fn);
+  }
+  dispose() {
+    super.dispose();
+    this._disposeListeners.forEach((fn) => {
+      fn();
+    });
+  }
   notify() {
-    if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    if (this._disposed) throw this._disposedError();
     if (this._queued) {
       if (!this._coalescedWhileQueued) {
         this._coalescedWhileQueued = true;
@@ -537,8 +622,22 @@ class ValueNode extends Node {
   [PICOFLOW_VALUE_NODE] = true;
   _value;
   _error;
+  /** Builds the "unreachable state" error, naming the primitive when a `name` was given at creation. */
+  _internalError() {
+    return new PicoFlowInternalError(
+      this._name ? `[PicoFlow] Internal error (${this._name})` : "[PicoFlow] Internal error"
+    );
+  }
+  /**
+   * Hook called just before a tracked read throws `PendingError`, i.e. a dependent registered while
+   * this node is mid-flight and has no other way to learn the computation later settled (A2-PERF-4).
+   * No-op by default; overridden by {@link ValueAsyncNode} to know when its own post-resolve
+   * `notifyDependents()` call cannot be skipped even if the resolved value is unchanged.
+   */
+  _markPendingRead() {
+  }
   watch(tracker) {
-    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    if (this.disposed) throw this._disposedError();
     super.watch(tracker);
     switch (this.status) {
       case "resolved":
@@ -546,26 +645,28 @@ class ValueNode extends Node {
       case "error":
         throw this._error;
       case "pending": {
+        this._markPendingRead();
         throw new PendingError(this._scheduler.settled);
       }
       case "dirty": {
         this.execute();
         switch (this.status) {
           case "pending":
+            this._markPendingRead();
             throw new PendingError(this._scheduler.settled);
           case "resolved":
             return;
           case "error":
             throw this._error;
           case "dirty": {
-            throw new Error("[PicoFlow] Internal error");
+            throw this._internalError();
           }
         }
       }
     }
   }
   notify() {
-    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    if (this.disposed) throw this._disposedError();
     if (this.status === "dirty") return;
     if (this.status === "pending") {
       ExecutionStack.pushPending(this);
@@ -578,7 +679,7 @@ class ValueNode extends Node {
     this._scheduler.dispose();
   }
   get(tracker) {
-    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    if (this.disposed) throw this._disposedError();
     super.watch(tracker);
     switch (this.status) {
       case "resolved":
@@ -586,6 +687,7 @@ class ValueNode extends Node {
       case "error":
         throw this._error;
       case "pending": {
+        this._markPendingRead();
         throw new PendingError(this._scheduler.settled);
       }
       case "dirty": {
@@ -596,17 +698,18 @@ class ValueNode extends Node {
           case "error":
             throw this._error;
           case "pending": {
+            this._markPendingRead();
             throw new PendingError(this._scheduler.settled);
           }
           case "dirty": {
-            throw new Error("[PicoFlow] Internal error");
+            throw this._internalError();
           }
         }
       }
     }
   }
   async pick() {
-    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    if (this.disposed) throw this._disposedError();
     switch (this.status) {
       case "resolved":
         return this._value;
@@ -614,7 +717,7 @@ class ValueNode extends Node {
         await this._scheduler.settled;
         if (this.status === "resolved") return this._value;
         if (this.status === "error") throw this._error;
-        throw new Error("[PicoFlow] Internal error");
+        throw this._internalError();
       }
       case "error":
         throw this._error;
@@ -627,12 +730,12 @@ class ValueNode extends Node {
             await this._scheduler.settled;
             if (this.status === "resolved") return this._value;
             if (this.status === "error") throw this._error;
-            throw new Error("[PicoFlow] Internal error");
+            throw this._internalError();
           }
           case "error":
             throw this._error;
           case "dirty": {
-            throw new Error("[PicoFlow] Internal error");
+            throw this._internalError();
           }
         }
       }
@@ -645,7 +748,7 @@ class ValueNode extends Node {
     this._scheduler.compute();
   }
   subscribe(onValue, onError, onPending) {
-    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    if (this.disposed) throw this._disposedError();
     const effect = new EffectNode((t) => this.get(t), onValue, onError, onPending);
     return effect;
   }
@@ -654,8 +757,17 @@ class ValueNode extends Node {
 class ValueAsyncNode extends ValueNode {
   _scheduler;
   _compute;
-  constructor(promiseOrCompute) {
-    super();
+  /** Set by {@link ValueNode._markPendingRead} when a dependent registers while this node is mid-flight. */
+  _hasPendingReader = false;
+  /**
+   * True only while the in-flight computation was started by `set()`, which already ran its own
+   * eager `notifyDependents()` cascade before this resolution. `refresh()` and a recompute pulled
+   * lazily after an upstream `notify()` have no such pre-cascade — for them, `_onResolve`'s own
+   * `notifyDependents()` call is the only notification, so it must never be skipped (A2-PERF-4).
+   */
+  _pendingFromSet = false;
+  constructor(promiseOrCompute, name) {
+    super(name);
     if (typeof promiseOrCompute === "function") {
       this._compute = () => promiseOrCompute(this, this._value);
     } else {
@@ -670,10 +782,18 @@ class ValueAsyncNode extends ValueNode {
   }
   _onResolve(value) {
     if (this.disposed) return;
+    const changed = value !== this._value;
+    const hadPendingReader = this._hasPendingReader;
+    const pendingFromSet = this._pendingFromSet;
+    this._hasPendingReader = false;
+    this._pendingFromSet = false;
     this.status = "resolved";
     this._value = value;
     this._error = void 0;
-    this.notifyDependents();
+    if (changed || hadPendingReader || !pendingFromSet) this.notifyDependents();
+  }
+  _markPendingRead() {
+    this._hasPendingReader = true;
   }
   _onReject(error) {
     if (this.disposed) return;
@@ -682,12 +802,13 @@ class ValueAsyncNode extends ValueNode {
     this.notifyDependents();
   }
   set(promiseOrUpdater) {
-    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    if (this.disposed) throw this._disposedError();
     if (typeof promiseOrUpdater === "function") {
       const updater = promiseOrUpdater;
       switch (this.status) {
         case "resolved": {
           this.status = "pending";
+          this._pendingFromSet = true;
           this._scheduler.overwrite(updater(this._value));
           this.notifyDependents();
           return;
@@ -696,6 +817,7 @@ class ValueAsyncNode extends ValueNode {
         case "error":
         case "dirty": {
           this.status = "pending";
+          this._pendingFromSet = true;
           this._scheduler.overwrite(updater(this._value));
           this.notifyDependents();
           return;
@@ -703,38 +825,39 @@ class ValueAsyncNode extends ValueNode {
       }
     } else {
       this.status = "pending";
+      this._pendingFromSet = true;
       const promise = promiseOrUpdater;
       this._scheduler.overwrite(promise);
       this.notifyDependents();
     }
   }
   refresh() {
-    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    if (this.disposed) throw this._disposedError();
     this.execute();
   }
 }
 
-function constantAsync(valueOrInitializer) {
-  return new ValueAsyncNode(valueOrInitializer);
+function constantAsync(valueOrInitializer, options) {
+  return new ValueAsyncNode(valueOrInitializer, options?.name);
 }
 
-function derivationAsync(compute) {
-  return new ValueAsyncNode(compute);
+function derivationAsync(compute, options) {
+  return new ValueAsyncNode(compute, options?.name);
 }
 
-function stateAsync(valueOrInitializer) {
-  return new ValueAsyncNode(valueOrInitializer);
+function stateAsync(valueOrInitializer, options) {
+  return new ValueAsyncNode(valueOrInitializer, options?.name);
 }
 
-function writableDerivationAsync(compute) {
-  return new ValueAsyncNode(compute);
+function writableDerivationAsync(compute, options) {
+  return new ValueAsyncNode(compute, options?.name);
 }
 
 class ValueSyncNode extends ValueNode {
   _scheduler;
   _compute;
-  constructor(valueOrCompute) {
-    super();
+  constructor(valueOrCompute, name) {
+    super(name);
     if (typeof valueOrCompute === "function") {
       this._compute = () => valueOrCompute(this, this._value);
     } else {
@@ -760,7 +883,7 @@ class ValueSyncNode extends ValueNode {
     this._error = error;
   }
   set(valueOrUpdater) {
-    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    if (this.disposed) throw this._disposedError();
     if (typeof valueOrUpdater === "function") {
       const updater = valueOrUpdater;
       switch (this.status) {
@@ -804,7 +927,7 @@ class ValueSyncNode extends ValueNode {
     }
   }
   refresh() {
-    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    if (this.disposed) throw this._disposedError();
     const currentValue = this._value;
     const currentStatus = this.status;
     this.execute();
@@ -833,7 +956,7 @@ class ActionNode extends ValueSyncNode {
     }
   }
   set(valueOrUpdater) {
-    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    if (this.disposed) throw this._disposedError();
     if (typeof valueOrUpdater === "function") {
       const updater = valueOrUpdater;
       const nextValue2 = updater(this._value);
@@ -848,7 +971,7 @@ class ActionNode extends ValueSyncNode {
     super.set(nextValue);
   }
   subscribe(onValue, onError, onPending) {
-    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    if (this.disposed) throw this._disposedError();
     const slot = { queue: [] };
     this._slots.add(slot);
     const effect = new EffectNode(
@@ -867,11 +990,9 @@ class ActionNode extends ValueSyncNode {
       onError,
       onPending
     );
-    const originalDispose = effect.dispose.bind(effect);
-    effect.dispose = () => {
+    effect.onDispose(() => {
       this._slots.delete(slot);
-      originalDispose();
-    };
+    });
     return effect;
   }
   dispose() {
@@ -882,8 +1003,8 @@ class ActionNode extends ValueSyncNode {
 
 class ArrayNode extends ValueSyncNode {
   $lastAction;
-  constructor(value = []) {
-    super(value);
+  constructor(value = [], name) {
+    super(value, name);
     this.$lastAction = new ActionNode({
       type: "set",
       setItems: value,
@@ -899,11 +1020,11 @@ class ArrayNode extends ValueSyncNode {
     return [...values];
   }
   get length() {
-    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    if (this.disposed) throw this._disposedError();
     return this._value.length;
   }
   set(itemsOrUpdater) {
-    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    if (this.disposed) throw this._disposedError();
     const previousValue = this._value;
     super.set(itemsOrUpdater);
     this.$lastAction.set({
@@ -914,7 +1035,7 @@ class ArrayNode extends ValueSyncNode {
     return previousValue;
   }
   update(index, item) {
-    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    if (this.disposed) throw this._disposedError();
     if (index < 0 || index >= this._value.length || !Number.isInteger(index)) {
       throw new Error("[PicoFlow] Index out of bounds");
     }
@@ -930,13 +1051,13 @@ class ArrayNode extends ValueSyncNode {
     return previousValue;
   }
   push(item) {
-    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    if (this.disposed) throw this._disposedError();
     this._value.push(item);
     this.notifyDependents();
     this.$lastAction.set({ type: "push", addedItem: item });
   }
   pop() {
-    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    if (this.disposed) throw this._disposedError();
     if (this._value.length === 0) return void 0;
     const item = this._value.pop();
     this.notifyDependents();
@@ -944,13 +1065,13 @@ class ArrayNode extends ValueSyncNode {
     return item;
   }
   unshift(item) {
-    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    if (this.disposed) throw this._disposedError();
     this._value.unshift(item);
     this.notifyDependents();
     this.$lastAction.set({ type: "unshift", addedItem: item });
   }
   shift() {
-    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    if (this.disposed) throw this._disposedError();
     if (this._value.length === 0) return void 0;
     const item = this._value.shift();
     this.notifyDependents();
@@ -958,7 +1079,7 @@ class ArrayNode extends ValueSyncNode {
     return item;
   }
   splice(start, deleteCount, ...newItems) {
-    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    if (this.disposed) throw this._disposedError();
     const items = this._value.splice(start, deleteCount, ...newItems);
     this.notifyDependents();
     this.$lastAction.set({
@@ -971,7 +1092,7 @@ class ArrayNode extends ValueSyncNode {
     return items;
   }
   clear() {
-    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    if (this.disposed) throw this._disposedError();
     const previousValue = [...this._value];
     this._value = [];
     this.notifyDependents();
@@ -987,14 +1108,14 @@ class ArrayNode extends ValueSyncNode {
   }
 }
 
-function array(initial) {
-  return new ArrayNode(initial);
+function array(initial, options) {
+  return new ArrayNode(initial, options?.name);
 }
 
 class MapNode extends ValueSyncNode {
   $lastAction;
-  constructor(value = /* @__PURE__ */ new Map()) {
-    super(value);
+  constructor(value = /* @__PURE__ */ new Map(), name) {
+    super(value, name);
     this.$lastAction = new ActionNode({
       type: "set",
       setMap: value,
@@ -1002,7 +1123,7 @@ class MapNode extends ValueSyncNode {
     });
   }
   add(key, value) {
-    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    if (this.disposed) throw this._disposedError();
     if (this._value.has(key)) {
       throw new Error("[PicoFlow] Key already exists");
     }
@@ -1011,7 +1132,7 @@ class MapNode extends ValueSyncNode {
     this.$lastAction.set({ type: "add", key, addedValue: value });
   }
   update(key, value) {
-    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    if (this.disposed) throw this._disposedError();
     if (!this._value.has(key)) throw new Error("[PicoFlow] Key does not exist");
     const previousValue = this._value.get(key);
     this._value.set(key, value);
@@ -1025,7 +1146,7 @@ class MapNode extends ValueSyncNode {
     return previousValue;
   }
   delete(key) {
-    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    if (this.disposed) throw this._disposedError();
     if (!this._value.has(key)) throw new Error("[PicoFlow] Key does not exist");
     const value = this._value.get(key);
     this._value.delete(key);
@@ -1034,7 +1155,7 @@ class MapNode extends ValueSyncNode {
     return value;
   }
   set(mapOrUpdater) {
-    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    if (this.disposed) throw this._disposedError();
     const previousValue = this._value;
     super.set(mapOrUpdater);
     this.$lastAction.set({
@@ -1045,7 +1166,7 @@ class MapNode extends ValueSyncNode {
     return previousValue;
   }
   clear() {
-    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    if (this.disposed) throw this._disposedError();
     const previousValue = this._value;
     this._value = /* @__PURE__ */ new Map();
     this.notifyDependents();
@@ -1061,11 +1182,11 @@ class MapNode extends ValueSyncNode {
   }
 }
 
-function map(initial) {
+function map(initial, options) {
   if (initial instanceof Map) {
-    return new MapNode(initial);
+    return new MapNode(initial, options?.name);
   }
-  return new MapNode(new Map(initial ? Object.entries(initial) : []));
+  return new MapNode(new Map(initial ? Object.entries(initial) : []), options?.name);
 }
 
 function subscribe(data, onData, onError, onPending) {
@@ -1074,30 +1195,30 @@ function subscribe(data, onData, onError, onPending) {
 
 class SignalNode extends Observable {
   subscribe(onTrigger, onError, onPending) {
-    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    if (this.disposed) throw this._disposedError();
     const effect = new EffectNode((t) => this.watch(t), onTrigger, onError, onPending);
     return effect;
   }
 }
 
-function signal() {
-  return new SignalNode();
+function signal(options) {
+  return new SignalNode(options?.name);
 }
 
-function constant(initializer) {
-  return new ValueSyncNode(initializer);
+function constant(initializer, options) {
+  return new ValueSyncNode(initializer, options?.name);
 }
 
-function derivation(compute) {
-  return new ValueSyncNode(compute);
+function derivation(compute, options) {
+  return new ValueSyncNode(compute, options?.name);
 }
 
-function state(valueOrInitializer) {
-  return new ValueSyncNode(valueOrInitializer);
+function state(valueOrInitializer, options) {
+  return new ValueSyncNode(valueOrInitializer, options?.name);
 }
 
-function writableDerivation(compute) {
-  return new ValueSyncNode(compute);
+function writableDerivation(compute, options) {
+  return new ValueSyncNode(compute, options?.name);
 }
 
 function describeFlowInput(value) {
@@ -1160,4 +1281,4 @@ function from(flow) {
   throw new Error(`[PicoFlow] from(): expected a FlowValue or getter function, received ${describeFlowInput(flow)}`);
 }
 
-export { array, constant, constantAsync, derivation, derivationAsync, from, isDisposable, map, onFlushError, signal, state, stateAsync, subscribe, writableDerivation, writableDerivationAsync };
+export { PicoFlowCycleError, PicoFlowDisposedError, PicoFlowError, PicoFlowInternalError, array, constant, constantAsync, derivation, derivationAsync, from, isDisposable, map, onFlushError, signal, state, stateAsync, subscribe, writableDerivation, writableDerivationAsync };