@ersbeth/picoflow 1.1.2 → 2.0.0

package/src/nodes/valueSyncNode.ts

@@ -0,0 +1,128 @@
+import type { InitFunction } from "~/api/nodes/sync/flowConstant";
+import type { DerivationFunction } from "~/api/nodes/sync/flowDerivation";
+import type { UpdateFunction } from "~/api/nodes/sync/flowState";
+import type { NotPromise } from "~/api/nodes/utils";
+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 "~/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");
+        });
+    });
+});

package/test/converters/solid.derivation.browser.test.tsx

@@ -0,0 +1,69 @@
+import { cleanup, render } from "@solidjs/testing-library";
+import { type Component, Match, Switch } from "solid-js";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { userEvent } from "vitest/browser";
+import { derivation, from } from "~";
+
+describe("solid converter", () => {
+    beforeEach(() => {
+        cleanup();
+    });
+
+    describe("updates", () => {
+        describe("error", () => {
+            describe("flag", () => {
+                it("update-error-flag: should handle error in FlowDerivation", async () => {
+                    const Comp: Component = () => {
+                        let condition = false;
+                        const $derivation = derivation(() => {
+                            if (condition) {
+                                throw new Error("Test error");
+                            }
+                            return 42;
+                        });
+
+                        const $$derivation = from($derivation);
+
+                        return (
+                            <div>
+                                <Switch>
+                                    <Match when={$$derivation.error}>
+                                        <div>Error</div>
+                                    </Match>
+                                    <Match when={$$derivation()}>
+                                        <div>{$$derivation()}</div>
+                                    </Match>
+                                </Switch>
+                                <button
+                                    type="button"
+                                    onClick={() => {
+                                        condition = true;
+                                        $derivation.refresh();
+                                    }}
+                                >
+                                    Update Error
+                                </button>
+                                <button
+                                    type="button"
+                                    onClick={() => {
+                                        condition = false;
+                                        $derivation.refresh();
+                                    }}
+                                >
+                                    Update Value
+                                </button>
+                            </div>
+                        );
+                    };
+
+                    const { getByText } = render(() => <Comp />);
+                    await vi.waitFor(() => expect.element(getByText("42")).toBeInTheDocument());
+                    await userEvent.click(getByText("Update Error"));
+                    await vi.waitFor(() => expect.element(getByText("Error")).toBeInTheDocument());
+                    await userEvent.click(getByText("Update Value"));
+                    await vi.waitFor(() => expect.element(getByText("42")).toBeInTheDocument());
+                });
+            });
+        });
+    });
+});