@ersbeth/picoflow 1.1.2 → 2.0.0

package/dist/types/nodes/valueSyncNode.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=valueSyncNode.d.ts.map

package/dist/types/nodes/valueSyncNode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"valueSyncNode.d.ts","sourceRoot":"","sources":["../../../src/nodes/valueSyncNode.ts"],"names":[],"mappings":""}

package/dist/types/schedulers/asyncResolver.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=asyncResolver.d.ts.map

package/dist/types/schedulers/asyncResolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"asyncResolver.d.ts","sourceRoot":"","sources":["../../../src/schedulers/asyncResolver.ts"],"names":[],"mappings":""}

package/dist/types/schedulers/asyncScheduler.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=asyncScheduler.d.ts.map

package/dist/types/schedulers/asyncScheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"asyncScheduler.d.ts","sourceRoot":"","sources":["../../../src/schedulers/asyncScheduler.ts"],"names":[],"mappings":""}

package/dist/types/schedulers/index.d.ts

@@ -0,0 +1,5 @@
+export * from './asyncScheduler';
+export * from './pendingError';
+export * from './scheduler';
+export * from './syncScheduler';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/schedulers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/schedulers/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC"}

package/dist/types/schedulers/pendingError.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=pendingError.d.ts.map

package/dist/types/schedulers/pendingError.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pendingError.d.ts","sourceRoot":"","sources":["../../../src/schedulers/pendingError.ts"],"names":[],"mappings":""}

package/dist/types/schedulers/scheduler.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=scheduler.d.ts.map

package/dist/types/schedulers/scheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.d.ts","sourceRoot":"","sources":["../../../src/schedulers/scheduler.ts"],"names":[],"mappings":""}

package/dist/types/schedulers/syncResolver.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=syncResolver.d.ts.map

package/dist/types/schedulers/syncResolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"syncResolver.d.ts","sourceRoot":"","sources":["../../../src/schedulers/syncResolver.ts"],"names":[],"mappings":""}

package/dist/types/schedulers/syncScheduler.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=syncScheduler.d.ts.map

package/dist/types/schedulers/syncScheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"syncScheduler.d.ts","sourceRoot":"","sources":["../../../src/schedulers/syncScheduler.ts"],"names":[],"mappings":""}

package/docs/.vitepress/config.mts

@@ -3,108 +3,143 @@ 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/",
+    defineConfig({
+        title: "PicoFlow",
+        description: "Lightweight reactive dataflow library for TypeScript",
+        base: "/picoflow/",
 
-		mermaid: {},
+        mermaid: {},
 
-		head: [["link", { rel: "icon", type: "image/svg+xml", href: "/logo.svg" }]],
+        head: [["link", { rel: "icon", type: "image/svg+xml", href: "/logo.svg" }]],
 
-		themeConfig: {
-			logo: "/logo.svg",
+        themeConfig: {
+            logo: "/logo.svg",
 
-			nav: [
-				{ text: "Guide", link: "/guide/introduction/getting-started" },
-				{ text: "Examples", link: "/examples/patterns" },
-				{ text: "API Reference", link: "/api/" },
-			],
+            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: "Lifecycle", link: "/guide/introduction/lifecycle" },
-						],
-					},
-					{
-						text: "Primitives",
-						items: [
-							{ text: "Overview", link: "/guide/primitives/overview" },
-							{ text: "Signals", link: "/guide/primitives/signal" },
-							{ text: "States", link: "/guide/primitives/state" },
-							{ text: "Derivations", link: "/guide/primitives/derivations" },
-							{ text: "Effects", link: "/guide/primitives/effects" },
-							// { text: "Resources", link: "/guide/primitives/resources" },
-							// { text: "Streams", link: "/guide/primitives/streams" },
-							{ text: "Maps", link: "/guide/primitives/map" },
-							{ text: "Arrays", link: "/guide/primitives/array" },
-							// { text: "Constants", link: "/guide/primitives/constant" },
-						],
-					},
-					{
-						text: "Advanced",
-						items: [
-							{
-								text: "Disposal",
-								link: "/guide/advanced/disposal",
-							},
-							{
-								text: "Use with SolidJS",
-								link: "/guide/advanced/solidjs",
-							},
-							{
-								text: "Upgrade from v0.x",
-								link: "/guide/advanced/upgrading",
-							},
-						],
-					},
-				],
+            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" },
 
-				"/examples/": [
-					{
-						text: "Examples",
-						items: [
-							{ text: "Common Patterns", link: "/examples/patterns" },
-							{ text: "Code Examples", link: "/examples/examples" },
-						],
-					},
-				],
+                            { 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",
+                            // },
+                        ],
+                    },
+                ],
 
-				"/api/": [
-					{
-						text: "API Reference",
-						items: typedocSidebar,
-					},
-				],
-			},
+                // "/examples/": [
+                //     {
+                //         text: "Examples",
+                //         items: [
+                //             {
+                //                 text: "Common Patterns",
+                //                 link: "/examples/patterns",
+                //             },
+                //             {
+                //                 text: "Code Examples",
+                //                 link: "/examples/examples",
+                //             },
+                //         ],
+                //     },
+                // ],
 
-			socialLinks: [
-				{ icon: "gitlab", link: "https://gitlab.com/ersbeth-web/picoflow" },
-			],
+                "/api/": [
+                    {
+                        text: "API Reference",
+                        items: typedocSidebar,
+                    },
+                ],
+            },
 
-			search: {
-				provider: "local",
-			},
+            socialLinks: [
+                {
+                    icon: "gitlab",
+                    link: "https://gitlab.com/ersbeth-web/picoflow",
+                },
+            ],
 
