@ersbeth/picoflow 0.2.4 → 1.0.1

package/docs/api/functions/stream.md

@@ -0,0 +1,53 @@
+[@ersbeth/picoflow](/api/index.md) / stream
+
+# Function: stream()
+
+```ts
+function stream<T>(updater): FlowStream<T>;
+```
+
+Defined in: [creators.ts:200](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/creators.ts#L200)
+
+Creates a new reactive stream that bridges external event sources with PicoFlow's reactive system.
+
+## Type Parameters
+
+| Type Parameter | Description |
+| ------ | ------ |
+| `T` | The type of the stream value. |
+
+## Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `updater` | (`set`) => () => `void` | A function that receives a setter to update the stream's value. It should return a disposer function to clean up resources. |
+
+## Returns
+
+[`FlowStream`](/api/classes/FlowStream.md)\<`T`\>
+
+A new instance of [FlowStream](/api/classes/FlowStream.md).
+
+## Remarks
+
+Streams are ideal for integrating push-based data sources like WebSockets, DOM events,
+timers, or any event emitter. The updater sets up subscriptions and calls the setter
+when new data arrives. The returned disposer is called on cleanup.
+
+## Example
+
+```typescript
+// WebSocket stream
+const $messages = stream<string>((set) => {
+  const ws = new WebSocket('ws://example.com');
+  ws.onmessage = (e) => set(e.data);
+  return () => ws.close();
+});
+
+// Timer stream
+const $tick = stream<number>((set) => {
+  let count = 0;
+  const id = setInterval(() => set(count++), 1000);
+  return () => clearInterval(id);
+});
+```

package/docs/api/functions/streamAsync.md

@@ -0,0 +1,50 @@
+[@ersbeth/picoflow](/api/index.md) / streamAsync
+
+# Function: streamAsync()
+
+```ts
+function streamAsync<T>(updater): FlowStreamAsync<T>;
+```
+
+Defined in: [creators.ts:235](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/creators.ts#L235)
+
+Creates a new reactive asynchronous stream that always returns a Promise.
+
+## Type Parameters
+
+| Type Parameter | Description |
+| ------ | ------ |
+| `T` | The type of the stream value. |
+
+## Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `updater` | (`set`) => () => `void` | A function that receives a setter to update the stream's value. It should return a disposer function to clean up resources. |
+
+## Returns
+
+[`FlowStreamAsync`](/api/classes/FlowStreamAsync.md)\<`T`\>
+
+A new instance of [FlowStreamAsync](/api/classes/FlowStreamAsync.md).
+
+## Remarks
+
+Async streams are ideal for push-based async data sources where you want to use async/await.
+Unlike [stream](/api/functions/stream.md), this always returns a Promise that resolves to the value. The initial
+Promise is created on construction and resolves when the setter is first called.
+
+## Example
+
+```typescript
+const $asyncMessages = streamAsync<string>((set) => {
+  const ws = new WebSocket('ws://example.com');
+  ws.onmessage = (e) => set(e.data);
+  return () => ws.close();
+});
+
+effect(async (t) => {
+  const message = await $asyncMessages.get(t);
+  console.log('Received:', message);
+});
+```

package/docs/api/index.md

@@ -0,0 +1,118 @@
+# @ersbeth/picoflow
+
+# PicoFlow
+
+PicoFlow is a lightweight reactive dataflow library that provides a comprehensive set of
+reactive primitives for building reactive applications with explicit dependency tracking.
+
+## Core Concepts
+
+**Reactive Primitives:**
+- [FlowSignal](/api/classes/FlowSignal.md): Event-like notifications without values
+- [FlowState](/api/classes/FlowState.md): Mutable reactive values
+- [FlowConstant](/api/classes/FlowConstant.md): Immutable reactive values (computed once)
+- [FlowDerivation](/api/classes/FlowDerivation.md): Computed values that track dependencies
+- [FlowEffect](/api/classes/FlowEffect.md): Side effects that run when dependencies change
+
+**Advanced Primitives:**
+- [FlowArray](/api/classes/FlowArray.md): Reactive arrays with mutation tracking
+- [FlowMap](/api/classes/FlowMap.md): Reactive maps with operation tracking
+- [FlowResource](/api/classes/FlowResource.md): Async data fetching returning `T | undefined`
+- [FlowResourceAsync](/api/classes/FlowResourceAsync.md): Async data fetching returning `Promise<T>`
+- [FlowStream](/api/classes/FlowStream.md): Event streams from external sources
+- [FlowStreamAsync](/api/classes/FlowStreamAsync.md): Async event streams returning Promises
+
+**Tracking Context:**
+- [TrackingContext](/api/classes/TrackingContext.md): The core mechanism for explicit dependency tracking
+- Use `observable.get(t)` to read with tracking
+- Use `observable.pick()` to read without tracking
+- Use `signal.watch(t)` to track signals without values
+
+## Key Features
+
+- **Explicit tracking**: Full control over what triggers re-execution via TrackingContext
+- **Lazy evaluation**: Derivations compute only when accessed
+- **Fine-grained reactivity**: Track specific operations on collections
+- **Resource management**: Automatic cleanup with dispose patterns
+- **SolidJS integration**: Seamless bridge to SolidJS primitives
+
+## Basic Usage
+
+```typescript
+import { state, effect, derivation } from 'picoflow';
+
+// Create reactive state
+const $count = state(0);
+
+// Create derived value
+const $double = derivation((t) => $count.get(t) * 2);
+
+// Create effect
+effect((t) => {
+  console.log('Count:', $count.get(t), 'Double:', $double.get(t));
+});
+
+// Update state
+$count.set(1); // Logs: "Count: 1 Double: 2"
+```
+
+## See
+
+[GitHub Repository](https://github.com/yourusername/picoflow)
+
+## Classes
+
+| Class | Description |
+| ------ | ------ |
+| [FlowArray](/api/classes/FlowArray.md) | Represents a reactive array. |
+| [FlowConstant](/api/classes/FlowConstant.md) | Represents a reactive and immutable constant value that can be computed lazily upon first access. |
+| [FlowDerivation](/api/classes/FlowDerivation.md) | Represents a reactive derivation whose value is computed based on other reactive signals. |
+| [FlowEffect](/api/classes/FlowEffect.md) | Represents a reactive effect that executes side-effect functions based on its tracked dependencies. |
+| [FlowMap](/api/classes/FlowMap.md) | Represents a reactive map that extends [FlowState](/api/classes/FlowState.md) for tracking key-value pairs. |
+| [FlowObservable](/api/classes/FlowObservable.md) | Represents a reactive observable that holds and tracks a value. |
+| [FlowResource](/api/classes/FlowResource.md) | Represents a reactive resource that asynchronously fetches its value and returns `T | undefined`. |
+| [FlowResourceAsync](/api/classes/FlowResourceAsync.md) | Represents a reactive resource that asynchronously fetches its value and always returns a Promise. |
+| [FlowSignal](/api/classes/FlowSignal.md) | Represents a reactive signal. |
+| [FlowState](/api/classes/FlowState.md) | Represents a reactive state that holds a mutable value. |
+| [FlowStream](/api/classes/FlowStream.md) | Represents a reactive stream that updates its value based on an external updater function. |
+| [FlowStreamAsync](/api/classes/FlowStreamAsync.md) | Represents an asynchronous reactive stream that always returns a Promise and updates based on an updater function. |
+| [SolidDerivation](/api/classes/SolidDerivation.md) | Solid-style derivation wrapping SolidJS's createMemo, providing a computed reactive value. |
+| [SolidResource](/api/classes/SolidResource.md) | Solid-style resource wrapping SolidJS's createResource, providing async data loading with reactive state. |
+| [SolidState](/api/classes/SolidState.md) | Solid-style state container wrapping SolidJS's createSignal, providing a writable reactive signal. |
+| [TrackingContext](/api/classes/TrackingContext.md) | Represents a tracking context used to register dependencies during reactive computations. |
+
+## Interfaces
+
+| Interface | Description |
+| ------ | ------ |
+| [FlowDisposable](/api/interfaces/FlowDisposable.md) | Represents an object with a disposable lifecycle that manages resources requiring cleanup. |
+| [SolidObservable](/api/interfaces/SolidObservable.md) | Interface for a Solid-style observable value. |
+
+## Type Aliases
+
+| Type Alias | Description |
+| ------ | ------ |
+| [FlowArrayAction](/api/type-aliases/FlowArrayAction.md) | Represents the actions that can be performed on a FlowArray. |
+| [FlowStreamDisposer](/api/type-aliases/FlowStreamDisposer.md) | A function type that disposes of a resource. |
+| [FlowStreamSetter](/api/type-aliases/FlowStreamSetter.md) | A function type that sets a new value for the reactive stream. |
+| [FlowStreamUpdater](/api/type-aliases/FlowStreamUpdater.md) | A function type that updates a stream and returns a disposer for cleanup. |
+| [NotPromise](/api/type-aliases/NotPromise.md) | Utility type that excludes Promise types from T. Used to ensure type safety for synchronous derivations/resources. |
+| [SolidGetter](/api/type-aliases/SolidGetter.md) | A getter function or value for Solid state/derivation. |
+
+## Functions
+
+| Function | Description |
+| ------ | ------ |
+| [array](/api/functions/array.md) | Creates a new reactive array with mutation methods and fine-grained action tracking. |
+| [constant](/api/functions/constant.md) | Creates a new reactive constant. |
+| [derivation](/api/functions/derivation.md) | Creates a new reactive derivation whose value is computed based on other reactive signals. |
+| [effect](/api/functions/effect.md) | Creates a new reactive effect that executes a side-effect function based on its dependencies. |
+| [from](/api/functions/from.md) | Converts a FlowObservable or getter function into a Solid derivation or resource, depending on whether the value is synchronous or asynchronous. |
+| [isDisposable](/api/functions/isDisposable.md) | Type guard that checks whether an object implements the FlowDisposable interface. |
+| [map](/api/functions/map.md) | Creates a new reactive map state with fine-grained tracking of operations. |
+| [resource](/api/functions/resource.md) | Creates a new reactive resource that asynchronously fetches its value, returning `T | undefined`. |
+| [resourceAsync](/api/functions/resourceAsync.md) | Creates a new reactive asynchronous resource that always returns a Promise. |
+| [signal](/api/functions/signal.md) | Creates a new reactive signal. |
+| [state](/api/functions/state.md) | Creates a new reactive state holding a mutable value. |
+| [stream](/api/functions/stream.md) | Creates a new reactive stream that bridges external event sources with PicoFlow's reactive system. |
+| [streamAsync](/api/functions/streamAsync.md) | Creates a new reactive asynchronous stream that always returns a Promise. |

package/docs/api/interfaces/FlowDisposable.md

@@ -0,0 +1,65 @@
+[@ersbeth/picoflow](/api/index.md) / FlowDisposable
+
+# Interface: FlowDisposable
+
+Defined in: [basic/disposable.ts:35](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/basic/disposable.ts#L35)
+
+Represents an object with a disposable lifecycle that manages resources requiring cleanup.
+
+## Remarks
+
+FlowDisposable is the interface for PicoFlow primitives that hold resources needing
+explicit cleanup. Implementing this interface ensures that objects can properly release
+resources such as subscriptions, event listeners, and dependent effects.
+
+**Disposal Behavior:**
+All PicoFlow reactive primitives (signals, states, effects, derivations, etc.) implement
+this interface. When disposed:
+- The primitive becomes unusable and throws errors on further access
+- All subscriptions and dependencies are cleaned up
+- Memory is freed for garbage collection
+
+**Options:**
+The optional `options` parameter controls disposal behavior:
+- `{ self: true }`: Dispose only this object, leaving dependent effects/listeners active
+- `{ self: false }` or omitted: Dispose this object AND all dependent effects/listeners (cascade)
+
+## Example
+
+```typescript
+const $state = state(0);
+const fx = effect((t) => console.log($state.get(t)));
+
+// Cascade disposal - disposes $state and all its effects
+$state.dispose();
+
+// Self-only disposal - disposes $state but leaves effects intact
+$state.dispose({ self: true });
+```
+
+## Methods
+
+### dispose()
+
+```ts
+dispose(options?): void;
+```
+
+Defined in: [basic/disposable.ts:45](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/basic/disposable.ts#L45)
+
+Disposes resources held by this object.
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `options?` | \{ `self`: `boolean`; \} | Optional configuration for disposal behavior. |
+| `options.self?` | `boolean` | When true, disposes only this object without cascading to dependents. When false or omitted, disposes this object and all its dependent effects and listeners. |
+
+#### Returns
+
+`void`
+
+#### Throws
+
+Error if the object has already been disposed (behavior may vary by implementation).

package/docs/api/interfaces/SolidObservable.md

@@ -0,0 +1,19 @@
+[@ersbeth/picoflow](/api/index.md) / SolidObservable
+
+# Interface: SolidObservable\<T\>
+
+Defined in: [solid/primitives.ts:22](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/solid/primitives.ts#L22)
+
+Interface for a Solid-style observable value.
+
+## Type Parameters
+
+| Type Parameter | Description |
+| ------ | ------ |
+| `T` | The value type. |
+
+## Properties
+
+| Property | Type | Description | Defined in |
+| ------ | ------ | ------ | ------ |
+| <a id="get"></a> `get` | () => `T` | Returns the current value. | [solid/primitives.ts:26](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/solid/primitives.ts#L26) |

package/docs/api/type-aliases/FlowArrayAction.md

@@ -0,0 +1,49 @@
+[@ersbeth/picoflow](/api/index.md) / FlowArrayAction
+
+# Type Alias: FlowArrayAction\<T\>
+
+```ts
+type FlowArrayAction<T> = 
+  | {
+  items: T[];
+  type: "set";
+}
+  | {
+  index: number;
+  item: T;
+  type: "setItem";
+}
+  | {
+  item: T;
+  type: "push";
+}
+  | {
+  type: "pop";
+}
+  | {
+  item: T;
+  type: "unshift";
+}
+  | {
+  type: "shift";
+}
+  | {
+  deleteCount: number;
+  items: T[];
+  start: number;
+  type: "splice";
+}
+  | {
+  type: "clear";
+};
+```
+
+Defined in: [advanced/array.ts:8](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/advanced/array.ts#L8)
+
+Represents the actions that can be performed on a FlowArray.
+
+## Type Parameters
+
+| Type Parameter |
+| ------ |
+| `T` |

package/docs/api/type-aliases/FlowStreamDisposer.md

@@ -0,0 +1,15 @@
+[@ersbeth/picoflow](/api/index.md) / FlowStreamDisposer
+
+# Type Alias: FlowStreamDisposer()
+
+```ts
+type FlowStreamDisposer = () => void;
+```
+
+Defined in: [advanced/stream.ts:14](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/advanced/stream.ts#L14)
+
+A function type that disposes of a resource.
+
+## Returns
+
+`void`

package/docs/api/type-aliases/FlowStreamSetter.md

@@ -0,0 +1,27 @@
+[@ersbeth/picoflow](/api/index.md) / FlowStreamSetter
+
+# Type Alias: FlowStreamSetter()\<T\>
+
+```ts
+type FlowStreamSetter<T> = (value) => void;
+```
+
+Defined in: [advanced/stream.ts:8](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/advanced/stream.ts#L8)
+
+A function type that sets a new value for the reactive stream.
+
+## Type Parameters
+
+| Type Parameter | Description |
+| ------ | ------ |
+| `T` | The type of the value. |
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `value` | `T` |
+
+## Returns
+
+`void`

package/docs/api/type-aliases/FlowStreamUpdater.md

@@ -0,0 +1,32 @@
+[@ersbeth/picoflow](/api/index.md) / FlowStreamUpdater
+
+# Type Alias: FlowStreamUpdater()\<T\>
+
+```ts
+type FlowStreamUpdater<T> = (set) => FlowStreamDisposer;
+```
+
+Defined in: [advanced/stream.ts:24](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/advanced/stream.ts#L24)
+
+A function type that updates a stream and returns a disposer for cleanup.
+
+## Type Parameters
+
+| Type Parameter | Description |
+| ------ | ------ |
+| `T` | The type of the stream value. |
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `set` | [`FlowStreamSetter`](/api/type-aliases/FlowStreamSetter.md)\<`T`\> |
+
+## Returns
+
+[`FlowStreamDisposer`](/api/type-aliases/FlowStreamDisposer.md)
+
+## Remarks
+
+The updater receives a setter function to update the stream's value.
+It should return a disposer function to release any resources or subscriptions.

package/docs/api/type-aliases/NotPromise.md

@@ -0,0 +1,18 @@
+[@ersbeth/picoflow](/api/index.md) / NotPromise
+
+# Type Alias: NotPromise\<T\>
+
+```ts
+type NotPromise<T> = T extends Promise<unknown> ? never : T;
+```
+
+Defined in: [solid/converters.ts:149](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/solid/converters.ts#L149)
+
+Utility type that excludes Promise types from T.
+Used to ensure type safety for synchronous derivations/resources.
+
+## Type Parameters
+
+| Type Parameter |
+| ------ |
+| `T` |

package/docs/api/type-aliases/SolidGetter.md

@@ -0,0 +1,17 @@
+[@ersbeth/picoflow](/api/index.md) / SolidGetter
+
+# Type Alias: SolidGetter\<T\>
+
+```ts
+type SolidGetter<T> = (previous) => T | T;
+```
+
+Defined in: [solid/primitives.ts:14](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/solid/primitives.ts#L14)
+
+A getter function or value for Solid state/derivation.
+
+## Type Parameters
+
+| Type Parameter | Description |
+| ------ | ------ |
+| `T` | The value type. |

package/docs/api/typedoc-sidebar.json

@@ -0,0 +1 @@
+[{"text":"Classes","collapsed":true,"items":[{"text":"FlowArray","link":"/api/classes/FlowArray.md"},{"text":"FlowConstant","link":"/api/classes/FlowConstant.md"},{"text":"FlowDerivation","link":"/api/classes/FlowDerivation.md"},{"text":"FlowEffect","link":"/api/classes/FlowEffect.md"},{"text":"FlowMap","link":"/api/classes/FlowMap.md"},{"text":"FlowObservable","link":"/api/classes/FlowObservable.md"},{"text":"FlowResource","link":"/api/classes/FlowResource.md"},{"text":"FlowResourceAsync","link":"/api/classes/FlowResourceAsync.md"},{"text":"FlowSignal","link":"/api/classes/FlowSignal.md"},{"text":"FlowState","link":"/api/classes/FlowState.md"},{"text":"FlowStream","link":"/api/classes/FlowStream.md"},{"text":"FlowStreamAsync","link":"/api/classes/FlowStreamAsync.md"},{"text":"SolidDerivation","link":"/api/classes/SolidDerivation.md"},{"text":"SolidResource","link":"/api/classes/SolidResource.md"},{"text":"SolidState","link":"/api/classes/SolidState.md"},{"text":"TrackingContext","link":"/api/classes/TrackingContext.md"}]},{"text":"Interfaces","collapsed":true,"items":[{"text":"FlowDisposable","link":"/api/interfaces/FlowDisposable.md"},{"text":"SolidObservable","link":"/api/interfaces/SolidObservable.md"}]},{"text":"Type Aliases","collapsed":true,"items":[{"text":"FlowArrayAction","link":"/api/type-aliases/FlowArrayAction.md"},{"text":"FlowStreamDisposer","link":"/api/type-aliases/FlowStreamDisposer.md"},{"text":"FlowStreamSetter","link":"/api/type-aliases/FlowStreamSetter.md"},{"text":"FlowStreamUpdater","link":"/api/type-aliases/FlowStreamUpdater.md"},{"text":"NotPromise","link":"/api/type-aliases/NotPromise.md"},{"text":"SolidGetter","link":"/api/type-aliases/SolidGetter.md"}]},{"text":"Functions","collapsed":true,"items":[{"text":"array","link":"/api/functions/array.md"},{"text":"constant","link":"/api/functions/constant.md"},{"text":"derivation","link":"/api/functions/derivation.md"},{"text":"effect","link":"/api/functions/effect.md"},{"text":"from","link":"/api/functions/from.md"},{"text":"isDisposable","link":"/api/functions/isDisposable.md"},{"text":"map","link":"/api/functions/map.md"},{"text":"resource","link":"/api/functions/resource.md"},{"text":"resourceAsync","link":"/api/functions/resourceAsync.md"},{"text":"signal","link":"/api/functions/signal.md"},{"text":"state","link":"/api/functions/state.md"},{"text":"stream","link":"/api/functions/stream.md"},{"text":"streamAsync","link":"/api/functions/streamAsync.md"}]}]