@ersbeth/picoflow 2.0.2 → 2.1.0

package/docs/.vitepress/config.mts

@@ -1,145 +0,0 @@
-import { defineConfig } from "vitepress";
-import { withMermaid } from "vitepress-plugin-mermaid";
-import typedocSidebar from "../api/typedoc-sidebar.json";
-
-export default withMermaid(
-    defineConfig({
-        title: "PicoFlow",
-        description: "Lightweight reactive dataflow library for TypeScript",
-        base: "/picoflow/",
-
-        mermaid: {},
-
-        head: [["link", { rel: "icon", type: "image/svg+xml", href: "/logo.svg" }]],
-
-        themeConfig: {
-            logo: "/logo.svg",
-
-            nav: [
-                { text: "Guide", link: "/guide/introduction/getting-started" },
-                // { text: "Examples", link: "/examples/patterns" },
-                { text: "API Reference", link: "/api/" },
-            ],
-
-            sidebar: {
-                "/guide/": [
-                    {
-                        text: "Introduction",
-                        items: [
-                            {
-                                text: "Getting Started",
-                                link: "/guide/introduction/getting-started",
-                            },
-                            {
-                                text: "Conventions",
-                                link: "/guide/introduction/conventions",
-                            },
-                            {
-                                text: "Concepts",
-                                link: "/guide/introduction/concepts",
-                            },
-                        ],
-                    },
-                    {
-                        text: "Primitives",
-                        items: [
-                            {
-                                text: "Overview",
-                                link: "/guide/primitives/overview",
-                            },
-                            {
-                                text: "Signals",
-                                link: "/guide/primitives/signal",
-                            },
-                            { text: "Constants", link: "/guide/primitives/constant" },
-
-                            { text: "States", link: "/guide/primitives/state" },
-                            {
-                                text: "Derivations",
-                                link: "/guide/primitives/derivations",
-                            },
-                            { text: "Maps", link: "/guide/primitives/map" },
-                            { text: "Arrays", link: "/guide/primitives/array" },
-                            {
-                                text: "Side Effects",
-                                link: "/guide/primitives/effects",
-                            },
-                        ],
-                    },
-                    {
-                        text: "Advanced",
-                        items: [
-                            {
-                                text: "Use with SolidJS",
-                                link: "/guide/advanced/solidjs",
-                            },
-                            {
-                                text: "Upgrade to v2",
-                                link: "/guide/advanced/migration-v2",
-                            },
-                            {
-                                text: "Upgrade to v1",
-                                link: "/guide/advanced/migration-v1",
-                            },
-                            // {
-                            //     text: "Lifecycle",
-                            //     link: "/guide/introduction/lifecycle",
-                            // },
-                            // {
-                            //     text: "Disposal",
-                            //     link: "/guide/advanced/disposal",
-                            // },
-                            // {
-                            //     text: "Architecture",
-                            //     link: "/guide/advanced/architecture",
-                            // },
-                        ],
-                    },
-                ],
-
-                // "/examples/": [
-                //     {
-                //         text: "Examples",
-                //         items: [
-                //             {
-                //                 text: "Common Patterns",
-                //                 link: "/examples/patterns",
-                //             },
-                //             {
-                //                 text: "Code Examples",
-                //                 link: "/examples/examples",
-                //             },
-                //         ],
-                //     },
-                // ],
-
-                "/api/": [
-                    {
-                        text: "API Reference",
-                        items: typedocSidebar,
-                    },
-                ],
-            },
-
-            socialLinks: [
-                {
-                    icon: "gitlab",
-                    link: "https://gitlab.com/ersbeth-web/picoflow",
-                },
-            ],
-
-            search: {
-                provider: "local",
-            },
-
-            editLink: {
-                pattern: "https://gitlab.com/ersbeth-web/picoflow/-/edit/main/docs/:path",
-                text: "Edit this page on GitLab",
-            },
-
-            footer: {
-                copyright: "Copyright ©2025 <a href='https://gitlab.com/ersbeth/'>Ersbeth</a>",
-            },
-        },
-    }),
-);

package/docs/api/functions/array.md

