@ersbeth/picoflow 2.0.2 → 2.0.3

package/src/api/base/flowSubscribable.ts

@@ -1,87 +0,0 @@
-import type { FlowEffect } from "../nodes/flowEffect";
-import type { FlowTracker } from "./flowTracker";
-
-/**
- * Function that tracks reactive dependencies and returns data.
- *
- * This function is called during effect execution with a tracker parameter that automatically
- * records any reactive values accessed. The tracker enables automatic dependency tracking without
- * explicit subscriptions. The returned data is passed to the `onData` callback.
- *
- * @param t - Tracker object that records dependencies when reactive values are accessed
- * @returns The computed data of type T
- *
- * @public
- */
-export type FlowDataTracker<T> = (t: FlowTracker) => T;
-
-/**
- * Callback invoked when new data is available.
- *
- * This callback runs each time the effect executes successfully, receiving the data returned
- * by the tracker function. It's called immediately on effect creation and then on every reactive
- * re-execution. Use this callback to perform side effects with the computed data.
- *
- * @param data - The computed data from the tracker function
- * @returns Always returns undefined (callbacks are for side effects)
- *
- * @public
- */
-export type FlowOnDataListener<T> = (data: T) => void;
-
-/**
- * Callback invoked when an error occurs during effect execution.
- *
- * If provided, this callback handles any errors thrown by the tracker function (except PendingError).
- * Without this callback, errors propagate and may crash the application. Use this for error logging,
- * recovery, or user feedback. The effect remains active and will retry on the next reactive trigger.
- *
- * @param error - The error that occurred, always normalized to an Error instance
- * @returns Always returns undefined (callbacks are for side effects)
- *
- * @public
- */
-export type FlowOnErrorListener = (error: Error) => void;
-
-/**
- * Callback invoked when an async computation is pending.
- *
- * This callback is triggered when the tracker function throws a PendingError, indicating that
- * async dependencies are still resolving. Use this to show loading states or pending indicators.
- * The effect will automatically re-execute once the async values settle.
- *
- * @returns Always returns undefined (callbacks are for side effects)
- *
- * @public
- */
-export type FlowOnPendingListener = () => void;
-
-/**
- * Contract for observables that can be subscribed to with lifecycle callbacks.
- *
- * This interface enables imperative subscription to reactive values, allowing manual control over
- * when effects run. The subscribe method returns a disposal function to stop the subscription.
- * Useful for integrating with non-reactive code or frameworks that manage subscriptions differently.
- *
- * @public
- */
-export interface FlowSubscribable<T> {
-    /**
-     * Subscribes to this observable with lifecycle callbacks.
-     *
-     * Creates an active subscription that executes immediately and then re-executes whenever
-     * the observable's dependencies change. The subscription remains active until the returned
-     * disposal function is called. The `onData` callback receives the computed value, while
-     * `onError` handles errors and `onPending` signals async operations in progress.
-     *
-     * @param onData - Callback invoked with the computed data on each execution
-     * @param onError - Optional callback for handling errors during execution
-     * @param onPending - Optional callback invoked when async dependencies are pending
-     * @returns A function to dispose the subscription and stop receiving updates
-     */
-    subscribe(
-        onData: FlowOnDataListener<T>,
-        onError?: FlowOnErrorListener,
-        onPending?: FlowOnPendingListener,
-    ): FlowEffect;
-}

package/src/api/base/flowTracker.ts

@@ -1,7 +0,0 @@
-import type { FlowDisposable } from "./flowDisposable";
-
-/**
- * Contract for reactive computations that track dependencies and react to changes in the reactivity graph.
- * @public
- */
-export interface FlowTracker extends FlowDisposable {}

package/src/api/base/index.ts

@@ -1,4 +0,0 @@
-export * from "./flowDisposable";
-export * from "./flowObservable";
-export * from "./flowSubscribable";
-export * from "./flowTracker";

package/src/api/index.ts

@@ -1,2 +0,0 @@
-export * from "./base";
-export * from "./nodes";

package/src/api/nodes/async/flowConstantAsync.ts

