@ersbeth/picoflow 0.0.1 → 0.2.0

package/dist/types/basic/signal.d.ts

@@ -0,0 +1,40 @@
+import { FlowDisposable } from './disposable';
+/**
+ * A function for watching a FlowSignal.
+ * @param signal - The FlowSignal that is being observed.
+ * @public
+ */
+export type FlowWatcher = (signal: FlowSignal) => void;
+/**
+ * Represents a reactive signal.
+ *
+ * @remarks Use FlowSignal to create reactive streams that notify listeners and execute associated effects.
+ * Signals can be triggered and disposed. Once disposed, interactions with the signal will throw errors.
+ * @public
+ */
+export declare class FlowSignal implements FlowDisposable {
+    /**
+     * Triggers the FlowSignal.
+     * Notifies all registered listeners and schedules execution of associated effects.
+     * @throws If the FlowSignal has already been disposed.
+     * @public
+     */
+    trigger(): void;
+    /**
+     * 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(options?: {
+        self: boolean;
+    }): void;
+    /**
+     * Indicates whether the FlowSignal has been disposed.
+     * @remarks Once disposed, the signal should not be used.
+     * @public
+     */
+    get disposed(): boolean;
+}
+//# sourceMappingURL=signal.d.ts.map

package/dist/types/basic/signal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signal.d.ts","sourceRoot":"","sources":["../../../src/basic/signal.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAGnD;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,MAAM,EAAE,UAAU,KAAK,IAAI,CAAC;AAEvD;;;;;;GAMG;AACH,qBAAa,UAAW,YAAW,cAAc;IAC7C;;;;;OAKG;IACI,OAAO,IAAI,IAAI;IAKtB;;;;;;OAMG;IACI,OAAO,CAAC,OAAO,CAAC,EAAE;QAAE,IAAI,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI;IAqBjD;;;;OAIG;IACH,IAAW,QAAQ,IAAI,OAAO,CAE7B;CAoDJ"}

package/dist/types/basic/state.d.ts

@@ -0,0 +1,26 @@
+import { FlowConstant } from './constant';
+/**
+ * Represents a reactive state that holds a mutable value.
+ *
+ * @typeparam T - The type of the state value.
+ *
+ * @remarks
+ * FlowState extends FlowConstant, which provides the {@link FlowConstant.get} method to read
+ * the current state. Use the {@link FlowState.set} method to update the state. When the state is updated,
+ * subscribers are notified automatically. This class notifies subscribers only when the value changes.
+ *
+ * @public
+ */
+export declare class FlowState<T> extends FlowConstant<T> {
+    /**
+     * Updates the state with a new value.
+     * @param value - A new value or a callback function that computes a new value based on the current state.
+     * @remarks
+     * If the computed new value is strictly equal to the current state value, no change is made and subscribers
+     * will not be notified. Otherwise, the state is updated and all subscribers are informed of the change.
+     * @throws Error if the state has been disposed.
+     * @public
+     */
+    set(value: T | ((current: T) => T)): void;
+}
+//# sourceMappingURL=state.d.ts.map

package/dist/types/basic/state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../../src/basic/state.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE1C;;;;;;;;;;;GAWG;AACH,qBAAa,SAAS,CAAC,CAAC,CAAE,SAAQ,YAAY,CAAC,CAAC,CAAC;IAC7C;;;;;;;;OAQG;IACH,GAAG,CAAC,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,IAAI;CAc5C"}

package/dist/types/creators.d.ts

@@ -1,17 +1,19 @@
-import { FlowDerivation } from './derivation';
-import { FlowEffect } from './effect';
-import { FlowGetter } from './observable';
-import { FlowResource } from './resource';
-import { FlowSignal, FlowWatcher } from './signal';
-import { FlowState } from './state';
-import { FlowMap } from './map';
-import { FlowStream } from './stream';
+import { FlowMap, FlowResource, FlowResourceAsync, FlowStream, FlowStreamAsync } from './advanced/';
+import { FlowArray } from './advanced/array';
+import { FlowConstant, FlowDerivation, FlowEffect, FlowSignal, FlowState, FlowGetter, FlowWatcher } from './basic/';
 /**
  * Creates a new reactive signal.
  * @returns A new instance of {@link FlowSignal}.
  * @public
  */
 export declare function signal(): FlowSignal;
