@ersbeth/picoflow 1.1.2 → 2.0.1

package/src/converters/solid.ts

@@ -0,0 +1,109 @@
+import { createEffect, createResource, onCleanup, onMount, type Resource, resetErrorBoundaries } from "solid-js";
+import { type FlowEffect, type FlowObservable, type FlowTracker, type NotPromise, subscribe } from "../api";
+import { ValueAsyncNode, ValueSyncNode } from "../nodes";
+
+/**
+ * Internal helper that converts a PicoFlow node into a SolidJS resource.
+ * @internal
+ */
+function fromNode<T>(node: ValueAsyncNode<T> | ValueSyncNode<T>): Resource<T> {
+    const [resource, { refetch }] = createResource(() => node.pick());
+
+    let fx: FlowEffect;
+
+    onMount(() => {
+        fx = subscribe(
+            // data
+            (t) => node.get(t),
+            // onData
+            () => {
+                refetch(); // Force createResource to refetch
+            },
+            // onError
+            () => {
+                refetch(); // Force createResource to refetch
+            },
+            // onPending
+            () => {
+                refetch(); // Force createResource to refetch
+            },
+        );
+    });
+
+    createEffect(() => {
+        // reset error boundaries when error state changes
+        resource.error ?? resource();
+        resetErrorBoundaries();
+    });
+
+    onCleanup(() => fx.dispose());
+
+    return resource;
+}
+
+/**
+ * Internal helper that wraps a getter function in a PicoFlow node and converts it to a SolidJS resource.
+ * @internal
+ */
+function fromGetter<T>(getter: (t: FlowTracker) => NotPromise<T>): Resource<T> {
+    const derivation = new ValueSyncNode<T>((t) => {
+        return getter(t);
+    });
+
+    return fromNode(derivation);
+}
+
+/**
+ * Converts a PicoFlow observable or getter function into a SolidJS resource.
+ *
+ * @param flow - The FlowObservable or getter function to convert.
+ * @returns A SolidJS Resource that wraps the value or computation.
+ *
+ * @remarks
+ * This function bridges PicoFlow's reactive system with SolidJS, allowing you to use
+ * PicoFlow primitives and computations within Solid components. All conversions return a
+ * SolidJS Resource, which can handle both synchronous and asynchronous values seamlessly.
+ *
+ * The conversion works with:
+ * - **FlowObservable**: Any PicoFlow reactive primitive (e.g., from `state()`, `derivation()`, `stateAsync()`, `derivationAsync()`)
+ * - **Getter functions**: Computation functions that use a FlowTracker to access reactive values
+ *
+ * The created Resource automatically subscribes to the PicoFlow observables and updates
+ * when their values change. The subscription is properly cleaned up when the Solid
+ * component unmounts.
+ *
+ * @example
+ * ```typescript
+ * import { from } from 'picoflow/solid';
+ * import { state, derivation } from 'picoflow';
+ *
+ * // Convert a PicoFlow state to a Solid resource
+ * const $count = state(0);
+ * const solidCount = from($count);
+ *
+ * // Use in a Solid component
+ * function Counter() {
+ *   return <div>Count: {solidCount()}</div>;
+ * }
+ *
+ * // Or convert a computation function
+ * const solidDerived = from((t) => {
+ *   return $count.get(t) * 2;
+ * });
+ * ```
+ *
+ * @public
+ */
+export function from<T>(flow: FlowObservable<T>): Resource<T>;
+export function from<T>(flow: (t: FlowTracker) => NotPromise<T>): Resource<T>;
+export function from<T>(flow: FlowObservable<T> | ((t: FlowTracker) => NotPromise<T>)): Resource<T> {
+    if (flow instanceof ValueAsyncNode || flow instanceof ValueSyncNode) {
+        return fromNode(flow);
+    }
+
+    if (typeof flow === "function") {
+        return fromGetter(flow);
+    }
+
+    throw new Error("Invalid flow type");
+}

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,180 @@
+import type { FlowArray, FlowArrayAction, FlowTracker, NotPromise, UpdateFunction } from "../api";
+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: [],
+        });
+    }
+
+    override get(tracker: FlowTracker): T[] {
+        const values = super.get(tracker);
+        return [...values];
+    }
+
+    override async pick(): Promise<T[]> {
+        const values = await super.pick();
+        return [...values];
+    }
+
+    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,58 @@
+import type {
+    FlowDataTracker,
+    FlowEffect,
+    FlowOnDataListener,
+    FlowOnErrorListener,
+    FlowOnPendingListener,
+} from "../api";
+import { ExecutionStack, 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,7 @@
+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,125 @@
+import type { FlowMap, FlowMapAction, NotPromise, UpdateFunction } from "../api";
+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,19 @@
+import type { FlowEffect, FlowOnDataListener, FlowOnErrorListener, FlowOnPendingListener, FlowSignal } from "../api";
+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,85 @@
+import type { DerivationFunctionAsync, InitFunctionAsync, NotPromise, UpdateFunctionAsync } from "../api";
+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();
+    }
+}