@ersbeth/picoflow 2.0.2 → 2.0.3

package/src/api/nodes/sync/flowConstant.ts

@@ -1,33 +0,0 @@
-import { ValueSyncNode } from "../../../nodes/valueSyncNode";
-import type { FlowValue } from "../flowValue";
-import type { NotPromise } from "../utils";
-
-/** Function that initializes a value. */
-export type InitFunction<T> = () => NotPromise<T>;
-
-/**
- * Read-only reactive value that computes once on initialization and never changes.
- *
- * Constants provide lazy initialization - the value isn't computed until first accessed via `get()` or `pick()`.
- * Once computed, the value is cached forever. Use constants for expensive computations that only need to run once,
- * such as loading configuration, computing static lookups, or initializing resources.
- *
- * @public
- */
-export interface FlowConstant<T> extends FlowValue<T> {}
-
-/**
- * Creates a constant reactive value that initializes lazily and never recomputes.
- *
- * The initializer function runs once on first access, and the result is cached permanently.
- * Unlike state or derivations, constants never react to changes - they represent immutable values
- * in the reactive graph. Useful for expensive one-time computations or static configuration.
- *
- * @param initializer - Function that computes the constant value on first access
- * @returns A FlowConstant that provides read-only access to the cached value
- *
- * @public
- */
-export function constant<T>(initializer: InitFunction<T>): FlowConstant<T> {
-    return new ValueSyncNode(initializer);
-}

package/src/api/nodes/sync/flowDerivation.ts

@@ -1,41 +0,0 @@
-import { ValueSyncNode } from "../../../nodes/valueSyncNode";
-import type { FlowTracker } from "../../base/flowTracker";
-import type { FlowValue } from "../flowValue";
-import type { NotPromise } from "../utils";
-
-/** Function that derives a value from dependencies and optionally the previous value. */
-export type DerivationFunction<T> = (tracker: FlowTracker, previous?: NotPromise<T> | undefined) => NotPromise<T>;
-
-/**
- * Read-only reactive value that recomputes automatically when dependencies change.
- *
- * Derivations track reactive values accessed during computation and automatically recompute when any
- * tracked dependency changes. The computed value is cached until dependencies change, avoiding unnecessary
- * recomputations. Use derivations for values derived from other reactive state, such as filtered lists,
- * computed properties, or aggregated data.
- *
- * @public
- */
-export interface FlowDerivation<T> extends FlowValue<T> {
-    /**
-     * Forces the derivation to recompute even if dependencies haven't changed.
-     */
-    refresh(): void;
-}
-
-/**
- * Creates a derived reactive value that automatically recomputes when dependencies change.
- *
- * The compute function runs when any tracked dependency changes, and the result is cached until the next change.
- * Access reactive values within the compute function to establish dependencies automatically. The derivation
- * computes lazily on first access and then reactively thereafter. Use for derived data that should stay
- * synchronized with source state.
- *
- * @param compute - Function that accesses dependencies and computes the derived value
- * @returns A FlowDerivation that provides read-only access to the computed value
- *
- * @public
- */
-export function derivation<T>(compute: DerivationFunction<T>): FlowDerivation<T> {
-    return new ValueSyncNode(compute);
-}

package/src/api/nodes/sync/flowState.ts

@@ -1,45 +0,0 @@
-import { ValueSyncNode } from "../../../nodes/valueSyncNode";
-import type { FlowValue } from "../flowValue";
-import type { NotPromise } from "../utils";
-import type { InitFunction } from "./flowConstant";
-
-/** Function that updates a value based on the previous value. */
-export type UpdateFunction<T> = (previous: NotPromise<T> | undefined) => NotPromise<T>;
-
-/**
- * Writable reactive value that can be updated manually and notifies dependents on changes.
- *
- * State is the simplest writable reactive primitive. Unlike derivations, it has no dependencies and never
- * recomputes automatically - changes only occur when you explicitly call `set()`. Use state for user input,
- * application state, or any data that changes imperatively. Changes propagate automatically to all dependents.
- *
- * @public
- */
-export interface FlowState<T> extends FlowValue<T> {
-    /**
-     * Updates the state with a new value or via an updater function.
-     * Notifies all dependents after the update.
-     *
-     * @param value - New value to set, or function that receives current value and returns new value
-     */
-    set(value: NotPromise<T>): void;
-    set(updater: UpdateFunction<T>): void;
-}
-
-/**
- * Creates a mutable reactive state that can be read and updated imperatively.
- *
- * State can be initialized with a direct value or a lazy initializer function. Changes propagate
- * automatically to all reactive computations that depend on this state. Use state for data that
- * changes through user actions, external events, or application logic rather than derived computations.
- *
- * @param value - Initial value for the state, or lazy initializer function
- * @returns A FlowState that can be read and modified
- *
- * @public
- */
-export function state<T>(value: NotPromise<T>): FlowState<T>;
-export function state<T>(initializer: InitFunction<T>): FlowState<T>;
-export function state<T>(valueOrInitializer: NotPromise<T> | InitFunction<T>): FlowState<T> {
-    return new ValueSyncNode(valueOrInitializer);
-}

