@ersbeth/picoflow 1.1.2 → 2.0.0

package/docs/api/classes/FlowConstant.md

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

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