@ersbeth/picoflow 0.0.1 → 0.2.0

package/dist/picoflow.js

@@ -1,236 +1,110 @@
 class FlowSignal {
-  /* API ---------------------------------------------------------------------- */
   /**
-   * Triggers the signal.
-   * @remarks
-   * This method notifies all registered listeners and causes associated effects to execute.
-   * @throws Error if the signal is disposed.
+   * Triggers the FlowSignal.
+   * Notifies all registered listeners and schedules execution of associated effects.
+   * @throws If the FlowSignal has already been disposed.
    * @public
    */
   trigger() {
-    if (this._disposed) throw new Error("Signal is disposed");
+    if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
     this._notify();
   }
   /**
-   * Disposes the signal.
-   * @remarks
-   * Disposing a signal will dispose all registered effects and listeners,
-   * and unregister all dependencies. Once disposed, any further calls to the signal
-   * will throw an error.
-   * @throws Error if the signal is already disposed.
+   * 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.
    * @public
    */
-  dispose() {
-    if (this._disposed) throw new Error("Signal is disposed");
-    Array.from(this._effects).forEach((effect) => effect.dispose());
-    Array.from(this._listeners).forEach((listener) => listener.dispose());
+  dispose(options) {
+    if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    if (options?.self) {
+      Array.from(this._effects).forEach(
+        (effect) => effect._unregisterDependency(this)
+      );
+      Array.from(this._listeners).forEach(
+        (listener) => listener._unregisterDependency(this)
+      );
+    } else {
+      Array.from(this._effects).forEach((effect) => effect.dispose());
+      Array.from(this._listeners).forEach(
+        (listener) => listener.dispose()
+      );
+    }
     Array.from(this._dependencies).forEach((dependency) => {
       this._unregisterDependency(dependency);
     });
     this._disposed = true;
   }
   /**
-   * Indicates whether the signal has been disposed.
-   * @remarks
-   * Once disposed, the signal should not be used.
+   * Indicates whether the FlowSignal has been disposed.
+   * @remarks Once disposed, the signal should not be used.
    * @public
    */
   get disposed() {
     return this._disposed;
   }
   /* INTERNAL ------------------------------------------------------------- */
-  /**
-   * @internal
-   */
+  /*@internal*/
   _disposed = false;
-  /**
-   * @internal
-   */
+  /*@internal*/
   _dependencies = /* @__PURE__ */ new Set();
-  /**
-   * @internal
-   */
+  /*@internal*/
   _listeners = /* @__PURE__ */ new Set();
-  /**
-   * @internal
-   */
+  /*@internal*/
   _effects = /* @__PURE__ */ new Set();
-  /**
-   * @internal
-   * Internal method to watch the signal.
-   * @throws Error if the signal is disposed.
-   */
+  /*@internal*/
   _watch() {
-    if (this._disposed) throw new Error("Signal is disposed");
+    if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
   }
-  /**
-   * @internal
-   * Notifies all listeners and executes all registered effects.
-   */
+  /*@internal*/
   _notify() {
     this._listeners.forEach((listener) => listener._notify());
     this._effects.forEach((effect) => effect._exec());
   }
-  /**
-   * @internal
-   * Registers a dependency from the given listener and watches the signal.
-   * @param listener - A FlowSignal or FlowEffect that will depend on this signal.
-   */
+  /*@internal*/
   _watchFrom(listener) {
     listener._registerDependency(this);
     this._watch();
   }
-  /**
-   * @internal
-   * Registers a dependency with the given FlowSignal.
-   * @param dependency - The FlowSignal to register as a dependency.
-   */
+  /*@internal*/
   _registerDependency(dependency) {
     this._dependencies.add(dependency);
     dependency._registerListener(this);
   }
-  /**
-   * @internal
-   * Unregisters the given dependency.
-   * @param dependency - The FlowSignal to unregister.
-   */
+  /*@internal*/
   _unregisterDependency(dependency) {
     this._dependencies.delete(dependency);
     dependency._unregisterListener(this);
   }
-  /**
-   * @internal
-   * Registers a listener (another FlowSignal) to this signal.
-   * @param signal - The FlowSignal to register as a listener.
-   */
+  /*@internal*/
   _registerListener(signal) {
     this._listeners.add(signal);
   }
-  /**
-   * @internal
-   * Unregisters the given listener.
-   * @param signal - The FlowSignal to unregister.
-   */
+  /*@internal*/
   _unregisterListener(signal) {
     this._listeners.delete(signal);
   }
-  /**
-   * @internal
-   * Registers a FlowEffect to this signal.
-   * @param effect - The FlowEffect to register.
-   */
+  /*@internal*/
   _registerEffect(effect) {
     this._effects.add(effect);
   }
-  /**
-   * @internal
-   * Unregisters the given FlowEffect.
-   * @param effect - The FlowEffect to unregister.
-   */
+  /*@internal*/
   _unregisterEffect(effect) {
     this._effects.delete(effect);
   }
 }
 
-class FlowObservable extends FlowSignal {
-  /* INTERNAL -------------------------------------------*/
-  /**
-   * @internal
-   * Internal storage for the observable's value.
-   */
-  _value;
-  /**
-   * @internal
-   * Retrieves the current value from the observable and registers a dependency
-   * from the provided listener.
-   * @param listener - The FlowObservable or FlowEffect that is accessing this observable.
-   * @returns The current value, as returned by {@link FlowObservable.get}.
-   */
-  _getFrom(listener) {
-    listener._registerDependency(this);
-    return this.get();
-  }
-}
-
-class FlowDerivation extends FlowObservable {
-  /**
-   * Creates a new FlowDerivation.
-   * @param compute - A function that computes the derived value. It is provided with a getter
-   * and a watcher function to access observables and signals dependencies.
-   * @public
-   */
-  constructor(compute) {
-    super();
-    this._trackedExec = () => compute(this._trackedGet, this._trackedWatch);
-    this._untrackedExec = () => compute(this._untrackedGet, this._untrackedWatch);
-  }
-  /**
-   * Gets the current derived value.
-   * @returns The current computed value.
-   * @remarks
-   * This method ensures that the derivation is up-to-date before returning the value.
-   * @public
-   */
-  get() {
-    this._exec();
-    return this._value;
-  }
-  /* INTERNAL MEMBERS AND METHODS */
-  /** @internal */
-  _initialized = false;
-  /** @internal */
-  _dirty = true;
-  /** @internal */
-  _trackedGet = (observable) => observable._getFrom(this);
-  /** @internal */
-  _trackedWatch = (signal) => signal._watchFrom(this);
-  /** @internal */
-  _untrackedGet = (observable) => observable.get();
-  /** @internal */
-  _untrackedWatch = (signal) => signal._watch();
-  /** @internal */
-  _trackedExec;
-  /** @internal */
-  _untrackedExec;
-  /**
-   * @internal
-   * Executes the compute function if necessary to update the derived value.
-   */
-  _exec() {
-    if (this._disposed) throw new Error("Effect is disposed");
-    if (this._dirty) {
-      if (this._initialized) this._value = this._untrackedExec();
-      else {
-        this._value = this._trackedExec();
-        this._initialized = true;
-      }
-      this._dirty = false;
-    }
-  }
-  /**
-   * @internal
-   * Marks the derivation as dirty and notifies downstream dependencies.
-   */
-  _notify() {
-    this._dirty = true;
-    super._notify();
-  }
-  /**
-   * @internal
-   * Ensures that the derivation is up-to-date when it is watched.
-   */
-  _watch() {
-    this._exec();
-  }
-}
-
 class FlowEffect {
-  /* API --------------------------------------------------- */
   /**
    * Creates a new FlowEffect.
    *
-   * @param apply - A function that performs the side effect. It receives a getter and a watcher
-   * function to access and register dependencies on reactive observables and signals.
+   * @param apply - A side-effect function that receives a getter and a watcher to
+   * access and register dependencies on reactive observables and signals.
+   *
+   * @remarks
+   * The provided function is executed immediately in a tracked mode to collect dependencies.
+   * On subsequent executions, it runs in an untracked mode.
    *
    * @public
    */
@@ -240,16 +114,16 @@ class FlowEffect {
     this._exec();
   }
   /**
-   * Disposes the effect, unregistering all its dependencies.
+   * Disposes the effect, unregistering all its tracked dependencies.
    *
    * @remarks
-   * After disposal, the effect should no longer be used. Calling this method on an already
-   * disposed effect will throw an error.
+   * Once disposed, the effect must no longer be used. Trying to dispose an effect
+   * that is already disposed will throw an error.
    *
    * @public
    */
   dispose() {
-    if (this._disposed) throw new Error("Effect is disposed");
+    if (this._disposed) throw new Error("[PicoFlow] Effect is disposed");
     Array.from(this._dependencies).forEach((dependency) => {
       this._unregisterDependency(dependency);
     });
@@ -258,7 +132,7 @@ class FlowEffect {
   /**
    * Indicates whether this effect has been disposed.
    *
-   * @returns A boolean value indicating if the effect is disposed.
+   * @returns A boolean value that is true if the effect is disposed, false otherwise.
    *
    * @public
    */
@@ -266,168 +140,198 @@ class FlowEffect {
     return this._disposed;
   }
   /* INTERNAL ------------------------------------------------------------ */
-  /**
-   * @internal
-   */
   _disposed = false;
-  /**
-   * @internal
-   */
   _initialized = false;
-  /**
-   * @internal
-   */
   _dependencies = /* @__PURE__ */ new Set();
-  /**
-   * @internal
-   * A tracked getter that registers a dependency when accessing an observable.
-   */
   _trackedGet = (observable) => observable._getFrom(this);
-  /**
-   * @internal
-   * A tracked watcher that registers a dependency when watching a signal.
-   */
   _trackedWatch = (signal) => signal._watchFrom(this);
-  /**
-   * @internal
-   * An untracked getter that simply retrieves the current value from an observable.
-   */
   _untrackedGet = (observable) => observable.get();
-  /**
-   * @internal
-   * An untracked watcher that calls the default watch on a signal.
-   */
   _untrackedWatch = (signal) => signal._watch();
-  /**
-   * @internal
-   * Execution function used during initialization (tracked mode).
-   */
   _trackedExec;
-  /**
-   * @internal
-   * Execution function used after initialization (untracked mode).
-   */
   _untrackedExec;
-  /**
-   * @internal
-   * Executes the effect. If the effect has not been initialized, it runs in tracked mode;
-   * otherwise, it runs in untracked mode.
-   *
-   * @throws Error if the effect has been disposed.
-   */
+  /*@internal*/
   _exec() {
-    if (this._disposed) throw new Error("Effect is disposed");
+    if (this._disposed)
+      throw new Error("[PicoFlow] Effect is disposed");
     if (this._initialized) this._untrackedExec();
     else {
       this._trackedExec();
       this._initialized = true;
     }
   }
-  /**
-   * @internal
-   * Registers a dependency on the given signal.
-   *
-   * @param dependency - The FlowSignal to register as a dependency.
-   */
+  /*@internal*/
   _registerDependency(dependency) {
     this._dependencies.add(dependency);
     dependency._registerEffect(this);
   }
-  /**
-   * @internal
-   * Unregisters the given dependency.
-   *
-   * @param dependency - The FlowSignal to unregister.
-   */
+  /*@internal*/
   _unregisterDependency(dependency) {
     this._dependencies.delete(dependency);
     dependency._unregisterEffect(this);
   }
 }
 
-class FlowResource extends FlowObservable {
+class FlowObservable extends FlowSignal {
+  /* INTERNAL -------------------------------------------*/
+  /*@internal*/
+  _value;
+  /*@internal*/
+  _getFrom(listener) {
+    listener._registerDependency(this);
+    return this.get();
+  }
   /**
-   * Creates a new FlowResource.
-   * @param fetch - An asynchronous function that retrieves the resource's value.
-   * @param initial - The initial value of the resource.
+   * 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.
+   */
+  subscribe(listener) {
+    const effect = new FlowEffect((get) => {
+      listener(get(this));
+    });
+    return () => effect.dispose();
+  }
+}
+
+class FlowConstant extends FlowObservable {
+  /**
+   * Creates a new FlowConstant instance.
+   *
+   * @param value - Either a direct value of type T or a function returning a value of type T for lazy initialization.
    * @public
    */
-  constructor(fetch, initial) {
+  constructor(value) {
     super();
-    this._value = initial;
-    this._fetch = fetch;
+    this._initEager(value);
   }
   /**
-   * Retrieves the current resource value.
-   * @returns The current value.
-   * @throws Error if the resource is disposed.
+   * Retrieves the constant value, computing it lazily if needed.
+   *
+   * Accessing this method will initialize the value if it has not been computed already.
+   * Throws an error if the instance has been disposed or if lazy initialization fails.
+   *
+   * @returns The cached constant value.
+   * @throws Error if the constant is disposed or cannot be initialized.
    * @public
    */
   get() {
-    if (this._disposed) throw new Error("Resource is disposed");
+    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;
+    } else {
+      this._value = value;
+      this._initialized = true;
+    }
+  }
+  /*@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");
+  }
+}
+
+class FlowState extends FlowConstant {
   /**
-   * Asynchronously fetches a new value for the resource.
+   * Updates the state with a new value.
+   * @param value - A new value or a callback function that computes a new value based on the current state.
    * @remarks
-   * 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.
+   * If the computed new value is strictly equal to the current state value, no change is made and subscribers
+   * will not be notified. Otherwise, the state is updated and all subscribers are informed of the change.
+   * @throws Error if the state has been disposed.
    * @public
    */
-  async fetch() {
-    if (this._disposed) throw new Error("Resource is disposed");
-    const value = await this._fetch();
-    if (value === this._value) return;
-    this._value = value;
+  set(value) {
+    if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    const next = typeof value === "function" ? value(this._value) : value;
+    if (next === this._value) return;
+    this._value = next;
     this._notify();
   }
-  /* INTERNAL ------------------------------------------------ */
-  /**
-   * @internal
-   * The asynchronous function used to fetch the resource value.
-   */
-  _fetch;
 }
 
-class FlowState extends FlowObservable {
+class FlowDerivation extends FlowObservable {
   /**
-   * Creates a new FlowState with the given initial value.
-   * @param value - The initial value for the state.
+   * Creates a new FlowDerivation.
+   * @param compute - A function that computes the derived value. It is provided with two parameters:
+   * a getter and a watcher that respect dependency tracking.
    * @public
    */
-  constructor(value) {
+  constructor(compute) {
     super();
-    this._value = value;
+    this._initEager(compute);
   }
   /**
-   * Retrieves the current state value.
-   * @returns The current value of the state.
-   * @throws Error if the state has been disposed.
+   * Gets the current derived value.
+   * @returns The current computed value.
+   * @remarks
+   * This method lazily initializes and updates the derivation if it is marked as dirty. It throws an error
+   * if the derivation has been disposed.
    * @public
    */
   get() {
-    if (this._disposed) throw new Error("State is disposed");
+    if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    this._initLazy();
+    this._compute();
     return this._value;
   }
-  /**
-   * Updates the state with a new value.
-   * @param value - The new value to set.
-   * @remarks
-   * If the new value is identical to the current value, no update or notification occurs.
-   * Otherwise, the state is updated and all subscribers are notified.
-   * @throws Error if the state has been disposed.
-   * @public
-   */
-  set(value) {
-    if (this._disposed) throw new Error("State is disposed");
-    if (value === this._value) return;
-    this._value = value;
-    this._notify();
+  /* INTERNAL --------------------------------------------------------- */
+  _initialized = false;
+  _dirty = false;
+  _trackedGet = (observable) => observable._getFrom(this);
+  _trackedWatch = (signal) => signal._watchFrom(this);
+  _untrackedGet = (observable) => observable.get();
+  _untrackedWatch = (signal) => signal._watch();
+  _trackedCompute;
+  _untrackedCompute;
+  _initEager(compute) {
+    this._trackedCompute = () => compute(this._trackedGet, this._trackedWatch);
+    this._untrackedCompute = () => compute(this._untrackedGet, this._untrackedWatch);
+  }
+  _initLazy() {
+    if (!this._initialized) {
+      this._value = this._trackedCompute();
+      this._initialized = true;
+    }
+  }
+  /* @internal */
+  _compute() {
+    if (this._dirty) {
+      this._value = this._untrackedCompute();
+      this._dirty = false;
+    }
+  }
+  /* @internal */
+  _notify() {
+    this._dirty = true;
+    super._notify();
+  }
+  /* @internal */
+  _watch() {
+    if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    this._initLazy();
+    this._compute();
   }
 }
 
+function isDisposable(obj) {
+  return obj !== null && obj !== void 0 && typeof obj.dispose === "function";
+}
+
 class FlowMap extends FlowState {
   /**
    * A reactive state that holds the most recent key and value that were set.
@@ -454,15 +358,16 @@ class FlowMap extends FlowState {
    *
    * @param key - The key at which to set the value.
    * @param value - The value to set.
+   * @throws If the FlowMap instance is disposed.
    *
    * @remarks
-   * This method updates the internal map with the given key and value, emits the new
-   * key-value pair via {@link FlowMap.$lastSet}, and notifies subscribers of the change.
+   * Updates the internal map, emits the key-value pair via {@link FlowMap.$lastSet},
+   * and notifies all subscribers of the change.
    *
    * @public
    */
   setAt(key, value) {
-    if (this._disposed) throw new Error("StateMap is disposed");
+    if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
     this._value.set(key, value);
     this.$lastSet.set({ key, value });
     this._notify();
@@ -471,16 +376,16 @@ class FlowMap extends FlowState {
    * Deletes the value at the specified key from the underlying map.
    *
    * @param key - The key to delete.
+   * @throws If the FlowMap instance is disposed.
    *
    * @remarks
-   * This method removes the key from the internal map, emits the deleted key and its
-   * corresponding value via {@link FlowMap.$lastDeleted}, and notifies subscribers
-   * of the change.
+   * Removes the key from the internal map, emits the deleted key and its value via {@link FlowMap.$lastDeleted},
+   * and notifies all subscribers of the change.
    *
    * @public
    */
   delete(key) {
-    if (this._disposed) throw new Error("StateMap is disposed");
+    if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
     const value = this._value.get(key);
     this._value.delete(key);
     this.$lastDeleted.set({ key, value });
@@ -489,29 +394,26 @@ class FlowMap extends FlowState {
 }
 
 class FlowStream extends FlowObservable {
-  /* API -------------------------------------------------------- */
   /**
    * Creates a new FlowStream.
    * @param updater - A function that receives a setter to update the stream's value.
    * It should return a disposer function that will be called upon disposal.
-   * @param initial - The initial value of the stream.
    * @public
    */
-  constructor(updater, initial) {
+  constructor(updater) {
     super();
-    this._value = initial;
     this._disposer = updater((value) => {
       this._set(value);
     });
   }
   /**
    * Retrieves the current value of the stream.
-   * @returns The current value.
+   * @returns The current value, or undefined if no value has been set yet.
    * @throws Error if the stream is disposed.
    * @public
    */
   get() {
-    if (this._disposed) throw new Error("Stream is disposed");
+    if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
     return this._value;
   }
   /**
@@ -526,36 +428,339 @@ class FlowStream extends FlowObservable {
     this._disposer();
   }
   /* INTERNAL ------------------------------------------------------ */
+  _disposer;
+  _set(value) {
+    if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    if (value === this._value) return;
+    this._value = value;
+    this._notify();
+  }
+}
+
+class FlowStreamAsync extends FlowObservable {
   /**
-   * @internal
-   * The disposer function returned by the updater.
+   * Creates a new asynchronous FlowStream.
+   * @param updater - A function that receives a setter to update the stream's value.
+   * It should return a disposer function that will be called upon disposal.
+   * @remarks The updater function can invoke the setter asynchronously to update the stream.
+   * @public
    */
-  _disposer;
+  constructor(updater) {
+    super();
+    this._disposer = updater((value) => {
+      this._set(value);
+    });
+    this._value = new Promise((resolve) => {
+      this._resolve = resolve;
+    });
+  }
+  /**
+   * Retrieves the current value of the stream as a Promise.
+   * @returns A Promise that resolves to the current value.
+   * @throws Error if the stream is disposed.
+   * @public
+   */
+  get() {
+    if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    return this._value;
+  }
   /**
-   * @internal
-   * Updates the stream's value and notifies subscribers if the value changes.
-   * @param value - The new value to set.
-   * @internal
+   * Disposes the stream, releasing all resources.
+   * @remarks In addition to disposing the underlying observable, this method calls the disposer
+   * returned by the updater.
+   * @public
    */
+  dispose() {
+    super.dispose();
+    this._disposer();
+  }
+  /* INTERNAL ------------------------------------------------------ */
+  _initialized = false;
+  _awaitedValue;
+  _resolve;
+  _disposer;
   _set(value) {
-    if (this._disposed) throw new Error("Stream is disposed");
+    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 FlowResource extends FlowObservable {
+  /**
+   * Creates a new FlowResource.
+   * @param fetch - An asynchronous function that retrieves the resource's value.
+   *
+   * @public
+   */
+  constructor(fetch) {
+    super();
+    this._fetch = fetch;
+  }
+  /**
+   * Retrieves the current resource value.
+   * @returns The current value, or undefined if the resource has not been fetched yet.
+   * @throws Error if the resource is disposed.
+   * @public
+   */
+  get() {
+    if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    return this._value;
+  }
+  /**
+   * Asynchronously fetches a new value for the resource.
+   * @remarks
+   * Executes the internal fetch function. If the fetched value differs from the current one,
+   * updates the resource's value and notifies subscribers.
+   * @returns A Promise that resolves when the fetch operation is complete.
+   * @throws Error if the resource is disposed.
+   * @public
+   */
+  async fetch() {
+    if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    const value = await this._fetch();
     if (value === this._value) return;
     this._value = value;
     this._notify();
   }
+  /* INTERNAL ------------------------------------------------ */
+  _fetch;
+}
+
+class FlowResourceAsync extends FlowObservable {
+  /**
+   * Creates a new FlowResource.
+   * @param fetch - An asynchronous function that retrieves the resource's value.
+   * @public
+   */
+  constructor(fetch) {
+    super();
+    this._fetch = fetch;
+  }
+  /**
+   * Retrieves the current resource value.
+   * @returns The current value, or undefined if the resource has not been fetched yet.
+   * @throws Error if the resource is disposed.
+   * @public
+   */
+  get() {
+    if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    if (!this._value) this._value = this._fetch();
+    return this._value;
+  }
+  /**
+   * Asynchronously fetches a new value for the resource.
+   * @remarks
+   * Executes the internal fetch function. If the fetched value differs from the current one,
+   * updates the resource's value and notifies subscribers.
+   * @returns A Promise that resolves when the fetch operation is complete.
+   * @throws Error if the resource is disposed.
+   * @public
+   */
+  async fetch() {
+    if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    this._value = this._fetch();
+    this._notify();
+  }
+  /* INTERNAL ------------------------------------------------ */
+  _fetch;
+}
+
+class FlowArray extends FlowObservable {
+  /**
+   * Last action performed on the FlowArray.
+   * @public
+   */
+  $lastAction;
+  /**
+   * Creates an instance of FlowArray.
+   * @param value - Initial array value.
+   * @public
+   */
+  constructor(value = []) {
+    super();
+    this._value = value;
+    this.$lastAction = state({
+      type: "set",
+      items: value
+    });
+  }
+  /**
+   * Gets the current length of the array.
+   * @returns The length of the array.
+   * @public
+   */
+  get length() {
+    if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    return this._value.length;
+  }
+  /**
+   * Returns a copy of the internal array.
+   * @returns A copy of the array.
+   * @public
+   */
+  get() {
+    if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    return [...this._value];
+  }
+  /**
+   * Replaces the entire array with new items.
+   * @param items - The new array of items.
+   * @public
+   */
+  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 });
+  }
+  /**
+   * Replaces an item at a specific index.
+   * @param index - The index of the item to replace.
+   * @param item - The new item.
+   * @public
+   */
+  setItem(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 });
+  }
+  /**
+   * Appends an item to the end of the array.
+   * @param item - The item to append.
+   * @public
+   */
+  push(item) {
+    if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    this._value.push(item);
+    this._notify();
+    this.$lastAction.set({ type: "push", item });
+  }
+  /**
+   * Removes the last item from the array.
+   * @public
+   */
+  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" });
+  }
+  /**
+   * Inserts an item at the beginning of the array.
+   * @param item - The item to insert.
+   * @public
+   */
+  unshift(item) {
+    if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    this._value.unshift(item);
+    this._notify();
+    this.$lastAction.set({ type: "unshift", item });
+  }
+  /**
+   * Removes the first item from the array.
+   * @public
+   */
+  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" });
+  }
+  /**
+   * Changes the content of the array.
+   * @param start - The starting index.
+   * @param deleteCount - Number of items to remove.
+   * @param newItems - New items to add.
+   * @public
+   */
+  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
+    });
+  }
+  /**
+   * Clears all items from the array.
+   * @public
+   */
+  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" });
+  }
+  /**
+   * Disposes the FlowArray and its items.
+   * @param options - Disposal options.
+   * @public
+   */
+  dispose(options) {
+    super.dispose(options);
+    this._value.forEach((item) => {
+      if (isDisposable(item)) item.dispose(options);
+    });
+    this._value = [];
+  }
+  /* INTERNAL */
+  /*@internal*/
+  _value = [];
 }
 
 function signal() {
   return new FlowSignal();
 }
+function constant(value) {
+  return new FlowConstant(value);
+}
 function state(value) {
   return new FlowState(value);
 }
-function resource(fn, initial) {
-  return new FlowResource(fn, initial);
+function resource(fn) {
+  return new FlowResource(fn);
 }
-function stream(updater, initial) {
-  return new FlowStream(updater, initial);
+function resourceAsync(fn) {
+  return new FlowResourceAsync(fn);
+}
+function stream(updater) {
+  return new FlowStream(updater);
+}
+function streamAsync(updater) {
+  return new FlowStreamAsync(updater);
 }
 function derivation(fn) {
   return new FlowDerivation(fn);
@@ -568,5 +773,8 @@ function map(initial) {
     new Map(initial ? Object.entries(initial) : [])
   );
 }
+function array(initial) {
+  return new FlowArray(initial);
+}
 
-export { derivation, effect, map, resource, signal, state, stream };
+export { array, constant, derivation, effect, isDisposable, map, resource, resourceAsync, signal, state, stream, streamAsync };