@ersbeth/picoflow 1.1.2 → 2.0.0

package/docs/api/interfaces/FlowMap.md

@@ -0,0 +1,374 @@
+[@ersbeth/picoflow](/api/index.md) / FlowMap
+
+# Interface: FlowMap\<K, V\>
+
+Defined in: [api/nodes/collections/flowMap.ts:52](https://gitlab.com/ersbeth-web/picoflow/-/blob/4e864254f0eac72524c3be40b9e41d799a16e020/src/api/nodes/collections/flowMap.ts#L52)
+
+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.
+
+## Extends
+
+- [`FlowState`](/api/interfaces/FlowState.md)\<`Map`\<`K`, `V`\>\>
+
+## Type Parameters
+
+| Type Parameter |
+| ------ |
+| `K` |
+| `V` |
+
+## Properties
+
+| Property | Type | Description | Defined in |
+| ------ | ------ | ------ | ------ |
+| <a id="lastaction"></a> `$lastAction` | [`FlowState`](/api/interfaces/FlowState.md)\<[`FlowMapAction`](/api/type-aliases/FlowMapAction.md)\<`K`, `V`\>\> | Reactive state containing the last mutation operation performed on the map. Subscribe to this for fine-grained reactivity to specific mutation types. | [api/nodes/collections/flowMap.ts:93](https://gitlab.com/ersbeth-web/picoflow/-/blob/4e864254f0eac72524c3be40b9e41d799a16e020/src/api/nodes/collections/flowMap.ts#L93) |
+
+## 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
+
+[`FlowState`](/api/interfaces/FlowState.md).[`disposed`](/api/interfaces/FlowState.md#disposed)
+
+## Methods
+
+### add()
+
+```ts
+add(key, value): void;
+```
+
+Defined in: [api/nodes/collections/flowMap.ts:79](https://gitlab.com/ersbeth-web/picoflow/-/blob/4e864254f0eac72524c3be40b9e41d799a16e020/src/api/nodes/collections/flowMap.ts#L79)
+
+Adds a new key-value pair to the map.
+Emits an "add" action to $lastAction.
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `key` | `K` | The key to add (must not exist) |
+| `value` | `V` | The value to associate with the key |
+
+#### Returns
+
+`void`
+
+***
+
+### clear()
+
+```ts
+clear(): Map<K, V>;
+```
+
+Defined in: [api/nodes/collections/flowMap.ts:87](https://gitlab.com/ersbeth-web/picoflow/-/blob/4e864254f0eac72524c3be40b9e41d799a16e020/src/api/nodes/collections/flowMap.ts#L87)
+
+Removes all entries from the map.
+Emits a "clear" action to $lastAction.
+
+#### Returns
+
+`Map`\<`K`, `V`\>
+
+Map of all removed entries
+
+***
+
+### delete()
+
+```ts
+delete(key): V;
+```
+
+Defined in: [api/nodes/collections/flowMap.ts:60](https://gitlab.com/ersbeth-web/picoflow/-/blob/4e864254f0eac72524c3be40b9e41d799a16e020/src/api/nodes/collections/flowMap.ts#L60)
+
+Removes a key-value pair from the map.
+Emits a "delete" action to $lastAction.
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `key` | `K` | The key to delete |
+
+#### Returns
+
+`V`
+
+The deleted value
+
+***
+
+### 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
+
+[`FlowState`](/api/interfaces/FlowState.md).[`dispose`](/api/interfaces/FlowState.md#dispose)
+
+***
+
+### get()
+
+```ts
+get(tracker): Map;
+```
+
+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
+
+`Map`
+
+The current value
+
+#### Inherited from
+
+[`FlowState`](/api/interfaces/FlowState.md).[`get`](/api/interfaces/FlowState.md#get)
+
+***
+
+### pick()
+
+```ts
+pick(): Promise<Map<K, V>>;
+```
+
+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`\<`Map`\<`K`, `V`\>\>
+
+Promise that resolves with the current value
+
+#### Inherited from
+
+[`FlowState`](/api/interfaces/FlowState.md).[`pick`](/api/interfaces/FlowState.md#pick)
+
+***
+
+### set()
+
+#### Call Signature
+
+```ts
+set(value): void;
+```
+
+Defined in: [api/nodes/sync/flowState.ts:25](https://gitlab.com/ersbeth-web/picoflow/-/blob/4e864254f0eac72524c3be40b9e41d799a16e020/src/api/nodes/sync/flowState.ts#L25)
+
+Updates the state with a new value or via an updater function.
+Notifies all dependents after the update.
+
+##### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `value` | `Map`\<`K`\> | New value to set, or function that receives current value and returns new value |
+
+##### Returns
+
+`void`
+
+##### Inherited from
+
+[`FlowState`](/api/interfaces/FlowState.md).[`set`](/api/interfaces/FlowState.md#set)
+
+#### Call Signature
+
+```ts
+set(updater): void;
+```
+
+Defined in: [api/nodes/sync/flowState.ts:26](https://gitlab.com/ersbeth-web/picoflow/-/blob/4e864254f0eac72524c3be40b9e41d799a16e020/src/api/nodes/sync/flowState.ts#L26)
+
+##### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `updater` | [`UpdateFunction`](/api/type-aliases/UpdateFunction.md)\<`Map`\<`K`, `V`\>\> |
+
+##### Returns
+
+`void`
+
+##### Inherited from
+
+[`FlowState`](/api/interfaces/FlowState.md).[`set`](/api/interfaces/FlowState.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)\<`Map`\<`K`, `V`\>\> | 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
+
+[`FlowState`](/api/interfaces/FlowState.md).[`subscribe`](/api/interfaces/FlowState.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
+
+[`FlowState`](/api/interfaces/FlowState.md).[`trigger`](/api/interfaces/FlowState.md#trigger)
+
+***
+
+### update()
+
+```ts
+update(key, value): V | undefined;
+```
+
+Defined in: [api/nodes/collections/flowMap.ts:70](https://gitlab.com/ersbeth-web/picoflow/-/blob/4e864254f0eac72524c3be40b9e41d799a16e020/src/api/nodes/collections/flowMap.ts#L70)
+
+Updates an existing key-value pair in the map.
+Emits an "update" action to $lastAction.
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `key` | `K` | The key to update (must exist) |
+| `value` | `V` | The new value |
+
+#### Returns
+
+`V` \| `undefined`
+
+The previous value
+
+***
+
+### 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
+
+[`FlowState`](/api/interfaces/FlowState.md).[`watch`](/api/interfaces/FlowState.md#watch)

package/docs/api/interfaces/FlowObservable.md

@@ -0,0 +1,155 @@
+[@ersbeth/picoflow](/api/index.md) / FlowObservable
+
+# Interface: FlowObservable\<T\>
+
+Defined in: [api/base/flowObservable.ts:9](https://gitlab.com/ersbeth-web/picoflow/-/blob/4e864254f0eac72524c3be40b9e41d799a16e020/src/api/base/flowObservable.ts#L9)
+
+Contract for reactive primitives that emit changes and notify their dependents in the reactivity graph.
+
+## Extends
+
+- [`FlowDisposable`](/api/interfaces/FlowDisposable.md).[`FlowSubscribable`](/api/interfaces/FlowSubscribable.md)\<`T`\>
+
+## Extended by
+
+- [`FlowSignal`](/api/interfaces/FlowSignal.md)
+- [`FlowValue`](/api/interfaces/FlowValue.md)
+
+## 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
+
+[`FlowDisposable`](/api/interfaces/FlowDisposable.md).[`disposed`](/api/interfaces/FlowDisposable.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
+
+[`FlowDisposable`](/api/interfaces/FlowDisposable.md).[`dispose`](/api/interfaces/FlowDisposable.md#dispose)
+
+***
+
+### 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
+
+[`FlowSubscribable`](/api/interfaces/FlowSubscribable.md).[`subscribe`](/api/interfaces/FlowSubscribable.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`
+
+***
+
+### 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`

package/docs/api/interfaces/FlowSignal.md

@@ -0,0 +1,156 @@
+[@ersbeth/picoflow](/api/index.md) / FlowSignal
+
+# Interface: FlowSignal
+
+Defined in: [api/nodes/flowSignal.ts:13](https://gitlab.com/ersbeth-web/picoflow/-/blob/4e864254f0eac72524c3be40b9e41d799a16e020/src/api/nodes/flowSignal.ts#L13)
+
+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.
+
+## Extends
+
+- [`FlowObservable`](/api/interfaces/FlowObservable.md)\<`void`\>
+
+## 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
+
+[`FlowObservable`](/api/interfaces/FlowObservable.md).[`disposed`](/api/interfaces/FlowObservable.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
+
+[`FlowObservable`](/api/interfaces/FlowObservable.md).[`dispose`](/api/interfaces/FlowObservable.md#dispose)
+
+***
+
+### 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)\<`void`\> | 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
+
+[`FlowObservable`](/api/interfaces/FlowObservable.md).[`subscribe`](/api/interfaces/FlowObservable.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
+
+[`FlowObservable`](/api/interfaces/FlowObservable.md).[`trigger`](/api/interfaces/FlowObservable.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
+
+[`FlowObservable`](/api/interfaces/FlowObservable.md).[`watch`](/api/interfaces/FlowObservable.md#watch)