@@ -1,36 +0,0 @@
-import { ValueAsyncNode } from "../../../nodes/valueAsyncNode";
-import type { FlowValue } from "../flowValue";
-
-/** Function that initializes a value asynchronously. */
-export type InitFunctionAsync<T> = () => Promise<T>;
-
-/**
- * Read-only reactive value that resolves once from a promise or async initializer.
- *
- * Async constants provide lazy initialization for asynchronous values. The promise or async initializer
- * runs once on first access, and the resolved value is cached forever. While pending, accessing the value
- * throws PendingError. Use for async operations that only need to run once, such as loading remote configuration,
- * fetching initial data, or computing expensive async resources.
- *
- * @public
- */
-export interface FlowConstantAsync<T> extends FlowValue<T> {}
-
-/**
- * Creates a constant reactive value from a promise or async initializer that resolves once and never recomputes.
- *
- * The promise or async initializer executes once on first access, and the resolved value is cached permanently.
- * While the promise is pending, any reactive computation that accesses the value will receive PendingError and
- * automatically retry once the promise resolves. Use for one-time async operations that don't depend on other
- * reactive values, such as loading configuration or fetching initial data.
- *
- * @param value - Promise to resolve, or async function that returns a promise on first access
- * @returns A FlowConstantAsync that provides read-only access to the resolved value
- *
- * @public
- */
-export function constantAsync<T>(value: Promise<T>): FlowConstantAsync<T>;
-export function constantAsync<T>(initializer: InitFunctionAsync<T>): FlowConstantAsync<T>;
-export function constantAsync<T>(valueOrInitializer: Promise<T> | InitFunctionAsync<T>): FlowConstantAsync<T> {
-    return new ValueAsyncNode(valueOrInitializer);
-}

package/src/api/nodes/async/flowDerivationAsync.ts

@@ -1,42 +0,0 @@
-import { ValueAsyncNode } from "../../../nodes/valueAsyncNode";
-import type { FlowTracker } from "../../base";
-import type { FlowValue } from "../flowValue";
-import type { NotPromise } from "../utils";
-
-/** Function that derives a value asynchronously from dependencies and optionally the previous value. */
-export type DerivationFunctionAsync<T> = (tracker: FlowTracker, previous?: NotPromise<T> | undefined) => Promise<T>;
-
-/**
- * Read-only reactive value that recomputes asynchronously when dependencies change.
- *
- * Async derivations track reactive values accessed during computation and automatically recompute when any
- * tracked dependency changes. The compute function returns a promise, and the resolved value is cached until
- * dependencies change. While recomputing, accessing the value throws PendingError. Use for values derived from
- * async operations like API calls, database queries, or any computation that depends on reactive state and
- * requires async work.
- *
- * @public
- */
-export interface FlowDerivationAsync<T> extends FlowValue<T> {
-    /**
-     * Forces the derivation to recompute even if dependencies haven't changed.
-     */
-    refresh(): void;
-}
-
-/**
- * Creates an async derived value that automatically recomputes when dependencies change.
- *
- * The async compute function tracks dependencies and returns a promise. When any tracked dependency changes,
- * the function runs again and returns a new promise. The resolved value is cached until the next change.
- * While the promise is pending, reactive computations that access this value receive PendingError and automatically
- * retry once resolved. Use for derived data from async sources like filtered API results or computed database queries.
- *
- * @param compute - Async function that accesses dependencies and returns a promise of the derived value
- * @returns A FlowDerivationAsync that provides read-only access to the resolved computed value
- *
- * @public
- */
-export function derivationAsync<T>(compute: DerivationFunctionAsync<T>): FlowDerivationAsync<T> {
-    return new ValueAsyncNode(compute);
-}

package/src/api/nodes/async/flowStateAsync.ts

