@ersbeth/picoflow 0.2.3 → 1.0.0

package/docs/api/classes/FlowEffect.md

@@ -0,0 +1,100 @@
+[@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

@@ -0,0 +1,512 @@
+[@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)