@ersbeth/picoflow 0.0.1 → 0.1.0

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,105 @@
+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 {
+    /**
+     * 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(): void {
+        if (this._disposed) throw new Error("[PicoFlow] Primitive 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 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();
+    }
+}

package/src/creators.ts

@@ -1,11 +1,18 @@
-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";
+import {
+    FlowMap,
+    FlowResource,
+    FlowResourceAsync,
+    FlowStream,
+    FlowStreamAsync,
+} from "./advanced/";
+import {
+    FlowConstant,
+    FlowDerivation,
+    FlowEffect,
+    FlowSignal,
+    FlowState,
+} from "./basic/";
+import type { FlowGetter, FlowWatcher } from "./basic/";
 
 /**
  * Creates a new reactive signal.
@@ -16,6 +23,16 @@ export function signal(): FlowSignal {
     return new FlowSignal();
 }
 
+/**
+ * Creates a new reactive constant.
+ * @param value - The value or a function that returns the value.
+ * @returns A new instance of {@link FlowConstant}.
+ * @public
+ */
+export function constant<T>(value: T | (() => T)): FlowConstant<T> {
+    return new FlowConstant<T>(value);
+}
+
 /**
  * Creates a new reactive state holding a value.
  * @typeparam T - The type of the state value.
@@ -23,7 +40,7 @@ export function signal(): FlowSignal {
  * @returns A new instance of {@link FlowState}.
  * @public
  */
-export function state<T>(value: T): FlowState<T> {
+export function state<T>(value: T | (() => T)): FlowState<T> {
     return new FlowState(value);
 }
 
@@ -31,12 +48,22 @@ export function state<T>(value: T): FlowState<T> {
  * 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);
+export function resource<T>(fn: () => Promise<T>): FlowResource<T> {
+    return new FlowResource(fn);
+}
+
+/**
+ * Creates a new reactive asynchronous resource that fetches its value.
+ * @typeparam T - The type of the resource value.
+ * @param fn - An asynchronous function that fetches the resource value.
+ * @returns A new instance of {@link FlowResourceAsync}.
+ * @public
+ */
+export function resourceAsync<T>(fn: () => Promise<T>): FlowResourceAsync<T> {
+    return new FlowResourceAsync(fn);
 }
 
 /**
@@ -44,15 +71,27 @@ export function resource<T>(fn: () => Promise<T>, initial: T): FlowResource<T> {
  * @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);
+    return new FlowStream(updater);
+}
+
+/**
+ * Creates a new reactive asynchronous 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.
+ * @returns A new instance of {@link FlowStreamAsync}.
+ * @public
+ */
+export function streamAsync<T>(
+    updater: (set: (value: T) => void) => () => void,
+): FlowStreamAsync<T> {
+    return new FlowStreamAsync(updater);
 }
 
 /**

package/src/index.ts

@@ -9,22 +9,32 @@
 export {
     signal,
     state,
+    constant,
     resource,
     stream,
     derivation,
     effect,
     map,
+    streamAsync,
+    resourceAsync,
 } 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 {
+    FlowDerivation,
+    FlowEffect,
+    FlowGetter,
+    FlowObservable,
+    FlowSignal,
+    FlowWatcher,
+    FlowState,
+    FlowConstant,
+} from "./basic/";
+export type {
+    FlowResource,
+    FlowMap,
+    FlowResourceAsync,
+    FlowStreamAsync,
     FlowStream,
-    FlowDisposer,
-    FlowSetter,
-    FlowUpdater,
-} from "./stream";
+    FlowStreamDisposer,
+    FlowStreamSetter,
+    FlowStreamUpdater,
+} from "./advanced/";

package/test/constant.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, test, vi } from "vitest";
+import { constant, effect } from "#package";
+
+describe("constant", () => {
+    test("is initialized", () => {
+        const $constant = constant(1);
+        expect($constant.get()).toBe(1);
+    });
+
+    test("is lazy initialized", () => {
+        const $constant = constant(() => 1);
+        expect($constant.get()).toBe(1);
+    });
+
+    test("get throws when disposed", () => {
+        const $constant = constant(1);
+
+        expect($constant.get()).toBe(1);
+
+        $constant.dispose();
+
+        expect(() => $constant.get()).toThrow(
+            "[PicoFlow] Primitive is disposed",
+        );
+    });
+});
+
+describe("effect", () => {
+    test("called with init value", () => {
+        const $constant = constant(1);
+        const effectFn = vi.fn();
+        effect((get) => effectFn(get($constant)));
+
+        expect(effectFn).toHaveBeenCalledTimes(1);
+        expect(effectFn).toHaveBeenLastCalledWith(1);
+    });
+
+    test("called with lazy init value", () => {
+        const $constant = constant(() => 1);
+        const effectFn = vi.fn();
+        effect((get) => effectFn(get($constant)));
+
+        expect(effectFn).toHaveBeenCalledTimes(1);
+        expect(effectFn).toHaveBeenLastCalledWith(1);
+    });
+});

package/test/derivation.test.ts

@@ -21,7 +21,9 @@ describe("derivation", () => {
             expect($derivation.get()).toBe(4);
 
             $derivation.dispose();
-            expect(() => $derivation.get()).toThrow("Effect is disposed");
+            expect(() => $derivation.get()).toThrow(
+                "[PicoFlow] Primitive is disposed",
+            );
         });
 
         test("get throws when state is disposed", () => {
@@ -33,7 +35,9 @@ describe("derivation", () => {
             expect($derivation.get()).toBe(4);
 
             $state.dispose();
-            expect(() => $derivation.get()).toThrow("Effect is disposed");
+            expect(() => $derivation.get()).toThrow(
+                "[PicoFlow] Primitive is disposed",
+            );
         });
 
         test("is updated (chained dependencies)", () => {
@@ -111,8 +115,8 @@ describe("derivation", () => {
                 resourceCounter++;
                 return resourceCounter;
             };
-            const $resource = resource(fetchResource, 0);
-            const $derivation = derivation((get) => get($resource) * 2);
+            const $resource = resource(fetchResource);
+            const $derivation = derivation((get) => (get($resource) ?? 0) * 2);
 
             expect($derivation.get()).toBe(0);
 
@@ -374,6 +378,26 @@ describe("effect", () => {
             expect(effectFn).toHaveBeenLastCalledWith(4);
         });
 
+        test("NOT called when derivation is disposed (watch)", () => {
+            const $state = state(1);
+            const $derivation = derivation((get) => get($state) * 2);
+            const effectFn = vi.fn();
+            effect((_, watch) => {
+                watch($derivation);
+                effectFn();
+            });
+
+            expect(effectFn).toHaveBeenCalledTimes(1);
+
+            $state.set(2);
+            expect(effectFn).toHaveBeenCalledTimes(2);
+
+            $derivation.dispose();
+
+            $state.set(3);
+            expect(effectFn).toHaveBeenCalledTimes(2);
+        });
+
         test("NOT called when disposed", () => {
             const $state = state(1);
             const $derivation = derivation((get) => get($state) * 2);
@@ -402,8 +426,8 @@ describe("effect", () => {
                 resourceCounter++;
                 return resourceCounter;
             };
-            const $resource = resource(fetchResource, 0);
-            const $derivation = derivation((get) => get($resource) * 2);
+            const $resource = resource(fetchResource);
+            const $derivation = derivation((get) => (get($resource) ?? 0) * 2);
             const effectFn = vi.fn();
             effect((get) => effectFn(get($derivation)));
 

package/test/effect.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, test, vi } from "vitest";
+import { effect, signal } from "#package";
+
+describe("effect", () => {
+    test("disposed is correct", () => {
+        const $signal = signal();
+        const effectFn = vi.fn();
+        const $effect = effect((_, watch) => {
+            watch($signal);
+            effectFn();
+        });
+
+        expect($effect.disposed).toBe(false);
+        $effect.dispose();
+        expect($effect.disposed).toBe(true);
+    });
+
+    test("throw when disposed twice", () => {
+        const $signal = signal();
+        const effectFn = vi.fn();
+        const $effect = effect((_, watch) => {
+            watch($signal);
+            effectFn();
+        });
+
+        $effect.dispose();
+        expect(() => $effect.dispose()).toThrow("Effect is disposed");
+    });
+});

package/test/map.test.ts

@@ -2,6 +2,20 @@ import { describe, expect, test, vi } from "vitest";
 import { effect, map } from "#package";
 
 describe("map", () => {
+    test("is initialized", () => {
+        const $map = map({
+            key1: 1,
+            key2: 2,
+            key3: 3,
+        });
+
+        expect(Array.from($map.get().entries())).toEqual([
+            ["key1", 1],
+            ["key2", 2],
+            ["key3", 3],
+        ]);
+    });
+
     test("is updated", () => {
         const $map = map();
 
@@ -26,6 +40,30 @@ describe("map", () => {
         expect($map.get().get("key2")).toBe(2);
         expect($map.$lastDeleted.get()).toEqual({ key: "key1", value: 3 });
     });
+
+    test("get throws when disposed", () => {
+        const $map = map({ key1: 1, key2: 2, key3: 3 });
+        $map.dispose();
+        expect(() => $map.get()).toThrowError(
+            "[PicoFlow] Primitive is disposed",
+        );
+    });
+
+    test("set throws when disposed", () => {
+        const $map = map<string, number>();
+        $map.dispose();
+        expect(() => $map.setAt("key1", 2)).toThrowError(
+            "[PicoFlow] Primitive is disposed",
+        );
+    });
+
+    test("delete throws when disposed", () => {
+        const $map = map<string, number>({ key1: 1, key2: 2, key3: 3 });
+        $map.dispose();
+        expect(() => $map.delete("key1")).toThrowError(
+            "[PicoFlow] Primitive is disposed",
+        );
+    });
 });
 
 describe("effect", () => {

package/test/resource.test.ts

@@ -9,8 +9,8 @@ describe("resource", () => {
             return resourceCounter;
         };
 
-        const $resource = resource(fetchResource, 0);
-        expect($resource.get()).toBe(0);
+        const $resource = resource(fetchResource);
+        expect($resource.get()).toBe(undefined);
 
         await $resource.fetch();
         expect($resource.get()).toBe(1);
@@ -26,15 +26,15 @@ describe("resource", () => {
             return resourceCounter;
         };
 
-        const $resource = resource(fetchResource, 0);
-        expect($resource.get()).toBe(0);
+        const $resource = resource(fetchResource);
+        expect($resource.get()).toBe(undefined);
 
         await $resource.fetch();
         expect($resource.get()).toBe(1);
 
         $resource.dispose();
         await expect(() => $resource.fetch()).rejects.toThrow(
-            "Resource is disposed",
+            "[PicoFlow] Primitive is disposed",
         );
     });
 
@@ -45,14 +45,16 @@ describe("resource", () => {
             return resourceCounter;
         };
 
-        const $resource = resource(fetchResource, 0);
-        expect($resource.get()).toBe(0);
+        const $resource = resource(fetchResource);
+        expect($resource.get()).toBe(undefined);
 
         await $resource.fetch();
         expect($resource.get()).toBe(1);
 
         $resource.dispose();
-        expect(() => $resource.get()).toThrow("Resource is disposed");
+        expect(() => $resource.get()).toThrow(
+            "[PicoFlow] Primitive is disposed",
+        );
     });
 });
 
@@ -64,12 +66,12 @@ describe("effect", () => {
             return resourceCounter;
         };
 
-        const $resource = resource(fetchResource, 0);
+        const $resource = resource(fetchResource);
         const effectFn = vi.fn();
         effect((get) => effectFn(get($resource)));
 
         expect(effectFn).toHaveBeenCalledTimes(1);
-        expect(effectFn).toHaveBeenLastCalledWith(0);
+        expect(effectFn).toHaveBeenLastCalledWith(undefined);
 
         await $resource.fetch();
         expect(effectFn).toHaveBeenCalledTimes(2);
@@ -85,19 +87,19 @@ describe("effect", () => {
             return 0;
         };
 
-        const $resource = resource(fetchResource, 0);
+        const $resource = resource(fetchResource);
         const effectFn = vi.fn();
         effect((get) => effectFn(get($resource)));
 
         expect(effectFn).toHaveBeenCalledTimes(1);
-        expect(effectFn).toHaveBeenLastCalledWith(0);
+        expect(effectFn).toHaveBeenLastCalledWith(undefined);
 
         await $resource.fetch();
-        expect(effectFn).toHaveBeenCalledTimes(1);
+        expect(effectFn).toHaveBeenCalledTimes(2);
         expect(effectFn).toHaveBeenLastCalledWith(0);
 
         await $resource.fetch();
-        expect(effectFn).toHaveBeenCalledTimes(1);
+        expect(effectFn).toHaveBeenCalledTimes(2);
         expect(effectFn).toHaveBeenLastCalledWith(0);
     });
 
@@ -108,12 +110,12 @@ describe("effect", () => {
             return resourceCounter;
         };
 
-        const $resource = resource(fetchResource, 0);
+        const $resource = resource(fetchResource);
         const effectFn = vi.fn();
         const $effect = effect((get) => effectFn(get($resource)));
 
         expect(effectFn).toHaveBeenCalledTimes(1);
-        expect(effectFn).toHaveBeenLastCalledWith(0);
+        expect(effectFn).toHaveBeenLastCalledWith(undefined);
 
         await $resource.fetch();
         expect(effectFn).toHaveBeenCalledTimes(2);