+/**
+ * Creates a new reactive constant.
+ * @param value - The value or a function that returns the value.
+ * @returns A new instance of {@link FlowConstant}.
+ * @public
+ */
+export declare function constant<T>(value: T | (() => T)): FlowConstant<T>;
 /**
  * Creates a new reactive state holding a value.
  * @typeparam T - The type of the state value.
@@ -19,26 +21,41 @@ export declare function signal(): FlowSignal;
  * @returns A new instance of {@link FlowState}.
  * @public
  */
-export declare function state<T>(value: T): FlowState<T>;
+export declare function state<T>(value: T | (() => T)): FlowState<T>;
 /**
  * Creates a new reactive resource that asynchronously fetches its value.
  * @typeparam T - The type of the resource value.
  * @param fn - An asynchronous function that fetches the resource value.
- * @param initial - The initial value of the resource.
  * @returns A new instance of {@link FlowResource}.
  * @public
  */
-export declare function resource<T>(fn: () => Promise<T>, initial: T): FlowResource<T>;
+export declare function resource<T>(fn: () => Promise<T>): FlowResource<T>;
+/**
+ * Creates a new reactive asynchronous resource that fetches its value.
+ * @typeparam T - The type of the resource value.
+ * @param fn - An asynchronous function that fetches the resource value.
+ * @returns A new instance of {@link FlowResourceAsync}.
+ * @public
+ */
+export declare function resourceAsync<T>(fn: () => Promise<T>): FlowResourceAsync<T>;
 /**
  * Creates a new reactive stream.
  * @typeparam T - The type of the stream value.
  * @param updater - A function that receives a setter to update the stream's value.
  * It should return a disposer function to clean up resources.
- * @param initial - The initial value of the stream.
  * @returns A new instance of {@link FlowStream}.
  * @public
  */
-export declare function stream<T>(updater: (set: (value: T) => void) => () => void, initial: T): FlowStream<T>;
+export declare function stream<T>(updater: (set: (value: T) => void) => () => void): FlowStream<T>;
+/**
+ * Creates a new reactive asynchronous stream.
+ * @typeparam T - The type of the stream value.
+ * @param updater - A function that receives a setter to update the stream's value.
+ * It should return a disposer function to clean up resources.
+ * @returns A new instance of {@link FlowStreamAsync}.
+ * @public
+ */
+export declare function streamAsync<T>(updater: (set: (value: T) => void) => () => void): FlowStreamAsync<T>;
 /**
  * Creates a new reactive derivation whose value is computed based on other reactive signals.
  * @typeparam T - The type of the derived value.
@@ -67,4 +84,12 @@ export declare function effect(fn: (get: FlowGetter, watch: FlowWatcher) => void
  * @public
  */
 export declare function map<K extends string | number | symbol, V>(initial?: Record<K, V>): FlowMap<K, V>;
+/**
+ * Creates a new reactive array.
+ * @typeparam T - The type of the array elements.
+ * @param initial - An optional array of initial values.
+ * @returns A new instance of {@link FlowArray}.
+ * @public
+ */
+export declare function array<T>(initial?: T[]): FlowArray<T>;
 //# sourceMappingURL=creators.d.ts.map

