@ersbeth/picoflow 1.1.2 → 2.0.0

package/src/index.ts

@@ -1,64 +1,2 @@
-/**
- * @packageDocumentation
- *
- * # PicoFlow
- *
- * PicoFlow is a lightweight reactive dataflow library that provides a comprehensive set of
- * reactive primitives for building reactive applications with explicit dependency tracking.
- *
- * ## Core Concepts
- *
- * **Reactive Primitives:**
- * - {@link FlowSignal}: Event-like notifications without values
- * - {@link FlowState}: Mutable reactive values
- * - {@link FlowConstant}: Immutable reactive values (computed once)
- * - {@link FlowDerivation}: Computed values that track dependencies
- * - {@link FlowEffect}: Side effects that run when dependencies change
- *
- * **Advanced Primitives:**
- * - {@link FlowArray}: Reactive arrays with mutation tracking
- * - {@link FlowMap}: Reactive maps with operation tracking
- * - {@link FlowResource}: Async data fetching returning `T | undefined`
- * - {@link FlowResourceAsync}: Async data fetching returning `Promise<T>`
- * - {@link FlowStream}: Event streams from external sources
- * - {@link FlowStreamAsync}: Async event streams returning Promises
- *
- * **Tracking Context:**
- * - {@link TrackingContext}: The core mechanism for explicit dependency tracking
- * - Use `observable.get(t)` to read with tracking
- * - Use `observable.pick()` to read without tracking
- * - Use `signal.watch(t)` to track signals without values
- *
- * ## Key Features
- *
- * - **Explicit tracking**: Full control over what triggers re-execution via TrackingContext
- * - **Lazy evaluation**: Derivations compute only when accessed
- * - **Fine-grained reactivity**: Track specific operations on collections
- * - **Resource management**: Automatic cleanup with dispose patterns
- * - **SolidJS integration**: Seamless bridge to SolidJS primitives
- *
- * ## Basic Usage
- *
- * ```typescript
- * import { state, effect, derivation } from 'picoflow';
- *
- * // Create reactive state
- * const $count = state(0);
- *
- * // Create derived value
- * const $double = derivation((t) => $count.get(t) * 2);
- *
- * // Create effect
- * effect((t) => {
- *   console.log('Count:', $count.get(t), 'Double:', $double.get(t));
- * });
- *
- * // Update state
- * $count.set(1); // Logs: "Count: 1 Double: 2"
- * ```
- *
- * @see {@link https://github.com/yourusername/picoflow | GitHub Repository}
- */
-
-export * from "./flow";
-export * from "./solid";
+export * from "./api";
+export * from "./converters";

package/src/nodes/arrayNode.ts

