@ersbeth/picoflow 0.0.1

package/src/creators.ts

@@ -0,0 +1,101 @@
+import { FlowDerivation } from "./derivation";
+import { FlowEffect } from "./effect";
+import { FlowMap } from "./map";
+import type { FlowGetter } from "./observable";
+import { FlowResource } from "./resource";
+import { FlowSignal, type FlowWatcher } from "./signal";
+import { FlowState } from "./state";
+import { FlowStream } from "./stream";
+
+/**
+ * Creates a new reactive signal.
+ * @returns A new instance of {@link FlowSignal}.
+ * @public
+ */
+export function signal(): FlowSignal {
+    return new FlowSignal();
+}
+
+/**
+ * Creates a new reactive state holding a value.
+ * @typeparam T - The type of the state value.
+ * @param value - The initial value for the state.
+ * @returns A new instance of {@link FlowState}.
+ * @public
+ */
+export function state<T>(value: T): FlowState<T> {
+    return new FlowState(value);
+}
+
+/**
+ * Creates a new reactive resource that asynchronously fetches its value.
+ * @typeparam T - The type of the resource value.
+ * @param fn - An asynchronous function that fetches the resource value.
+ * @param initial - The initial value of the resource.
+ * @returns A new instance of {@link FlowResource}.
+ * @public
+ */
+export function resource<T>(fn: () => Promise<T>, initial: T): FlowResource<T> {
+    return new FlowResource(fn, initial);
+}
+
+/**
+ * Creates a new reactive stream.
+ * @typeparam T - The type of the stream value.
+ * @param updater - A function that receives a setter to update the stream's value.
+ * It should return a disposer function to clean up resources.
+ * @param initial - The initial value of the stream.
+ * @returns A new instance of {@link FlowStream}.
+ * @public
+ */
+export function stream<T>(
+    updater: (set: (value: T) => void) => () => void,
+    initial: T,
+): FlowStream<T> {
+    return new FlowStream(updater, initial);
+}
+
+/**
+ * Creates a new reactive derivation whose value is computed based on other reactive signals.
+ * @typeparam T - The type of the derived value.
+ * @param fn - A function that computes the derived value. It receives a getter and a watcher
+ * function to access and register dependencies.
+ * @returns A new instance of {@link FlowDerivation}.
+ * @public
+ */
+export function derivation<T>(
+    fn: (get: FlowGetter, watch: FlowWatcher) => T,
+): FlowDerivation<T> {
+    return new FlowDerivation(fn);
+}
+
+/**
+ * Creates a new reactive effect that executes a side-effect function based on its dependencies.
+ * @param fn - A function that performs side effects. It receives a getter and a watcher
+ * function for tracking reactive dependencies.
+ * @returns A new instance of {@link FlowEffect}.
+ * @public
+ */
+export function effect(
+    fn: (get: FlowGetter, watch: FlowWatcher) => void,
+): FlowEffect {
+    return new FlowEffect(fn);
+}
+
+/**
+ * Creates a new reactive map state.
+ * @typeparam K - The type of the keys.
+ * @typeparam V - The type of the values.
+ * @param initial - An optional record of key-value pairs to initialize the map.
+ * @returns A new instance of {@link FlowMap}.
+ * @remarks
+ * The initial record is converted to a native Map before being used.
+ * @public
+ */
+export function map<K extends string | number | symbol, V>(
+    initial?: Record<K, V>,
+): FlowMap<K, V> {
+    return new FlowMap<K, V>(
+        new Map<K, V>(initial ? (Object.entries(initial) as [K, V][]) : []),
+    );
+}

package/src/derivation.ts

@@ -0,0 +1,96 @@
+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

@@ -0,0 +1,152 @@
+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/index.ts

@@ -0,0 +1,30 @@
+/**
+ * @packageDocumentation
+ *
+ * PicoFlow is a lightweight reactive dataflow library that provides a set of
+ * reactive primitives such as signals, state, resources, streams, derivations,
+ * effects, and reactive maps.
+ *
+ */
+export {
+    signal,
+    state,
+    resource,
+    stream,
+    derivation,
+    effect,
+    map,
+} from "./creators";
+export type { FlowDerivation } from "./derivation";
+export type { FlowEffect } from "./effect";
+export type { FlowGetter, FlowObservable } from "./observable";
+export type { FlowResource } from "./resource";
+export type { FlowSignal, FlowWatcher } from "./signal";
+export type { FlowState } from "./state";
+export type { FlowMap } from "./map";
+export type {
+    FlowStream,
+    FlowDisposer,
+    FlowSetter,
+    FlowUpdater,
+} from "./stream";

package/src/map.ts

