@ersbeth/picoflow 1.1.2 → 2.0.1

package/src/nodes/valueNode.ts

@@ -0,0 +1,148 @@
+import type {
+    FlowEffect,
+    FlowOnDataListener,
+    FlowOnErrorListener,
+    FlowOnPendingListener,
+    FlowTracker,
+    NotPromise,
+} from "../api";
+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;
+    }
+}

package/src/nodes/valueSyncNode.ts

@@ -0,0 +1,125 @@
+import type { DerivationFunction, InitFunction, NotPromise, UpdateFunction } from "../api";
+import { SyncScheduler } from "../schedulers";
+import { ValueNode } from "./valueNode";
+
+/**
+ * Function that computes a value (either initialization or derivation).
+ * @internal
+ */
+export type ComputeFunction<T> = InitFunction<T> | DerivationFunction<T>;
+
+/**
+ * Synchronous reactive value that computes immediately without async scheduling.
+ * @internal
+ */
+export class ValueSyncNode<T extends NotPromise<unknown>> extends ValueNode<T> {
+    protected _scheduler: SyncScheduler<T>;
+    private _compute: () => T;
+
+    constructor(valueOrCompute: NotPromise<T> | ComputeFunction<T>) {
+        super();
+        if (typeof valueOrCompute === "function") {
+            // compute is a function
+            // @ts-expect-error valueOrCompute is a function
+            this._compute = () => valueOrCompute(this, this._value);
+        } else {
+            // compute is a value
+            this._compute = () => valueOrCompute;
+        }
+
+        this.status = "dirty";
+        this._scheduler = new SyncScheduler<T>(
+            () => this._compute(),
+            (value) => this._onResolve(value as NotPromise<T>),
+            (error) => this._onReject(error),
+        );
+
+        if (typeof valueOrCompute !== "function") {
+            this._scheduler.compute();
+        }
+    }
+
+    private _onResolve(value: NotPromise<T>) {
+        this.status = "resolved";
+        this._value = value;
+        this._error = undefined;
+    }
+
+    private _onReject(error: unknown) {
+        this.status = "error";
+        this._error = error;
+    }
+
+    set(value: NotPromise<T>): void;
+    set(updater: UpdateFunction<T>): void;
+    set(valueOrUpdater: NotPromise<T> | UpdateFunction<T>): void {
+        if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+
+        if (typeof valueOrUpdater === "function") {
+            const updater = valueOrUpdater as UpdateFunction<T>;
+            switch (this.status) {
+                case "resolved": {
+                    const nextValue = updater(this._value);
+                    if (nextValue === this._value) return;
+                    this.status = "pending";
+                    this._scheduler.overwrite(nextValue);
+                    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 ?
+                    const nextValue = updater(this._value);
+                    this.status = "pending";
+                    this._scheduler.overwrite(nextValue);
+                    this.notifyDependents();
+                    return;
+                }
+            }
+        } else {
+            const nextValue = valueOrUpdater;
+            switch (this.status) {
+                case "resolved": {
+                    if (nextValue === this._value) return;
+                    this.status = "pending";
+                    this._scheduler.overwrite(nextValue);
+                    this.notifyDependents();
+                    return;
+                }
+                case "pending":
+                case "error":
+                case "dirty": {
+                    this.status = "pending";
+                    this._scheduler.overwrite(nextValue);
+                    this.notifyDependents();
+                    return;
+                }
+            }
+        }
+    }
+
+    refresh(): void {
+        if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+
+        const currentValue = this._value;
+        const currentStatus = this.status;
+        this.execute();
+
+        switch (this.status) {
+            case "resolved": {
+                const nextValue = this._value;
+                if (nextValue === currentValue && currentStatus === this.status) return;
+                this.notifyDependents();
+                return;
+            }
+            case "error":
+            case "pending":
+            case "dirty": {
+                this.notifyDependents();
+                return;
+            }
+        }
+    }
+}

package/src/schedulers/asyncResolver.ts