@@ -1,47 +0,0 @@
-import { ValueAsyncNode } from "../../../nodes/valueAsyncNode";
-import type { FlowValue } from "../flowValue";
-import type { NotPromise } from "../utils";
-import type { InitFunctionAsync } from "./flowConstantAsync";
-
-/** Function that updates a value asynchronously based on the previous value. */
-export type UpdateFunctionAsync<T> = (previous: NotPromise<T> | undefined) => Promise<T>;
-
-/**
- * Writable reactive value that resolves promises and can be updated with new promises.
- *
- * Async state is the async equivalent of regular state. Unlike sync state, it accepts promises instead of
- * direct values. Set new promises or async updater functions to update the state. While a promise is pending,
- * accessing the value throws PendingError. Use for async data that changes imperatively, such as user-triggered
- * API calls, async form submissions, or any async operation that updates based on user actions.
- *
- * @public
- */
-export interface FlowStateAsync<T> extends FlowValue<T> {
-    /**
-     * Updates the state with a new promise or via an async updater function.
-     * Notifies all dependents immediately (they will receive PendingError until resolved).
-     *
-     * @param promise - New promise to resolve, or async function that receives current value and returns a promise
-     */
-    set(promise: Promise<T>): void;
-    set(updater: UpdateFunctionAsync<T>): void;
-}
-
-/**
- * Creates a mutable async reactive state that resolves promises and can be updated imperatively.
- *
- * State can be initialized with a direct promise or a lazy async initializer function. Update the state by
- * calling `set()` with a new promise or an async updater function. Changes propagate automatically to all
- * reactive computations that depend on this state. Use for async data that changes through user actions or
- * application logic, such as loading user profiles, fetching search results, or any async state updates.
- *
- * @param value - Initial promise to resolve, or lazy async initializer function
- * @returns A FlowStateAsync that can be read and modified with promises
- *
- * @public
- */
-export function stateAsync<T>(value: Promise<T>): FlowStateAsync<T>;
-export function stateAsync<T>(initializer: InitFunctionAsync<T>): FlowStateAsync<T>;
-export function stateAsync<T>(valueOrInitializer: Promise<T> | InitFunctionAsync<T>): FlowStateAsync<T> {
-    return new ValueAsyncNode(valueOrInitializer);
-}

package/src/api/nodes/async/flowWritableDerivationAsync.ts

@@ -1,33 +0,0 @@
-import { ValueAsyncNode } from "../../../nodes/valueAsyncNode";
-import type { DerivationFunctionAsync, FlowDerivationAsync } from "./flowDerivationAsync";
-import type { FlowStateAsync } from "./flowStateAsync";
-
-/**
- * Writable reactive value that recomputes asynchronously when dependencies change, but can be manually overridden.
- *
- * Async writable derivations combine reactive async computation with manual control. They track dependencies and
- * recompute asynchronously like regular async derivations, but you can also call `set()` to override the computed
- * value with a new promise. While recomputing or pending, accessing the value throws PendingError. Use for computed
- * async values that users can edit, such as formatted async fields, calculated async totals that can be adjusted,
- * or any async value that is usually derived but sometimes needs manual correction.
- *
- * @public
- */
-export interface FlowWritableDerivationAsync<T> extends FlowStateAsync<T>, FlowDerivationAsync<T> {}
-
-/**
- * Creates an async derived value that recomputes automatically but can also be manually overridden.
- *
- * The async compute function tracks dependencies and returns a promise. When any tracked dependency changes,
- * the function runs again and returns a new promise. However, you can also call `set()` to override the computed
- * value with a new promise. Use for async values that are normally derived but need occasional manual adjustments,
- * such as editable async calculated fields or user-correctable async totals.
- *
- * @param compute - Async function that accesses dependencies and returns a promise of the derived value
- * @returns A FlowWritableDerivationAsync that provides both reactive async computation and manual control
- *
- * @public
- */
-export function writableDerivationAsync<T>(compute: DerivationFunctionAsync<T>): FlowWritableDerivationAsync<T> {
-    return new ValueAsyncNode(compute);
-}

package/src/api/nodes/async/index.ts

@@ -1,4 +0,0 @@
-export * from "./flowConstantAsync";
-export * from "./flowDerivationAsync";
-export * from "./flowStateAsync";
-export * from "./flowWritableDerivationAsync";

package/src/api/nodes/collections/flowArray.ts

