@ersbeth/picoflow 1.0.0 → 1.1.0

package/dist/types/solid/converters.d.ts

@@ -1,5 +1,6 @@
-import { FlowObservable, TrackingContext } from '../basic';
-import { SolidDerivation, SolidResource } from './primitives';
+import { FlowReadonly, FlowReadonlyAsync } from '../flow';
+import { FlowTracker } from '../flow/base/flowTracker';
+import { SolidResource } from './primitives';
 /**
  * Utility type that excludes Promise types from T.
  * Used to ensure type safety for synchronous derivations/resources.
@@ -8,57 +9,46 @@ import { SolidDerivation, SolidResource } from './primitives';
  */
 export type NotPromise<T> = T extends Promise<unknown> ? never : T;
 /**
- * Converts a FlowObservable of a Promise value into a SolidResource.
+ * Converts a FlowNode, FlowNodeAsync, or getter function into a SolidResource.
  *
- * @param flow - The FlowObservable to convert.
- * @returns A SolidResource wrapping the observable.
+ * @param flow - The FlowNode, FlowNodeAsync, or getter function to convert.
+ * @returns A SolidResource that wraps the value or computation.
  *
- * @public
- */
-export declare function from<T>(flow: FlowObservable<Promise<NotPromise<T>>>): SolidResource<NotPromise<T>>;
-/**
- * Converts a FlowObservable of a non-Promise value into a SolidDerivation.
- *
- * @param flow - The FlowObservable to convert.
- * @returns A SolidDerivation wrapping the observable.
- *
- * @public
- */
-export declare function from<T>(flow: FlowObservable<NotPromise<T>>): SolidDerivation<NotPromise<T>>;
-/**
- * Converts a FlowObservable into a Solid derivation or resource, depending on whether the value is synchronous or asynchronous.
- *
- * @param flow - The FlowObservable to convert.
- * @returns A SolidDerivation or SolidResource, depending on the input type.
+ * @remarks
+ * This function bridges PicoFlow's reactive system with SolidJS, allowing you to use
+ * PicoFlow nodes and computations within Solid components. All conversions return a
+ * `SolidResource`, which can handle both synchronous and asynchronous values seamlessly.
  *
- * @public
- */
-export declare function from<T>(flow: FlowObservable<Promise<NotPromise<T>>> | FlowObservable<NotPromise<T>>): SolidDerivation<NotPromise<T>> | SolidResource<NotPromise<T>>;
-/**
- * Converts a getter function returning a non-Promise value into a SolidDerivation.
+ * The conversion works with:
+ * - **FlowNode**: Synchronous reactive nodes (e.g., from `state()` or `derivation()`)
+ * - **FlowNodeAsync**: Asynchronous reactive nodes (e.g., from `resourceAsync()`)
+ * - **Getter functions**: Computation functions that use a FlowTracker to access reactive values
  *
- * @param flow - The getter function to convert.
- * @returns A SolidDerivation wrapping the getter.
+ * The created SolidResource automatically subscribes to the PicoFlow nodes and updates
+ * when their values change. The subscription is properly cleaned up when the Solid
+ * component unmounts.
  *
- * @public
- */
-export declare function from<T>(flow: (t: TrackingContext) => NotPromise<T>): SolidDerivation<NotPromise<T>>;
-/**
- * Converts a getter function returning a Promise into a SolidResource.
+ * @example
+ * ```typescript
+ * import { from } from 'picoflow/solid';
+ * import { state } from 'picoflow';
  *
- * @param flow - The getter function to convert.
- * @returns A SolidResource wrapping the getter.
+ * // Convert a PicoFlow state to a Solid resource
+ * const $count = state(0);
+ * const solidCount = from($count);
  *
- * @public
- */
-export declare function from<T>(flow: (t: TrackingContext) => Promise<NotPromise<T>>): SolidResource<NotPromise<T>>;
-/**
- * Converts a getter function into a Solid derivation or resource, depending on whether the returned value is synchronous or asynchronous.
+ * // Use in a Solid component
+ * function Counter() {
+ *   return <div>Count: {solidCount.get()}</div>;
+ * }
  *
- * @param flow - The getter function to convert.
- * @returns A SolidDerivation or SolidResource, depending on the input type.
+ * // Or convert a computation function
+ * const solidDerived = from((t) => {
+ *   return solidCount.get(t) * 2;
+ * });
+ * ```
  *
  * @public
  */
