@ersbeth/picoflow 1.1.2 → 2.0.0

package/dist/types/api/base/flowDisposable.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Contract for resources that can be explicitly released to prevent memory leaks.
+ *
+ * All reactive primitives in PicoFlow implement this interface, allowing manual cleanup of subscriptions
+ * and dependencies. Once disposed, the resource cannot be reused and will throw errors on further access.
+ * Call `dispose()` when you no longer need a reactive primitive to free its resources.
+ *
+ * @public
+ */
+export interface FlowDisposable {
+    /**
+     * Indicates whether this resource has been disposed.
+     *
+     * Returns `true` if `dispose()` has been called, `false` otherwise. Once disposed,
+     * the resource is no longer usable and any operations on it will throw errors.
+     */
+    get disposed(): boolean;
+    /**
+     * Releases all resources held by this disposable object.
+     *
+     * Cleans up all subscriptions, dependencies, and internal state. After calling this method,
+     * the resource enters a disposed state and cannot be reused. Any subsequent operations will
+     * throw errors. This method should be called when you no longer need the reactive primitive
+     * to prevent memory leaks.
+     */
+    dispose(): void;
+}
+/**
+ * Type guard to check if an object implements the FlowDisposable interface.
+ *
+ * Useful for conditionally disposing objects that may or may not be disposable,
+ * such as when cleaning up mixed collections of values. Returns true if the object
+ * has a `dispose` method, providing type-safe access to disposal functionality.
+ *
+ * @param obj - The object to check
+ * @returns True if the object implements FlowDisposable, false otherwise
+ *
+ * @public
+ */
+export declare function isDisposable(obj: unknown): obj is FlowDisposable;
+//# sourceMappingURL=flowDisposable.d.ts.map

package/dist/types/api/base/flowDisposable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flowDisposable.d.ts","sourceRoot":"","sources":["../../../../src/api/base/flowDisposable.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAc;IAC3B;;;;;OAKG;IACH,IAAI,QAAQ,IAAI,OAAO,CAAC;IAExB;;;;;;;OAOG;IACH,OAAO,IAAI,IAAI,CAAC;CACnB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,cAAc,CAEhE"}

package/dist/types/api/base/flowObservable.d.ts

@@ -0,0 +1,27 @@
+import { FlowDisposable } from './flowDisposable';
+import { FlowSubscribable } from './flowSubscribable';
+import { FlowTracker } from './flowTracker';
+/**
+ * Contract for reactive primitives that emit changes and notify their dependents in the reactivity graph.
+ * @public
+ */
+export interface FlowObservable<T> extends FlowDisposable, FlowSubscribable<T> {
+    /**
+     * Establishes a reactive dependency without reading the value.
+     *
+     * Registers this observable as a dependency of the given tracker, allowing it to be notified
+     * when changes occur. This enables dependency tracking without accessing the actual value.
+     *
+     * @param tracker - Tracker that records this observable as a dependency
+     */
+    watch(tracker: FlowTracker): void;
+    /**
+     * Manually triggers notifications to all dependents.
+     *
+     * Forces all dependents of this observable to be notified and re-executed, even if the
+     * value hasn't actually changed. Useful for imperatively triggering updates when the
+     * reactive system cannot detect changes automatically.
+     */
+    trigger(): void;
+}
+//# sourceMappingURL=flowObservable.d.ts.map

package/dist/types/api/base/flowObservable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flowObservable.d.ts","sourceRoot":"","sources":["../../../../src/api/base/flowObservable.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAEjD;;;GAGG;AACH,MAAM,WAAW,cAAc,CAAC,CAAC,CAAE,SAAQ,cAAc,EAAE,gBAAgB,CAAC,CAAC,CAAC;IAC1E;;;;;;;OAOG;IACH,KAAK,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,CAAC;IAElC;;;;;;OAMG;IACH,OAAO,IAAI,IAAI,CAAC;CACnB"}

package/dist/types/api/base/flowSubscribable.d.ts

