@ersbeth/picoflow 0.0.1 → 0.2.0

package/src/advanced/stream.ts

@@ -0,0 +1,87 @@
+import { FlowObservable } from "../basic/";
+
+/**
+ * A function type that sets a new value for the reactive stream.
+ * @typeparam T - The type of the value.
+ * @public
+ */
+export type FlowStreamSetter<T> = (value: T) => void;
+
+/**
+ * A function type that disposes of a resource.
+ * @public
+ */
+export type FlowStreamDisposer = () => void;
+
+/**
+ * A function type that updates a stream and returns a disposer for cleanup.
+ * @remarks
+ * The updater receives a setter function to update the stream's value.
+ * It should return a disposer function to release any resources or subscriptions.
+ * @typeparam T - The type of the stream value.
+ * @public
+ */
+export type FlowStreamUpdater<T> = (
+    set: FlowStreamSetter<T>,
+) => FlowStreamDisposer;
+
+/**
+ * Represents a reactive stream that updates its value based on an updater function.
+ *
+ * @remarks
+ * FlowStream extends FlowObservable to encapsulate an update mechanism provided by an external updater function.
+ * The updater is invoked during construction with a setter, and it returns a disposer to be called upon disposal.
+ * Note: The stream's current value may be undefined until explicitly set.
+ *
+ * @typeparam T - The type of the stream's value.
+ * @public
+ */
+export class FlowStream<T> extends FlowObservable<T | undefined> {
+    /**
+     * Creates a new FlowStream.
+     * @param updater - A function that receives a setter to update the stream's value.
+     * It should return a disposer function that will be called upon disposal.
+     * @public
+     */
+    constructor(updater: FlowStreamUpdater<T>) {
+        super();
+        this._disposer = updater((value: T) => {
+            this._set(value);
+        });
+    }
+
+    /**
+     * Retrieves the current value of the stream.
+     * @returns The current value, or undefined if no value has been set yet.
+     * @throws Error if the stream is disposed.
+     * @public
+     */
+    public get(): T | undefined {
+        if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+        return this._value;
+    }
+
+    /**
+     * Disposes the stream, releasing all resources.
+     * @remarks
+     * In addition to disposing the underlying observable, this method calls the disposer
+     * returned by the updater.
+     * @public
+     */
+    public override dispose(): void {
+        super.dispose();
+        this._disposer();
+    }
+
+    /* INTERNAL ------------------------------------------------------ */
+
+    private _disposer: FlowStreamDisposer;
+
+    private _set(value: T): void {
+        /* v8 ignore next */
+        if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+        if (value === this._value) return;
+        this._value = value;
+        this._notify();
+    }
+}

package/src/advanced/streamAsync.ts

@@ -0,0 +1,82 @@
+import { FlowObservable } from "../basic";
+import type { FlowStreamDisposer, FlowStreamUpdater } from "./stream";
+
+/**
+ * Represents an asynchronous reactive stream that updates its value based on an updater function.
+ *
+ * @remarks
+ * A FlowStreamAsync extends FlowObservable and encapsulates a mechanism for asynchronously updating its value.
+ * The updater is invoked during construction with a setter, and its returned disposer is called upon disposal.
+ * Note: The stream's current value may be undefined until it is set.
+ *
+ * @typeparam T - The type of the stream's value.
+ * @public
+ */
+export class FlowStreamAsync<T> extends FlowObservable<Promise<T>> {
+    /**
+     * Creates a new asynchronous FlowStream.
+     * @param updater - A function that receives a setter to update the stream's value.
+     * It should return a disposer function that will be called upon disposal.
+     * @remarks The updater function can invoke the setter asynchronously to update the stream.
+     * @public
+     */
+    constructor(updater: FlowStreamUpdater<T>) {
+        super();
+        this._disposer = updater((value: T) => {
+            this._set(value);
+        });
+
+        this._value = new Promise((resolve) => {
+            this._resolve = resolve;
+        });
+    }
+
+    /**
+     * Retrieves the current value of the stream as a Promise.
+     * @returns A Promise that resolves to the current value.
+     * @throws Error if the stream is disposed.
+     * @public
+     */
+    public get(): Promise<T> {
+        if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+        return this._value;
+    }
+
+    /**
+     * Disposes the stream, releasing all resources.
+     * @remarks In addition to disposing the underlying observable, this method calls the disposer
+     * returned by the updater.
+     * @public
+     */
+    public override dispose(): void {
+        super.dispose();
+        this._disposer();
+    }
+
+    /* INTERNAL ------------------------------------------------------ */
+
+    private _initialized = false;
+    private _awaitedValue?: T;
+
+    private _resolve!: (value: T) => void;
+    private _disposer: FlowStreamDisposer;
+
+    private _set(value: T): void {
+        /* v8 ignore next */
+        if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+
+        if (!this._initialized) {
+            this._resolve(value);
+            this._initialized = true;
+            this._awaitedValue = value;
+            this._notify();
+            return;
+        }
+
+        if (value === this._awaitedValue) return;
+
+        this._value = Promise.resolve(value);
+        this._awaitedValue = value;
+        this._notify();
+    }
+}

