@ersbeth/picoflow 1.0.1 → 1.1.0

package/src/flow/collections/flowArray.ts

@@ -0,0 +1,409 @@
+import { FlowGraph, isDisposable } from "../base";
+import { FlowNode, type FlowState, state } from "../nodes";
+
+/**
+ * Represents the actions that can be performed on a FlowArray.
+ * @public
+ */
+export type FlowArrayAction<T> =
+	| {
+			type: "set";
+			items: T[];
+	  }
+	| {
+			type: "update";
+			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 FlowNode<T[]> {
+	/**
+	 * Last action performed on the FlowArray.
+	 * @public
+	 */
+	$lastAction: FlowState<FlowArrayAction<T>>;
+	protected declare _value: T[];
+
+	/**
+	 * Creates an instance of FlowArray.
+	 * @param value - Initial array value.
+	 * @public
+	 */
+	constructor(value: T[] = []) {
+		super(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;
+	}
+
+	/**
+	 * Internal method to get the raw value.
+	 * @internal
+	 */
+	protected _getRaw(): 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
+	 */
+	override async set(items: T[]): Promise<void> {
+		if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+		const update = () => {
+			// compute current value
+			const currentValue = this._value;
+
+			if (currentValue !== items) {
+				// dispose old items
+				currentValue.forEach((item) => {
+					if (isDisposable(item)) item.dispose({ self: true });
+				});
+
+				// assign new items
+				this._value = items;
+
+				// emit last action
+				this.$lastAction.set({ type: "set", items: items });
+			}
+
+			// return value changed check
+			return currentValue !== items;
+		};
+
+		const notify = () => {
+			// call super method to avoid setting dirty flag back to true
+			super._notify();
+		};
+
+		return FlowGraph.requestWrite(notify, update);
+	}
+
+	/**
+	 * Replaces an item at a specific index.
+	 * @param index - The index of the item to replace.
+	 * @param item - The new item.
+	 * @public
+	 */
+	async update(index: number, item: T): Promise<void> {
+		if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+		const update = () => {
+			if (index < 0 || index >= this._value.length) {
+				throw new Error("[PicoFlow] Index out of bounds");
+			}
+
+			// compute current value
+			const currentValue = this._value[index];
+
+			if (currentValue !== item) {
+				// dispose item
+				if (isDisposable(currentValue)) {
+					currentValue.dispose({ self: true });
+				}
+
+				// update item
+				this._value[index] = item;
+
+				// emit last action
+				this.$lastAction.set({ type: "update", index: index, item: item });
+			}
+
+			// return value changed check
+			return currentValue !== item;
+		};
+
+		const notify = () => {
+			// call super method to avoid setting dirty flag back to true
+			super._notify();
+		};
+
+		return FlowGraph.requestWrite(notify, update);
+	}
+
+	/**
+	 * Appends an item to the end of the array.
+	 * @param item - The item to append.
+	 * @public
+	 */
+	async push(item: T): Promise<void> {
+		if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+		const update = () => {
+			// push item
+			this._value.push(item);
+
+			// emit last action
+			this.$lastAction.set({ type: "push", item: item });
+
+			// return value changed check
+			return true;
+		};
+
+		const notify = () => {
+			// call super method to avoid setting dirty flag back to true
+			super._notify();
+		};
+
+		return FlowGraph.requestWrite(notify, update);
+	}
+
+	/**
+	 * Removes the last item from the array.
+	 * @public
+	 */
+	async pop(): Promise<void> {
+		if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+
+		const update = () => {
+			// pop item
+			const item = this._value.pop();
+
+			if (item !== undefined) {
+				// dispose item
+				if (isDisposable(item)) {
+					item.dispose({ self: true });
+				}
+
+				// emit last action
+				this.$lastAction.set({ type: "pop" });
+
+				// return value changed check
+				return true;
+			}
+			return false;
+		};
+
+		const notify = () => {
+			// call super method to avoid setting dirty flag back to true
+			super._notify();
+		};
+
+		return FlowGraph.requestWrite(notify, update);
+	}
+
+	/**
+	 * Inserts an item at the beginning of the array.
+	 * @param item - The item to insert.
+	 * @public
+	 */
+	async unshift(item: T): Promise<void> {
+		if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+		const update = () => {
+			// unshift item
+			this._value.unshift(item);
+
+			// emit last action
+			this.$lastAction.set({ type: "unshift", item: item });
+
+			// return value changed check
+			return true;
+		};
+
+		const notify = () => {
+			// call super method to avoid setting dirty flag back to true
+			super._notify();
+		};
+
+		return FlowGraph.requestWrite(notify, update);
+	}
+
+	/**
+	 * Removes the first item from the array.
+	 * @public
+	 */
+	async shift(): Promise<void> {
+		if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+		const update = () => {
+			// shift item
+			const item = this._value.shift();
+
+			if (item !== undefined) {
+				// dispose item
+				if (isDisposable(item)) {
+					item.dispose({ self: true });
+				}
+				// emit last action
+				this.$lastAction.set({ type: "shift" });
+
+				// return value changed check
+				return true;
+			}
+
+			return false;
+		};
+
+		const notify = () => {
+			// call super method to avoid setting dirty flag back to true
+			super._notify();
+		};
+
+		return FlowGraph.requestWrite(notify, update);
+	}
+
+	/**
+	 * 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
+	 */
+	async splice(
+		start: number,
+		deleteCount: number,
+		...newItems: T[]
+	): Promise<void> {
+		if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+		const update = () => {
+			// splice items
+			const items = this._value.splice(start, deleteCount, ...newItems);
+
+			// dispose items
+			items.forEach((item) => {
+				if (isDisposable(item)) item.dispose({ self: true });
+			});
+
+			// emit last action
+			this.$lastAction.set({
+				type: "splice",
+				start: start,
+				deleteCount: deleteCount,
+				items: newItems,
+			});
+
+			// return value changed check
+			return true;
+		};
+
+		const notify = () => {
+			// call super method to avoid setting dirty flag back to true
+			super._notify();
+		};
+
+		return FlowGraph.requestWrite(notify, update);
+	}
+
+	/**
+	 * Clears all items from the array.
+	 * @public
+	 */
+	async clear(): Promise<void> {
+		if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+		const update = () => {
+			// dispose old items
+			const items = [...this._value];
+			items.forEach((item) => {
+				if (isDisposable(item)) item.dispose({ self: true });
+			});
+
+			// clear array
+			this._value = [];
+
+			// emit last action
+			this.$lastAction.set({ type: "clear" });
+
+			// return value changed check
+			return true;
+		};
+
+		const notify = () => {
+			// call super method to avoid setting dirty flag back to true
+			super._notify();
+		};
+
+		return FlowGraph.requestWrite(notify, update);
+	}
+
+	/**
+	 * 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 */
+}
+
+/**
+ * Creates a new reactive array with mutation methods and fine-grained action tracking.
+ *
+ * @typeParam T - The type of the array elements.
+ * @param initial - An optional array of initial values.
+ * @returns A new instance of {@link FlowArray}.
+ *
+ * @remarks
+ * A reactive array provides array-like mutation methods (push, pop, shift, unshift, splice)
+ * and tracks the last operation performed via `$lastAction`. This enables both whole-array
+ * reactivity and fine-grained tracking of specific mutations.
+ *
+ * The array automatically disposes disposable items when they are removed (if they implement
+ * the FlowDisposable interface).
+ *
+ * @example
+ * ```typescript
+ * const $items = array([1, 2, 3]);
+ *
+ * // Track the whole array
+ * effect((t) => {
+ *   console.log('Items:', $items.get(t));
+ * });
+ *
+ * // Track the last action
+ * effect((t) => {
+ *   const action = $items.$lastAction.get(t);
+ *   console.log('Action:', action.type);
+ * });
+ *
+ * $items.push(4); // Logs action: "push"
+ * $items.pop();   // Logs action: "pop"
+ * ```
+ *
+ * @public
+ */
+export function array<T>(initial?: T[]): FlowArray<T> {
+	return new FlowArray<T>(initial);
+}