@@ -0,0 +1,79 @@
+import { FlowEffect } from '../nodes';
+import { 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) => undefined;
+/**
+ * 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) => undefined;
+/**
+ * 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 = () => undefined;
+/**
+ * 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;
+}
+//# sourceMappingURL=flowSubscribable.d.ts.map

package/dist/types/api/base/flowSubscribable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flowSubscribable.d.ts","sourceRoot":"","sources":["../../../../src/api/base/flowSubscribable.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAC3C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAEjD;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,eAAe,CAAC,CAAC,IAAI,CAAC,CAAC,EAAE,WAAW,KAAK,CAAC,CAAC;AAEvD;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,kBAAkB,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,KAAK,SAAS,CAAC;AAE3D;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,KAAK,EAAE,KAAK,KAAK,SAAS,CAAC;AAE9D;;;;;;;;;;GAUG;AACH,MAAM,MAAM,qBAAqB,GAAG,MAAM,SAAS,CAAC;AAEpD;;;;;;;;GAQG;AACH,MAAM,WAAW,gBAAgB,CAAC,CAAC;IAC/B;;;;;;;;;;;;OAYG;IACH,SAAS,CACL,MAAM,EAAE,kBAAkB,CAAC,CAAC,CAAC,EAC7B,OAAO,CAAC,EAAE,mBAAmB,EAC7B,SAAS,CAAC,EAAE,qBAAqB,GAClC,UAAU,CAAC;CACjB"}

package/dist/types/api/base/flowTracker.d.ts

@@ -0,0 +1,8 @@
+import { FlowDisposable } from './flowDisposable';
+/**
+ * Contract for reactive computations that track dependencies and react to changes in the reactivity graph.
+ * @public
+ */
+export interface FlowTracker extends FlowDisposable {
+}
+//# sourceMappingURL=flowTracker.d.ts.map

package/dist/types/api/base/flowTracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flowTracker.d.ts","sourceRoot":"","sources":["../../../../src/api/base/flowTracker.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEvD;;;GAGG;AACH,MAAM,WAAW,WAAY,SAAQ,cAAc;CAAG"}

package/dist/types/api/base/index.d.ts

@@ -0,0 +1,5 @@
+export * from './flowDisposable';
+export * from './flowObservable';
+export * from './flowSubscribable';
+export * from './flowTracker';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/api/base/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,eAAe,CAAC"}

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

@@ -0,0 +1,3 @@
+export * from './base';
+export * from './nodes';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/api/index.ts"],"names":[],"mappings":"AAAA,cAAc,QAAQ,CAAC;AACvB,cAAc,SAAS,CAAC"}

package/dist/types/api/nodes/async/flowConstantAsync.d.ts