@@ -0,0 +1,172 @@
+import type { FlowArray, FlowArrayAction } from "~/api/nodes/collections/flowArray";
+import type { UpdateFunction } from "~/api/nodes/sync/flowState";
+import type { NotPromise } from "~/api/nodes/utils";
+import { Disposable } from "~/base";
+import { ValueSyncNode } from "./valueSyncNode";
+
+/**
+ * Internal implementation of reactive array with mutation tracking.
+ * @internal
+ */
+export class ArrayNode<T> extends ValueSyncNode<T[]> implements FlowArray<T> {
+    $lastAction: ValueSyncNode<FlowArrayAction<T>>;
+    protected declare _value: T[];
+
+    constructor(value: T[] = []) {
+        super(value);
+        this.$lastAction = new ValueSyncNode<FlowArrayAction<T>>({
+            type: "set",
+            setItems: value,
+            clearedItems: [],
+        });
+    }
+
+    get length(): number {
+        if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+        return this._value.length;
+    }
+
+    override set(items: NotPromise<T[]>): T[];
+    override set(updater: UpdateFunction<T[]>): T[];
+    override set(itemsOrUpdater: NotPromise<T[]> | UpdateFunction<T[]>): T[] {
+        if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+
+        // compute previous value
+        const previousValue = this._value;
+
+        // set new value
+        // @ts-expect-error - we know that this._value is an array
+        super.set(itemsOrUpdater);
+
+        // emit last action
+        this.$lastAction.set({
+            type: "set",
+            setItems: this._value,
+            clearedItems: previousValue,
+        });
+
+        // return previous value
+        return previousValue;
+    }
+
+    update(index: number, item: T): T | undefined {
+        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");
+        }
+
+        // compute previous value
+        const previousValue = this._value[index];
+
+        // update item
+        this._value[index] = item;
+        this.notifyDependents();
+
+        // emit last action
+        this.$lastAction.set({
+            type: "update",
+            index: index,
+            setItem: item,
+            clearedItem: previousValue,
+        });
+
+        // return previous value
+        return previousValue;
+    }
+
+    push(item: T): void {
+        if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+
+        // push item
+        this._value.push(item);
+        this.notifyDependents();
+
+        // emit last action
+        this.$lastAction.set({ type: "push", addedItem: item });
+    }
+
+    pop(): T | undefined {
+        if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+
+        // pop item
+        const item = this._value.pop();
+        this.notifyDependents();
+
+        // emit last action
+        this.$lastAction.set({ type: "pop", removedItem: item });
+
+        // return previous value
+        return item;
+    }
+
+    unshift(item: T): void {
+        if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+
+        // unshift item
+        this._value.unshift(item);
+        this.notifyDependents();
+
+        // emit last action
+        this.$lastAction.set({ type: "unshift", addedItem: item });
+    }
+
+    shift(): T | undefined {
+        if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+
+        // shift item
+        const item = this._value.shift();
+        this.notifyDependents();
+
+        // emit last action
+        this.$lastAction.set({ type: "shift", removedItem: item });
+
+        // return previous value
+        return item;
+    }
+
+    splice(start: number, deleteCount: number, ...newItems: T[]): T[] {
+        if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+
+        // splice items
+        const items = this._value.splice(start, deleteCount, ...newItems);
+        this.notifyDependents();
+
+        // emit last action
+        this.$lastAction.set({
+            type: "splice",
+            start: start,
+            deleteCount: deleteCount,
+            addedItems: newItems,
+            removedItems: items,
+        });
+
+        // return value changed check
+        return items;
+    }
+
+    clear(): T[] {
+        if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+
+        // compute previous value
+        const previousValue = [...this._value];
+
+        // clear array
+        this._value = [];
+        this.notifyDependents();
+
+        // emit last action
+        this.$lastAction.set({ type: "clear", clearedItems: previousValue });
+
+        // return value changed check
+        return previousValue;
+    }
+
+    override dispose(): void {
+        super.dispose();
+        this._value.forEach((item) => {
+            if (item instanceof Disposable) item.dispose();
+        });
+        this._value = [];
+    }
+}

package/src/nodes/effectNode.ts

@@ -0,0 +1,59 @@
+import type {
+    FlowDataTracker,
+    FlowOnDataListener,
+    FlowOnErrorListener,
+    FlowOnPendingListener,
+} from "~/api/base/flowSubscribable";
+import type { FlowEffect } from "~/api/nodes/flowEffect";
+import { ExecutionStack } from "~/base";
+import { Observer } from "~/base/";
+import { PendingError } from "~/schedulers";
+
+/**
+ * Reactive effect that automatically re-executes when its dependencies change.
+ * @internal
+ */
+export class EffectNode<T> extends Observer implements FlowEffect {
+    private _data: FlowDataTracker<T>;
+    private _onData: FlowOnDataListener<T>;
+    private _onError?: FlowOnErrorListener;
+    private _onPending?: FlowOnPendingListener;
+
+    constructor(
+        data: FlowDataTracker<T>,
+        onData: FlowOnDataListener<T>,
+        onError?: FlowOnErrorListener,
+        onPending?: FlowOnPendingListener,
+    ) {
+        super();
+        this._data = data;
+        this._onData = onData;
+        this._onError = onError;
+        this._onPending = onPending;
+        this.execute();
+    }
+
+    notify(): void {
+        if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+        ExecutionStack.pushEffect(this as unknown as EffectNode<unknown>);
+    }
+
+    execute(): void {
+        try {
+            if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+            this.clearDependencies();
+            const data = this._data(this);
+            this._onData(data);
+        } catch (error) {
+            if (error instanceof PendingError) {
+                this._onPending?.();
+            } else {
+                if (this._onError) {
+                    this._onError(error instanceof Error ? error : new Error(String(error)));
+                } else {
+                    throw error;
+                }
+            }
+        }
+    }
+}