package/src/basic/constant.ts

@@ -0,0 +1,64 @@
+import { FlowObservable } from "./observable";
+
+/**
+ * Represents a reactive and immutable constant value computed lazily upon first access.
+ *
+ * @remarks This class extends FlowObservable and supports initializing the constant using either a direct value
+ * or a lazy initializer function. Once computed, the value is cached for all subsequent accesses.
+ *
+ * @typeparam T - The type of the constant value.
+ *
+ * @public
+ */
+export class FlowConstant<T> extends FlowObservable<T> {
+    /**
+     * Creates a new FlowConstant instance.
+     *
+     * @param value - Either a direct value of type T or a function returning a value of type T for lazy initialization.
+     * @public
+     */
+    constructor(value: T | (() => T)) {
+        super();
+        this._initEager(value);
+    }
+
+    /**
+     * Retrieves the constant value, computing it lazily if needed.
+     *
+     * Accessing this method will initialize the value if it has not been computed already.
+     * Throws an error if the instance has been disposed or if lazy initialization fails.
+     *
+     * @returns The cached constant value.
+     * @throws Error if the constant is disposed or cannot be initialized.
+     * @public
+     */
+    get(): T {
+        if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+        this._initLazy();
+        return this._value;
+    }
+
+    /* INTERNAL --------------------------------------------------------- */
+
+    /*@internal*/ protected _initialized = false;
+    /*@internal*/ protected _init?: () => T;
+
+    /*@internal*/ protected _initEager(value: T | (() => T)): void {
+        if (typeof value === "function") {
+            this._init = value as () => T;
+        } else {
+            this._value = value;
+            this._initialized = true;
+        }
+    }
+
+    /*@internal*/ protected _initLazy(): void {
+        if (!this._initialized && this._init) {
+            this._value = this._init();
+            this._initialized = true;
+        }
+        /* v8 ignore next 2 */
+        if (!this._initialized)
+            throw new Error("[PicoFlow] Primitive can't be initialized");
+    }
+}

package/src/basic/derivation.ts

@@ -0,0 +1,86 @@
+import { type FlowGetter, FlowObservable } from "./observable";
+import type { FlowWatcher } from "./signal";
+
+/**
+ * Represents a reactive derivation whose value is computed based on other reactive signals.
+ * @remarks
+ * It tracks dependencies automatically and recomputes its value when any dependency changes.
+ * Use FlowDerivation to create derived values in a reactive manner. It lazily initializes the computed value,
+ * ensuring that computations only occur when necessary.
+ * @typeparam T - The type of the computed value.
+ * @public
+ */
+export class FlowDerivation<T> extends FlowObservable<T> {
+    /**
+     * Creates a new FlowDerivation.
+     * @param compute - A function that computes the derived value. It is provided with two parameters:
+     * a getter and a watcher that respect dependency tracking.
+     * @public
+     */
+    constructor(compute: (get: FlowGetter, watch: FlowWatcher) => T) {
+        super();
+        this._initEager(compute);
+    }
+
+    /**
+     * Gets the current derived value.
+     * @returns The current computed value.
+     * @remarks
+     * This method lazily initializes and updates the derivation if it is marked as dirty. It throws an error
+     * if the derivation has been disposed.
+     * @public
+     */
+    public get(): T {
+        if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+        this._initLazy();
+        this._compute();
+        return this._value;
+    }
+
+    /* INTERNAL --------------------------------------------------------- */
+
+    private _initialized = false;
+    private _dirty = false;
+
+    private _trackedGet: FlowGetter = (observable) => observable._getFrom(this);
+    private _trackedWatch: FlowWatcher = (signal) => signal._watchFrom(this);
+    private _untrackedGet: FlowGetter = (observable) => observable.get();
+    private _untrackedWatch: FlowWatcher = (signal) => signal._watch();
+    private _trackedCompute!: () => T;
+    private _untrackedCompute!: () => T;
+
+    private _initEager(
+        compute: (get: FlowGetter, watch: FlowWatcher) => T,
+    ): void {
+        this._trackedCompute = () =>
+            compute(this._trackedGet, this._trackedWatch);
+        this._untrackedCompute = () =>
+            compute(this._untrackedGet, this._untrackedWatch);
+    }
+
+    private _initLazy(): void {
+        if (!this._initialized) {
+            this._value = this._trackedCompute();
+            this._initialized = true;
+        }
+    }
+
+    /* @internal */ _compute(): void {
+        if (this._dirty) {
+            this._value = this._untrackedCompute();
+            this._dirty = false;
+        }
+    }
+
+    /* @internal */ override _notify(): void {
+        this._dirty = true;
+        super._notify();
+    }
+
+    /* @internal */ override _watch(): void {
+        /* v8 ignore next 1 */
+        if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+        this._initLazy();
+        this._compute();
+    }
+}