package/src/api/nodes/sync/flowWritableDerivation.ts

@@ -1,31 +0,0 @@
-import { ValueSyncNode } from "../../../nodes/valueSyncNode";
-import type { DerivationFunction, FlowDerivation } from "./flowDerivation";
-import type { FlowState } from "./flowState";
-
-/**
- * Writable reactive value that recomputes automatically when dependencies change, but can be manually overridden.
- *
- * Writable derivations combine reactive computation with manual control. They track dependencies and recompute
- * like regular derivations, but you can also call `set()` to override the computed value temporarily. Use this
- * for computed values that users can edit, such as formatted fields, calculated totals that can be adjusted,
- * or any value that is usually derived but sometimes needs manual correction.
- *
- * @public
- */
-export interface FlowWritableDerivation<T> extends FlowState<T>, FlowDerivation<T> {}
-
-/**
- * Creates a derived value that recomputes automatically but can also be manually overridden.
- *
- * The compute function tracks dependencies and recomputes when they change, just like a regular derivation.
- * However, you can also call `set()` to override the computed value. Use this for values that are normally
- * derived but need occasional manual adjustments, such as editable calculated fields or user-correctable totals.
- *
- * @param compute - Function that accesses dependencies and computes the derived value
- * @returns A FlowWritableDerivation that provides both reactive computation and manual control
- *
- * @public
- */
-export function writableDerivation<T>(compute: DerivationFunction<T>): FlowWritableDerivation<T> {
-    return new ValueSyncNode(compute);
-}

package/src/api/nodes/sync/index.ts

@@ -1,4 +0,0 @@
-export * from "./flowConstant";
-export * from "./flowDerivation";
-export * from "./flowState";
-export * from "./flowWritableDerivation";

package/src/api/nodes/utils.ts

@@ -1,24 +0,0 @@
-import type { FlowValue } from "./flowValue";
-
-/**
- * Type that excludes Promise values from a type union.
- *
- * This utility type ensures that synchronous reactive primitives (like `state`, `constant`, `derivation`)
- * only accept non-Promise values. Use this to prevent accidental mixing of sync and async values, which
- * would cause runtime errors. For async values, use the async variants (like `stateAsync`, `constantAsync`).
- *
- * @public
- */
-export type NotPromise<T> = T extends Promise<unknown> ? never : T;
-
-/**
- * Type that restricts mutation methods to create read-only versions of reactive primitives.
- *
- * This utility type removes mutation methods (`set`, `refresh`, `trigger`) from a reactive primitive,
- * creating a read-only interface. Use this when you want to expose reactive values to consumers who
- * should observe but not modify them, such as passing state to child components or external modules
- * while maintaining encapsulation of write access.
- *
- * @public
- */
-export type FlowReadonly<T> = Omit<FlowValue<T>, "set" | "refresh" | "trigger">;

package/src/base/disposable.ts

@@ -1,18 +0,0 @@
-import type { FlowDisposable } from "../api";
-
-/**
- * Base implementation of the disposable pattern for reactive primitives.
- * Throws an error if disposed multiple times.
- */
-export class Disposable implements FlowDisposable {
-    protected _disposed = false;
-
-    get disposed(): boolean {
-        return this._disposed;
-    }
-
-    dispose(): void {
-        if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-        this._disposed = true;
-    }
-}

package/src/base/executionStack.ts