package/src/nodes/index.ts

@@ -0,0 +1,8 @@
+export * from "../base/executionStack";
+export * from "./arrayNode";
+export * from "./effectNode";
+export * from "./mapNode";
+export * from "./signalNode";
+export * from "./valueAsyncNode";
+export * from "./valueNode";
+export * from "./valueSyncNode";

package/src/nodes/mapNode.ts

@@ -0,0 +1,127 @@
+import type { FlowMap, FlowMapAction } from "~/api/nodes/collections/flowMap";
+import type { UpdateFunction } from "~/api/nodes/sync/flowState";
+import type { NotPromise } from "~/api/nodes/utils";
+import { Disposable } from "~/base";
+import { ValueSyncNode } from "./valueSyncNode";
+
+/**
+ * Internal implementation of reactive map with mutation tracking.
+ * @internal
+ */
+export class MapNode<K, V> extends ValueSyncNode<Map<K, V>> implements FlowMap<K, V> {
+    public $lastAction: ValueSyncNode<FlowMapAction<K, V>>;
+    protected declare _value: Map<K, V>;
+
+    constructor(value: Map<K, V> = new Map()) {
+        super(value);
+        this.$lastAction = new ValueSyncNode<FlowMapAction<K, V>>({
+            type: "set",
+            setMap: value,
+            clearedMap: new Map(),
+        });
+    }
+
+    add(key: K, value: V) {
+        if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+
+        // get value
+        const previousValue = this._value.get(key);
+        if (previousValue) {
+            throw new Error("[PicoFlow] Key already exists");
+        }
+
+        // add key
+        this._value.set(key, value);
+        this.notifyDependents();
+
+        // emit last action
+        this.$lastAction.set({ type: "add", key, addedValue: value });
+    }
+
+    update(key: K, value: V): V {
+        if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+
+        // get value
+        const previousValue = this._value.get(key);
+        if (!previousValue) throw new Error("[PicoFlow] Key does not exist");
+
+        // update key
+        this._value.set(key, value);
+        this.notifyDependents();
+
+        // emit last action
+        this.$lastAction.set({
+            type: "update",
+            key,
+            setValue: value,
+            clearedValue: previousValue,
+        });
+
+        // return previous value
+        return previousValue;
+    }
+
+    delete(key: K): V {
+        if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+
+        // get value
+        const value = this._value.get(key);
+        if (value === undefined) throw new Error("[PicoFlow] Key does not exist");
+
+        // delete key
+        this._value.delete(key);
+        this.notifyDependents();
+
+        // emit last action
+        this.$lastAction.set({ type: "delete", key, removedValue: value });
+
+        // return previous value
+        return value;
+    }
+
+    override set(map: NotPromise<Map<K, V>>): Map<K, V>;
+    override set(updater: UpdateFunction<Map<K, V>>): Map<K, V>;
+    override set(mapOrUpdater: NotPromise<Map<K, V>> | UpdateFunction<Map<K, V>>): Map<K, V> {
+        if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+        // compute current value
+        const previousValue = this._value;
+
+        // @ts-expect-error - we know that this._value is a Map
+        super.set(mapOrUpdater);
+
+        // emit last action
+        this.$lastAction.set({
+            type: "set",
+            setMap: this._value,
+            clearedMap: previousValue,
+        });
+
+        // return previous value
+        return previousValue;
+    }
+
+    clear(): Map<K, V> {
+        if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+
+        // compute previous value
+        const previousValue = this._value;
+
+        // clear map
+        this._value = new Map();
+        this.notifyDependents();
+
+        // emit last action
+        this.$lastAction.set({ type: "clear", clearedMap: previousValue });
+
+        // return value changed check
+        return previousValue;
+    }
+
+    override dispose(): void {
+        super.dispose();
+        this._value.forEach((item) => {
+            if (item instanceof Disposable) item.dispose();
+        });
+        this._value.clear();
+    }
+}

package/src/nodes/signalNode.ts