package/dist/types/creators.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"creators.d.ts","sourceRoot":"","sources":["../../src/creators.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACtC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,UAAU,EAAE,KAAK,WAAW,EAAE,MAAM,UAAU,CAAC;AACxD,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAChC,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAEtC;;;;GAIG;AACH,wBAAgB,MAAM,IAAI,UAAU,CAEnC;AAED;;;;;;GAMG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,CAE/C;AAED;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC,CAE7E;AAED;;;;;;;;GAQG;AACH,wBAAgB,MAAM,CAAC,CAAC,EACpB,OAAO,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,KAAK,MAAM,IAAI,EAChD,OAAO,EAAE,CAAC,GACX,UAAU,CAAC,CAAC,CAAC,CAEf;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,GAAG,EAAE,UAAU,EAAE,KAAK,EAAE,WAAW,KAAK,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,CAE/F;AAED;;;;;;GAMG;AACH,wBAAgB,MAAM,CAAC,EAAE,EAAE,CAAC,GAAG,EAAE,UAAU,EAAE,KAAK,EAAE,WAAW,KAAK,IAAI,GAAG,UAAU,CAEpF;AAED;;;;;;;;;GASG;AACH,wBAAgB,GAAG,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,GAAG,MAAM,EAAE,CAAC,EACrD,OAAO,CAAC,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,GACvB,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC,CAIf"}
+{"version":3,"file":"creators.d.ts","sourceRoot":"","sources":["../../src/creators.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,OAAO,EACP,YAAY,EACZ,iBAAiB,EACjB,UAAU,EACV,eAAe,EAClB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EACH,YAAY,EACZ,cAAc,EACd,UAAU,EACV,UAAU,EACV,SAAS,EACZ,MAAM,UAAU,CAAC;AAClB,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAExD;;;;GAIG;AACH,wBAAgB,MAAM,IAAI,UAAU,CAEnC;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC,CAEjE;AAED;;;;;;GAMG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,CAE3D;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC,CAEjE;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,iBAAiB,CAAC,CAAC,CAAC,CAE3E;AAED;;;;;;;GAOG;AACH,wBAAgB,MAAM,CAAC,CAAC,EACpB,OAAO,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,KAAK,MAAM,IAAI,GACjD,UAAU,CAAC,CAAC,CAAC,CAEf;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,CAAC,EACzB,OAAO,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,KAAK,MAAM,IAAI,GACjD,eAAe,CAAC,CAAC,CAAC,CAEpB;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,CAAC,EACxB,EAAE,EAAE,CAAC,GAAG,EAAE,UAAU,EAAE,KAAK,EAAE,WAAW,KAAK,CAAC,GAC/C,cAAc,CAAC,CAAC,CAAC,CAEnB;AAED;;;;;;GAMG;AACH,wBAAgB,MAAM,CAClB,EAAE,EAAE,CAAC,GAAG,EAAE,UAAU,EAAE,KAAK,EAAE,WAAW,KAAK,IAAI,GAClD,UAAU,CAEZ;AAED;;;;;;;;;GASG;AACH,wBAAgB,GAAG,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,GAAG,MAAM,EAAE,CAAC,EACrD,OAAO,CAAC,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,GACvB,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC,CAIf;AAED;;;;;;GAMG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,CAAC,EAAE,GAAG,SAAS,CAAC,CAAC,CAAC,CAEpD"}

package/dist/types/index.d.ts

@@ -6,13 +6,8 @@
  * effects, and reactive maps.
  *
  */
-export { signal, state, resource, stream, derivation, effect, map } from './creators';
-export type { FlowDerivation } from './derivation';
-export type { FlowEffect } from './effect';
-export type { FlowGetter, FlowObservable } from './observable';
-export type { FlowResource } from './resource';
-export type { FlowSignal, FlowWatcher } from './signal';
-export type { FlowState } from './state';
-export type { FlowMap } from './map';
-export type { FlowStream, FlowDisposer, FlowSetter, FlowUpdater } from './stream';
+export { signal, state, constant, resource, stream, derivation, effect, map, array, streamAsync, resourceAsync, } from './creators';
+export { isDisposable } from './basic';
+export type { FlowDerivation, FlowEffect, FlowGetter, FlowObservable, FlowSignal, FlowWatcher, FlowState, FlowConstant, FlowDisposable, } from './basic/';
+export type { FlowResource, FlowMap, FlowResourceAsync, FlowStreamAsync, FlowStream, FlowStreamDisposer, FlowStreamSetter, FlowStreamUpdater, FlowArray, FlowArrayAction, } from './advanced/';
 //# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,YAAY,CAAC;AACtF,YAAY,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,YAAY,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAC3C,YAAY,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC/D,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACxD,YAAY,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACzC,YAAY,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AACrC,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EACH,MAAM,EACN,KAAK,EACL,QAAQ,EACR,QAAQ,EACR,MAAM,EACN,UAAU,EACV,MAAM,EACN,GAAG,EACH,KAAK,EACL,WAAW,EACX,aAAa,GAChB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,YAAY,EACR,cAAc,EACd,UAAU,EACV,UAAU,EACV,cAAc,EACd,UAAU,EACV,WAAW,EACX,SAAS,EACT,YAAY,EACZ,cAAc,GACjB,MAAM,UAAU,CAAC;AAClB,YAAY,EACR,YAAY,EACZ,OAAO,EACP,iBAAiB,EACjB,eAAe,EACf,UAAU,EACV,kBAAkB,EAClB,gBAAgB,EAChB,iBAAiB,EACjB,SAAS,EACT,eAAe,GAClB,MAAM,aAAa,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@ersbeth/picoflow",
-    "version": "0.0.1",
+    "version": "0.2.0",
     "description": "Minimal Dataflow librairy for TypeScript",
     "type": "module",
     "exports": {

package/src/advanced/array.ts

@@ -0,0 +1,224 @@
+import { FlowObservable, type FlowState } from "../basic";
+import { isDisposable } from "../basic";
+import { state } from "../creators";
+
+/**
+ * Represents the actions that can be performed on a FlowArray.
+ * @public
+ */
+export type FlowArrayAction<T> =
+    | {
+          type: "set";
+          items: T[];
+      }
+    | {
+          type: "setItem";
+          index: number;
+          item: T;
+      }
+    | {
+          type: "push";
+          item: T;
+      }
+    | {
+          type: "pop";
+      }
+    | {
+          type: "unshift";
+          item: T;
+      }
+    | {
+          type: "shift";
+      }
+    | {
+          type: "splice";
+          start: number;
+          deleteCount: number;
+          items: T[];
+      }
+    | {
+          type: "clear";
+      };
+
+/**
+ * Represents a reactive array.
+ * @public
+ */
+export class FlowArray<T> extends FlowObservable<T[]> {
+    /**
+     * Last action performed on the FlowArray.
+     * @public
+     */
+    $lastAction: FlowState<FlowArrayAction<T>>;
+
+    /**
+     * Creates an instance of FlowArray.
+     * @param value - Initial array value.
+     * @public
+     */
+    constructor(value: T[] = []) {
+        super();
+        this._value = value;
+        this.$lastAction = state<FlowArrayAction<T>>({
+            type: "set",
+            items: value,
+        });
+    }
+
+    /**
+     * Gets the current length of the array.
+     * @returns The length of the array.
+     * @public
+     */
+    get length(): number {
+        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(): T[] {
+        if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+        return [...this._value]; // Ensure nobody can modify the original array
+    }
+
+    /**
+     * Replaces the entire array with new items.
+     * @param items - The new array of items.
+     * @public
+     */
+    set(items: T[]): void {
+        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: 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: number, item: T): void {
+        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: index, item: item });
+    }
+
+    /**
+     * Appends an item to the end of the array.
+     * @param item - The item to append.
+     * @public
+     */
+    push(item: T): void {
+        if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+        this._value.push(item);
+        this._notify();
+        this.$lastAction.set({ type: "push", item: item });
+    }
+
+    /**
+     * Removes the last item from the array.
+     * @public
+     */
+    pop(): void {
+        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: T): void {
+        if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+        this._value.unshift(item);
+        this._notify();
+        this.$lastAction.set({ type: "unshift", item: item });
+    }
+
+    /**
+     * Removes the first item from the array.
+     * @public
+     */
+    shift(): void {
+        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: number, deleteCount: number, ...newItems: T[]): void {
+        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: start,
+            deleteCount: deleteCount,
+            items: newItems,
+        });
+    }
+
+    /**
+     * Clears all items from the array.
+     * @public
+     */
+    clear(): void {
+        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
+     */
+    override dispose(options?: { self: boolean }): void {
+        super.dispose(options);
+        this._value.forEach((item) => {
+            if (isDisposable(item)) item.dispose(options);
+        });
+        this._value = [];
+    }
+
+    /* INTERNAL */
+
+    /*@internal*/ protected override _value: T[] = [];
+}