@@ -1,42 +0,0 @@
-import type { IObserver } from "./observer";
-
-/**
- * Global scheduler that batches and executes reactive computations asynchronously.
- */
-export class ExecutionStack {
-    private static readonly _pendingQueue: IObserver[] = [];
-    private static readonly _effectQueue: IObserver[] = [];
-    private static _executionScheduled?: Promise<void>;
-
-    static pushPending(node: IObserver): void {
-        ExecutionStack._scheduleExecution();
-        ExecutionStack._pendingQueue.push(node);
-    }
-
-    static pushEffect(effect: IObserver): void {
-        ExecutionStack._scheduleExecution();
-        ExecutionStack._effectQueue.push(effect);
-    }
-
-    private static _scheduleExecution(): void {
-        if (ExecutionStack._executionScheduled) return;
-        ExecutionStack._executionScheduled = new Promise((resolve) => {
-            setTimeout(() => {
-                ExecutionStack._executionScheduled = undefined;
-                ExecutionStack._execute();
-                resolve();
-            }, 0);
-        });
-    }
-
-    private static _execute(): void {
-        ExecutionStack._pendingQueue.forEach((node) => {
-            node.execute();
-        });
-        ExecutionStack._pendingQueue.length = 0;
-        ExecutionStack._effectQueue.forEach((effect) => {
-            effect.execute();
-        });
-        ExecutionStack._effectQueue.length = 0;
-    }
-}

package/src/base/index.ts

@@ -1,5 +0,0 @@
-export * from "./disposable";
-export * from "./executionStack";
-export * from "./node";
-export * from "./observable";
-export * from "./observer";

package/src/base/node.ts

@@ -1,98 +0,0 @@
-import type { FlowEffect, FlowOnDataListener, FlowOnErrorListener, FlowOnPendingListener, FlowTracker } from "../api";
-import { Disposable } from "./disposable";
-import type { IObservable, ObservableStatus } from "./observable";
-import type { IObserver } from "./observer";
-
-/**
- * Base implementation for reactive nodes that propagate changes through the dependency graph.
- */
-export abstract class Node<T> extends Disposable implements IObservable<T>, IObserver {
-    private _dependencies = new Set<IObservable<unknown>>();
-    private _dependents = new Set<IObserver>();
-    protected _status: ObservableStatus = "resolved";
-
-    get status(): ObservableStatus {
-        if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
-        return this._status;
-    }
-
-    set status(status: ObservableStatus) {
-        if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
-        this._status = status;
-    }
-
-    registerDependency(dependency: IObservable<unknown>): void {
-        if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-        this._dependencies.add(dependency);
-        dependency.registerDependent(this);
-    }
-
-    unregisterDependency(dependency: IObservable<unknown>): void {
-        if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-        this._dependencies.delete(dependency);
-        dependency.unregisterDependent(this);
-    }
-
-    clearDependencies(): void {
-        if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
-        this._dependencies.forEach((dependency) => {
-            dependency.unregisterDependent(this);
-        });
-        this._dependencies.clear();
-    }
-
-    registerDependent(dependent: IObserver): void {
-        if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
-        this._dependents.add(dependent);
-    }
-
-    unregisterDependent(dependent: IObserver): void {
-        if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
-        this._dependents.delete(dependent);
-    }
-
-    notifyDependents(): void {
-        if (this.disposed) return;
-        this._dependents.forEach((dependent) => {
-            dependent.notify();
-        });
-    }
-
-    watch(tracker: FlowTracker): void {
-        if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
-        (tracker as unknown as IObserver).registerDependency(this);
-    }
-
-    trigger(): void {
-        if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
-        this.notifyDependents();
-    }
-
-    notify(): void {
-        if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
-        if (this.status === "dirty") return;
-        this.status = "dirty";
-        this.notifyDependents();
-    }
-
-    override dispose(): void {
-        if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-        Array.from(this._dependents).forEach((dependant) => {
-            dependant.unregisterDependency(this);
-            this.unregisterDependent(dependant);
-        });
-        Array.from(this._dependencies).forEach((dependency) => {
-            this.unregisterDependency(dependency);
-        });
-
-        this._disposed = true;
-    }
-
-    abstract execute(): void;
-
-    abstract subscribe(
-        onValue: FlowOnDataListener<T>,
-        onError?: FlowOnErrorListener,
-        onPending?: FlowOnPendingListener,
-    ): FlowEffect;
-}

package/src/base/observable.ts