@@ -1,155 +0,0 @@
-import { ArrayNode } from "../../../nodes/arrayNode";
-import type { FlowState } from "../sync/flowState";
-
-/**
- * Discriminated union representing all possible array mutation operations.
- *
- * Each mutation on a FlowArray emits an action describing what changed. This enables fine-grained
- * reactive tracking - you can observe the array itself or subscribe to `$lastAction` to react only
- * to specific mutations. Use this for optimized rendering, undo/redo systems, or any scenario where
- * you need to know exactly what changed rather than just that something changed.
- *
- * @public
- */
-export type FlowArrayAction<T> =
-    | {
-          type: "set";
-          setItems: T[];
-          clearedItems: T[];
-      }
-    | {
-          type: "update";
-          index: number;
-          setItem: T;
-          clearedItem: T | undefined;
-      }
-    | {
-          type: "push";
-          addedItem: T;
-      }
-    | {
-          type: "pop";
-          removedItem: T | undefined;
-      }
-    | {
-          type: "unshift";
-          addedItem: T;
-      }
-    | {
-          type: "shift";
-          removedItem: T | undefined;
-      }
-    | {
-          type: "splice";
-          start: number;
-          deleteCount: number;
-          addedItems: T[];
-          removedItems: T[];
-      }
-    | {
-          type: "clear";
-          clearedItems: T[];
-      };
-
-/**
- * Reactive array with standard mutation methods and fine-grained change tracking.
- *
- * FlowArray behaves like a regular array but notifies dependents on mutations. It provides all standard
- * array mutation methods (push, pop, splice, etc.) and tracks each operation via the `$lastAction` signal.
- * This enables both coarse-grained reactivity (reacting to any change) and fine-grained reactivity (reacting
- * only to specific mutations). Use for lists that need reactive updates, such as todo lists, data tables,
- * or any collection that changes over time.
- *
- * @public
- */
-export interface FlowArray<T> extends FlowState<T[]> {
-    /**
-     * Replaces an item at a specific index.
-     * Emits an "update" action to $lastAction.
-     *
-     * @param index - The index of the item to replace
-     * @param item - The new item
-     * @returns The previous item at that index
-     */
-    update(index: number, item: T): T | undefined;
-
-    /**
-     * Appends an item to the end of the array.
-     * Emits a "push" action to $lastAction.
-     *
-     * @param item - The item to append
-     */
-    push(item: T): void;
-
-    /**
-     * Removes and returns the last item from the array.
-     * Emits a "pop" action to $lastAction.
-     *
-     * @returns The removed item, or undefined if the array was empty
-     */
-    pop(): T | undefined;
-
-    /**
-     * Inserts an item at the beginning of the array.
-     * Emits an "unshift" action to $lastAction.
-     *
-     * @param item - The item to insert
-     */
-    unshift(item: T): void;
-
-    /**
-     * Removes and returns the first item from the array.
-     * Emits a "shift" action to $lastAction.
-     *
-     * @returns The removed item, or undefined if the array was empty
-     */
-    shift(): T | undefined;
-
-    /**
-     * Changes the content of the array by removing, replacing, or adding items.
-     * Emits a "splice" action to $lastAction.
-     *
-     * @param start - The starting index
-     * @param deleteCount - Number of items to remove
-     * @param newItems - New items to add at the start position
-     * @returns Array of removed items
-     */
-    splice(start: number, deleteCount: number, ...newItems: T[]): T[];
-
-    /**
-     * Removes all items from the array.
-     * Emits a "clear" action to $lastAction.
-     *
-     * @returns Array of all removed items
-     */
-    clear(): T[];
-
-    /**
-     * The current length of the array.
-     */
-    length: number;
-
-    /**
-     * Reactive state containing the last mutation operation performed on the array.
-     * Subscribe to this for fine-grained reactivity to specific mutation types.
-     */
-    $lastAction: FlowState<FlowArrayAction<T>>;
-}
-
-/**
- * Creates a reactive array with mutation methods and fine-grained action tracking.
- *
- * The array starts with the provided initial items (or empty if none provided). All mutation methods
- * (push, pop, splice, etc.) notify dependents and emit detailed action information to `$lastAction`.
- * Use the array itself for coarse-grained reactivity, or subscribe to `$lastAction` for fine-grained
- * reactivity to specific mutation types. Useful for reactive lists, collections, or any data that
- * needs array-like operations with automatic change propagation.
- *
- * @param initial - Optional initial array of items
- * @returns A FlowArray with reactive mutation methods
- *
- * @public
- */
-export function array<T>(initial?: T[]): FlowArray<T> {
-    return new ArrayNode<T>(initial);
-}

package/src/api/nodes/collections/flowMap.ts