package/src/basic/disposable.ts

@@ -0,0 +1,27 @@
+/**
+ * Represents an object with a disposable lifecycle.
+ * @remarks
+ * Objects implementing this interface require explicit resource disposal.
+ * @public
+ */
+export interface FlowDisposable {
+    /**
+     * Disposes resources held by this object.
+     * @param options - Options to specify disposal behavior.
+     */
+    dispose(options?: { self: boolean }): void;
+}
+
+/**
+ * Checks whether an object implements the FlowDisposable interface.
+ * @param obj - The object to test.
+ * @returns True if the object has a dispose method, otherwise false.
+ * @public
+ */
+export function isDisposable(obj: unknown): obj is FlowDisposable {
+    return (
+        obj !== null &&
+        obj !== undefined &&
+        typeof (obj as FlowDisposable).dispose === "function"
+    );
+}

package/src/basic/effect.ts

@@ -0,0 +1,96 @@
+import type { FlowGetter } from "./observable";
+import type { FlowSignal, FlowWatcher } from "./signal";
+
+/**
+ * Represents a reactive effect that executes side-effect functions based
+ * on its tracked dependencies.
+ *
+ * @remarks
+ * The FlowEffect executes an apply function that performs side effects,
+ * running initially in a tracked mode to register dependencies and then in
+ * an untracked mode to re-execute the effect on updates.
+ *
+ * @public
+ */
+export class FlowEffect {
+    /**
+     * Creates a new FlowEffect.
+     *
+     * @param apply - A side-effect function that receives a getter and a watcher to
+     * access and register dependencies on reactive observables and signals.
+     *
+     * @remarks
+     * The provided function is executed immediately in a tracked mode to collect dependencies.
+     * On subsequent executions, it runs in an untracked mode.
+     *
+     * @public
+     */
+    constructor(apply: (get: FlowGetter, watch: FlowWatcher) => void) {
+        this._trackedExec = () => apply(this._trackedGet, this._trackedWatch);
+        this._untrackedExec = () =>
+            apply(this._untrackedGet, this._untrackedWatch);
+        this._exec();
+    }
+
+    /**
+     * Disposes the effect, unregistering all its tracked dependencies.
+     *
+     * @remarks
+     * Once disposed, the effect must no longer be used. Trying to dispose an effect
+     * that is already disposed will throw an error.
+     *
+     * @public
+     */
+    public dispose(): void {
+        if (this._disposed) throw new Error("[PicoFlow] Effect is disposed");
+        Array.from(this._dependencies).forEach((dependency) => {
+            this._unregisterDependency(dependency);
+        });
+        this._disposed = true;
+    }
+
+    /**
+     * Indicates whether this effect has been disposed.
+     *
+     * @returns A boolean value that is true if the effect is disposed, false otherwise.
+     *
+     * @public
+     */
+    public get disposed(): boolean {
+        return this._disposed;
+    }
+
+    /* INTERNAL ------------------------------------------------------------ */
+
+    private _disposed = false;
+    private _initialized = false;
+    private _dependencies = new Set<FlowSignal>();
+
+    private _trackedGet: FlowGetter = (observable) => observable._getFrom(this);
+    private _trackedWatch: FlowWatcher = (signal) => signal._watchFrom(this);
+    private _untrackedGet: FlowGetter = (observable) => observable.get();
+    private _untrackedWatch: FlowWatcher = (signal) => signal._watch();
+    private _trackedExec: () => void;
+    private _untrackedExec: () => void;
+
+    /*@internal*/ _exec(): void {
+        if (this._disposed)
+            /* v8 ignore next 1 */
+            throw new Error("[PicoFlow] Effect is disposed");
+        if (this._initialized) this._untrackedExec();
+        else {
+            this._trackedExec();
+            this._initialized = true;
+        }
+    }
+
+    /*@internal*/ _registerDependency(dependency: FlowSignal): void {
+        this._dependencies.add(dependency);
+        dependency._registerEffect(this);
+    }
+
+    /*@internal*/ _unregisterDependency(dependency: FlowSignal): void {
+        this._dependencies.delete(dependency);
+        dependency._unregisterEffect(this);
+    }
+}