@@ -0,0 +1,78 @@
+import { PendingError } from "./pendingError";
+
+/**
+ * Manages asynchronous computation lifecycle with iteration tracking to prevent race conditions.
+ * @internal
+ */
+export class AsyncResolver<T> {
+    private readonly _compute: () => Promise<T>;
+    private readonly _computed = Promise.withResolvers<T>();
+    private _iteration = 0;
+    private _aborted = false;
+    private _finished = false;
+
+    constructor(compute: () => Promise<T>) {
+        this._compute = compute;
+
+        // Prevent unhandled rejections before finally block is executed: catch all errors so they don't propagate.
+        // Actual error handling occurs elsewhere in ComputationScheduler through proper promise chaining.
+        this._computed.promise
+            .catch(() => {})
+            .finally(() => {
+                this._finished = true;
+            });
+    }
+
+    get computed(): Promise<T> {
+        return this._computed.promise;
+    }
+
+    get aborted(): boolean {
+        return this._aborted;
+    }
+
+    get finished(): boolean {
+        return this._finished;
+    }
+
+    compute(): void {
+        if (this._finished) throw new Error("[Picoflow] PendingResolver: Can't restart a settled resolver");
+        if (this._aborted) throw new Error("[Picoflow] PendingResolver: Can't restart an aborted resolver");
+
+        this._iteration++;
+        const currentIteration = this._iteration;
+        this._compute()
+            .then((value) => {
+                if (this._iteration === currentIteration && !this._aborted) this._computed.resolve(value);
+            })
+            .catch((error) => {
+                if (this._iteration === currentIteration && !this._aborted) {
+                    if (!(error instanceof PendingError)) {
+                        this._computed.reject(error);
+                    }
+                }
+            });
+    }
+
+    overwrite(promise: Promise<T>): void {
+        if (this._finished) throw new Error("[Picoflow] PendingResolver: Can't overwrite a settled resolver");
+        if (this._aborted) throw new Error("[Picoflow] PendingResolver: Can't overwrite an aborted resolver");
+
+        this._iteration++;
+        const currentIteration = this._iteration;
+        promise
+            .then((value) => {
+                if (this._iteration === currentIteration && !this._aborted) this._computed.resolve(value);
+            })
+            .catch((error) => {
+                if (this._iteration === currentIteration && !this._aborted) {
+                    this._computed.reject(error);
+                }
+            });
+    }
+
+    abort(): void {
+        this._iteration++;
+        this._aborted = true;
+    }
+}

package/src/schedulers/asyncScheduler.ts

@@ -0,0 +1,66 @@
+import { AsyncResolver } from "./asyncResolver";
+import type { Scheduler } from "./scheduler";
+
+/**
+ * Scheduler that manages asynchronous computation lifecycle with resolver instances.
+ * @internal
+ */
+export class AsyncScheduler<T> implements Scheduler {
+    private readonly _compute: () => Promise<T>;
+    private _resolver: AsyncResolver<T>;
+    private _onResolve: (value: T) => void;
+    private _onReject: (error: unknown) => void;
+    private _settled = Promise.withResolvers<void>();
+    private _disposed = false;
+
+    constructor(compute: () => Promise<T>, onResolve: (value: T) => void, onReject: (error: unknown) => void) {
+        this._compute = compute;
+        this._onResolve = onResolve;
+        this._onReject = onReject;
+        this._resolver = new AsyncResolver(compute);
+        this._resolver.computed
+            .then(this._onResolve)
+            .catch(this._onReject)
+            .finally(() => this._settled.resolve());
+    }
+
+    get settled(): Promise<void> {
+        if (this._disposed) throw new Error("[PicoFlow] ComputationScheduler is disposed");
+        return this._settled.promise;
+    }
+
+    get disposed(): boolean {
+        return this._disposed;
+    }
+
+    overwrite(promise: Promise<T>): void {
+        if (this._disposed) throw new Error("[PicoFlow] ComputationScheduler is disposed");
+        if (this._resolver.finished) {
+            this._resolver = new AsyncResolver(this._compute);
+            this._settled = Promise.withResolvers<void>();
+            this._resolver.computed
+                .then(this._onResolve)
+                .catch(this._onReject)
+                .finally(() => this._settled.resolve());
+        }
+        this._resolver.overwrite(promise);
+    }
+
+    compute(): void {
+        if (this._disposed) throw new Error("[PicoFlow] ComputationScheduler is disposed");
+        if (this._resolver.finished) {
+            this._resolver = new AsyncResolver(this._compute);
+            this._settled = Promise.withResolvers<void>();
+            this._resolver.computed
+                .then(this._onResolve)
+                .catch(this._onReject)
+                .finally(() => this._settled.resolve());
+        }
+        this._resolver.compute();
+    }
+
+    dispose(): void {
+        this._resolver.abort();
+        this._disposed = true;
+    }
+}