@@ -1,115 +0,0 @@
-import { MapNode } from "../../../nodes/mapNode";
-import type { FlowState } from "../sync/flowState";
-
-/**
- * Discriminated union representing all possible map mutation operations.
- *
- * Each mutation on a FlowMap emits an action describing what changed. This enables fine-grained
- * reactive tracking - you can observe the map itself or subscribe to `$lastAction` to react only
- * to specific mutations. Use this for optimized updates, undo/redo systems, or any scenario where
- * you need to know exactly what changed rather than just that something changed.
- *
- * @public
- */
-export type FlowMapAction<K, V> =
-    | {
-          type: "set";
-          setMap: Map<K, V>;
-          clearedMap: Map<K, V>;
-      }
-    | {
-          type: "add";
-          key: K;
-          addedValue: V;
-      }
-    | {
-          type: "update";
-          key: K;
-          setValue: V;
-          clearedValue: V;
-      }
-    | {
-          type: "delete";
-          key: K;
-          removedValue: V;
-      }
-    | {
-          type: "clear";
-          clearedMap: Map<K, V>;
-      };
-
-/**
- * Reactive map with standard mutation methods and fine-grained change tracking.
- *
- * FlowMap behaves like a regular Map but notifies dependents on mutations. It provides standard
- * map operations (add, update, delete) and tracks each operation via the `$lastAction` signal.
- * This enables both coarse-grained reactivity (reacting to any change) and fine-grained reactivity
- * (reacting only to specific mutations). Use for key-value collections that need reactive updates,
- * such as entity stores, lookup tables, or any map-based data that changes over time.
- *
- * @public
- */
-export interface FlowMap<K, V> extends FlowState<Map<K, V>> {
-    /**
-     * Removes a key-value pair from the map.
-     * Emits a "delete" action to $lastAction.
-     *
-     * @param key - The key to delete
-     * @returns The deleted value
-     */
-    delete(key: K): V;
-
-    /**
-     * Updates an existing key-value pair in the map.
-     * Emits an "update" action to $lastAction.
-     *
-     * @param key - The key to update (must exist)
-     * @param value - The new value
-     * @returns The previous value
-     */
-    update(key: K, value: V): V | undefined;
-
-    /**
-     * Adds a new key-value pair to the map.
-     * Emits an "add" action to $lastAction.
-     *
-     * @param key - The key to add (must not exist)
-     * @param value - The value to associate with the key
-     */
-    add(key: K, value: V): void;
-
-    /**
-     * Removes all entries from the map.
-     * Emits a "clear" action to $lastAction.
-     *
-     * @returns Map of all removed entries
-     */
-    clear(): Map<K, V>;
-
-    /**
-     * Reactive state containing the last mutation operation performed on the map.
-     * Subscribe to this for fine-grained reactivity to specific mutation types.
-     */
-    $lastAction: FlowState<FlowMapAction<K, V>>;
-}
-
-/**
- * Creates a reactive map with mutation methods and fine-grained action tracking.
- *
- * The map starts with the provided initial entries (or empty if none provided). All mutation methods
- * (add, update, delete) notify dependents and emit detailed action information to `$lastAction`.
- * Use the map itself for coarse-grained reactivity, or subscribe to `$lastAction` for fine-grained
- * reactivity to specific mutation types. Useful for entity stores, lookup tables, or any key-value
- * data that needs reactive updates.
- *
- * @param initial - Optional initial entries as a Record or Map
- * @returns A FlowMap with reactive mutation methods
- *
- * @public
- */
-export function map<K extends string | number | symbol, V>(initial?: Record<K, V> | Map<K, V>): FlowMap<K, V> {
-    if (initial instanceof Map) {
-        return new MapNode<K, V>(initial);
-    }
-    return new MapNode<K, V>(new Map<K, V>(initial ? (Object.entries(initial) as [K, V][]) : []));
-}

package/src/api/nodes/collections/index.ts

@@ -1,2 +0,0 @@
-export * from "./flowArray";
-export * from "./flowMap";

package/src/api/nodes/flowEffect.ts