-			editLink: {
-				pattern:
-					"https://gitlab.com/ersbeth-web/picoflow/-/edit/main/docs/:path",
-				text: "Edit this page on GitLab",
-			},
+            search: {
+                provider: "local",
+            },
 
-			footer: {
-				copyright:
-					"Copyright ©2025 <a href='https://gitlab.com/ersbeth/'>Ersbeth</a>",
-			},
-		},
-	}),
+            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

@@ -6,53 +6,30 @@
 function array<T>(initial?): FlowArray<T>;
 ```
 
-Defined in: [creators.ts:393](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/creators.ts#L393)
+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 new reactive array with mutation methods and fine-grained action tracking.
+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 | Description |
-| ------ | ------ |
-| `T` | The type of the array elements. |
+| Type Parameter |
+| ------ |
+| `T` |
 
 ## Parameters
 
 | Parameter | Type | Description |
 | ------ | ------ | ------ |
-| `initial?` | `T`[] | An optional array of initial values. |
+| `initial?` | `T`[] | Optional initial array of items |
 
 ## Returns
 
-[`FlowArray`](/api/classes/FlowArray.md)\<`T`\>
-
-A new instance of [FlowArray](/api/classes/FlowArray.md).
-
-## Remarks
-
-A reactive array provides array-like mutation methods (push, pop, shift, unshift, splice)
-and tracks the last operation performed via `$lastAction`. This enables both whole-array
-reactivity and fine-grained tracking of specific mutations.
-
-The array automatically disposes disposable items when they are removed (if they implement
-the FlowDisposable interface).
+[`FlowArray`](/api/interfaces/FlowArray.md)\<`T`\>
 
-## Example
-
-```typescript
-const $items = array([1, 2, 3]);
-
-// Track the whole array
-effect((t) => {
-  console.log('Items:', $items.get(t));
-});
-
-// Track the last action
-effect((t) => {
-  const action = $items.$lastAction.get(t);
-  console.log('Action:', action.type);
-});
-
-$items.push(4); // Logs action: "push"
-$items.pop();   // Logs action: "pop"
-```
+A FlowArray with reactive mutation methods

package/docs/api/functions/constant.md

@@ -3,43 +3,31 @@
 # Function: constant()
 
 ```ts
-function constant<T>(value): FlowConstant<T>;
+function constant<T>(initializer): FlowConstant<T>;
 ```
 
-Defined in: [creators.ts:69](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/creators.ts#L69)
+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 new reactive constant.
+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 | Description |
-| ------ | ------ |
-| `T` | The type of the constant value. |
+| Type Parameter |
+| ------ |
+| `T` |
 
 ## Parameters
 
 | Parameter | Type | Description |
 | ------ | ------ | ------ |
-| `value` | `T` \| () => `T` | The value or a function that returns the value (for lazy initialization). |
+| `initializer` | [`InitFunction`](/api/type-aliases/InitFunction.md)\<`T`\> | Function that computes the constant value on first access |
 
 ## Returns
 
-[`FlowConstant`](/api/classes/FlowConstant.md)\<`T`\>
-
-A new instance of [FlowConstant](/api/classes/FlowConstant.md).
-
-## Remarks
-
-A constant is an immutable reactive value that never changes after initialization.
-It can be initialized eagerly (direct value) or lazily (function). Use constants for
-configuration, computed-once values, or expensive initialization that should only run once.
+[`FlowConstant`](/api/interfaces/FlowConstant.md)\<`T`\>
 
-## Example
-
-```typescript
-// Eager initialization
-const $config = constant({ apiUrl: 'https://api.example.com' });
-
-// Lazy initialization
-const $computed = constant(() => expensiveCalculation());
-```
+A FlowConstant that provides read-only access to the cached value

package/docs/api/functions/constantAsync.md

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

@@ -3,51 +3,32 @@
 # Function: derivation()
 
 ```ts
-function derivation<T>(fn): FlowDerivation<T>;
+function derivation<T>(compute): FlowDerivation<T>;
 ```
 
-Defined in: [creators.ts:272](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/creators.ts#L272)
+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 new reactive derivation whose value is computed based on other reactive signals.
+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 | Description |
-| ------ | ------ |
-| `T` | The type of the derived value. |
+| Type Parameter |
+| ------ |
+| `T` |
 
 ## Parameters
 
 | Parameter | Type | Description |
 | ------ | ------ | ------ |
-| `fn` | (`t`) => `T` | A function that computes the derived value using a tracking context. |
+| `compute` | [`DerivationFunction`](/api/type-aliases/DerivationFunction.md)\<`T`\> | Function that accesses dependencies and computes the derived value |
 
 ## Returns
 
-[`FlowDerivation`](/api/classes/FlowDerivation.md)\<`T`\>
-
-A new instance of [FlowDerivation](/api/classes/FlowDerivation.md).
-
-## Remarks
-
-A derivation is a computed reactive value that automatically tracks its dependencies and
-recomputes when they change. The computation is lazy - it runs only when the value is
-accessed, not on construction. Use derivations to create derived state without manual
-dependency management.
-
-## Example
+[`FlowDerivation`](/api/interfaces/FlowDerivation.md)\<`T`\>
 
-```typescript
-const $firstName = state('John');
-const $lastName = state('Doe');
-
-const $fullName = derivation((t) => {
-  return `${$firstName.get(t)} ${$lastName.get(t)}`;
-});
-
-effect((t) => {
-  console.log($fullName.get(t)); // Logs: "John Doe"
-});
-
-$firstName.set('Jane'); // Logs: "Jane Doe"
-```
+A FlowDerivation that provides read-only access to the computed value

package/docs/api/functions/derivationAsync.md

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