@@ -1,35 +0,0 @@
-[@ersbeth/picoflow](/api/index.md) / array
-
-# Function: array()
-
-```ts
-function array<T>(initial?): FlowArray<T>;
-```
-
-Defined in: [api/nodes/collections/flowArray.ts:153](https://gitlab.com/ersbeth-web/picoflow/-/blob/4e864254f0eac72524c3be40b9e41d799a16e020/src/api/nodes/collections/flowArray.ts#L153)
-
-Creates a reactive array with mutation methods and fine-grained action tracking.
-
-The array starts with the provided initial items (or empty if none provided). All mutation methods
-(push, pop, splice, etc.) notify dependents and emit detailed action information to `$lastAction`.
-Use the array itself for coarse-grained reactivity, or subscribe to `$lastAction` for fine-grained
-reactivity to specific mutation types. Useful for reactive lists, collections, or any data that
-needs array-like operations with automatic change propagation.
-
-## Type Parameters
-
-| Type Parameter |
-| ------ |
-| `T` |
-
-## Parameters
-
-| Parameter | Type | Description |
-| ------ | ------ | ------ |
-| `initial?` | `T`[] | Optional initial array of items |
-
-## Returns
-
-[`FlowArray`](/api/interfaces/FlowArray.md)\<`T`\>
-
-A FlowArray with reactive mutation methods

package/docs/api/functions/constant.md

@@ -1,33 +0,0 @@
-[@ersbeth/picoflow](/api/index.md) / constant
-
-# Function: constant()
-
-```ts
-function constant<T>(initializer): FlowConstant<T>;
-```
-
-Defined in: [api/nodes/sync/flowConstant.ts:31](https://gitlab.com/ersbeth-web/picoflow/-/blob/4e864254f0eac72524c3be40b9e41d799a16e020/src/api/nodes/sync/flowConstant.ts#L31)
-
-Creates a constant reactive value that initializes lazily and never recomputes.
-
-The initializer function runs once on first access, and the result is cached permanently.
-Unlike state or derivations, constants never react to changes - they represent immutable values
-in the reactive graph. Useful for expensive one-time computations or static configuration.
-
-## Type Parameters
-
-| Type Parameter |
-| ------ |
-| `T` |
-
-## Parameters
-
-| Parameter | Type | Description |
-| ------ | ------ | ------ |
-| `initializer` | [`InitFunction`](/api/type-aliases/InitFunction.md)\<`T`\> | Function that computes the constant value on first access |
-
-## Returns
-
-[`FlowConstant`](/api/interfaces/FlowConstant.md)\<`T`\>
-
-A FlowConstant that provides read-only access to the cached value

package/docs/api/functions/constantAsync.md

@@ -1,69 +0,0 @@
-[@ersbeth/picoflow](/api/index.md) / constantAsync
-
-# Function: constantAsync()
-
-## Call Signature
-
-```ts
-function constantAsync<T>(value): FlowConstantAsync<T>;
-```
-
-Defined in: [api/nodes/async/flowConstantAsync.ts:32](https://gitlab.com/ersbeth-web/picoflow/-/blob/4e864254f0eac72524c3be40b9e41d799a16e020/src/api/nodes/async/flowConstantAsync.ts#L32)
-
-Creates a constant reactive value from a promise or async initializer that resolves once and never recomputes.
-
-The promise or async initializer executes once on first access, and the resolved value is cached permanently.
-While the promise is pending, any reactive computation that accesses the value will receive PendingError and
-automatically retry once the promise resolves. Use for one-time async operations that don't depend on other
-reactive values, such as loading configuration or fetching initial data.
-
-### Type Parameters
-
-| Type Parameter |
-| ------ |
-| `T` |
-
-### Parameters
-
-| Parameter | Type | Description |
-| ------ | ------ | ------ |
-| `value` | `Promise`\<`T`\> | Promise to resolve, or async function that returns a promise on first access |
-
-### Returns
-
-[`FlowConstantAsync`](/api/interfaces/FlowConstantAsync.md)\<`T`\>
-
-A FlowConstantAsync that provides read-only access to the resolved value
-
-## Call Signature
-
-```ts
-function constantAsync<T>(initializer): FlowConstantAsync<T>;
-```
-
-Defined in: [api/nodes/async/flowConstantAsync.ts:33](https://gitlab.com/ersbeth-web/picoflow/-/blob/4e864254f0eac72524c3be40b9e41d799a16e020/src/api/nodes/async/flowConstantAsync.ts#L33)
-
-Creates a constant reactive value from a promise or async initializer that resolves once and never recomputes.
-
-The promise or async initializer executes once on first access, and the resolved value is cached permanently.
-While the promise is pending, any reactive computation that accesses the value will receive PendingError and
-automatically retry once the promise resolves. Use for one-time async operations that don't depend on other
-reactive values, such as loading configuration or fetching initial data.
-
-### Type Parameters
-
-| Type Parameter |
-| ------ |
-| `T` |
-
-### Parameters
-
-| Parameter | Type |
-| ------ | ------ |
-| `initializer` | [`InitFunctionAsync`](/api/type-aliases/InitFunctionAsync.md)\<`T`\> |
-
-### Returns
-
-[`FlowConstantAsync`](/api/interfaces/FlowConstantAsync.md)\<`T`\>
-
-A FlowConstantAsync that provides read-only access to the resolved value

package/docs/api/functions/derivation.md

@@ -1,34 +0,0 @@
-[@ersbeth/picoflow](/api/index.md) / derivation
-
-# Function: derivation()
-
-```ts
-function derivation<T>(compute): FlowDerivation<T>;
-```
-
-Defined in: [api/nodes/sync/flowDerivation.ts:39](https://gitlab.com/ersbeth-web/picoflow/-/blob/4e864254f0eac72524c3be40b9e41d799a16e020/src/api/nodes/sync/flowDerivation.ts#L39)
-
-Creates a derived reactive value that automatically recomputes when dependencies change.
-
-The compute function runs when any tracked dependency changes, and the result is cached until the next change.
-Access reactive values within the compute function to establish dependencies automatically. The derivation
-computes lazily on first access and then reactively thereafter. Use for derived data that should stay
-synchronized with source state.
-
-## Type Parameters
-
-| Type Parameter |
-| ------ |
-| `T` |
-
-## Parameters
-
-| Parameter | Type | Description |
-| ------ | ------ | ------ |
-| `compute` | [`DerivationFunction`](/api/type-aliases/DerivationFunction.md)\<`T`\> | Function that accesses dependencies and computes the derived value |
-
-## Returns
-
-[`FlowDerivation`](/api/interfaces/FlowDerivation.md)\<`T`\>
-
-A FlowDerivation that provides read-only access to the computed value

package/docs/api/functions/derivationAsync.md

@@ -1,34 +0,0 @@
-[@ersbeth/picoflow](/api/index.md) / derivationAsync
-
-# Function: derivationAsync()
-
-```ts
-function derivationAsync<T>(compute): FlowDerivationAsync<T>;
-```
-
-Defined in: [api/nodes/async/flowDerivationAsync.ts:40](https://gitlab.com/ersbeth-web/picoflow/-/blob/4e864254f0eac72524c3be40b9e41d799a16e020/src/api/nodes/async/flowDerivationAsync.ts#L40)
-
-Creates an async derived value that automatically recomputes when dependencies change.
-
-The async compute function tracks dependencies and returns a promise. When any tracked dependency changes,
-the function runs again and returns a new promise. The resolved value is cached until the next change.
-While the promise is pending, reactive computations that access this value receive PendingError and automatically
-retry once resolved. Use for derived data from async sources like filtered API results or computed database queries.
-
-## Type Parameters
-
-| Type Parameter |
-| ------ |
-| `T` |
-
-## Parameters
-
-| Parameter | Type | Description |
-| ------ | ------ | ------ |
-| `compute` | [`DerivationFunctionAsync`](/api/type-aliases/DerivationFunctionAsync.md)\<`T`\> | Async function that accesses dependencies and returns a promise of the derived value |
-
-## Returns
-
-[`FlowDerivationAsync`](/api/interfaces/FlowDerivationAsync.md)\<`T`\>
-
-A FlowDerivationAsync that provides read-only access to the resolved computed value

package/docs/api/functions/from.md

@@ -1,129 +0,0 @@
-[@ersbeth/picoflow](/api/index.md) / from
-
-# Function: from()
-
-## Call Signature
-
-```ts
-function from<T>(flow): Resource<T>;
-```
-
-Defined in: [converters/solid.ts:97](https://gitlab.com/ersbeth-web/picoflow/-/blob/4e864254f0eac72524c3be40b9e41d799a16e020/src/converters/solid.ts#L97)
-
-Converts a PicoFlow observable or getter function into a SolidJS resource.
-
-### Type Parameters
-
-| Type Parameter |
-| ------ |
-| `T` |
-
-### Parameters
-
-| Parameter | Type | Description |
-| ------ | ------ | ------ |
-| `flow` | [`FlowObservable`](/api/interfaces/FlowObservable.md)\<`T`\> | The FlowObservable or getter function to convert. |
-
-### Returns
-
-`Resource`\<`T`\>
-
-A SolidJS Resource that wraps the value or computation.
-
-### Remarks
-
-This function bridges PicoFlow's reactive system with SolidJS, allowing you to use
-PicoFlow primitives and computations within Solid components. All conversions return a
-SolidJS Resource, which can handle both synchronous and asynchronous values seamlessly.
-
-The conversion works with:
-- **FlowObservable**: Any PicoFlow reactive primitive (e.g., from `state()`, `derivation()`, `stateAsync()`, `derivationAsync()`)
-- **Getter functions**: Computation functions that use a FlowTracker to access reactive values
-
-The created Resource automatically subscribes to the PicoFlow observables and updates
-when their values change. The subscription is properly cleaned up when the Solid
-component unmounts.
-
-### Example
-
-```typescript
-import { from } from 'picoflow/solid';
-import { state, derivation } from 'picoflow';
-
-// Convert a PicoFlow state to a Solid resource
-const $count = state(0);
-const solidCount = from($count);
-
-// Use in a Solid component
-function Counter() {
-  return <div>Count: {solidCount()}</div>;
-}
-
-// Or convert a computation function
-const solidDerived = from((t) => {
-  return $count.get(t) * 2;
-});
-```
-
-## Call Signature
-
-```ts
-function from<T>(flow): Resource<T>;
-```
-
-Defined in: [converters/solid.ts:98](https://gitlab.com/ersbeth-web/picoflow/-/blob/4e864254f0eac72524c3be40b9e41d799a16e020/src/converters/solid.ts#L98)
-
-Converts a PicoFlow observable or getter function into a SolidJS resource.
-
-### Type Parameters
-
-| Type Parameter |
-| ------ |
-| `T` |
-
-### Parameters
-
-| Parameter | Type | Description |
-| ------ | ------ | ------ |
-| `flow` | (`t`) => [`NotPromise`](/api/type-aliases/NotPromise.md)\<`T`\> | The FlowObservable or getter function to convert. |
-
-### Returns
-
-`Resource`\<`T`\>
-
-A SolidJS Resource that wraps the value or computation.
-
-### Remarks
-
-This function bridges PicoFlow's reactive system with SolidJS, allowing you to use
-PicoFlow primitives and computations within Solid components. All conversions return a
-SolidJS Resource, which can handle both synchronous and asynchronous values seamlessly.
-
-The conversion works with:
-- **FlowObservable**: Any PicoFlow reactive primitive (e.g., from `state()`, `derivation()`, `stateAsync()`, `derivationAsync()`)
-- **Getter functions**: Computation functions that use a FlowTracker to access reactive values
-
-The created Resource automatically subscribes to the PicoFlow observables and updates
-when their values change. The subscription is properly cleaned up when the Solid
-component unmounts.
-
-### Example
-
-```typescript
-import { from } from 'picoflow/solid';
-import { state, derivation } from 'picoflow';
-
-// Convert a PicoFlow state to a Solid resource
-const $count = state(0);
-const solidCount = from($count);
-
-// Use in a Solid component
-function Counter() {
-  return <div>Count: {solidCount()}</div>;
-}
-
-// Or convert a computation function
-const solidDerived = from((t) => {
-  return $count.get(t) * 2;
-});
-```

package/docs/api/functions/isDisposable.md

@@ -1,27 +0,0 @@
-[@ersbeth/picoflow](/api/index.md) / isDisposable
-
-# Function: isDisposable()
-
-```ts
-function isDisposable(obj): obj is FlowDisposable;
-```
-
-Defined in: [api/base/flowDisposable.ts:42](https://gitlab.com/ersbeth-web/picoflow/-/blob/4e864254f0eac72524c3be40b9e41d799a16e020/src/api/base/flowDisposable.ts#L42)
-
-Type guard to check if an object implements the FlowDisposable interface.
-
-Useful for conditionally disposing objects that may or may not be disposable,
-such as when cleaning up mixed collections of values. Returns true if the object
-has a `dispose` method, providing type-safe access to disposal functionality.
-
-## Parameters
-
-| Parameter | Type | Description |
-| ------ | ------ | ------ |
-| `obj` | `unknown` | The object to check |
-
-## Returns
-
-`obj is FlowDisposable`
-
-True if the object implements FlowDisposable, false otherwise

package/docs/api/functions/map.md

@@ -1,36 +0,0 @@
-[@ersbeth/picoflow](/api/index.md) / map
-
-# Function: map()
-
-```ts
-function map<K, V>(initial?): FlowMap<K, V>;
-```
-
-Defined in: [api/nodes/collections/flowMap.ts:110](https://gitlab.com/ersbeth-web/picoflow/-/blob/4e864254f0eac72524c3be40b9e41d799a16e020/src/api/nodes/collections/flowMap.ts#L110)
-
-Creates a reactive map with mutation methods and fine-grained action tracking.
-
-The map starts with the provided initial entries (or empty if none provided). All mutation methods
-(add, update, delete) notify dependents and emit detailed action information to `$lastAction`.
-Use the map itself for coarse-grained reactivity, or subscribe to `$lastAction` for fine-grained
-reactivity to specific mutation types. Useful for entity stores, lookup tables, or any key-value
-data that needs reactive updates.
-
-## Type Parameters
-
-| Type Parameter |
-| ------ |
-| `K` *extends* `string` \| `number` \| `symbol` |
-| `V` |
-
-## Parameters
-
-| Parameter | Type | Description |
-| ------ | ------ | ------ |
-| `initial?` | `Record`\<`K`, `V`\> \| `Map`\<`K`, `V`\> | Optional initial entries as a Record or Map |
-
-## Returns
-
-[`FlowMap`](/api/interfaces/FlowMap.md)\<`K`, `V`\>
-
-A FlowMap with reactive mutation methods

package/docs/api/functions/signal.md

@@ -1,21 +0,0 @@
-[@ersbeth/picoflow](/api/index.md) / signal
-
-# Function: signal()
-
-```ts
-function signal(): FlowSignal;
-```
-
-Defined in: [api/nodes/flowSignal.ts:26](https://gitlab.com/ersbeth-web/picoflow/-/blob/4e864254f0eac72524c3be40b9e41d799a16e020/src/api/nodes/flowSignal.ts#L26)
-
-Creates a signal that can be manually triggered to notify dependents.
-
-Signals act as event emitters in the reactive graph. Call `trigger()` to notify all subscribers
-and reactive computations that depend on the signal. Unlike state or derivations, signals don't
-carry data values - they simply represent that an event occurred.
-
-## Returns
-
-[`FlowSignal`](/api/interfaces/FlowSignal.md)
-
-A FlowSignal that can be triggered manually and subscribed to

package/docs/api/functions/state.md

@@ -1,67 +0,0 @@
-[@ersbeth/picoflow](/api/index.md) / state
-
-# Function: state()
-
-## Call Signature
-
-```ts
-function state<T>(value): FlowState<T>;
-```
-
-Defined in: [api/nodes/sync/flowState.ts:41](https://gitlab.com/ersbeth-web/picoflow/-/blob/4e864254f0eac72524c3be40b9e41d799a16e020/src/api/nodes/sync/flowState.ts#L41)
-
-Creates a mutable reactive state that can be read and updated imperatively.
-
-State can be initialized with a direct value or a lazy initializer function. Changes propagate
-automatically to all reactive computations that depend on this state. Use state for data that
-changes through user actions, external events, or application logic rather than derived computations.
-
-### Type Parameters
-
-| Type Parameter |
-| ------ |
-| `T` |
-
-### Parameters
-
-| Parameter | Type | Description |
-| ------ | ------ | ------ |
-| `value` | [`NotPromise`](/api/type-aliases/NotPromise.md)\<`T`\> | Initial value for the state, or lazy initializer function |
-
-### Returns
-
-[`FlowState`](/api/interfaces/FlowState.md)\<`T`\>
-
-A FlowState that can be read and modified
-
-## Call Signature
-
-```ts
-function state<T>(initializer): FlowState<T>;
-```
-
-Defined in: [api/nodes/sync/flowState.ts:42](https://gitlab.com/ersbeth-web/picoflow/-/blob/4e864254f0eac72524c3be40b9e41d799a16e020/src/api/nodes/sync/flowState.ts#L42)
-
-Creates a mutable reactive state that can be read and updated imperatively.
-
-State can be initialized with a direct value or a lazy initializer function. Changes propagate
-automatically to all reactive computations that depend on this state. Use state for data that
-changes through user actions, external events, or application logic rather than derived computations.
-
-### Type Parameters
-
-| Type Parameter |
-| ------ |
-| `T` |
-
-### Parameters
-
-| Parameter | Type |
-| ------ | ------ |
-| `initializer` | [`InitFunction`](/api/type-aliases/InitFunction.md)\<`T`\> |
-
-### Returns
-
-[`FlowState`](/api/interfaces/FlowState.md)\<`T`\>
-
-A FlowState that can be read and modified