@ersbeth/picoflow 1.1.2 → 2.0.0

package/docs/api/classes/FlowEffect.md

@@ -1,100 +0,0 @@
-[@ersbeth/picoflow](/api/index.md) / FlowEffect
-
-# Class: FlowEffect
-
-Defined in: [basic/effect.ts:31](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/basic/effect.ts#L31)
-
-Represents a reactive effect that executes side-effect functions based
-on its tracked dependencies.
-
-## Remarks
-
-FlowEffect executes an apply function that performs side effects. The effect always runs
-with a tracking context, allowing you to explicitly control which observables and signals
-become dependencies using `.get(t)` for tracked reads or `.pick()` for untracked reads.
-
-When any tracked dependency changes, the effect automatically re-executes. The effect
-runs immediately upon creation and whenever its dependencies trigger updates.
-
-Unlike the old API, effects in the new TrackingContext-based system always execute with
-a tracking context available. You control reactivity by choosing which observables to track
-within the effect body.
-
-## Example
-
-```typescript
-const fx = effect((t) => {
-  const reactive = $stateA.get(t);    // Tracked - effect re-runs when $stateA changes
-  const snapshot = $stateB.pick();    // Not tracked - changes don't trigger re-runs
-  console.log(reactive, snapshot);
-});
-```
-
-## Constructors
-
-### Constructor
-
-```ts
-new FlowEffect(apply): FlowEffect;
-```
-
-Defined in: [basic/effect.ts:45](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/basic/effect.ts#L45)
-
-Creates a new FlowEffect.
-
-#### Parameters
-
-| Parameter | Type | Description |
-| ------ | ------ | ------ |
-| `apply` | (`t`) => `void` | A side-effect function that receives a tracking context to access and register dependencies on reactive observables and signals. |
-
-#### Returns
-
-`FlowEffect`
-
-#### Remarks
-
-The provided function is executed immediately upon construction with a tracking context.
-Use the context parameter to call `.get(t)` on observables you want to track, or `.pick()`
-on observables you want to read without creating dependencies.
-
-## Accessors
-
-### disposed
-
-#### Get Signature
-
-```ts
-get disposed(): boolean;
-```
-
-Defined in: [basic/effect.ts:75](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/basic/effect.ts#L75)
-
-Indicates whether this effect has been disposed.
-
-##### Returns
-
-`boolean`
-
-A boolean value that is true if the effect is disposed, false otherwise.
-
-## Methods
-
-### dispose()
-
-```ts
-dispose(): void;
-```
-
-Defined in: [basic/effect.ts:60](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/basic/effect.ts#L60)
-
-Disposes the effect, unregistering all its tracked dependencies.
-
-#### Returns
-
-`void`
-
-#### Remarks
-
-Once disposed, the effect must no longer be used. Trying to dispose an effect
-that is already disposed will throw an error.

package/docs/api/classes/FlowMap.md

@@ -1,512 +0,0 @@
-[@ersbeth/picoflow](/api/index.md) / FlowMap
-
-# Class: FlowMap\<K, V\>
-
-Defined in: [advanced/map.ts:75](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/advanced/map.ts#L75)
-
-Represents a reactive map that extends [FlowState](/api/classes/FlowState.md) for tracking key-value pairs.
-
-## Remarks
-
-FlowMap wraps a native JavaScript Map and provides reactive tracking at multiple granularity levels.
-Unlike plain reactive state, FlowMap offers fine-grained reactivity that lets you track:
-
-1. **Whole map changes**: Via `get(t)` or `pick()` on the FlowMap itself
-2. **Last add operation**: Via the `$lastAdded` signal, track which key-value pair was most recently added
-3. **Last update operation**: Via the `$lastUpdated` signal, track which key-value pair was most recently updated
-4. **Last delete operation**: Via the `$lastDeleted` signal, track which key-value pair was most recently removed
-
-**Reactive Signals:**
-- **$lastAdded**: A FlowState containing `{ key?: K, value?: V }` updated on each `add()` call
-- **$lastUpdated**: A FlowState containing `{ key?: K, value?: V }` updated on each `update()` call
-- **$lastDeleted**: A FlowState containing `{ key?: K, value?: V }` updated on each `delete()` call
-
-These signals enable fine-grained reactivity patterns where effects can respond to specific
-map operations without re-processing the entire map.
-
-**Use Cases:**
-- Entity stores where you want to track additions/removals separately
-- Cache implementations with granular invalidation
-- Collections where operations on individual keys matter
-- UI state where you want to animate specific additions or removals
-
-## Example
-
-```typescript
-const $users = map<string, User>();
-
-// Track the whole map
-effect((t) => {
-  const users = $users.get(t);
-  console.log(`Total users: ${users.size}`);
-});
-
-// Track only additions
-effect((t) => {
-  const { key, value } = $users.$lastAdded.get(t);
-  if (key && value) {
-    console.log(`User ${key} was added:`, value);
-  }
-});
-
-// Track only updates
-effect((t) => {
-  const { key, value } = $users.$lastUpdated.get(t);
-  if (key && value) {
-    console.log(`User ${key} was updated:`, value);
-  }
-});
-
-// Track only deletions
-effect((t) => {
-  const { key, value } = $users.$lastDeleted.get(t);
-  if (key && value) {
-    console.log(`User ${key} was deleted:`, value);
-  }
-});
-
-// Modify the map
-$users.add('user1', { name: 'John', age: 30 });
-$users.add('user2', { name: 'Jane', age: 25 });
-$users.update('user1', { name: 'John', age: 31 });
-$users.delete('user1');
-```
-
-## Extends
-
-- [`FlowState`](/api/classes/FlowState.md)\<`Map`\<`K`, `V`\>\>
-
-## Type Parameters
-
-| Type Parameter | Description |
-| ------ | ------ |
-| `K` | The type of the map keys. |
-| `V` | The type of the map values. |
-
-## Constructors
-
-### Constructor
-
-```ts
-new FlowMap<K, V>(value): FlowMap<K, V>;
-```
-
-Defined in: [basic/constant.ts:59](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/basic/constant.ts#L59)
-
-Creates a new FlowConstant instance.
-
-#### Parameters
-
-| Parameter | Type | Description |
-| ------ | ------ | ------ |
-| `value` | `Map`\<`K`, `V`\> \| () => `Map` | Either a direct value of type T or a function returning a value of type T. If a function is provided, it will be invoked lazily on the first value access. If a direct value is provided, it is stored immediately. |
-
-#### Returns
-
-`FlowMap`\<`K`, `V`\>
-
-#### Inherited from
-
-[`FlowState`](/api/classes/FlowState.md).[`constructor`](/api/classes/FlowState.md#constructor)
-
-## Properties
-
-| Property | Modifier | Type | Description | Defined in |
-| ------ | ------ | ------ | ------ | ------ |
-| <a id="lastadded"></a> `$lastAdded` | `public` | [`FlowState`](/api/classes/FlowState.md)\< \| \{ `key`: `K`; `value`: `V`; \} \| `null`\> | A reactive state that holds the most recent key and value that were added. **Remarks** When a key is added via [FlowMap.add](/api/classes/FlowMap.md#add), this state is updated with the corresponding key and value. | [advanced/map.ts:85](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/advanced/map.ts#L85) |
-| <a id="lastdeleted"></a> `$lastDeleted` | `public` | [`FlowState`](/api/classes/FlowState.md)\< \| \{ `key`: `K`; `value`: `V`; \} \| `null`\> | A reactive state that holds the most recent key and value that were deleted. **Remarks** When a key is deleted via [FlowMap.delete](/api/classes/FlowMap.md#delete), this state is updated with the corresponding key and its last known value. | [advanced/map.ts:107](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/advanced/map.ts#L107) |
-| <a id="lastupdated"></a> `$lastUpdated` | `public` | [`FlowState`](/api/classes/FlowState.md)\< \| \{ `key`: `K`; `value`: `V`; \} \| `null`\> | A reactive state that holds the most recent key and value that were updated. **Remarks** When a key is updated via [FlowMap.update](/api/classes/FlowMap.md#update), this state is updated with the corresponding key and value. | [advanced/map.ts:96](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/advanced/map.ts#L96) |
-
-## Accessors
-
-### disposed
-
-#### Get Signature
-
-```ts
-get disposed(): boolean;
-```
-
-Defined in: [basic/signal.ts:97](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/basic/signal.ts#L97)
-
-Indicates whether the FlowSignal has been disposed.
-
-##### Remarks
-
-Once disposed, the signal should not be used.
-
-##### Returns
-
-`boolean`
-
-#### Inherited from
-
-[`FlowState`](/api/classes/FlowState.md).[`disposed`](/api/classes/FlowState.md#disposed)
-
-## Methods
-
-### add()
-
-```ts
-add(key, value): void;
-```
-
-Defined in: [advanced/map.ts:123](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/advanced/map.ts#L123)
-
-Adds a new key-value pair to the map.
-
-#### Parameters
-
-| Parameter | Type | Description |
-| ------ | ------ | ------ |
-| `key` | `K` | The key to add. |
-| `value` | `V` | The value to associate with the key. |
-
-#### Returns
-
-`void`
-
-#### Throws
-
-If the FlowMap instance is disposed.
-
-#### Throws
-
-If the key already exists in the map.
-
-#### Remarks
-
-Adds a new entry to the internal map, emits the key-value pair via [FlowMap.$lastAdded](/api/classes/FlowMap.md#lastadded),
-and notifies all subscribers of the change.
-
-***
-
-### delete()
-
-```ts
-delete(key): void;
-```
-
-Defined in: [advanced/map.ts:169](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/advanced/map.ts#L169)
-
-Deletes the value at the specified key from the underlying map.
-
-#### Parameters
-
-| Parameter | Type | Description |
-| ------ | ------ | ------ |
-| `key` | `K` | The key to delete. |
-
-#### Returns
-
-`void`
-
-#### Throws
-
-If the FlowMap instance is disposed.
-
-#### Remarks
-
-Removes the key from the internal map, emits the deleted key and its value via [FlowMap.$lastDeleted](/api/classes/FlowMap.md#lastdeleted),
-and notifies all subscribers of the change.
-
-***
-
-### dispose()
-
-```ts
-dispose(options?): void;
-```
-
-Defined in: [advanced/map.ts:183](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/advanced/map.ts#L183)
-
-Disposes the FlowMap and its values.
-
-#### Parameters
-
-| Parameter | Type | Description |
-| ------ | ------ | ------ |
-| `options?` | \{ `self`: `boolean`; \} | Disposal options. |
-| `options.self?` | `boolean` | - |
-
-#### Returns
-
-`void`
-
-#### Overrides
-
-[`FlowState`](/api/classes/FlowState.md).[`dispose`](/api/classes/FlowState.md#dispose)
-
-***
-
-### get()
-
-```ts
-get(context): Map;
-```
-
-Defined in: [basic/observable.ts:47](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/basic/observable.ts#L47)
-
-Gets the current value with optional dependency tracking.
-
-#### Parameters
-
-| Parameter | Type | Description |
-| ------ | ------ | ------ |
-| `context` | [`TrackingContext`](/api/classes/TrackingContext.md) \| `null` | The tracking context for reactive tracking, or null for untracked access. When a context is provided, this observable is registered as a dependency. When null, the value is read without any tracking. |
-
-#### Returns
-
-`Map`
-
-The current value of type T.
-
-#### Remarks
-
-Use `get(t)` within effects and derivations to create reactive dependencies.
-Use `get(null)` when you need to read a value without tracking (though `pick()` is more idiomatic).
-
-#### Example
-
-```typescript
-effect((t) => {
-  const tracked = $state.get(t);     // Dependency registered
-  const untracked = $other.get(null); // No dependency
-});
-```
-
-#### Inherited from
-
-[`FlowState`](/api/classes/FlowState.md).[`get`](/api/classes/FlowState.md#get)
-
-***
-
-### pick()
-
-```ts
-pick(): Map;
-```
-
-Defined in: [basic/observable.ts:82](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/basic/observable.ts#L82)
-
-Gets the current value without any dependency tracking.
-
-#### Returns
-
-`Map`
-
-The current value of type T.
-
-#### Remarks
-
-This method is equivalent to calling `get(null)` but provides a more semantic and readable API.
-Use `pick()` when you want to read a snapshot of the current value without creating a reactive
-dependency. This is useful for:
-- Reading initial values
-- Accessing configuration that shouldn't trigger updates
-- Mixing tracked and untracked reads in the same effect
-
-#### Example
-
-```typescript
-// Read a snapshot outside reactive context
-const currentValue = $state.pick();
-
-// Mix tracked and untracked reads
-effect((t) => {
-  const tracked = $reactive.get(t);    // Triggers re-runs
-  const snapshot = $config.pick();     // Doesn't trigger re-runs
-  processData(tracked, snapshot);
-});
-```
-
-#### Inherited from
-
-[`FlowState`](/api/classes/FlowState.md).[`pick`](/api/classes/FlowState.md#pick)
-
-***
-
-### set()
-
-```ts
-set(value): void;
-```
-
-Defined in: [basic/state.ts:46](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/basic/state.ts#L46)
-
-Updates the state with a new value.
-
-#### Parameters
-
-| Parameter | Type | Description |
-| ------ | ------ | ------ |
-| `value` | `Map`\<`K`, `V`\> \| (`current`) => `Map` | A new value or a callback function that computes a new value based on the current state. |
-
-#### Returns
-
-`void`
-
-#### Remarks
-
-If the computed new value is strictly equal to the current state value, no change is made and subscribers
-will not be notified. Otherwise, the state is updated and all subscribers are informed of the change.
-
-#### Throws
-
-Error if the state has been disposed.
-
-#### Inherited from
-
-[`FlowState`](/api/classes/FlowState.md).[`set`](/api/classes/FlowState.md#set)
-
-***
-
-### subscribe()
-
-```ts
-subscribe(listener): () => void;
-```
-
-Defined in: [basic/observable.ts:103](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/basic/observable.ts#L103)
-
-Subscribes a listener function to changes of the observable.
-The listener is executed immediately with the current value and on subsequent updates.
-
-#### Parameters
-
-| Parameter | Type | Description |
-| ------ | ------ | ------ |
-| `listener` | (`value`) => `void` | A callback function that receives the new value. |
-
-#### Returns
-
-A disposer function to cancel the subscription.
-
-```ts
-(): void;
-```
-
-##### Returns
-
-`void`
-
-#### Inherited from
-
-[`FlowState`](/api/classes/FlowState.md).[`subscribe`](/api/classes/FlowState.md#subscribe)
-
-***
-
-### trigger()
-
-```ts
-trigger(): void;
-```
-
-Defined in: [basic/signal.ts:19](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/basic/signal.ts#L19)
-
-Triggers the FlowSignal.
-Notifies all registered listeners and schedules execution of associated effects.
-
-#### Returns
-
-`void`
-
-#### Throws
-
-If the FlowSignal has already been disposed.
-
-#### Inherited from
-
-[`FlowState`](/api/classes/FlowState.md).[`trigger`](/api/classes/FlowState.md#trigger)
-
-***
-
-### update()
-
-```ts
-update(key, value): void;
-```
-
-Defined in: [advanced/map.ts:147](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/advanced/map.ts#L147)
-
-Updates an existing key-value pair in the map.
-
-#### Parameters
-
-| Parameter | Type | Description |
-| ------ | ------ | ------ |
-| `key` | `K` | The key to update. |
-| `value` | `V` | The new value to associate with the key. |
-
-#### Returns
-
-`void`
-
-#### Throws
-
-If the FlowMap instance is disposed.
-
-#### Throws
-
-If the key does not exist in the map.
-
-#### Remarks
-
-Updates an existing entry in the internal map, emits the key-value pair via [FlowMap.$lastUpdated](/api/classes/FlowMap.md#lastupdated),
-and notifies all subscribers of the change.
-
-***
-
-### watch()
-
-```ts
-watch(context): void;
-```
-
-Defined in: [basic/signal.ts:57](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/basic/signal.ts#L57)
-
-Watches the signal, registering it as a dependency in the tracking context.
-
-#### Parameters
-
-| Parameter | Type | Description |
-| ------ | ------ | ------ |
-| `context` | [`TrackingContext`](/api/classes/TrackingContext.md) | The tracking context in which to register this signal as a dependency. |
-
-#### Returns
-
-`void`
-
-#### Remarks
-
-Use `watch()` when you want to track a signal without reading its value (signals don't
-have values to read). This is useful for triggering effects based on signal events
-without needing associated data.
-
-When the signal is triggered via `trigger()`, any effects or derivations that have
-watched this signal will automatically re-execute.
-
-This method must be called within an effect or derivation context where a TrackingContext
-is available. For observables (which hold values), use `.get(t)` instead, which both
-reads the value and watches for changes.
-
-#### Throws
-
-Error if the signal has been disposed.
-
-#### Example
-
-```typescript
-const $signal = signal();
-
-effect((t) => {
-  $signal.watch(t);  // Track the signal
-  console.log('Signal triggered!');
-});
-
-$signal.trigger(); // Logs: "Signal triggered!"
-```
-
-#### Inherited from
-
-[`FlowState`](/api/classes/FlowState.md).[`watch`](/api/classes/FlowState.md#watch)