@@ -0,0 +1,83 @@
+import { FlowState } from "./state";
+
+/**
+ * Represents a reactive map of states that extends {@link FlowState} for a Map of key/value pairs.
+ *
+ * @remarks
+ * FlowMap wraps a native Map and provides reactive signals for fine-grained tracking
+ * of updates to the map. In addition to the reactive capabilities inherited from FlowState,
+ * it exposes two public signals:
+ *
+ * **$lastSet**: A FlowState that holds the most recent key-value pair that was set.
+ *
+ * **$lastDeleted**: A FlowState that holds the most recent key-value pair that was deleted.
+ *
+ * Use {@link FlowMap.setAt} to set a key-value pair and {@link FlowMap.delete} to remove a key.
+ *
+ * @typeparam K - The type of the map keys.
+ * @typeparam V - The type of the map values.
+ *
+ * @public
+ */
+export class FlowMap<K, V> extends FlowState<Map<K, V>> {
+    /**
+     * A reactive state that holds the most recent key and value that were set.
+     *
+     * @remarks
+     * When a key is set via {@link FlowMap.setAt}, this state is updated with
+     * the corresponding key and value.
+     *
+     * @public
+     */
+    public $lastSet: FlowState<{ key?: K; value?: V }> = new FlowState({});
+
+    /**
+     * A reactive state that holds the most recent key and value that were deleted.
+     *
+     * @remarks
+     * When a key is deleted via {@link FlowMap.delete}, this state is updated with
+     * the corresponding key and its last known value.
+     *
+     * @public
+     */
+    public $lastDeleted: FlowState<{ key?: K; value?: V }> = new FlowState({});
+
+    /**
+     * Sets a value at the specified key in the underlying map.
+     *
+     * @param key - The key at which to set the value.
+     * @param value - The value to set.
+     *
+     * @remarks
+     * This method updates the internal map with the given key and value, emits the new
+     * key-value pair via {@link FlowMap.$lastSet}, and notifies subscribers of the change.
+     *
+     * @public
+     */
+    public setAt(key: K, value: V): void {
+        if (this._disposed) throw new Error("StateMap is disposed");
+        this._value.set(key, value);
+        this.$lastSet.set({ key, value });
+        this._notify();
+    }
+
+    /**
+     * Deletes the value at the specified key from the underlying map.
+     *
+     * @param key - The key to delete.
+     *
+     * @remarks
+     * This method removes the key from the internal map, emits the deleted key and its
+     * corresponding value via {@link FlowMap.$lastDeleted}, and notifies subscribers
+     * of the change.
+     *
+     * @public
+     */
+    public delete(key: K): void {
+        if (this._disposed) throw new Error("StateMap is disposed");
+        const value = this._value.get(key);
+        this._value.delete(key);
+        this.$lastDeleted.set({ key, value });
+        this._notify();
+    }
+}

package/src/observable.ts

@@ -0,0 +1,50 @@
+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/resource.ts

@@ -0,0 +1,64 @@
+import { FlowObservable } from "./observable";
+
+/**
+ * Represents a reactive resource that asynchronously fetches its value.
+ *
+ * @remarks
+ * A FlowResource extends FlowObservable and encapsulates an asynchronous fetch function.
+ * It is used to retrieve and update its value asynchronously. When the fetch is executed,
+ * if the new value differs from the current value, the resource is updated and its subscribers
+ * are notified.
+ *
+ * @typeparam T - The type of the resource value.
+ *
+ * @public
+ */
+export class FlowResource<T> extends FlowObservable<T> {
+    /**
+     * Creates a new FlowResource.
+     * @param fetch - An asynchronous function that retrieves the resource's value.
+     * @param initial - The initial value of the resource.
+     * @public
+     */
+    constructor(fetch: () => Promise<T>, initial: T) {
+        super();
+        this._value = initial;
+        this._fetch = fetch;
+    }
+
+    /**
+     * Retrieves the current resource value.
+     * @returns The current value.
+     * @throws Error if the resource is disposed.
+     * @public
+     */
+    public get(): T {
+        if (this._disposed) throw new Error("Resource is disposed");
+        return this._value;
+    }
+
+    /**
+     * Asynchronously fetches a new value for the resource.
+     * @remarks
+     * Executes the internal fetch function. If the fetched value differs from the current one,
+     * updates the resource's value and notifies subscribers.
+     * @returns A Promise that resolves when the fetch operation is complete.
+     * @throws Error if the resource is disposed.
+     * @public
+     */
+    public async fetch(): Promise<void> {
+        if (this._disposed) throw new Error("Resource is disposed");
+        const value = await this._fetch();
+        if (value === this._value) return;
+        this._value = value;
+        this._notify();
+    }
+
+    /* INTERNAL ------------------------------------------------ */
+
+    /**
+     * @internal
+     * The asynchronous function used to fetch the resource value.
+     */
+    private _fetch: () => Promise<T>;
+}