package/src/schedulers/index.ts

@@ -0,0 +1,4 @@
+export * from "./asyncScheduler";
+export * from "./pendingError";
+export * from "./scheduler";
+export * from "./syncScheduler";

package/src/schedulers/pendingError.ts

@@ -0,0 +1,13 @@
+/**
+ * Error thrown when an async computation is pending, encapsulating its promise for cascading dependencies.
+ * @internal
+ */
+export class PendingError extends Error {
+    readonly pendingPromise: Promise<unknown>;
+
+    constructor(promise: Promise<unknown>) {
+        super("[PicoFlow] PendingResolver pending");
+        this.name = "PendingError";
+        this.pendingPromise = promise;
+    }
+}

package/src/schedulers/scheduler.ts

@@ -0,0 +1,9 @@
+/**
+ * Contract for schedulers that coordinate reactive computations and their lifecycle.
+ * @internal
+ */
+export interface Scheduler {
+    compute(): void;
+    dispose(): void;
+    settled: Promise<void>;
+}

package/src/schedulers/syncResolver.ts

@@ -0,0 +1,69 @@
+import { PendingError } from "./pendingError";
+
+/**
+ * Manages synchronous computation lifecycle with iteration tracking to prevent race conditions.
+ * @internal
+ */
+export class SyncResolver<T> {
+    private readonly _compute: () => T;
+    private _iteration = 0;
+    private _aborted = false;
+    private _finished = false;
+
+    private _onValue: (value: T) => void;
+    private _onError: (error: unknown) => void;
+
+    constructor(compute: () => T, onValue: (value: T) => void, onError: (error: unknown) => void) {
+        this._compute = compute;
+        this._onValue = onValue;
+        this._onError = onError;
+    }
+
+    get aborted(): boolean {
+        return this._aborted;
+    }
+
+    get finished(): boolean {
+        return this._finished;
+    }
+
+    compute(): void {
+        if (this._finished) throw new Error("[Picoflow] PendingResolver: Can't restart a settled resolver");
+        if (this._aborted) throw new Error("[Picoflow] PendingResolver: Can't restart an aborted resolver");
+
+        this._iteration++;
+        const currentIteration = this._iteration;
+        try {
+            const value = this._compute();
+            if (this._iteration === currentIteration && !this._aborted) {
+                this._finished = true;
+                this._onValue(value);
+            }
+        } catch (error) {
+            if (this._iteration === currentIteration && !this._aborted) {
+                if (!(error instanceof PendingError)) {
+                    this._finished = true;
+                    this._onError(error);
+                }
+            }
+        }
+    }
+
+    overwrite(value: T): void {
+        if (this._finished) throw new Error("[Picoflow] PendingResolver: Can't overwrite a settled resolver");
+        if (this._aborted) throw new Error("[Picoflow] PendingResolver: Can't overwrite an aborted resolver");
+
+        this._iteration++;
+        const currentIteration = this._iteration;
+
+        if (this._iteration === currentIteration && !this._aborted) {
+            this._finished = true;
+            this._onValue(value);
+        }
+    }
+
+    abort(): void {
+        this._iteration++;
+        this._aborted = true;
+    }
+}

package/src/schedulers/syncScheduler.ts