package/src/advanced/index.ts

@@ -0,0 +1,12 @@
+export { FlowMap } from "./map";
+export { FlowStream } from "./stream";
+export { FlowStreamAsync } from "./streamAsync";
+export { FlowResource } from "./resource";
+export { FlowResourceAsync } from "./resourceAsync";
+export type {
+    FlowStreamUpdater,
+    FlowStreamDisposer,
+    FlowStreamSetter,
+} from "./stream";
+export { FlowArray } from "./array";
+export type { FlowArrayAction } from "./array";

package/src/{map.ts → advanced/map.ts}

@@ -1,18 +1,17 @@
-import { FlowState } from "./state";
+import { FlowState } from "../basic/";
 
 /**
- * Represents a reactive map of states that extends {@link FlowState} for a Map of key/value pairs.
+ * Represents a reactive map of states extending {@link FlowState} for a Map of key/value pairs.
  *
  * @remarks
  * FlowMap wraps a native Map and provides reactive signals for fine-grained tracking
  * of updates to the map. In addition to the reactive capabilities inherited from FlowState,
- * it exposes two public signals:
+ * it exposes two reactive signals:
  *
- * **$lastSet**: A FlowState that holds the most recent key-value pair that was set.
+ * • $lastSet: Holds the most recent key-value pair that was set.
+ * • $lastDeleted: Holds the most recent key-value pair that was deleted.
  *
- * **$lastDeleted**: A FlowState that holds the most recent key-value pair that was deleted.
- *
- * Use {@link FlowMap.setAt} to set a key-value pair and {@link FlowMap.delete} to remove a key.
+ * Use {@link FlowMap.setAt} to add or update a key-value pair and {@link FlowMap.delete} to remove a key.
  *
  * @typeparam K - The type of the map keys.
  * @typeparam V - The type of the map values.
@@ -47,15 +46,16 @@ export class FlowMap<K, V> extends FlowState<Map<K, V>> {
      *
      * @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
      */
     public setAt(key: K, value: V): void {
-        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();
@@ -65,16 +65,16 @@ export class FlowMap<K, V> extends FlowState<Map<K, V>> {
      * 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
      */
     public delete(key: K): void {
-        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 });

package/src/advanced/resource.ts

@@ -0,0 +1,56 @@
+import { FlowObservable } from "../basic";
+
+/**
+ * Represents a reactive resource that asynchronously fetches its value.
+ *
+ * @remarks A FlowResource extends FlowObservable and encapsulates an asynchronous fetch function.
+ * It is used to retrieve and update its value asynchronously. When the fetch is executed,
+ * if the new value differs from the current value, the resource is updated and its subscribers
+ * are notified.
+ *
+ * @public
+ */
+export class FlowResource<T> extends FlowObservable<T | undefined> {
+    /**
+     * Creates a new FlowResource.
+     * @param fetch - An asynchronous function that retrieves the resource's value.
+     *
+     * @public
+     */
+    constructor(fetch: () => Promise<T>) {
+        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
+     */
+    public get(): T | undefined {
+        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
+     */
+    public async fetch(): Promise<void> {
+        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 ------------------------------------------------ */
+
+    private _fetch: () => Promise<T>;
+}

package/src/{resource.ts → advanced/resourceAsync.ts}

@@ -1,4 +1,4 @@
-import { FlowObservable } from "./observable";
+import { FlowObservable } from "../basic/";
 
 /**
  * Represents a reactive resource that asynchronously fetches its value.
@@ -13,27 +13,26 @@ import { FlowObservable } from "./observable";
  *
  * @public
  */
-export class FlowResource<T> extends FlowObservable<T> {
+export class FlowResourceAsync<T> extends FlowObservable<Promise<T>> {
     /**
      * Creates a new FlowResource.
      * @param fetch - An asynchronous function that retrieves the resource's value.
-     * @param initial - The initial value of the resource.
      * @public
      */
-    constructor(fetch: () => Promise<T>, initial: T) {
+    constructor(fetch: () => Promise<T>) {
         super();
-        this._value = initial;
         this._fetch = fetch;
     }
 
     /**
      * Retrieves the current resource value.
-     * @returns The current value.
+     * @returns The current value, or undefined if the resource has not been fetched yet.
      * @throws Error if the resource is disposed.
      * @public
      */
-    public get(): T {
-        if (this._disposed) throw new Error("Resource is disposed");
+    public get(): Promise<T> {
+        if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+        if (!this._value) this._value = this._fetch();
         return this._value;
     }
 
@@ -47,18 +46,12 @@ export class FlowResource<T> extends FlowObservable<T> {
      * @public
      */
     public async fetch(): Promise<void> {
-        if (this._disposed) throw new Error("Resource is disposed");
-        const value = await this._fetch();
-        if (value === this._value) return;
-        this._value = value;
+        if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+        this._value = this._fetch();
         this._notify();
     }
 
     /* INTERNAL ------------------------------------------------ */
 
-    /**
-     * @internal
-     * The asynchronous function used to fetch the resource value.
-     */
     private _fetch: () => Promise<T>;
 }