package/src/basic/index.ts

@@ -0,0 +1,10 @@
+export { FlowSignal } from "./signal";
+export { FlowState } from "./state";
+export { FlowObservable } from "./observable";
+export { FlowDerivation } from "./derivation";
+export { FlowEffect } from "./effect";
+export { FlowConstant } from "./constant";
+export { isDisposable } from "./disposable";
+export type { FlowGetter } from "./observable";
+export type { FlowWatcher } from "./signal";
+export type { FlowDisposable } from "./disposable";

package/src/basic/observable.ts

@@ -0,0 +1,51 @@
+import { FlowEffect } from "./effect";
+import { FlowSignal } from "./signal";
+
+/**
+ * A function that retrieves the current value from a FlowObservable.
+ * @typeparam T - The type of the value held by the observable.
+ * @param observable - The FlowObservable instance to retrieve the value from.
+ * @returns The current value of the observable.
+ * @public
+ */
+export type FlowGetter = <T>(observable: FlowObservable<T>) => T;
+
+/**
+ * Represents a reactive observable that holds and tracks a value.
+ *
+ *
+ * @remarks Subclasses must implement the {@link FlowObservable.get} method to return the current value.
+ * @typeparam T - The type of the value held by the observable.
+ * @public
+ */
+export abstract class FlowObservable<T> extends FlowSignal {
+    /**
+     * Retrieves the current value stored in the observable.
+     * Subclasses must override this method to provide the current value.
+     * @returns The current value of type T.
+     * @public
+     */
+    abstract get(): T;
+
+    /* INTERNAL -------------------------------------------*/
+
+    /*@internal*/ protected _value!: T;
+
+    /*@internal*/ _getFrom(listener: FlowObservable<unknown> | FlowEffect): T {
+        listener._registerDependency(this);
+        return this.get();
+    }
+
+    /**
+     * Subscribes a listener function to changes of the observable.
+     * The listener is executed immediately with the current value and on subsequent updates.
+     * @param listener - A callback function that receives the new value.
+     * @returns A disposer function to cancel the subscription.
+     */
+    subscribe(listener: (value: T) => void): () => void {
+        const effect = new FlowEffect((get) => {
+            listener(get(this));
+        });
+        return () => effect.dispose();
+    }
+}

package/src/basic/signal.ts

