@ersbeth/picoflow 1.1.1 → 2.0.0

package/docs/api/interfaces/FlowWritableDerivationAsync.md

@@ -0,0 +1,293 @@
+[@ersbeth/picoflow](/api/index.md) / FlowWritableDerivationAsync
+
+# Interface: FlowWritableDerivationAsync\<T\>
+
+Defined in: [api/nodes/async/flowWritableDerivationAsync.ts:16](https://gitlab.com/ersbeth-web/picoflow/-/blob/4e864254f0eac72524c3be40b9e41d799a16e020/src/api/nodes/async/flowWritableDerivationAsync.ts#L16)
+
+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.
+
+## Extends
+
+- [`FlowStateAsync`](/api/interfaces/FlowStateAsync.md)\<`T`\>.[`FlowDerivationAsync`](/api/interfaces/FlowDerivationAsync.md)\<`T`\>
+
+## Type Parameters
+
+| Type Parameter |
+| ------ |
+| `T` |
+
+## Accessors
+
+### disposed
+
+#### Get Signature
+
+```ts
+get disposed(): boolean;
+```
+
+Defined in: [api/base/flowDisposable.ts:17](https://gitlab.com/ersbeth-web/picoflow/-/blob/4e864254f0eac72524c3be40b9e41d799a16e020/src/api/base/flowDisposable.ts#L17)
+
+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.
+
+##### Returns
+
+`boolean`
+
+#### Inherited from
+
+[`FlowStateAsync`](/api/interfaces/FlowStateAsync.md).[`disposed`](/api/interfaces/FlowStateAsync.md#disposed)
+
+## Methods
+
+### dispose()
+
+```ts
+dispose(): void;
+```
+
+Defined in: [api/base/flowDisposable.ts:27](https://gitlab.com/ersbeth-web/picoflow/-/blob/4e864254f0eac72524c3be40b9e41d799a16e020/src/api/base/flowDisposable.ts#L27)
+
+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.
+
+#### Returns
+
+`void`
+
+#### Inherited from
+
+[`FlowStateAsync`](/api/interfaces/FlowStateAsync.md).[`dispose`](/api/interfaces/FlowStateAsync.md#dispose)
+
+***
+
+### get()
+
+```ts
+get(tracker): T;
+```
+
+Defined in: [api/nodes/flowValue.ts:24](https://gitlab.com/ersbeth-web/picoflow/-/blob/4e864254f0eac72524c3be40b9e41d799a16e020/src/api/nodes/flowValue.ts#L24)
+
+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.
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `tracker` | [`FlowTracker`](/api/interfaces/FlowTracker.md) | Tracker that records this value as a dependency |
+
+#### Returns
+
+`T`
+
+The current value
+
+#### Inherited from
+
+[`FlowStateAsync`](/api/interfaces/FlowStateAsync.md).[`get`](/api/interfaces/FlowStateAsync.md#get)
+
+***
+
+### pick()
+
+```ts
+pick(): Promise<T>;
+```
+
+Defined in: [api/nodes/flowValue.ts:35](https://gitlab.com/ersbeth-web/picoflow/-/blob/4e864254f0eac72524c3be40b9e41d799a16e020/src/api/nodes/flowValue.ts#L35)
+
+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`\<`T`\>
+
+Promise that resolves with the current value
+
+#### Inherited from
+
+[`FlowStateAsync`](/api/interfaces/FlowStateAsync.md).[`pick`](/api/interfaces/FlowStateAsync.md#pick)
+
+***
+
+### refresh()
+
+```ts
+refresh(): void;
+```
+
+Defined in: [api/nodes/async/flowDerivationAsync.ts:24](https://gitlab.com/ersbeth-web/picoflow/-/blob/4e864254f0eac72524c3be40b9e41d799a16e020/src/api/nodes/async/flowDerivationAsync.ts#L24)
+
+Forces the derivation to recompute even if dependencies haven't changed.
+
+#### Returns
+
+`void`
+
+#### Inherited from
+
+[`FlowDerivationAsync`](/api/interfaces/FlowDerivationAsync.md).[`refresh`](/api/interfaces/FlowDerivationAsync.md#refresh)
+
+***
+
+### set()
+
+#### Call Signature
+
+```ts
+set(promise): void;
+```
+
+Defined in: [api/nodes/async/flowStateAsync.ts:26](https://gitlab.com/ersbeth-web/picoflow/-/blob/4e864254f0eac72524c3be40b9e41d799a16e020/src/api/nodes/async/flowStateAsync.ts#L26)
+
+Updates the state with a new promise or via an async updater function.
+Notifies all dependents immediately (they will receive PendingError until resolved).
+
+##### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `promise` | `Promise`\<`T`\> | New promise to resolve, or async function that receives current value and returns a promise |
+
+##### Returns
+
+`void`
+
+##### Inherited from
+
+[`FlowStateAsync`](/api/interfaces/FlowStateAsync.md).[`set`](/api/interfaces/FlowStateAsync.md#set)
+
+#### Call Signature
+
+```ts
+set(updater): void;
+```
+
+Defined in: [api/nodes/async/flowStateAsync.ts:27](https://gitlab.com/ersbeth-web/picoflow/-/blob/4e864254f0eac72524c3be40b9e41d799a16e020/src/api/nodes/async/flowStateAsync.ts#L27)
+
+##### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `updater` | [`UpdateFunctionAsync`](/api/type-aliases/UpdateFunctionAsync.md)\<`T`\> |
+
+##### Returns
+
+`void`
+
+##### Inherited from
+
+[`FlowStateAsync`](/api/interfaces/FlowStateAsync.md).[`set`](/api/interfaces/FlowStateAsync.md#set)
+
+***
+
+### subscribe()
+
+```ts
+subscribe(
+   onData, 
+   onError?, 
+   onPending?): FlowEffect;
+```
+
+Defined in: [api/base/flowSubscribable.ts:82](https://gitlab.com/ersbeth-web/picoflow/-/blob/4e864254f0eac72524c3be40b9e41d799a16e020/src/api/base/flowSubscribable.ts#L82)
+
+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.
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `onData` | [`FlowOnDataListener`](/api/type-aliases/FlowOnDataListener.md)\<`T`\> | Callback invoked with the computed data on each execution |
+| `onError?` | [`FlowOnErrorListener`](/api/type-aliases/FlowOnErrorListener.md) | Optional callback for handling errors during execution |
+| `onPending?` | [`FlowOnPendingListener`](/api/type-aliases/FlowOnPendingListener.md) | Optional callback invoked when async dependencies are pending |
+
+#### Returns
+
+[`FlowEffect`](/api/interfaces/FlowEffect.md)
+
+A function to dispose the subscription and stop receiving updates
+
+#### Inherited from
+
+[`FlowStateAsync`](/api/interfaces/FlowStateAsync.md).[`subscribe`](/api/interfaces/FlowStateAsync.md#subscribe)
+
+***
+
+### trigger()
+
+```ts
+trigger(): void;
+```
+
+Defined in: [api/base/flowObservable.ts:27](https://gitlab.com/ersbeth-web/picoflow/-/blob/4e864254f0eac72524c3be40b9e41d799a16e020/src/api/base/flowObservable.ts#L27)
+
+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.
+
+#### Returns
+
+`void`
+
+#### Inherited from
+
+[`FlowStateAsync`](/api/interfaces/FlowStateAsync.md).[`trigger`](/api/interfaces/FlowStateAsync.md#trigger)
+
+***
+
+### watch()
+
+```ts
+watch(tracker): void;
+```
+
+Defined in: [api/base/flowObservable.ts:18](https://gitlab.com/ersbeth-web/picoflow/-/blob/4e864254f0eac72524c3be40b9e41d799a16e020/src/api/base/flowObservable.ts#L18)
+
+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.
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `tracker` | [`FlowTracker`](/api/interfaces/FlowTracker.md) | Tracker that records this observable as a dependency |
+
+#### Returns
+
+`void`
+
+#### Inherited from
+
+[`FlowStateAsync`](/api/interfaces/FlowStateAsync.md).[`watch`](/api/interfaces/FlowStateAsync.md#watch)

package/docs/api/type-aliases/DerivationFunction.md

@@ -0,0 +1,28 @@
+[@ersbeth/picoflow](/api/index.md) / DerivationFunction
+
+# Type Alias: DerivationFunction()\<T\>
+
+```ts
+type DerivationFunction<T> = (tracker, previous?) => NotPromise<T>;
+```
+
+Defined in: [api/nodes/sync/flowDerivation.ts:7](https://gitlab.com/ersbeth-web/picoflow/-/blob/4e864254f0eac72524c3be40b9e41d799a16e020/src/api/nodes/sync/flowDerivation.ts#L7)
+
+Function that derives a value from dependencies and optionally the previous value.
+
+## Type Parameters
+
+| Type Parameter |
+| ------ |
+| `T` |
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `tracker` | [`FlowTracker`](/api/interfaces/FlowTracker.md) |
+| `previous?` | [`NotPromise`](/api/type-aliases/NotPromise.md)\<`T`\> |
+
+## Returns
+
+[`NotPromise`](/api/type-aliases/NotPromise.md)\<`T`\>

package/docs/api/type-aliases/DerivationFunctionAsync.md

@@ -0,0 +1,28 @@
+[@ersbeth/picoflow](/api/index.md) / DerivationFunctionAsync
+
+# Type Alias: DerivationFunctionAsync()\<T\>
+
+```ts
+type DerivationFunctionAsync<T> = (tracker, previous?) => Promise<T>;
+```
+
+Defined in: [api/nodes/async/flowDerivationAsync.ts:7](https://gitlab.com/ersbeth-web/picoflow/-/blob/4e864254f0eac72524c3be40b9e41d799a16e020/src/api/nodes/async/flowDerivationAsync.ts#L7)
+
+Function that derives a value asynchronously from dependencies and optionally the previous value.
+
+## Type Parameters
+
+| Type Parameter |
+| ------ |
+| `T` |
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `tracker` | [`FlowTracker`](/api/interfaces/FlowTracker.md) |
+| `previous?` | [`NotPromise`](/api/type-aliases/NotPromise.md)\<`T`\> |
+
+## Returns
+
+`Promise`\<`T`\>

package/docs/api/type-aliases/FlowArrayAction.md

@@ -5,42 +5,53 @@
 ```ts
 type FlowArrayAction<T> = 
   | {
-  items: T[];
+  clearedItems: T[];
+  setItems: T[];
   type: "set";
 }
   | {
+  clearedItem: T | undefined;
   index: number;
-  item: T;
-  type: "setItem";
+  setItem: T;
+  type: "update";
 }
   | {
-  item: T;
+  addedItem: T;
   type: "push";
 }
   | {
+  removedItem: T | undefined;
   type: "pop";
 }
   | {
-  item: T;
+  addedItem: T;
   type: "unshift";
 }
   | {
+  removedItem: T | undefined;
   type: "shift";
 }
   | {
+  addedItems: T[];
   deleteCount: number;
-  items: T[];
+  removedItems: T[];
   start: number;
   type: "splice";
 }
   | {
+  clearedItems: T[];
   type: "clear";
 };
 ```
 
-Defined in: [advanced/array.ts:8](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/advanced/array.ts#L8)
+Defined in: [api/nodes/collections/flowArray.ts:14](https://gitlab.com/ersbeth-web/picoflow/-/blob/4e864254f0eac72524c3be40b9e41d799a16e020/src/api/nodes/collections/flowArray.ts#L14)
 
-Represents the actions that can be performed on a FlowArray.
+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.
 
 ## Type Parameters
 

package/docs/api/type-aliases/FlowDataTracker.md

@@ -0,0 +1,33 @@
+[@ersbeth/picoflow](/api/index.md) / FlowDataTracker
+
+# Type Alias: FlowDataTracker()\<T\>
+
+```ts
+type FlowDataTracker<T> = (t) => T;
+```
+
+Defined in: [api/base/flowSubscribable.ts:16](https://gitlab.com/ersbeth-web/picoflow/-/blob/4e864254f0eac72524c3be40b9e41d799a16e020/src/api/base/flowSubscribable.ts#L16)
+
+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.
+
+## Type Parameters
+
+| Type Parameter |
+| ------ |
+| `T` |
+
+## Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `t` | [`FlowTracker`](/api/interfaces/FlowTracker.md) | Tracker object that records dependencies when reactive values are accessed |
+
+## Returns
+
+`T`
+
+The computed data of type T

package/docs/api/type-aliases/FlowMapAction.md

@@ -0,0 +1,48 @@
+[@ersbeth/picoflow](/api/index.md) / FlowMapAction
+
+# Type Alias: FlowMapAction\<K, V\>
+
+```ts
+type FlowMapAction<K, V> = 
+  | {
+  clearedMap: Map<K, V>;
+  setMap: Map<K, V>;
+  type: "set";
+}
+  | {
+  addedValue: V;
+  key: K;
+  type: "add";
+}
+  | {
+  clearedValue: V;
+  key: K;
+  setValue: V;
+  type: "update";
+}
+  | {
+  key: K;
+  removedValue: V;
+  type: "delete";
+}
+  | {
+  clearedMap: Map<K, V>;
+  type: "clear";
+};
+```
+
+Defined in: [api/nodes/collections/flowMap.ts:14](https://gitlab.com/ersbeth-web/picoflow/-/blob/4e864254f0eac72524c3be40b9e41d799a16e020/src/api/nodes/collections/flowMap.ts#L14)
+
+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.
+
+## Type Parameters
+
+| Type Parameter |
+| ------ |
+| `K` |
+| `V` |

package/docs/api/type-aliases/FlowOnDataListener.md

@@ -0,0 +1,33 @@
+[@ersbeth/picoflow](/api/index.md) / FlowOnDataListener
+
+# Type Alias: FlowOnDataListener()\<T\>
+
+```ts
+type FlowOnDataListener<T> = (data) => undefined;
+```
+
+Defined in: [api/base/flowSubscribable.ts:30](https://gitlab.com/ersbeth-web/picoflow/-/blob/4e864254f0eac72524c3be40b9e41d799a16e020/src/api/base/flowSubscribable.ts#L30)
+
+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.
+
+## Type Parameters
+
+| Type Parameter |
+| ------ |
+| `T` |
+
+## Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `data` | `T` | The computed data from the tracker function |
+
+## Returns
+
+`undefined`
+
+Always returns undefined (callbacks are for side effects)

package/docs/api/type-aliases/FlowOnErrorListener.md

@@ -0,0 +1,27 @@
+[@ersbeth/picoflow](/api/index.md) / FlowOnErrorListener
+
+# Type Alias: FlowOnErrorListener()
+
+```ts
+type FlowOnErrorListener = (error) => undefined;
+```
+
+Defined in: [api/base/flowSubscribable.ts:44](https://gitlab.com/ersbeth-web/picoflow/-/blob/4e864254f0eac72524c3be40b9e41d799a16e020/src/api/base/flowSubscribable.ts#L44)
+
+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.
+
+## Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `error` | `Error` | The error that occurred, always normalized to an Error instance |
+
+## Returns
+
+`undefined`
+
+Always returns undefined (callbacks are for side effects)

package/docs/api/type-aliases/FlowOnPendingListener.md

@@ -0,0 +1,21 @@
+[@ersbeth/picoflow](/api/index.md) / FlowOnPendingListener
+
+# Type Alias: FlowOnPendingListener()
+
+```ts
+type FlowOnPendingListener = () => undefined;
+```
+
+Defined in: [api/base/flowSubscribable.ts:57](https://gitlab.com/ersbeth-web/picoflow/-/blob/4e864254f0eac72524c3be40b9e41d799a16e020/src/api/base/flowSubscribable.ts#L57)
+
+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
+
+`undefined`
+
+Always returns undefined (callbacks are for side effects)

package/docs/api/type-aliases/FlowReadonly.md

@@ -0,0 +1,22 @@
+[@ersbeth/picoflow](/api/index.md) / FlowReadonly
+
+# Type Alias: FlowReadonly\<T\>
+
+```ts
+type FlowReadonly<T> = Omit<T, "set" | "refresh" | "trigger">;
+```
+
+Defined in: [api/nodes/utils.ts:22](https://gitlab.com/ersbeth-web/picoflow/-/blob/4e864254f0eac72524c3be40b9e41d799a16e020/src/api/nodes/utils.ts#L22)
+
+Type that restricts mutation methods to create read-only versions of reactive primitives.
+
+This utility type removes mutation methods (`set`, `refresh`, `trigger`) from a reactive primitive,
+creating a read-only interface. Use this when you want to expose reactive values to consumers who
+should observe but not modify them, such as passing state to child components or external modules
+while maintaining encapsulation of write access.
+
+## Type Parameters
+
+| Type Parameter |
+| ------ |
+| `T` |

package/docs/api/type-aliases/InitFunction.md

@@ -0,0 +1,21 @@
+[@ersbeth/picoflow](/api/index.md) / InitFunction
+
+# Type Alias: InitFunction()\<T\>
+
+```ts
+type InitFunction<T> = () => NotPromise<T>;
+```
+
+Defined in: [api/nodes/sync/flowConstant.ts:6](https://gitlab.com/ersbeth-web/picoflow/-/blob/4e864254f0eac72524c3be40b9e41d799a16e020/src/api/nodes/sync/flowConstant.ts#L6)
+
+Function that initializes a value.
+
+## Type Parameters
+
+| Type Parameter |
+| ------ |
+| `T` |
+
+## Returns
+
+[`NotPromise`](/api/type-aliases/NotPromise.md)\<`T`\>

package/docs/api/type-aliases/InitFunctionAsync.md

@@ -0,0 +1,21 @@
+[@ersbeth/picoflow](/api/index.md) / InitFunctionAsync
+
+# Type Alias: InitFunctionAsync()\<T\>
+
+```ts
+type InitFunctionAsync<T> = () => Promise<T>;
+```
+
+Defined in: [api/nodes/async/flowConstantAsync.ts:5](https://gitlab.com/ersbeth-web/picoflow/-/blob/4e864254f0eac72524c3be40b9e41d799a16e020/src/api/nodes/async/flowConstantAsync.ts#L5)
+
+Function that initializes a value asynchronously.
+
+## Type Parameters
+
+| Type Parameter |
+| ------ |
+| `T` |
+
+## Returns
+
+`Promise`\<`T`\>

package/docs/api/type-aliases/NotPromise.md

@@ -6,10 +6,13 @@
 type NotPromise<T> = T extends Promise<unknown> ? never : T;
 ```
 
-Defined in: [solid/converters.ts:149](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/solid/converters.ts#L149)
+Defined in: [api/nodes/utils.ts:10](https://gitlab.com/ersbeth-web/picoflow/-/blob/4e864254f0eac72524c3be40b9e41d799a16e020/src/api/nodes/utils.ts#L10)
 
-Utility type that excludes Promise types from T.
-Used to ensure type safety for synchronous derivations/resources.
+Type that excludes Promise values from a type union.
+
+This utility type ensures that synchronous reactive primitives (like `state`, `constant`, `derivation`)
+only accept non-Promise values. Use this to prevent accidental mixing of sync and async values, which
+would cause runtime errors. For async values, use the async variants (like `stateAsync`, `constantAsync`).
 
 ## Type Parameters