@ersbeth/picoflow 0.0.1 → 0.1.0

package/src/derivation.ts

@@ -1,96 +0,0 @@
-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
- * A FlowDerivation automatically tracks its dependencies and recomputes its value when needed.
- * @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 a getter
-     * and a watcher function to access observables and signals dependencies.
-     * @public
-     */
-    constructor(compute: (get: FlowGetter, watch: FlowWatcher) => T) {
-        super();
-        this._trackedExec = () => compute(this._trackedGet, this._trackedWatch);
-        this._untrackedExec = () =>
-            compute(this._untrackedGet, this._untrackedWatch);
-    }
-
-    /**
-     * Gets the current derived value.
-     * @returns The current computed value.
-     * @remarks
-     * This method ensures that the derivation is up-to-date before returning the value.
-     * @public
-     */
-    public get(): T {
-        this._exec();
-        return this._value;
-    }
-
-    /* INTERNAL MEMBERS AND METHODS */
-
-    /** @internal */
-    private _initialized = false;
-
-    /** @internal */
-    private _dirty = true;
-
-    /** @internal */
-    private _trackedGet: FlowGetter = (observable) => observable._getFrom(this);
-
-    /** @internal */
-    private _trackedWatch: FlowWatcher = (signal) => signal._watchFrom(this);
-
-    /** @internal */
-    private _untrackedGet: FlowGetter = (observable) => observable.get();
-
-    /** @internal */
-    private _untrackedWatch: FlowWatcher = (signal) => signal._watch();
-
-    /** @internal */
-    private _trackedExec: () => T;
-
-    /** @internal */
-    private _untrackedExec: () => T;
-
-    /**
-     * @internal
-     * Executes the compute function if necessary to update the derived value.
-     */
-    _exec(): void {
-        if (this._disposed) throw new Error("Effect is disposed");
-
-        if (this._dirty) {
-            if (this._initialized) this._value = this._untrackedExec();
-            else {
-                this._value = this._trackedExec();
-                this._initialized = true;
-            }
-            this._dirty = false;
-        }
-    }
-
-    /**
-     * @internal
-     * Marks the derivation as dirty and notifies downstream dependencies.
-     */
-    override _notify(): void {
-        this._dirty = true;
-        super._notify();
-    }
-
-    /**
-     * @internal
-     * Ensures that the derivation is up-to-date when it is watched.
-     */
-    override _watch(): void {
-        this._exec();
-    }
-}

package/src/effect.ts

