@ersbeth/picoflow 0.1.0 → 0.2.0

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

@@ -8,3 +8,5 @@ export type {
     FlowStreamDisposer,
     FlowStreamSetter,
 } from "./stream";
+export { FlowArray } from "./array";
+export type { FlowArrayAction } from "./array";

package/src/basic/disposable.ts

@@ -0,0 +1,27 @@
+/**
+ * Represents an object with a disposable lifecycle.
+ * @remarks
+ * Objects implementing this interface require explicit resource disposal.
+ * @public
+ */
+export interface FlowDisposable {
+    /**
+     * Disposes resources held by this object.
+     * @param options - Options to specify disposal behavior.
+     */
+    dispose(options?: { self: boolean }): void;
+}
+
+/**
+ * Checks whether an object implements the FlowDisposable interface.
+ * @param obj - The object to test.
+ * @returns True if the object has a dispose method, otherwise false.
+ * @public
+ */
+export function isDisposable(obj: unknown): obj is FlowDisposable {
+    return (
+        obj !== null &&
+        obj !== undefined &&
+        typeof (obj as FlowDisposable).dispose === "function"
+    );
+}

package/src/basic/index.ts

@@ -4,5 +4,7 @@ export { FlowObservable } from "./observable";
 export { FlowDerivation } from "./derivation";
 export { FlowEffect } from "./effect";
 export { FlowConstant } from "./constant";
+export { isDisposable } from "./disposable";
 export type { FlowGetter } from "./observable";
 export type { FlowWatcher } from "./signal";
+export type { FlowDisposable } from "./disposable";

package/src/basic/observable.ts

@@ -12,8 +12,8 @@ export type FlowGetter = <T>(observable: FlowObservable<T>) => T;
 
 /**
  * Represents a reactive observable that holds and tracks a value.
- * 
- * 
+ *
+ *
  * @remarks Subclasses must implement the {@link FlowObservable.get} method to return the current value.
  * @typeparam T - The type of the value held by the observable.
  * @public

package/src/basic/signal.ts

@@ -1,3 +1,4 @@
+import type { FlowDisposable } from "./disposable";
 import type { FlowEffect } from "./effect";
 
 /**
@@ -9,12 +10,12 @@ 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 class FlowSignal {
+export class FlowSignal implements FlowDisposable {
     /**
      * Triggers the FlowSignal.
      * Notifies all registered listeners and schedules execution of associated effects.
@@ -33,10 +34,21 @@ export class FlowSignal {
      * @throws If the FlowSignal is already disposed.
      * @public
      */
-    public dispose(): void {
+    public dispose(options?: { self: boolean }): void {
         if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-        Array.from(this._effects).forEach((effect) => effect.dispose());
-        Array.from(this._listeners).forEach((listener) => listener.dispose());
+        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);
         });

package/src/creators.ts

@@ -5,6 +5,7 @@ import {
     FlowStream,
     FlowStreamAsync,
 } from "./advanced/";
+import { FlowArray } from "./advanced/array";
 import {
     FlowConstant,
     FlowDerivation,
@@ -138,3 +139,14 @@ export function map<K extends string | number | symbol, V>(
         new Map<K, V>(initial ? (Object.entries(initial) as [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 function array<T>(initial?: T[]): FlowArray<T> {
+    return new FlowArray<T>(initial);
+}

package/src/index.ts

@@ -15,9 +15,11 @@ export {
     derivation,
     effect,
     map,
+    array,
     streamAsync,
     resourceAsync,
 } from "./creators";
+export { isDisposable } from "./basic";
 export type {
     FlowDerivation,
     FlowEffect,
@@ -27,6 +29,7 @@ export type {
     FlowWatcher,
     FlowState,
     FlowConstant,
+    FlowDisposable,
 } from "./basic/";
 export type {
     FlowResource,
@@ -37,4 +40,6 @@ export type {
     FlowStreamDisposer,
     FlowStreamSetter,
     FlowStreamUpdater,
+    FlowArray,
+    FlowArrayAction,
 } from "./advanced/";