@@ -0,0 +1,21 @@
+import type { FlowEffect } from "~/api";
+import type { FlowOnDataListener, FlowOnErrorListener, FlowOnPendingListener } from "~/api/base/flowSubscribable";
+import type { FlowSignal } from "~/api/nodes/flowSignal";
+import { Observable, type Observer } from "~/base/";
+import { EffectNode } from "./effectNode";
+
+/**
+ * Manual trigger that notifies subscribers without carrying data.
+ * @internal
+ */
+export class SignalNode extends Observable<void> implements FlowSignal {
+    subscribe(
+        onTrigger: FlowOnDataListener<void>,
+        onError?: FlowOnErrorListener,
+        onPending?: FlowOnPendingListener,
+    ): FlowEffect {
+        if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+        const effect = new EffectNode<void>((t) => this.watch(t as unknown as Observer), onTrigger, onError, onPending);
+        return effect;
+    }
+}

package/src/nodes/valueAsyncNode.ts

@@ -0,0 +1,88 @@
+import type { InitFunctionAsync } from "~/api/nodes/async/flowConstantAsync";
+import type { DerivationFunctionAsync } from "~/api/nodes/async/flowDerivationAsync";
+import type { UpdateFunctionAsync } from "~/api/nodes/async/flowStateAsync";
+import type { NotPromise } from "~/api/nodes/utils";
+import { AsyncScheduler } from "~/schedulers";
+import { ValueNode } from "./valueNode";
+
+/**
+ * Function that computes a value asynchronously (either initialization or derivation).
+ * @internal
+ */
+export type ComputeFunctionAsync<T> = InitFunctionAsync<T> | DerivationFunctionAsync<T>;
+/**
+ * Asynchronous reactive value that resolves promises and propagates results when settled.
+ * @internal
+ */
+export class ValueAsyncNode<T extends NotPromise<unknown>> extends ValueNode<T> {
+    protected _scheduler: AsyncScheduler<T>;
+    private _compute: () => Promise<T>;
+
+    constructor(promiseOrCompute: Promise<T> | ComputeFunctionAsync<T>) {
+        super();
+        if (typeof promiseOrCompute === "function") {
+            // compute is a function
+            this._compute = () => promiseOrCompute(this, this._value);
+        } else {
+            // compute is a promise
+            this._compute = () => promiseOrCompute;
+        }
+        this.status = "dirty";
+        this._scheduler = new AsyncScheduler(
+            () => this._compute(),
+            (value) => this._onResolve(value as NotPromise<T>),
+            (error) => this._onReject(error),
+        );
+    }
+
+    private _onResolve(value: NotPromise<T>) {
+        this.status = "resolved";
+        this._value = value;
+        this._error = undefined;
+        this.notifyDependents();
+    }
+
+    private _onReject(error: unknown) {
+        this.status = "error";
+        this._error = error;
+        this.notifyDependents();
+    }
+
+    set(promise: Promise<T>): void;
+    set(updater: UpdateFunctionAsync<T>): void;
+    set(promiseOrUpdater: Promise<T> | UpdateFunctionAsync<T>): void {
+        if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+
+        if (typeof promiseOrUpdater === "function") {
+            const updater = promiseOrUpdater as UpdateFunctionAsync<T>;
+            switch (this.status) {
+                case "resolved": {
+                    this.status = "pending";
+                    this._scheduler.overwrite(updater(this._value));
+                    this.notifyDependents();
+                    return;
+                }
+                case "pending":
+                case "error":
+                case "dirty": {
+                    // TODO: For now we use latest value to compute the next value
+                    // Maybe we should throw instead ?
+                    this.status = "pending";
+                    this._scheduler.overwrite(updater(this._value));
+                    this.notifyDependents();
+                    return;
+                }
+            }
+        } else {
+            this.status = "pending";
+            const promise = promiseOrUpdater;
+            this._scheduler.overwrite(promise);
+            this.notifyDependents();
+        }
+    }
+
+    refresh(): void {
+        if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+        this.execute();
+    }
+}

package/src/nodes/valueNode.ts