@@ -1,152 +0,0 @@
-import type { FlowGetter } from "./observable";
-import type { FlowSignal, FlowWatcher } from "./signal";
-
-/**
- * Represents a reactive effect that executes a side‐effect function
- * based on its tracked dependencies.
- *
- * @remarks
- * A FlowEffect runs an apply function to perform side effects. The apply function
- * is executed in two modes:
- * Initially, in a tracked mode to register dependencies.
- * Subsequently, in an untracked mode to only re-execute the effect .
- *
- * @public
- */
-export class FlowEffect {
-    /* API --------------------------------------------------- */
-
-    /**
-     * Creates a new FlowEffect.
-     *
-     * @param apply - A function that performs the side effect. It receives a getter and a watcher
-     * function to access and register dependencies on reactive observables and signals.
-     *
-     * @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 dependencies.
-     *
-     * @remarks
-     * After disposal, the effect should no longer be used. Calling this method on an already
-     * disposed effect will throw an error.
-     *
-     * @public
-     */
-    public dispose(): void {
-        if (this._disposed) throw new Error("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 indicating if the effect is disposed.
-     *
-     * @public
-     */
-    public get disposed(): boolean {
-        return this._disposed;
-    }
-
-    /* INTERNAL ------------------------------------------------------------ */
-
-    /**
-     * @internal
-     */
-    private _disposed = false;
-
-    /**
-     * @internal
-     */
-    private _initialized = false;
-
-    /**
-     * @internal
-     */
-    private _dependencies = new Set<FlowSignal>();
-
-    /**
-     * @internal
-     * A tracked getter that registers a dependency when accessing an observable.
-     */
-    private _trackedGet: FlowGetter = (observable) => observable._getFrom(this);
-
-    /**
-     * @internal
-     * A tracked watcher that registers a dependency when watching a signal.
-     */
-    private _trackedWatch: FlowWatcher = (signal) => signal._watchFrom(this);
-
-    /**
-     * @internal
-     * An untracked getter that simply retrieves the current value from an observable.
-     */
-    private _untrackedGet: FlowGetter = (observable) => observable.get();
-
-    /**
-     * @internal
-     * An untracked watcher that calls the default watch on a signal.
-     */
-    private _untrackedWatch: FlowWatcher = (signal) => signal._watch();
-
-    /**
-     * @internal
-     * Execution function used during initialization (tracked mode).
-     */
-    private _trackedExec: () => void;
-
-    /**
-     * @internal
-     * Execution function used after initialization (untracked mode).
-     */
-    private _untrackedExec: () => void;
-
-    /**
-     * @internal
-     * Executes the effect. If the effect has not been initialized, it runs in tracked mode;
-     * otherwise, it runs in untracked mode.
-     *
-     * @throws Error if the effect has been disposed.
-     */
-    _exec(): void {
-        if (this._disposed) throw new Error("Effect is disposed");
-        if (this._initialized) this._untrackedExec();
-        else {
-            this._trackedExec();
-            this._initialized = true;
-        }
-    }
-
-    /**
-     * @internal
-     * Registers a dependency on the given signal.
-     *
-     * @param dependency - The FlowSignal to register as a dependency.
-     */
-    _registerDependency(dependency: FlowSignal): void {
-        this._dependencies.add(dependency);
-        dependency._registerEffect(this);
-    }
-
-    /**
-     * @internal
-     * Unregisters the given dependency.
-     *
-     * @param dependency - The FlowSignal to unregister.
-     */
-    _unregisterDependency(dependency: FlowSignal): void {
-        this._dependencies.delete(dependency);
-        dependency._unregisterEffect(this);
-    }
-}

package/src/observable.ts

@@ -1,50 +0,0 @@
-import type { FlowEffect } from "./effect";
-import { FlowSignal } from "./signal";
-
-/**
- * A function for retrieving the current value from a FlowObservable.
- * @typeparam T - The type of the value held by the observable.
- * @param atom - The FlowObservable from which to get the value.
- * @returns The current value of the observable.
- * @public
- */
-export type FlowGetter = <T>(observable: FlowObservable<T>) => T;
-
-/**
- * Represents a reactive observable that carries a value.
- * @typeparam T - The type of the value held by the observable.
- * @remarks
- * A FlowObservable extends the basic FlowSignal to store a value. Subclasses must
- * implement the abstract {@link FlowObservable.get} method to return the current value.
- * @public
- */
-export abstract class FlowObservable<T> extends FlowSignal {
-    /* API ----------------------------------------------- */
-
-    /**
-     * Retrieves the current value of the observable.
-     * @returns The current value.
-     * @public
-     */
-    abstract get(): T;
-
-    /* INTERNAL -------------------------------------------*/
-
-    /**
-     * @internal
-     * Internal storage for the observable's value.
-     */
-    protected _value!: T;
-
-    /**
-     * @internal
-     * Retrieves the current value from the observable and registers a dependency
-     * from the provided listener.
-     * @param listener - The FlowObservable or FlowEffect that is accessing this observable.
-     * @returns The current value, as returned by {@link FlowObservable.get}.
-     */
-    _getFrom(listener: FlowObservable<unknown> | FlowEffect): T {
-        listener._registerDependency(this);
-        return this.get();
-    }
-}

package/src/signal.ts

@@ -1,166 +0,0 @@
-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
- * A FlowSignal allows you to trigger notifications via {@link FlowSignal.trigger}
- * and to dispose the signal and all its registered dependencies, listeners, and effects via {@link FlowSignal.dispose}.
- * @public
- */
-export class FlowSignal {
-    /* API ---------------------------------------------------------------------- */
-
-    /**
-     * Triggers the signal.
-     * @remarks
-     * This method notifies all registered listeners and causes associated effects to execute.
-     * @throws Error if the signal is disposed.
-     * @public
-     */
-    public trigger(): void {
-        if (this._disposed) throw new Error("Signal is disposed");
-        this._notify();
-    }
-
-    /**
-     * Disposes the signal.
-     * @remarks
-     * Disposing a signal will dispose all registered effects and listeners,
-     * and unregister all dependencies. Once disposed, any further calls to the signal
-     * will throw an error.
-     * @throws Error if the signal is already disposed.
-     * @public
-     */
-    public dispose(): void {
-        if (this._disposed) throw new Error("Signal is disposed");
-        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 signal 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
-     * Internal method to watch the signal.
-     * @throws Error if the signal is disposed.
-     */
-    _watch(): void {
-        if (this._disposed) throw new Error("Signal is disposed");
-    }
-
-    /**
-     * @internal
-     * Notifies all listeners and executes all registered effects.
-     */
-    _notify(): void {
-        this._listeners.forEach((listener) => listener._notify());
-        this._effects.forEach((effect) => effect._exec());
-    }
-
-    /**
-     * @internal
-     * Registers a dependency from the given listener and watches the signal.
-     * @param listener - A FlowSignal or FlowEffect that will depend on this signal.
-     */
-    _watchFrom(listener: FlowSignal | FlowEffect): void {
-        listener._registerDependency(this);
-        this._watch();
-    }
-
-    /**
-     * @internal
-     * Registers a dependency with the given FlowSignal.
-     * @param dependency - The FlowSignal to register as a dependency.
-     */
-    _registerDependency(dependency: FlowSignal): void {
-        this._dependencies.add(dependency);
-        dependency._registerListener(this);
-    }
-
-    /**
-     * @internal
-     * Unregisters the given dependency.
-     * @param dependency - The FlowSignal to unregister.
-     */
-    _unregisterDependency(dependency: FlowSignal): void {
-        this._dependencies.delete(dependency);
-        dependency._unregisterListener(this);
-    }
-
-    /**
-     * @internal
-     * Registers a listener (another FlowSignal) to this signal.
-     * @param signal - The FlowSignal to register as a listener.
-     */
-    _registerListener(signal: FlowSignal): void {
-        this._listeners.add(signal);
-    }
-
-    /**
-     * @internal
-     * Unregisters the given listener.
-     * @param signal - The FlowSignal to unregister.
-     */
-    _unregisterListener(signal: FlowSignal): void {
-        this._listeners.delete(signal);
-    }
-
-    /**
-     * @internal
-     * Registers a FlowEffect to this signal.
-     * @param effect - The FlowEffect to register.
-     */
-    _registerEffect(effect: FlowEffect): void {
-        this._effects.add(effect);
-    }
-
-    /**
-     * @internal
-     * Unregisters the given FlowEffect.
-     * @param effect - The FlowEffect to unregister.
-     */
-    _unregisterEffect(effect: FlowEffect): void {
-        this._effects.delete(effect);
-    }
-}

package/src/state.ts

@@ -1,52 +0,0 @@
-import { FlowObservable } from "./observable";
-
-/**
- * Represents a reactive state that holds a mutable value.
- *
- * @typeparam T - The type of the state value.
- *
- * @remarks
- * FlowState extends FlowObservable to provide a simple reactive state primitive.
- * Use the {@link FlowState.get} method to read the current state and {@link FlowState.set} to update it.
- * When the state is updated, subscribers are notified automatically.
- *
- * @public
- */
-export class FlowState<T> extends FlowObservable<T> {
-    /**
-     * Creates a new FlowState with the given initial value.
-     * @param value - The initial value for the state.
-     * @public
-     */
-    constructor(value: T) {
-        super();
-        this._value = value;
-    }
-
-    /**
-     * Retrieves the current state value.
-     * @returns The current value of the state.
-     * @throws Error if the state has been disposed.
-     * @public
-     */
-    get(): T {
-        if (this._disposed) throw new Error("State is disposed");
-        return this._value;
-    }
-
-    /**
-     * Updates the state with a new value.
-     * @param value - The new value to set.
-     * @remarks
-     * If the new value is identical to the current value, no update or notification occurs.
-     * Otherwise, the state is updated and all subscribers are notified.
-     * @throws Error if the state has been disposed.
-     * @public
-     */
-    set(value: T): void {
-        if (this._disposed) throw new Error("State is disposed");
-        if (value === this._value) return;
-        this._value = value;
-        this._notify();
-    }
-}

package/src/stream.ts

@@ -1,99 +0,0 @@
-import { FlowObservable } from "./observable";
-
-/**
- * A function that sets a new value.
- * @typeparam T - The type of the value.
- * @public
- */
-export type FlowSetter<T> = (value: T) => void;
-
-/**
- * A function that disposes of a resource.
- * @public
- */
-export type FlowDisposer = () => void;
-
-/**
- * A function that performs updates on a stream.
- * @remarks
- * The updater receives a setter function that can be used to update the stream's value.
- * It should return a disposer function to clean up any resources or subscriptions.
- * @typeparam T - The type of the stream value.
- * @public
- */
-export type FlowUpdater<T> = (set: FlowSetter<T>) => FlowDisposer;
-
-/**
- * Represents a reactive stream that updates its value based on an updater function.
- *
- * @remarks
- * A FlowStream extends FlowObservable and encapsulates a mechanism for updating its value
- * via an external updater function. The updater is invoked during construction with a setter,
- * and it returns a disposer to be called when the stream is disposed.
- *
- * @typeparam T - The type of the stream's value.
- *
- * @public
- */
-export class FlowStream<T> extends FlowObservable<T> {
-    /* API -------------------------------------------------------- */
-
-    /**
-     * 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.
-     * @param initial - The initial value of the stream.
-     * @public
-     */
-    constructor(updater: FlowUpdater<T>, initial: T) {
-        super();
-        this._value = initial;
-        this._disposer = updater((value: T) => {
-            this._set(value);
-        });
-    }
-
-    /**
-     * Retrieves the current value of the stream.
-     * @returns The current value.
-     * @throws Error if the stream is disposed.
-     * @public
-     */
-    public get(): T {
-        if (this._disposed) throw new Error("Stream 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 ------------------------------------------------------ */
-
-    /**
-     * @internal
-     * The disposer function returned by the updater.
-     */
-    private _disposer: FlowDisposer;
-
-    /**
-     * @internal
-     * Updates the stream's value and notifies subscribers if the value changes.
-     * @param value - The new value to set.
-     * @internal
-     */
-    private _set(value: T): void {
-        if (this._disposed) throw new Error("Stream is disposed");
-        if (value === this._value) return;
-        this._value = value;
-        this._notify();
-    }
-}