@@ -1,92 +0,0 @@
-import type {
-    FlowEffect,
-    FlowObservable,
-    FlowOnDataListener,
-    FlowOnErrorListener,
-    FlowOnPendingListener,
-    FlowTracker,
-} from "../api";
-import { Disposable } from "./disposable";
-import type { IObserver } from "./observer";
-
-/**
- * Status of an observable: resolved (has value), pending (async in progress), error (failed), or dirty (needs recomputation).
- */
-export type ObservableStatus = "resolved" | "pending" | "error" | "dirty";
-
-/**
- * Internal interface extending FlowObservable with dependency graph management methods.
- */
-export interface IObservable<T> extends FlowObservable<T> {
-    get status(): ObservableStatus;
-    set status(status: ObservableStatus);
-    registerDependent(dependent: IObserver): void;
-    unregisterDependent(dependent: IObserver): void;
-    notifyDependents(): void;
-    subscribe(
-        onValue: FlowOnDataListener<T>,
-        onError?: FlowOnErrorListener,
-        onPending?: FlowOnPendingListener,
-    ): FlowEffect;
-}
-
-/**
- * Base implementation managing the dependency graph for reactive observables.
- */
-export abstract class Observable<T> extends Disposable implements IObservable<T> {
-    private _dependents = new Set<IObserver>();
-    protected _status: ObservableStatus = "resolved";
-
-    get status(): ObservableStatus {
-        if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
-        return this._status;
-    }
-
-    set status(status: ObservableStatus) {
-        if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
-        this._status = status;
-    }
-
-    registerDependent(dependent: IObserver): void {
-        if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
-        this._dependents.add(dependent);
-    }
-
-    unregisterDependent(dependent: IObserver): void {
-        if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
-        this._dependents.delete(dependent);
-    }
-
-    notifyDependents(): void {
-        if (this.disposed) return; //throw new Error("[PicoFlow] Primitive is disposed");
-        this._dependents.forEach((dependent) => {
-            dependent.notify();
-        });
-    }
-
-    watch(tracker: FlowTracker): void {
-        if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
-        (tracker as unknown as IObserver).registerDependency(this);
-    }
-
-    trigger(): void {
-        if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
-        this.notifyDependents();
-    }
-
-    override dispose(): void {
-        if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-        Array.from(this._dependents).forEach((dependant) => {
-            dependant.unregisterDependency(this);
-            this.unregisterDependent(dependant);
-        });
-
-        this._disposed = true;
-    }
-
-    abstract subscribe(
-        onValue: FlowOnDataListener<T>,
-        onError?: FlowOnErrorListener,
-        onPending?: FlowOnPendingListener,
-    ): FlowEffect;
-}

package/src/base/observer.ts

@@ -1,51 +0,0 @@
-import { Disposable } from "./disposable";
-import type { IObservable } from "./observable";
-
-/**
- * Internal interface for reactive computations that track dependencies and respond to changes.
- */
-export interface IObserver {
-    registerDependency(dependency: IObservable<unknown>): void;
-    unregisterDependency(dependency: IObservable<unknown>): void;
-    clearDependencies(): void;
-    notify(): void;
-    execute(): void;
-}
-
-/**
- * Base implementation managing dependency tracking for reactive observers.
- */
-export abstract class Observer extends Disposable implements IObserver {
-    private _dependencies = new Set<IObservable<unknown>>();
-
-    registerDependency(dependency: IObservable<unknown>): void {
-        if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-        this._dependencies.add(dependency);
-        dependency.registerDependent(this);
-    }
-
-    unregisterDependency(dependency: IObservable<unknown>): void {
-        if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-        this._dependencies.delete(dependency);
-        dependency.unregisterDependent(this);
-    }
-
-    clearDependencies(): void {
-        if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
-        this._dependencies.forEach((dependency) => {
-            dependency.unregisterDependent(this);
-        });
-        this._dependencies.clear();
-    }
-
-    override dispose(): void {
-        if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-        Array.from(this._dependencies).forEach((dependency) => {
-            this.unregisterDependency(dependency);
-        });
-        this._disposed = true;
-    }
-
-    abstract notify(): void;
-    abstract execute(): void;
-}

package/src/converters/index.ts

@@ -1 +0,0 @@
-export * from "./solid";

package/src/converters/solid.ts

@@ -1,109 +0,0 @@
-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,2 +0,0 @@
-export * from "./api";
-export * from "./converters";