-export declare function from<T>(flow: ((t: TrackingContext) => NotPromise<T>) | ((t: TrackingContext) => Promise<NotPromise<T>>)): SolidDerivation<T> | SolidResource<T>;
+export declare function from<T>(flow: FlowReadonlyAsync<T> | FlowReadonly<T> | ((t: FlowTracker) => T) | ((t: FlowTracker) => Promise<T>)): SolidResource<T>;
 //# sourceMappingURL=converters.d.ts.map

package/dist/types/solid/converters.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"converters.d.ts","sourceRoot":"","sources":["../../../src/solid/converters.ts"],"names":[],"mappings":"AACA,OAAO,EAGN,cAAc,EACd,KAAK,eAAe,EACpB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,KAAK,eAAe,EAAE,aAAa,EAAc,MAAM,cAAc,CAAC;AAuI/E;;;;;GAKG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,IAAI,CAAC,SAAS,OAAO,CAAC,OAAO,CAAC,GAAG,KAAK,GAAG,CAAC,CAAC;AAEnE;;;;;;;GAOG;AACH,wBAAgB,IAAI,CAAC,CAAC,EACrB,IAAI,EAAE,cAAc,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,GAC1C,aAAa,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;AAChC;;;;;;;GAOG;AACH,wBAAgB,IAAI,CAAC,CAAC,EACrB,IAAI,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,GACjC,eAAe,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;AAClC;;;;;;;GAOG;AACH,wBAAgB,IAAI,CAAC,CAAC,EACrB,IAAI,EAAE,cAAc,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,cAAc,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,GAC1E,eAAe,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;AACjE;;;;;;;GAOG;AACH,wBAAgB,IAAI,CAAC,CAAC,EACrB,IAAI,EAAE,CAAC,CAAC,EAAE,eAAe,KAAK,UAAU,CAAC,CAAC,CAAC,GACzC,eAAe,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;AAClC;;;;;;;GAOG;AACH,wBAAgB,IAAI,CAAC,CAAC,EACrB,IAAI,EAAE,CAAC,CAAC,EAAE,eAAe,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,GAClD,aAAa,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;AAChC;;;;;;;GAOG;AACH,wBAAgB,IAAI,CAAC,CAAC,EACrB,IAAI,EACD,CAAC,CAAC,CAAC,EAAE,eAAe,KAAK,UAAU,CAAC,CAAC,CAAC,CAAC,GACvC,CAAC,CAAC,CAAC,EAAE,eAAe,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,GACjD,eAAe,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC"}
+{"version":3,"file":"converters.d.ts","sourceRoot":"","sources":["../../../src/solid/converters.ts"],"names":[],"mappings":"AACA,OAAO,EAAY,KAAK,YAAY,EAAE,KAAK,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAE9E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAE5D,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAmE7C;;;;;GAKG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,IAAI,CAAC,SAAS,OAAO,CAAC,OAAO,CAAC,GAAG,KAAK,GAAG,CAAC,CAAC;AAEnE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,wBAAgB,IAAI,CAAC,CAAC,EACrB,IAAI,EACD,iBAAiB,CAAC,CAAC,CAAC,GACpB,YAAY,CAAC,CAAC,CAAC,GACf,CAAC,CAAC,CAAC,EAAE,WAAW,KAAK,CAAC,CAAC,GACvB,CAAC,CAAC,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC,GACjC,aAAa,CAAC,CAAC,CAAC,CAUlB"}

package/dist/types/solid/primitives.d.ts

@@ -171,6 +171,7 @@ export declare class SolidResource<T> implements SolidObservable<T | undefined>
      * Triggers a refetch of the resource.
      */
     readonly refetch: () => void;
