@ersbeth/picoflow 0.0.1 → 0.1.0

package/dist/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,YAAY,CAAC;AACtF,YAAY,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,YAAY,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAC3C,YAAY,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC/D,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACxD,YAAY,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACzC,YAAY,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AACrC,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EACH,MAAM,EACN,KAAK,EACL,QAAQ,EACR,QAAQ,EACR,MAAM,EACN,UAAU,EACV,MAAM,EACN,GAAG,EACH,WAAW,EACX,aAAa,GAChB,MAAM,YAAY,CAAC;AACpB,YAAY,EACR,cAAc,EACd,UAAU,EACV,UAAU,EACV,cAAc,EACd,UAAU,EACV,WAAW,EACX,SAAS,EACT,YAAY,GACf,MAAM,UAAU,CAAC;AAClB,YAAY,EACR,YAAY,EACZ,OAAO,EACP,iBAAiB,EACjB,eAAe,EACf,UAAU,EACV,kBAAkB,EAClB,gBAAgB,EAChB,iBAAiB,GACpB,MAAM,aAAa,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@ersbeth/picoflow",
-    "version": "0.0.1",
+    "version": "0.1.0",
     "description": "Minimal Dataflow librairy for TypeScript",
     "type": "module",
     "exports": {

package/src/advanced/index.ts

@@ -0,0 +1,10 @@
+export { FlowMap } from "./map";
+export { FlowStream } from "./stream";
+export { FlowStreamAsync } from "./streamAsync";
+export { FlowResource } from "./resource";
+export { FlowResourceAsync } from "./resourceAsync";
+export type {
+    FlowStreamUpdater,
+    FlowStreamDisposer,
+    FlowStreamSetter,
+} from "./stream";

package/src/{map.ts → advanced/map.ts}

@@ -1,18 +1,17 @@
-import { FlowState } from "./state";
+import { FlowState } from "../basic/";
 
 /**
- * Represents a reactive map of states that extends {@link FlowState} for a Map of key/value pairs.
+ * Represents a reactive map of states extending {@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:
+ * it exposes two reactive signals:
  *
- * **$lastSet**: A FlowState that holds the most recent key-value pair that was set.
+ * • $lastSet: Holds the most recent key-value pair that was set.
+ * • $lastDeleted: Holds the most recent key-value pair that was deleted.
  *
- * **$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.
+ * Use {@link FlowMap.setAt} to add or update 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.
@@ -47,15 +46,16 @@ export class FlowMap<K, V> extends FlowState<Map<K, V>> {
      *
      * @param key - The key at which to set the value.
      * @param value - The value to set.
+     * @throws If the FlowMap instance is disposed.
      *
      * @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.
+     * Updates the internal map, emits the key-value pair via {@link FlowMap.$lastSet},
+     * and notifies all subscribers of the change.
      *
      * @public
      */
     public setAt(key: K, value: V): void {
-        if (this._disposed) throw new Error("StateMap is disposed");
+        if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
         this._value.set(key, value);
         this.$lastSet.set({ key, value });
         this._notify();
@@ -65,16 +65,16 @@ export class FlowMap<K, V> extends FlowState<Map<K, V>> {
      * Deletes the value at the specified key from the underlying map.
      *
      * @param key - The key to delete.
+     * @throws If the FlowMap instance is disposed.
      *
      * @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.
+     * Removes the key from the internal map, emits the deleted key and its value via {@link FlowMap.$lastDeleted},
+     * and notifies all subscribers of the change.
      *
      * @public
      */
     public delete(key: K): void {
-        if (this._disposed) throw new Error("StateMap is disposed");
+        if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
         const value = this._value.get(key);
         this._value.delete(key);
         this.$lastDeleted.set({ key, value });

package/src/advanced/resource.ts

@@ -0,0 +1,56 @@
+import { FlowObservable } from "../basic";
+
+/**
+ * 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.
+ *
+ * @public
+ */
+export class FlowResource<T> extends FlowObservable<T | undefined> {
+    /**
+     * Creates a new FlowResource.
+     * @param fetch - An asynchronous function that retrieves the resource's value.
+     *
+     * @public
+     */
+    constructor(fetch: () => Promise<T>) {
+        super();
+        this._fetch = fetch;
+    }
+
+    /**
+     * Retrieves the current resource value.
+     * @returns The current value, or undefined if the resource has not been fetched yet.
+     * @throws Error if the resource is disposed.
+     * @public
+     */
+    public get(): T | undefined {
+        if (this._disposed) throw new Error("[PicoFlow] Primitive 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("[PicoFlow] Primitive is disposed");
+        const value = await this._fetch();
+        if (value === this._value) return;
+        this._value = value;
+        this._notify();
+    }
+
+    /* INTERNAL ------------------------------------------------ */
+
+    private _fetch: () => Promise<T>;
+}

package/src/{resource.ts → advanced/resourceAsync.ts}

@@ -1,4 +1,4 @@
-import { FlowObservable } from "./observable";
+import { FlowObservable } from "../basic/";
 
 /**
  * Represents a reactive resource that asynchronously fetches its value.
@@ -13,27 +13,26 @@ import { FlowObservable } from "./observable";
  *
  * @public
  */
-export class FlowResource<T> extends FlowObservable<T> {
+export class FlowResourceAsync<T> extends FlowObservable<Promise<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) {
+    constructor(fetch: () => Promise<T>) {
         super();
-        this._value = initial;
         this._fetch = fetch;
     }
 
     /**
      * Retrieves the current resource value.
-     * @returns The current value.
+     * @returns The current value, or undefined if the resource has not been fetched yet.
      * @throws Error if the resource is disposed.
      * @public
      */
-    public get(): T {
-        if (this._disposed) throw new Error("Resource is disposed");
+    public get(): Promise<T> {
+        if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+        if (!this._value) this._value = this._fetch();
         return this._value;
     }
 
@@ -47,18 +46,12 @@ export class FlowResource<T> extends FlowObservable<T> {
      * @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;
+        if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+        this._value = this._fetch();
         this._notify();
     }
 
     /* INTERNAL ------------------------------------------------ */
 
-    /**
-     * @internal
-     * The asynchronous function used to fetch the resource value.
-     */
     private _fetch: () => Promise<T>;
 }

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/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,8 @@
+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 type { FlowGetter } from "./observable";
+export type { FlowWatcher } from "./signal";