@@ -0,0 +1,55 @@
+import type { Scheduler } from "./scheduler";
+import { SyncResolver } from "./syncResolver";
+
+/**
+ * Scheduler that manages synchronous computation lifecycle with resolver instances.
+ * @internal
+ */
+export class SyncScheduler<T> implements Scheduler {
+    private readonly _compute: () => T;
+    private _resolver: SyncResolver<T>;
+    private _onResolve: (value: T) => void;
+    private _onReject: (error: unknown) => void;
+    private _settled = Promise.withResolvers<void>();
+    private _disposed = false;
+
+    constructor(compute: () => T, onResolve: (value: T) => void, onReject: (error: unknown) => void) {
+        this._compute = compute;
+        this._onResolve = (value) => {
+            onResolve(value);
+            this._settled.resolve();
+        };
+        this._onReject = (error) => {
+            onReject(error);
+            this._settled.resolve();
+        };
+        this._resolver = new SyncResolver(compute, this._onResolve, this._onReject);
+    }
+
+    get settled(): Promise<void> {
+        return this._settled.promise;
+    }
+
+    overwrite(value: T): void {
+        if (this._disposed) throw new Error("[PicoFlow] ComputationScheduler is disposed");
+        if (this._resolver.finished) {
+            this._settled = Promise.withResolvers<void>();
+            this._resolver = new SyncResolver(this._compute, this._onResolve, this._onReject);
+        }
+        this._resolver.overwrite(value);
+    }
+
+    compute(): void {
+        if (this._disposed) throw new Error("[PicoFlow] ComputationScheduler is disposed");
+        if (this._resolver.finished) {
+            this._settled = Promise.withResolvers<void>();
+            this._resolver = new SyncResolver(this._compute, this._onResolve, this._onReject);
+        }
+        this._resolver.compute();
+    }
+
+    dispose(): void {
+        this._resolver.abort();
+        this._disposed = true;
+    }
+}

package/test/base/pendingError.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, it } from "vitest";
+import { PendingError } from "../../src/schedulers";
+
+describe("PendingError", () => {
+    describe("constructor and properties", () => {
+        it("should create instance with pending promise", () => {
+            const promise = Promise.resolve(42);
+            const error = new PendingError(promise);
+
+            expect(error).toBeInstanceOf(PendingError);
+            expect(error.pendingPromise).toBe(promise);
+        });
+
+        it("should have correct name", () => {
+            const promise = Promise.resolve(42);
+            const error = new PendingError(promise);
+
+            expect(error.name).toBe("PendingError");
+        });
+
+        it("should have correct message", () => {
+            const promise = Promise.resolve(42);
+            const error = new PendingError(promise);
+
+            expect(error.message).toBe("[PicoFlow] PendingResolver pending");
+        });
+
+        it("should extend Error", () => {
+            const promise = Promise.resolve(42);
+            const error = new PendingError(promise);
+
+            expect(error).toBeInstanceOf(Error);
+        });
+
+        it("should store pendingPromise property correctly", async () => {
+            const promise = Promise.resolve("test-value");
+            const error = new PendingError(promise);
+
+            expect(error.pendingPromise).toBe(promise);
+            expect(await error.pendingPromise).toBe("test-value");
+        });
+    });
+
+    describe("pendingPromise behavior", () => {
+        it("should expose the pending promise", () => {
+            const promise = Promise.resolve(100);
+            const error = new PendingError(promise);
+
+            expect(error.pendingPromise).toBe(promise);
+        });
+
+        it("should allow awaiting the pending promise", async () => {
+            const promise = Promise.resolve("resolved-value");
+            const error = new PendingError(promise);
+
+            const result = await error.pendingPromise;
+            expect(result).toBe("resolved-value");
+        });
+
+        it("should allow awaiting rejected promise", async () => {
+            const promise = Promise.reject(new Error("test-error"));
+            const error = new PendingError(promise);
+
+            await expect(error.pendingPromise).rejects.toThrow("test-error");
+        });
+    });
+});