@@ -0,0 +1,31 @@
+import { 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 declare function constantAsync<T>(value: Promise<T>): FlowConstantAsync<T>;
+export declare function constantAsync<T>(initializer: InitFunctionAsync<T>): FlowConstantAsync<T>;
+//# sourceMappingURL=flowConstantAsync.d.ts.map

package/dist/types/api/nodes/async/flowConstantAsync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flowConstantAsync.d.ts","sourceRoot":"","sources":["../../../../../src/api/nodes/async/flowConstantAsync.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE9C,wDAAwD;AACxD,MAAM,MAAM,iBAAiB,CAAC,CAAC,IAAI,MAAM,OAAO,CAAC,CAAC,CAAC,CAAC;AAEpD;;;;;;;;;GASG;AACH,MAAM,WAAW,iBAAiB,CAAC,CAAC,CAAE,SAAQ,SAAS,CAAC,CAAC,CAAC;CAAG;AAE7D;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,iBAAiB,CAAC,CAAC,CAAC,CAAC;AAC1E,wBAAgB,aAAa,CAAC,CAAC,EAAE,WAAW,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAAG,iBAAiB,CAAC,CAAC,CAAC,CAAC"}

package/dist/types/api/nodes/async/flowDerivationAsync.d.ts

@@ -0,0 +1,37 @@
+import { FlowTracker } from '../../../../api/base';
+import { FlowValue } from '../flowValue';
+import { 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 declare function derivationAsync<T>(compute: DerivationFunctionAsync<T>): FlowDerivationAsync<T>;
+//# sourceMappingURL=flowDerivationAsync.d.ts.map

package/dist/types/api/nodes/async/flowDerivationAsync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flowDerivationAsync.d.ts","sourceRoot":"","sources":["../../../../../src/api/nodes/async/flowDerivationAsync.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAE3C,wGAAwG;AACxG,MAAM,MAAM,uBAAuB,CAAC,CAAC,IAAI,CAAC,OAAO,EAAE,WAAW,EAAE,QAAQ,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,SAAS,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;AAEpH;;;;;;;;;;GAUG;AACH,MAAM,WAAW,mBAAmB,CAAC,CAAC,CAAE,SAAQ,SAAS,CAAC,CAAC,CAAC;IACxD;;OAEG;IACH,OAAO,IAAI,IAAI,CAAC;CACnB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,OAAO,EAAE,uBAAuB,CAAC,CAAC,CAAC,GAAG,mBAAmB,CAAC,CAAC,CAAC,CAE9F"}

package/dist/types/api/nodes/async/flowStateAsync.d.ts

@@ -0,0 +1,41 @@
+import { FlowValue } from '../flowValue';
+import { NotPromise } from '../utils';
+import { 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 declare function stateAsync<T>(value: Promise<T>): FlowStateAsync<T>;
+export declare function stateAsync<T>(initializer: InitFunctionAsync<T>): FlowStateAsync<T>;
+//# sourceMappingURL=flowStateAsync.d.ts.map

package/dist/types/api/nodes/async/flowStateAsync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flowStateAsync.d.ts","sourceRoot":"","sources":["../../../../../src/api/nodes/async/flowStateAsync.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAC3C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAE7D,gFAAgF;AAChF,MAAM,MAAM,mBAAmB,CAAC,CAAC,IAAI,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,SAAS,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;AAEzF;;;;;;;;;GASG;AACH,MAAM,WAAW,cAAc,CAAC,CAAC,CAAE,SAAQ,SAAS,CAAC,CAAC,CAAC;IACnD;;;;;OAKG;IACH,GAAG,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAC/B,GAAG,CAAC,OAAO,EAAE,mBAAmB,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;CAC9C;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,CAAC;AACpE,wBAAgB,UAAU,CAAC,CAAC,EAAE,WAAW,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,CAAC"}

package/dist/types/api/nodes/async/flowWritableDerivationAsync.d.ts

@@ -0,0 +1,30 @@
+import { DerivationFunctionAsync, FlowDerivationAsync } from './flowDerivationAsync';
+import { 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 declare function writableDerivationAsync<T>(compute: DerivationFunctionAsync<T>): FlowWritableDerivationAsync<T>;
+//# sourceMappingURL=flowWritableDerivationAsync.d.ts.map

package/dist/types/api/nodes/async/flowWritableDerivationAsync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flowWritableDerivationAsync.d.ts","sourceRoot":"","sources":["../../../../../src/api/nodes/async/flowWritableDerivationAsync.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,uBAAuB,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC1F,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEvD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,2BAA2B,CAAC,CAAC,CAAE,SAAQ,cAAc,CAAC,CAAC,CAAC,EAAE,mBAAmB,CAAC,CAAC,CAAC;CAAG;AAEpG;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,EAAE,OAAO,EAAE,uBAAuB,CAAC,CAAC,CAAC,GAAG,2BAA2B,CAAC,CAAC,CAAC,CAE9G"}

package/dist/types/{flow → api}/nodes/async/index.d.ts

@@ -1,6 +1,5 @@
 export * from './flowConstantAsync';
 export * from './flowDerivationAsync';
-export * from './flowNodeAsync';
-export * from './flowReadonlyAsync';
 export * from './flowStateAsync';
+export * from './flowWritableDerivationAsync';
 //# sourceMappingURL=index.d.ts.map

package/dist/types/api/nodes/async/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/api/nodes/async/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,kBAAkB,CAAC;AACjC,cAAc,+BAA+B,CAAC"}

package/dist/types/api/nodes/collections/flowArray.d.ts

@@ -0,0 +1,134 @@
+import { 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 declare function array<T>(initial?: T[]): FlowArray<T>;
+//# sourceMappingURL=flowArray.d.ts.map

package/dist/types/api/nodes/collections/flowArray.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flowArray.d.ts","sourceRoot":"","sources":["../../../../../src/api/nodes/collections/flowArray.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAEnD;;;;;;;;;GASG;AACH,MAAM,MAAM,eAAe,CAAC,CAAC,IACvB;IACI,IAAI,EAAE,KAAK,CAAC;IACZ,QAAQ,EAAE,CAAC,EAAE,CAAC;IACd,YAAY,EAAE,CAAC,EAAE,CAAC;CACrB,GACD;IACI,IAAI,EAAE,QAAQ,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,CAAC,CAAC;IACX,WAAW,EAAE,CAAC,GAAG,SAAS,CAAC;CAC9B,GACD;IACI,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,CAAC,CAAC;CAChB,GACD;IACI,IAAI,EAAE,KAAK,CAAC;IACZ,WAAW,EAAE,CAAC,GAAG,SAAS,CAAC;CAC9B,GACD;IACI,IAAI,EAAE,SAAS,CAAC;IAChB,SAAS,EAAE,CAAC,CAAC;CAChB,GACD;IACI,IAAI,EAAE,OAAO,CAAC;IACd,WAAW,EAAE,CAAC,GAAG,SAAS,CAAC;CAC9B,GACD;IACI,IAAI,EAAE,QAAQ,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,CAAC,EAAE,CAAC;IAChB,YAAY,EAAE,CAAC,EAAE,CAAC;CACrB,GACD;IACI,IAAI,EAAE,OAAO,CAAC;IACd,YAAY,EAAE,CAAC,EAAE,CAAC;CACrB,CAAC;AAER;;;;;;;;;;GAUG;AACH,MAAM,WAAW,SAAS,CAAC,CAAC,CAAE,SAAQ,SAAS,CAAC,CAAC,EAAE,CAAC;IAChD;;;;;;;OAOG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,GAAG,SAAS,CAAC;IAE9C;;;;;OAKG;IACH,IAAI,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC;IAEpB;;;;;OAKG;IACH,GAAG,IAAI,CAAC,GAAG,SAAS,CAAC;IAErB;;;;;OAKG;IACH,OAAO,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC;IAEvB;;;;;OAKG;IACH,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC;IAEvB;;;;;;;;OAQG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,QAAQ,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC;IAElE;;;;;OAKG;IACH,KAAK,IAAI,CAAC,EAAE,CAAC;IAEb;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,WAAW,EAAE,SAAS,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC;CAC9C;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,CAAC,EAAE,GAAG,SAAS,CAAC,CAAC,CAAC,CAEpD"}

package/dist/types/api/nodes/collections/flowMap.d.ts

@@ -0,0 +1,98 @@
+import { 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 declare function map<K extends string | number | symbol, V>(initial?: Record<K, V> | Map<K, V>): FlowMap<K, V>;
+//# sourceMappingURL=flowMap.d.ts.map

package/dist/types/api/nodes/collections/flowMap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flowMap.d.ts","sourceRoot":"","sources":["../../../../../src/api/nodes/collections/flowMap.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAEnD;;;;;;;;;GASG;AACH,MAAM,MAAM,aAAa,CAAC,CAAC,EAAE,CAAC,IACxB;IACI,IAAI,EAAE,KAAK,CAAC;IACZ,MAAM,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAClB,UAAU,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;CACzB,GACD;IACI,IAAI,EAAE,KAAK,CAAC;IACZ,GAAG,EAAE,CAAC,CAAC;IACP,UAAU,EAAE,CAAC,CAAC;CACjB,GACD;IACI,IAAI,EAAE,QAAQ,CAAC;IACf,GAAG,EAAE,CAAC,CAAC;IACP,QAAQ,EAAE,CAAC,CAAC;IACZ,YAAY,EAAE,CAAC,CAAC;CACnB,GACD;IACI,IAAI,EAAE,QAAQ,CAAC;IACf,GAAG,EAAE,CAAC,CAAC;IACP,YAAY,EAAE,CAAC,CAAC;CACnB,GACD;IACI,IAAI,EAAE,OAAO,CAAC;IACd,UAAU,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;CACzB,CAAC;AAER;;;;;;;;;;GAUG;AACH,MAAM,WAAW,OAAO,CAAC,CAAC,EAAE,CAAC,CAAE,SAAQ,SAAS,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACvD;;;;;;OAMG;IACH,MAAM,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC;IAElB;;;;;;;OAOG;IACH,MAAM,CAAC,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,GAAG,SAAS,CAAC;IAExC;;;;;;OAMG;IACH,GAAG,CAAC,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC;IAE5B;;;;;OAKG;IACH,KAAK,IAAI,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAEnB;;;OAGG;IACH,WAAW,EAAE,SAAS,CAAC,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;CAC/C;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,GAAG,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,GAAG,MAAM,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC,CAK5G"}

package/dist/types/api/nodes/collections/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/api/nodes/collections/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC"}

package/dist/types/api/nodes/flowEffect.d.ts

@@ -0,0 +1,28 @@
+import { FlowDataTracker, FlowDisposable, FlowOnDataListener, FlowOnErrorListener, FlowOnPendingListener } from '../../../api/base';
+/**
+ * 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 declare function subscribe<T>(data: FlowDataTracker<T>, onData: FlowOnDataListener<T>, onError?: FlowOnErrorListener, onPending?: FlowOnPendingListener): FlowEffect;
+//# sourceMappingURL=flowEffect.d.ts.map

package/dist/types/api/nodes/flowEffect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flowEffect.d.ts","sourceRoot":"","sources":["../../../../src/api/nodes/flowEffect.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACR,eAAe,EACf,cAAc,EACd,kBAAkB,EAClB,mBAAmB,EACnB,qBAAqB,EACxB,MAAM,YAAY,CAAC;AAGpB;;;;;;;GAOG;AACH,MAAM,WAAW,UAAW,SAAQ,cAAc;CAAG;AAErD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,SAAS,CAAC,CAAC,EACvB,IAAI,EAAE,eAAe,CAAC,CAAC,CAAC,EACxB,MAAM,EAAE,kBAAkB,CAAC,CAAC,CAAC,EAC7B,OAAO,CAAC,EAAE,mBAAmB,EAC7B,SAAS,CAAC,EAAE,qBAAqB,GAClC,UAAU,CAEZ"}