@@ -0,0 +1,144 @@
+import type { FlowEffect } from "~/api";
+import type { FlowOnDataListener, FlowOnErrorListener, FlowOnPendingListener } from "~/api/base/flowSubscribable";
+import type { FlowTracker } from "~/api/base/flowTracker";
+import type { NotPromise } from "~/api/nodes/utils";
+import { ExecutionStack, Node, type ObservableStatus, type Observer } from "~/base";
+import { PendingError, type Scheduler } from "~/schedulers";
+import { EffectNode } from "./effectNode";
+
+/**
+ * Base class for reactive values that compute, cache, and propagate changes through the dependency graph.
+ * @internal
+ */
+export abstract class ValueNode<T> extends Node<T> {
+    protected abstract _scheduler: Scheduler;
+    protected _value?: NotPromise<T>;
+    protected _error?: unknown;
+
+    override watch(tracker: FlowTracker): void {
+        if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+        super.watch(tracker as unknown as Observer);
+
+        switch (this.status as ObservableStatus) {
+            case "resolved":
+                return;
+            case "error":
+                throw this._error;
+            case "pending": {
+                throw new PendingError(this._scheduler.settled);
+            }
+            case "dirty": {
+                this.execute();
+                switch (this.status as ObservableStatus) {
+                    case "pending":
+                        throw new PendingError(this._scheduler.settled);
+                    case "resolved":
+                        return;
+                    case "error":
+                        throw this._error;
+                    case "dirty": {
+                        throw new Error("[PicoFlow] Internal error");
+                    }
+                }
+            }
+        }
+    }
+
+    override notify(): void {
+        if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+        if (this.status === "dirty") return;
+        if (this.status === "pending") {
+            ExecutionStack.pushPending(this);
+        }
+        this.status = "dirty";
+        this.notifyDependents();
+    }
+
+    override dispose(): void {
+        super.dispose();
+        this._scheduler.dispose();
+    }
+
+    get(tracker: FlowTracker): T {
+        if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+        super.watch(tracker);
+
+        switch (this.status as ObservableStatus) {
+            case "resolved":
+                return this._value as T;
+            case "error":
+                throw this._error;
+            case "pending": {
+                throw new PendingError(this._scheduler.settled);
+            }
+            case "dirty": {
+                this.execute();
+                switch (this.status as ObservableStatus) {
+                    case "resolved":
+                        return this._value as T;
+                    case "error":
+                        throw this._error;
+                    case "pending": {
+                        throw new PendingError(this._scheduler.settled);
+                    }
+                    case "dirty": {
+                        throw new Error("[PicoFlow] Internal error");
+                    }
+                }
+            }
+        }
+    }
+
+    async pick(): Promise<T> {
+        if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+        switch (this.status) {
+            case "resolved":
+                return this._value as T;
+            case "pending": {
+                await this._scheduler.settled;
+                if ((this.status as ObservableStatus) === "resolved") return this._value as T;
+                if ((this.status as ObservableStatus) === "error") throw this._error;
+                throw new Error("[PicoFlow] Internal error");
+            }
+            case "error":
+                throw this._error;
+            case "dirty": {
+                this.execute();
+                switch (this.status as ObservableStatus) {
+                    case "resolved":
+                        return this._value as T;
+                    case "pending": {
+                        await this._scheduler.settled;
+                        if ((this.status as ObservableStatus) === "resolved") return this._value as T;
+                        if ((this.status as ObservableStatus) === "error") throw this._error;
+                        throw new Error("[PicoFlow] Internal error");
+                    }
+                    case "error":
+                        throw this._error;
+                    case "dirty": {
+                        throw new Error("[PicoFlow] Internal error");
+                    }
+                }
+            }
+        }
+    }
+
+    execute(): void {
+        // TODO: Should we throw instead ?
+        if (this.disposed) return;
+
+        this.clearDependencies();
+        this.status = "pending";
+        this._scheduler.compute();
+    }
+
+    subscribe(
+        onValue: FlowOnDataListener<T>,
+        onError?: FlowOnErrorListener,
+        onPending?: FlowOnPendingListener,
+    ): FlowEffect {
+        if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+        const effect = new EffectNode((t) => this.get(t), onValue, onError, onPending);
+        return effect;
+    }
+}