@@ -1,42 +0,0 @@
-import { EffectNode } from "../../nodes/effectNode";
-import type { FlowDisposable } from "../base/flowDisposable";
-import type {
-    FlowDataTracker,
-    FlowOnDataListener,
-    FlowOnErrorListener,
-    FlowOnPendingListener,
-} from "../base/flowSubscribable";
-
-/**
- * Handle to a reactive effect that automatically tracks dependencies and re-executes when they change.
- *
- * Effects run immediately upon creation and then reactively respond to changes in any reactive values
- * accessed during execution. Call `dispose()` to stop the effect and clean up its subscriptions.
- *
- * @public
- */
-export interface FlowEffect extends FlowDisposable {}
-
-/**
- * Creates a reactive effect that runs immediately and automatically re-runs when dependencies change.
- *
- * The effect function tracks any reactive values accessed and subscribes to their changes.
- * When any tracked value changes, the effect re-executes with the new values.
- * Optional callbacks handle errors and pending async states.
- *
- * @param data - Function that accesses reactive dependencies and returns data
- * @param onData - Callback invoked with the computed data on each execution
- * @param onError - Optional callback for handling errors during execution
- * @param onPending - Optional callback invoked when async dependencies are pending
- * @returns A FlowEffect handle with a `dispose()` method to stop the effect
- *
- * @public
- */
-export function subscribe<T>(
-    data: FlowDataTracker<T>,
-    onData: FlowOnDataListener<T>,
-    onError?: FlowOnErrorListener,
-    onPending?: FlowOnPendingListener,
-): FlowEffect {
-    return new EffectNode(data, onData, onError, onPending);
-}

package/src/api/nodes/flowSignal.ts

@@ -1,28 +0,0 @@
-import { SignalNode } from "../../nodes/signalNode";
-import type { FlowObservable } from "../base/flowObservable";
-
-/**
- * Manual trigger that notifies subscribers without carrying data.
- *
- * Unlike reactive state or derivations, signals don't hold values. They serve as event emitters
- * that notify dependents when explicitly triggered. Use signals for side effects that should run
- * in response to manual actions rather than data changes.
- *
- * @public
- */
-export interface FlowSignal extends FlowObservable<void> {}
-
-/**
- * Creates a signal that can be manually triggered to notify dependents.
- *
- * Signals act as event emitters in the reactive graph. Call `trigger()` to notify all subscribers
- * and reactive computations that depend on the signal. Unlike state or derivations, signals don't
- * carry data values - they simply represent that an event occurred.
- *
- * @returns A FlowSignal that can be triggered manually and subscribed to
- *
- * @public
- */
-export function signal(): FlowSignal {
-    return new SignalNode();
-}

package/src/api/nodes/flowValue.ts

@@ -1,37 +0,0 @@
-import type { FlowObservable } from "../base/flowObservable";
-import type { FlowTracker } from "../base/flowTracker";
-
-/**
- * Base interface for reactive values that can be read synchronously or asynchronously.
- *
- * FlowValue extends FlowObservable with methods to access the current value. Use `get()` to read
- * the value reactively (establishing a dependency), or `pick()` to read it non-reactively. All
- * value-based primitives (state, derivation, constant, and their async variants) implement this
- * interface, providing a consistent API for value access across the reactive system.
- *
- * @public
- */
-export interface FlowValue<T> extends FlowObservable<T> {
-    /**
-     * Gets the current value and establishes a reactive dependency.
-     *
-     * When called from within a reactive computation, this method registers the value as a dependency,
-     * ensuring the computation re-executes when the value changes. The value is computed on first access
-     * (if lazy) and then cached. For async values, throws PendingError while the value is resolving.
-     *
-     * @param tracker - Tracker that records this value as a dependency
-     * @returns The current value
-     */
-    get(tracker: FlowTracker): T;
-
-    /**
-     * Asynchronously gets the current value without establishing a reactive dependency.
-     *
-     * This method reads the value non-reactively, meaning it won't trigger re-execution of the calling
-     * computation when the value changes. The value is computed on first access (if lazy) and then cached.
-     * For async values, the promise resolves once the value is available.
-     *
-     * @returns Promise that resolves with the current value
-     */
-    pick(): Promise<T>;
-}

package/src/api/nodes/index.ts

@@ -1,7 +0,0 @@
-export * from "./async";
-export * from "./collections";
-export * from "./flowEffect";
-export * from "./flowSignal";
-export * from "./flowValue";
-export * from "./sync";
-export * from "./utils";