+    readonly set: (param: SolidGetter<T>) => void;
     /**
      * Creates a new SolidResource from a fetcher function.
      * @param fetcher - The async fetcher function.

package/dist/types/solid/primitives.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"primitives.d.ts","sourceRoot":"","sources":["../../../src/solid/primitives.ts"],"names":[],"mappings":"AAAA,OAAO,EAIN,KAAK,eAAe,EACpB,MAAM,UAAU,CAAC;AAElB;;;;;GAKG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC;AAEtD;;;;;GAKG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC;IACjC;;OAEG;IACH,GAAG,EAAE,MAAM,CAAC,CAAC;CACb;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBAAa,UAAU,CAAC,CAAC,CAAE,YAAW,eAAe,CAAC,CAAC,CAAC;IACvD;;OAEG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IACtB;;OAEG;IACH,QAAQ,CAAC,GAAG,EAAE,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;IAE9C;;;OAGG;gBACS,YAAY,EAAE,CAAC;CAK3B;AAGD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,qBAAa,eAAe,CAAC,CAAC,CAAE,YAAW,eAAe,CAAC,CAAC,CAAC;IAC5D;;OAEG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IAEtB;;;OAGG;gBACS,UAAU,EAAE,WAAW,CAAC,CAAC,CAAC;CAItC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,qBAAa,aAAa,CAAC,CAAC,CAAE,YAAW,eAAe,CAAC,CAAC,GAAG,SAAS,CAAC;IACtE;;OAEG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,GAAG,SAAS,CAAC;IAClC;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,MACb,YAAY,GACZ,SAAS,GACT,SAAS,GACT,OAAO,GACP,YAAY,CAAC;IAChB;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAAC;IACrC;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,CAAC;IAE7B;;;OAGG;gBACS,OAAO,EAAE,eAAe,CAAC,IAAI,EAAE,CAAC,EAAE,OAAO,CAAC;CAOtD"}
+{"version":3,"file":"primitives.d.ts","sourceRoot":"","sources":["../../../src/solid/primitives.ts"],"names":[],"mappings":"AAAA,OAAO,EAIN,KAAK,eAAe,EACpB,MAAM,UAAU,CAAC;AAElB;;;;;GAKG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC;AAEtD;;;;;GAKG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC;IACjC;;OAEG;IACH,GAAG,EAAE,MAAM,CAAC,CAAC;CACb;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBAAa,UAAU,CAAC,CAAC,CAAE,YAAW,eAAe,CAAC,CAAC,CAAC;IACvD;;OAEG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IACtB;;OAEG;IACH,QAAQ,CAAC,GAAG,EAAE,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;IAE9C;;;OAGG;gBACS,YAAY,EAAE,CAAC;CAK3B;AAGD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,qBAAa,eAAe,CAAC,CAAC,CAAE,YAAW,eAAe,CAAC,CAAC,CAAC;IAC5D;;OAEG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IAEtB;;;OAGG;gBACS,UAAU,EAAE,WAAW,CAAC,CAAC,CAAC;CAItC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,qBAAa,aAAa,CAAC,CAAC,CAAE,YAAW,eAAe,CAAC,CAAC,GAAG,SAAS,CAAC;IACtE;;OAEG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,GAAG,SAAS,CAAC;IAClC;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,MACb,YAAY,GACZ,SAAS,GACT,SAAS,GACT,OAAO,GACP,YAAY,CAAC;IAChB;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAAC;IACrC;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,CAAC;IAE7B,QAAQ,CAAC,GAAG,EAAE,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;IAE9C;;;OAGG;gBACS,OAAO,EAAE,eAAe,CAAC,IAAI,EAAE,CAAC,EAAE,OAAO,CAAC;CAStD"}

package/docs/.vitepress/config.mts

@@ -64,7 +64,7 @@ export default withMermaid(
 							{
 								text: "Upgrade from v0.x",
 								link: "/guide/advanced/upgrading",
-							}
+							},
 						],
 					},
 				],

package/docs/api/typedoc-sidebar.json

@@ -1 +1,81 @@
-[{"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"}]}]
+[
+	{
+		"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" }
+		]
+	}
+]

package/package.json

@@ -1,59 +1,61 @@
 {
-	"name": "@ersbeth/picoflow",
-	"version": "1.0.0",
-	"description": "Minimal Dataflow librairy for TypeScript",
-	"type": "module",
-	"exports": {
-		"types": "./dist/types/index.d.ts",
-		"default": "./dist/picoflow.js"
-	},
-	"imports": {
-		"#package": "./src/index.ts"
-	},
-	"scripts": {
-		"check": "pnpm exec tsc --noEmit",
-		"lint": "pnpm exec biome check --fix",
-		"build": "pnpm exec vite build --config vite.config.ts",
-		"test": "pnpm exec vitest",
-		"docs:dev": "vitepress dev docs",
-		"docs:build": "pnpm docs:generate && vitepress build docs",
-		"docs:preview": "vitepress preview docs",
-		"docs:generate": "typedoc",
-		"api:extract": "pnpm exec api-extractor run --local",
-		"api:generate": "pnpm exec api-documenter markdown -i ./api/temp -o ./api/doc",
-		"api:clean": "rm ./api/temp/*",
-		"api": "pnpm api:extract && pnpm api:generate && pnpm api:clean"
-	},
-	"peerDependencies": {
-		"solid-js": "^1.9.7"
-	},
-	"devDependencies": {
-		"@biomejs/biome": "2.3.8",
-		"@braintree/sanitize-url": "^7.1.1",
-		"@vitest/coverage-v8": "^3.0.9",
-		"cytoscape": "^3.33.1",
-		"cytoscape-cose-bilkent": "^4.1.0",
-		"dayjs": "^1.11.19",
-		"dompurify": "^3.3.0",
-		"mermaid": "^11.12.1",
-		"typedoc": "^0.28.15",
-		"typedoc-plugin-markdown": "^4.9.0",
-		"typedoc-vitepress-theme": "^1.1.2",
-		"typescript": "^5.9.3",
-		"vite": "^6.2.3",
-		"vite-plugin-dts": "^4.5.3",
-		"vitepress": "^1.6.4",
-		"vitepress-plugin-mermaid": "^2.0.17",
-		"vitest": "^3.0.9"
-	},
-	"repository": {
-		"type": "git",
-		"url": "git+ssh://git@gitlab.com/ersbeth-web/picoflow.git"
-	},
-	"author": "Elisabeth Rousset",
-	"license": "MIT",
-	"bugs": {
-		"url": "https://gitlab.com/ersbeth-web/picoflow/issues"
-	},
-	"homepage": "https://gitlab.com/ersbeth-web/picoflow#readme"
-}
+  "name": "@ersbeth/picoflow",
+  "version": "1.1.0",
+  "description": "Minimal Dataflow librairy for TypeScript",
+  "type": "module",
+  "exports": {
+    "types": "./dist/types/index.d.ts",
+    "default": "./dist/picoflow.js"
+  },
+  "imports": {
+    "#package": "./src/index.ts"
+  },
+  "peerDependencies": {
+    "solid-js": "^1.9.7"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.3.8",
+    "@braintree/sanitize-url": "^7.1.1",
+    "@vitest/coverage-v8": "^3.0.9",
+    "cytoscape": "^3.33.1",
+    "cytoscape-cose-bilkent": "^4.1.0",
+    "dayjs": "^1.11.19",
+    "dompurify": "^3.3.0",
+    "jsdom": "^27.3.0",
+    "mermaid": "^11.12.1",
+    "typedoc": "^0.28.15",
+    "typedoc-plugin-markdown": "^4.9.0",
+    "typedoc-vitepress-theme": "^1.1.2",
+    "typescript": "^5.9.3",
+    "vite": "^6.2.3",
+    "vite-plugin-dts": "^4.5.3",
+    "vite-plugin-solid": "^2.11.10",
+    "vitepress": "^1.6.4",
+    "vitepress-plugin-mermaid": "^2.0.17",
+    "vitest": "^3.0.9"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@gitlab.com/ersbeth-web/picoflow.git"
+  },
+  "author": "Elisabeth Rousset",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://gitlab.com/ersbeth-web/picoflow/issues"
+  },
+  "homepage": "https://gitlab.com/ersbeth-web/picoflow#readme",
+  "scripts": {
+    "check": "pnpm exec tsc --noEmit",
+    "lint": "pnpm exec biome check --fix",
+    "build": "pnpm exec vite build --config vite.config.ts",
+    "test": "pnpm exec vitest",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "pnpm docs:generate && vitepress build docs",
+    "docs:preview": "vitepress preview docs",
+    "docs:generate": "typedoc",
+    "api:extract": "pnpm exec api-extractor run --local",
+    "api:generate": "pnpm exec api-documenter markdown -i ./api/temp -o ./api/doc",
+    "api:clean": "rm ./api/temp/*",
+    "api": "pnpm api:extract && pnpm api:generate && pnpm api:clean"
+  }
+}

package/src/flow/base/flowDisposable.ts

@@ -0,0 +1,71 @@
+/**
+ * Contract for objects that own resources and must be cleaned up explicitly.
+ *
+ * @remarks
+ * Many PicoFlow primitives expose `dispose()` so you can tear down subscriptions,
+ * listeners, or reactive links when they are no longer needed (e.g., component
+ * unmount, feature teardown, test cleanup).
+ *
+ * Typical options:
+ * - `{ self: true }` — dispose only this instance (dependents decide their own lifecycle).
+ * - `{ self: false }` or omitted — also dispose dependents, if the implementation supports it.
+ *
+ * The exact cascade behavior depends on the concrete primitive; consult its docs.
+ *
+ * @example
+ * ```typescript
+ * const $state = state(0);
+ * const fx = effect((t) => console.log($state.get(t)));
+ *
+ * $state.dispose();          // Common teardown path
+ * $state.dispose({ self: true }); // Dispose only this instance if you want dependents to persist
+ * ```
+ *
+ * @public
+ */
+export interface FlowDisposable {
+	/**
+	 * Disposes resources held by this object.
+	 *
+	 * @param options - Optional disposal behavior.
+	 * @param options.self - When true, dispose only this object. When false or
+	 * omitted, the implementation may also dispose dependents.
+	 *
+	 * @remarks
+	 * Use `dispose()` during teardown (unmount, test cleanup, feature shutdown).
+	 * Calling `dispose()` more than once may throw; behavior is defined by the
+	 * concrete implementation.
+	 *
+	 * @throws Error if the object has already been disposed (implementation-specific).
+	 */
+	dispose(options?: { self: boolean }): void;
+}
+
+/**
+ * Runtime type guard that checks whether an object is disposable.
+ *
+ * @param obj - Value to test.
+ * @returns `true` if `obj` exposes a callable `dispose`; otherwise `false`.
+ *
+ * @remarks
+ * Use this for defensive cleanup in mixed collections or optional resources.
+ * It performs a runtime shape check; no assumptions about specific types are made.
+ *
+ * @example
+ * ```typescript
+ * function cleanup(items: unknown[]) {
+ *   for (const item of items) {
+ *     if (isDisposable(item)) item.dispose();
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
+export function isDisposable(obj: unknown): obj is FlowDisposable {
+	return (
+		obj !== null &&
+		obj !== undefined &&
+		typeof (obj as FlowDisposable).dispose === "function"
+	);
+}

package/src/flow/base/flowEffect.ts

@@ -0,0 +1,171 @@
+import { FlowGraph } from "./flowGraph";
+import type { FlowSignal } from "./flowSignal";
+import type { FlowTracker } from "./flowTracker";
+
+/**
+ * Runs side-effect code in response to reactive state changes.
+ *
+ * @remarks
+ * A `FlowEffect` is the bridge between reactive data and the outside world
+ * (UI updates, logging, network calls, timers, etc.). It executes a callback
+ * with a tracking context so you can choose which observables/signals should
+ * re-trigger the effect:
+ *
+ * - Use `observable.get(t)` or `signal.watch(t)` to create dependencies.
+ * - Use `observable.pick()` for untracked reads that should not re-run the effect.
+ *
+ * The callback runs immediately when the effect is created and re-runs whenever
+ * any tracked dependency changes. The effect itself is the tracking context
+ * (it implements `FlowTracker`), so `t` in your callback is the effect instance.
+ *
+ * Async callbacks are supported: if the callback returns a promise, the effect
+ * awaits it before finishing the current run. A later change can re-run the
+ * effect even if a previous async run is still pending, so write idempotent
+ * side effects when working with async flows.
+ *
+ * @example
+ * ```typescript
+ * // Mixed tracked/untracked reads
+ * const fx = effect((t) => {
+ *   const tracked = $stateA.get(t);   // tracked -> re-runs when $stateA changes
+ *   const snapshot = $config.pick();  // untracked -> does not re-run on changes
+ *   console.log(tracked, snapshot);
+ * });
+ *
+ * // Async work
+ * const fxAsync = effect(async (t) => {
+ *   const userId = $userId.get(t);
+ *   const profile = await fetchProfile(userId);
+ *   renderProfile(profile);
+ * });
+ * ```
+ *
+ * @public
+ */
+export class FlowEffect {
+	private _disposed = false;
+	private _dependencies = new Set<FlowSignal>();
+	private _apply: (t: FlowTracker) => void | Promise<void>;
+	settled: Promise<void>;
+
+	/**
+	 * Creates a new effect and runs it once immediately.
+	 *
+	 * @param apply - Side-effect function receiving the tracking context (`t`).
+	 * It can be sync or async (returning `Promise<void>`).
+	 *
+	 * @remarks
+	 * Use `t` to opt-in to reactive tracking:
+	 * - `observable.get(t)` / `signal.watch(t)` to re-run when they change
+	 * - `observable.pick()` for reads that should not re-run the effect
+	 *
+	 * The effect schedules its first run during construction. Each subsequent
+	 * change to a tracked dependency queues another run.
+	 *
+	 * @public
+	 */
+	constructor(apply: (t: FlowTracker) => void | Promise<void>) {
+		this._apply = apply;
+		this.settled = FlowGraph.requestRead(() => this._exec());
+	}
+
+	/**
+	 * Stops the effect and detaches it from all tracked dependencies.
+	 *
+	 * @remarks
+	 * Call this when the effect's work is no longer needed (e.g., component
+	 * unmount, teardown of a feature). After disposal:
+	 * - The effect will not re-run.
+	 * - All dependency links are removed.
+	 * - Calling `dispose()` again throws an error.
+	 *
+	 * @example
+	 * ```typescript
+	 * const fx = effect((t) => $signal.watch(t));
+	 * // ... later
+	 * fx.dispose();
+	 * ```
+	 *
+	 * @public
+	 */
+	public dispose(): void {
+		if (this._disposed) throw new Error("[PicoFlow] Effect is disposed");
+		Array.from(this._dependencies).forEach((dependency) => {
+			this._unregisterDependency(dependency);
+		});
+		this._disposed = true;
+	}
+
+	/**
+	 * Whether the effect has been disposed.
+	 *
+	 * @returns `true` once disposal has run; `false` while the effect is active.
+	 *
+	 * @public
+	 */
+	public get disposed(): boolean {
+		return this._disposed;
+	}
+
+	/** @internal */ async _requestExec(): Promise<void> {
+		this.settled = this._exec();
+		return this.settled;
+	}
+
+	/** @internal */ _registerDependency(dependency: FlowSignal): void {
+		this._dependencies.add(dependency);
+		dependency._registerEffect(this);
+	}
+
+	/** @internal */ _unregisterDependency(dependency: FlowSignal): void {
+		this._dependencies.delete(dependency);
+		dependency._unregisterEffect(this);
+	}
+
+	private async _exec(): Promise<void> {
+		if (this._disposed)
+			/* v8 ignore next 1 */
+			throw new Error("[PicoFlow] Effect is disposed");
+
+		const result = this._apply(this);
+		if (result instanceof Promise) {
+			await result;
+		}
+	}
+}
+
+/**
+ * Creates a reactive effect that runs now and re-runs when its tracked
+ * dependencies change.
+ *
+ * @param fn - Side-effect function that receives the tracking context (`t`).
+ * @returns A new {@link FlowEffect}.
+ *
+ * @remarks
+ * Use an effect when you need to react to state changes with side effects
+ * (UI updates, logging, network calls, timers). For computing derived values,
+ * prefer derivations; for one-off work, use a normal function.
+ *
+ * - Track dependencies with `observable.get(t)` or `signal.watch(t)`.
+ * - Read without tracking using `observable.pick()`.
+ * - Async callbacks are supported; return a promise if you `await` inside.
+ *
+ * @example
+ * ```typescript
+ * const $count = state(0);
+ *
+ * const fx = effect((t) => {
+ *   console.log("Count is:", $count.get(t));
+ * });
+ *
+ * $count.set(1); // Logs "Count is: 1"
+ * $count.set(2); // Logs "Count is: 2"
+ *
+ * fx.dispose();  // Stop reacting
+ * ```
+ *
+ * @public
+ */
+export function effect(fn: (t: FlowTracker) => void): FlowEffect {
+	return new FlowEffect(fn);
+}