@@ -0,0 +1,117 @@
+import type { FlowDisposable } from "./disposable";
+import type { FlowEffect } from "./effect";
+
+/**
+ * A function for watching a FlowSignal.
+ * @param signal - The FlowSignal that is being observed.
+ * @public
+ */
+export type FlowWatcher = (signal: FlowSignal) => void;
+
+/**
+ * Represents a reactive signal.
+ *
+ * @remarks Use FlowSignal to create reactive streams that notify listeners and execute associated effects.
+ * Signals can be triggered and disposed. Once disposed, interactions with the signal will throw errors.
+ * @public
+ */
+export class FlowSignal implements FlowDisposable {
+    /**
+     * Triggers the FlowSignal.
+     * Notifies all registered listeners and schedules execution of associated effects.
+     * @throws If the FlowSignal has already been disposed.
+     * @public
+     */
+    public trigger(): void {
+        if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+        this._notify();
+    }
+
+    /**
+     * Disposes the FlowSignal.
+     * Cleans up all registered effects, listeners, and dependencies.
+     * Once disposed, further usage of the signal will throw an error.
+     * @throws If the FlowSignal is already disposed.
+     * @public
+     */
+    public dispose(options?: { self: boolean }): void {
+        if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+        if (options?.self) {
+            Array.from(this._effects).forEach((effect) =>
+                effect._unregisterDependency(this),
+            );
+            Array.from(this._listeners).forEach((listener) =>
+                listener._unregisterDependency(this),
+            );
+        } else {
+            Array.from(this._effects).forEach((effect) => effect.dispose());
+            Array.from(this._listeners).forEach((listener) =>
+                listener.dispose(),
+            );
+        }
+        Array.from(this._dependencies).forEach((dependency) => {
+            this._unregisterDependency(dependency);
+        });
+        this._disposed = true;
+    }
+
+    /**
+     * Indicates whether the FlowSignal has been disposed.
+     * @remarks Once disposed, the signal should not be used.
+     * @public
+     */
+    public get disposed(): boolean {
+        return this._disposed;
+    }
+
+    /* INTERNAL ------------------------------------------------------------- */
+
+    /*@internal*/ protected _disposed = false;
+
+    /*@internal*/ protected _dependencies = new Set<FlowSignal>();
+
+    /*@internal*/ protected _listeners = new Set<FlowSignal>();
+
+    /*@internal*/ protected _effects = new Set<FlowEffect>();
+
+    /*@internal*/ _watch(): void {
+        /* v8 ignore next 1 */
+        if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    }
+
+    /*@internal*/ _notify(): void {
+        this._listeners.forEach((listener) => listener._notify());
+        this._effects.forEach((effect) => effect._exec());
+    }
+
+    /*@internal*/ _watchFrom(listener: FlowSignal | FlowEffect): void {
+        listener._registerDependency(this);
+        this._watch();
+    }
+
+    /*@internal*/ _registerDependency(dependency: FlowSignal): void {
+        this._dependencies.add(dependency);
+        dependency._registerListener(this);
+    }
+
+    /*@internal*/ _unregisterDependency(dependency: FlowSignal): void {
+        this._dependencies.delete(dependency);
+        dependency._unregisterListener(this);
+    }
+
+    /*@internal*/ _registerListener(signal: FlowSignal): void {
+        this._listeners.add(signal);
+    }
+
+    /*@internal*/ _unregisterListener(signal: FlowSignal): void {
+        this._listeners.delete(signal);
+    }
+
+    /*@internal*/ _registerEffect(effect: FlowEffect): void {
+        this._effects.add(effect);
+    }
+
+    /*@internal*/ _unregisterEffect(effect: FlowEffect): void {
+        this._effects.delete(effect);
+    }
+}

package/src/basic/state.ts

@@ -0,0 +1,39 @@
+import { FlowConstant } from "./constant";
+
+/**
+ * Represents a reactive state that holds a mutable value.
+ *
+ * @typeparam T - The type of the state value.
+ *
+ * @remarks
+ * FlowState extends FlowConstant, which provides the {@link FlowConstant.get} method to read
+ * the current state. Use the {@link FlowState.set} method to update the state. When the state is updated,
+ * subscribers are notified automatically. This class notifies subscribers only when the value changes.
+ *
+ * @public
+ */
+export class FlowState<T> extends FlowConstant<T> {
+    /**
+     * Updates the state with a new value.
+     * @param value - A new value or a callback function that computes a new value based on the current state.
+     * @remarks
+     * If the computed new value is strictly equal to the current state value, no change is made and subscribers
+     * will not be notified. Otherwise, the state is updated and all subscribers are informed of the change.
+     * @throws Error if the state has been disposed.
+     * @public
+     */
+    set(value: T | ((current: T) => T)): void {
+        if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+
+        // compute new value
+        const next =
+            typeof value === "function"
+                ? (value as (current: T) => T)(this._value)
+                : value;
+
+        // apply new value
+        if (next === this._value) return;
+        this._value = next;
+        this._notify();
+    }
+}