@ersbeth/picoflow 0.2.4 → 1.0.1

package/docs/api/classes/FlowConstant.md

@@ -0,0 +1,350 @@
+[@ersbeth/picoflow](/api/index.md) / FlowConstant
+
+# Class: FlowConstant\<T\>
+
+Defined in: [basic/constant.ts:49](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/basic/constant.ts#L49)
+
+Represents a reactive and immutable constant value that can be computed lazily upon first access.
+
+## Remarks
+
+FlowConstant extends FlowObservable to provide an immutable reactive value. Unlike [FlowState](/api/classes/FlowState.md),
+which is mutable via the `set()` method, a constant's value never changes after initialization.
+
+**Initialization Patterns:**
+- **Direct value**: Pass a value directly; it's stored immediately.
+- **Lazy initialization**: Pass a function; it's called only when the value is first accessed
+  via `get()` or `pick()`.
+
+**Lazy Evaluation Benefits:**
+Lazy initialization is useful when:
+- The computation is expensive and may not be needed immediately
+- The value depends on resources that aren't available at construction time
+- You want to defer computation until the value is actually needed
+
+**Caching:**
+Once computed (either immediately or lazily), the value is cached permanently. All subsequent
+accesses return the cached value without re-computation.
+
+**Use Cases:**
+- Configuration values that don't change
+- Expensive computations that should only run once
+- Initialization values for other reactive primitives
+
+## Example
+
+```typescript
+// Direct value - initialized immediately
+const $config = constant({ apiUrl: 'https://api.example.com' });
+
+// Lazy initialization - computed on first access
+const $expensiveValue = constant(() => {
+  console.log('Computing...');
+  return performExpensiveCalculation();
+});
+
+$expensiveValue.pick(); // Logs: "Computing..."
+$expensiveValue.pick(); // No log - returns cached value
+```
+
+## Extends
+
+- [`FlowObservable`](/api/classes/FlowObservable.md)\<`T`\>
+
+## Extended by
+
+- [`FlowState`](/api/classes/FlowState.md)
+
+## Type Parameters
+
+| Type Parameter | Description |
+| ------ | ------ |
+| `T` | The type of the constant value. |
+
+## Constructors
+
+### Constructor
+
+```ts
+new FlowConstant<T>(value): FlowConstant<T>;
+```
+
+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` | `T` \| () => `T` | 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
+
+`FlowConstant`\<`T`\>
+
+#### Overrides
+
+[`FlowObservable`](/api/classes/FlowObservable.md).[`constructor`](/api/classes/FlowObservable.md#constructor)
+
+## 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
+
+[`FlowObservable`](/api/classes/FlowObservable.md).[`disposed`](/api/classes/FlowObservable.md#disposed)
+
+## Methods
+
+### dispose()
+
+```ts
+dispose(options?): void;
+```
+
+Defined in: [basic/signal.ts:69](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/basic/signal.ts#L69)
+
+Disposes the FlowSignal.
+Cleans up all registered effects, listeners, and dependencies.
+Once disposed, further usage of the signal will throw an error.
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `options?` | \{ `self`: `boolean`; \} |
+| `options.self?` | `boolean` |
+
+#### Returns
+
+`void`
+
+#### Throws
+
+If the FlowSignal is already disposed.
+
+#### Inherited from
+
+[`FlowObservable`](/api/classes/FlowObservable.md).[`dispose`](/api/classes/FlowObservable.md#dispose)
+
+***
+
+### get()
+
+```ts
+get(context): T;
+```
+
+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
+
+`T`
+
+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
+
+[`FlowObservable`](/api/classes/FlowObservable.md).[`get`](/api/classes/FlowObservable.md#get)
+
+***
+
+### pick()
+
+```ts
+pick(): T;
+```
+
+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
+
+`T`
+
+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
+
+[`FlowObservable`](/api/classes/FlowObservable.md).[`pick`](/api/classes/FlowObservable.md#pick)
+
+***
+
+### 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
+
+[`FlowObservable`](/api/classes/FlowObservable.md).[`subscribe`](/api/classes/FlowObservable.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
+
+[`FlowObservable`](/api/classes/FlowObservable.md).[`trigger`](/api/classes/FlowObservable.md#trigger)
+
+***
+
+### 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
+
+[`FlowObservable`](/api/classes/FlowObservable.md).[`watch`](/api/classes/FlowObservable.md#watch)

package/docs/api/classes/FlowDerivation.md

@@ -0,0 +1,334 @@
+[@ersbeth/picoflow](/api/index.md) / FlowDerivation
+
+# Class: FlowDerivation\<T\>
+
+Defined in: [basic/derivation.ts:43](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/basic/derivation.ts#L43)
+
+Represents a reactive derivation whose value is computed based on other reactive signals.
+
+## Remarks
+
+FlowDerivation creates a computed value that automatically tracks its dependencies and
+recomputes when any dependency changes. The computation is lazy: it doesn't execute until
+the value is first accessed (via `get()` or `pick()`), and subsequent accesses return the
+cached value until a dependency changes.
+
+**Lazy Initialization:**
+The compute function doesn't run immediately upon creation. It runs only when:
+- The value is first read via `get()` or `pick()`
+- The derivation is watched via `watch()`
+
+**Dirty Checking and Recomputation:**
+When a tracked dependency changes, the derivation is marked as "dirty" but doesn't recompute
+immediately. Recomputation happens lazily on the next value access. This prevents unnecessary
+computations when multiple dependencies change in quick succession.
+
+**Dynamic Dependencies:**
+Dependencies are tracked dynamically during each computation. If the compute function
+conditionally tracks different observables, the dependency graph updates automatically.
+
+## Example
+
+```typescript
+const $firstName = state('John');
+const $lastName = state('Doe');
+
+const $fullName = derivation((t) => {
+  return `${$firstName.get(t)} ${$lastName.get(t)}`;
+});
+
+// Compute function hasn't run yet (lazy)
+const name = $fullName.pick(); // Now it computes
+```
+
+## Extends
+
+- [`FlowObservable`](/api/classes/FlowObservable.md)\<`T`\>
+
+## Type Parameters
+
+| Type Parameter | Description |
+| ------ | ------ |
+| `T` | The type of the computed value. |
+
+## Constructors
+
+### Constructor
+
+```ts
+new FlowDerivation<T>(compute): FlowDerivation<T>;
+```
+
+Defined in: [basic/derivation.ts:53](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/basic/derivation.ts#L53)
+
+Creates a new FlowDerivation.
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `compute` | (`t`) => `T` | A function that computes the derived value using a tracking context. The function receives a TrackingContext and should use it to access dependencies via `.get(t)`. The function is not executed immediately; it runs lazily on first access. |
+
+#### Returns
+
+`FlowDerivation`\<`T`\>
+
+#### Overrides
+
+[`FlowObservable`](/api/classes/FlowObservable.md).[`constructor`](/api/classes/FlowObservable.md#constructor)
+
+## 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
+
+[`FlowObservable`](/api/classes/FlowObservable.md).[`disposed`](/api/classes/FlowObservable.md#disposed)
+
+## Methods
+
+### dispose()
+
+```ts
+dispose(options?): void;
+```
+
+Defined in: [basic/signal.ts:69](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/basic/signal.ts#L69)
+
+Disposes the FlowSignal.
+Cleans up all registered effects, listeners, and dependencies.
+Once disposed, further usage of the signal will throw an error.
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `options?` | \{ `self`: `boolean`; \} |
+| `options.self?` | `boolean` |
+
+#### Returns
+
+`void`
+
+#### Throws
+
+If the FlowSignal is already disposed.
+
+#### Inherited from
+
+[`FlowObservable`](/api/classes/FlowObservable.md).[`dispose`](/api/classes/FlowObservable.md#dispose)
+
+***
+
+### get()
+
+```ts
+get(context): T;
+```
+
+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
+
+`T`
+
+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
+
+[`FlowObservable`](/api/classes/FlowObservable.md).[`get`](/api/classes/FlowObservable.md#get)
+
+***
+
+### pick()
+
+```ts
+pick(): T;
+```
+
+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
+
+`T`
+
+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
+
+[`FlowObservable`](/api/classes/FlowObservable.md).[`pick`](/api/classes/FlowObservable.md#pick)
+
+***
+
+### 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
+
+[`FlowObservable`](/api/classes/FlowObservable.md).[`subscribe`](/api/classes/FlowObservable.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
+
+[`FlowObservable`](/api/classes/FlowObservable.md).[`trigger`](/api/classes/FlowObservable.md#trigger)
+
+***
+
+### watch()
+
+```ts
+watch(context): void;
+```
+
+Defined in: [basic/derivation.ts:139](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/basic/derivation.ts#L139)
+
+Watches the derivation, registering it as a dependency in the given context.
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `context` | [`TrackingContext`](/api/classes/TrackingContext.md) | The tracking context in which to register this derivation. |
+
+#### Returns
+
+`void`
+
+#### Remarks
+
+This method overrides the base `watch()` to handle a special case: when a derivation
+is watched without having its value read (e.g., `$derivation.watch(t)` instead of
+`$derivation.get(t)`), the derivation still needs to compute its value to establish
+its own dependencies. Otherwise, the derivation would be tracked but wouldn't track
+its own dependencies, breaking the reactive chain.
+
+This override ensures that:
+1. The derivation is registered as a dependency in the provided context
+2. The derivation computes its value (if not already computed)
+3. The derivation tracks its own dependencies during computation
+
+#### Example
+
+```typescript
+const $derived = derivation((t) => $state.get(t) * 2);
+
+effect((t) => {
+  $derived.watch(t); // Derivation computes even without reading value
+  doSomething();     // Effect re-runs when $derived's dependencies change
+});
+```
+
+#### Overrides
+
+[`FlowObservable`](/api/classes/FlowObservable.md).[`watch`](/api/classes/FlowObservable.md#watch)