@ersbeth/picoflow 0.2.4 → 1.0.1

package/docs/index.md

@@ -0,0 +1,47 @@
+---
+layout: home
+
+hero:
+  name: PicoFlow
+  text: Lightweight Reactive Dataflow
+  tagline: Fine-grained reactive primitives for TypeScript with explicit dependency tracking
+  image:
+    src: /logo.svg
+    alt: PicoFlow
+  actions:
+    - theme: brand
+      text: Get Started
+      link: /guide/introduction/getting-started
+    - theme: alt
+      text: API Reference
+      link: /api/
+    - theme: alt
+      text: View on GitLab
+      link: https://gitlab.com/ersbeth-web/picoflow
+
+features:
+  - icon: 🎯
+    title: Explicit Tracking
+    details: Full control over reactive dependencies with TrackingContext. Choose between reactive reads with get(t) and non-reactive reads with pick().
+  
+  - icon: ⚡
+    title: Lazy Evaluation
+    details: Derivations compute only when accessed, not on construction. Smart caching ensures computations run only when dependencies change.
+  
+  - icon: 🔧
+    title: Fine-grained Reactivity
+    details: Track specific operations on collections with reactive arrays and maps. Subscribe to additions, deletions, or entire collection changes.
+  
+  - icon: 🧹
+    title: Resource Management
+    details: Automatic cleanup with dispose patterns. Manage async resources, streams, and effects with confidence.
+  
+  - icon: 📦
+    title: Lightweight
+    details: Minimal bundle size with zero dependencies. Tree-shakeable exports ensure you only ship what you use.
+  
+  - icon: 🔄
+    title: SolidJS Integration
+    details: Seamless integration with SolidJS through built-in converters. Use PicoFlow primitives directly in Solid components.
+---
+

package/docs/public/logo.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 640 640"><!--!Font Awesome Free v7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free Copyright 2025 Fonticons, Inc.--><path d="M176 120C189.3 120 200 130.7 200 144C200 157.3 189.3 168 176 168C162.7 168 152 157.3 152 144C152 130.7 162.7 120 176 120zM208.4 217.2C236.4 204.8 256 176.7 256 144C256 99.8 220.2 64 176 64C131.8 64 96 99.8 96 144C96 176.8 115.7 205 144 217.3L144 422.6C115.7 435 96 463.2 96 496C96 540.2 131.8 576 176 576C220.2 576 256 540.2 256 496C256 463.2 236.3 435 208 422.7L208 336.1C234.7 356.2 268 368.1 304 368.1L390.7 368.1C403 396.4 431.2 416.1 464 416.1C508.2 416.1 544 380.3 544 336.1C544 291.9 508.2 256.1 464 256.1C431.2 256.1 403 275.8 390.7 304.1L304 304C254.1 304 213 265.9 208.4 217.2zM176 472C189.3 472 200 482.7 200 496C200 509.3 189.3 520 176 520C162.7 520 152 509.3 152 496C152 482.7 162.7 472 176 472zM440 336C440 322.7 450.7 312 464 312C477.3 312 488 322.7 488 336C488 349.3 477.3 360 464 360C450.7 360 440 349.3 440 336z" fill="#5672cd"/></svg>

package/package.json

@@ -1,43 +1,59 @@
 {
-    "name": "@ersbeth/picoflow",
-    "version": "0.2.4",
-    "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": {
-        "build": "npx vite build --config vite.config.ts",
-        "format": "npx biome check --fix",
-        "test": "npx vitest",
-        "lint": "npx biome ci",
-        "api:extract": "api-extractor run --local",
-        "api:generate": "api-documenter markdown -i ./api/temp -o ./api/doc",
-        "api:clean": "rm ./api/temp/*",
-        "api": "npm run api:extract && npm run api:generate && npm run api:clean"
-    },
-    "peerDependencies": {
-        "solid-js": "^1.9.7"
-    },
-    "devDependencies": {
-        "@biomejs/biome": "^1.9.4",
-        "@vitest/coverage-v8": "^3.0.9",
-        "vite": "^6.2.3",
-        "vite-plugin-dts": "^4.5.3",
-        "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.0.1",
+	"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"
 }

package/src/advanced/array.ts

@@ -1,5 +1,4 @@
-import { FlowObservable, type FlowState } from "../basic";
-import { isDisposable } from "../basic";
+import { FlowObservable, type FlowState, isDisposable } from "../basic";
 import { state } from "../creators";
 
 /**
@@ -7,218 +6,217 @@ import { state } from "../creators";
  * @public
  */
 export type FlowArrayAction<T> =
-    | {
-          type: "set";
-          items: T[];
-      }
-    | {
-          type: "setItem";
-          index: number;
-          item: T;
-      }
-    | {
-          type: "push";
-          item: T;
-      }
-    | {
-          type: "pop";
-      }
-    | {
-          type: "unshift";
-          item: T;
-      }
-    | {
-          type: "shift";
-      }
-    | {
-          type: "splice";
-          start: number;
-          deleteCount: number;
-          items: T[];
-      }
-    | {
-          type: "clear";
-      };
+	| {
+			type: "set";
+			items: T[];
+	  }
+	| {
+			type: "setItem";
+			index: number;
+			item: T;
+	  }
+	| {
+			type: "push";
+			item: T;
+	  }
+	| {
+			type: "pop";
+	  }
+	| {
+			type: "unshift";
+			item: T;
+	  }
+	| {
+			type: "shift";
+	  }
+	| {
+			type: "splice";
+			start: number;
+			deleteCount: number;
+			items: T[];
+	  }
+	| {
+			type: "clear";
+	  };
 
 /**
  * Represents a reactive array.
  * @public
  */
 export class FlowArray<T> extends FlowObservable<T[]> {
-    /**
-     * Last action performed on the FlowArray.
-     * @public
-     */
-    $lastAction: FlowState<FlowArrayAction<T>>;
-
-    /**
-     * Creates an instance of FlowArray.
-     * @param value - Initial array value.
-     * @public
-     */
-    constructor(value: T[] = []) {
-        super();
-        this._value = value;
-        this.$lastAction = state<FlowArrayAction<T>>({
-            type: "set",
-            items: value,
-        });
-    }
-
-    /**
-     * Gets the current length of the array.
-     * @returns The length of the array.
-     * @public
-     */
-    get length(): number {
-        if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-        return this._value.length;
-    }
-
-    /**
-     * Returns a copy of the internal array.
-     * @returns A copy of the array.
-     * @public
-     */
-    get(): T[] {
-        if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-        return [...this._value]; // Ensure nobody can modify the original array
-    }
-
-    /**
-     * Replaces the entire array with new items.
-     * @param items - The new array of items.
-     * @public
-     */
-    set(items: T[]): void {
-        if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-        this._value.forEach((item) => {
-            if (isDisposable(item)) item.dispose({ self: true });
-        });
-        this._value = items;
-        this._notify();
-        this.$lastAction.set({ type: "set", items: items });
-    }
-
-    /**
-     * Replaces an item at a specific index.
-     * @param index - The index of the item to replace.
-     * @param item - The new item.
-     * @public
-     */
-    setItem(index: number, item: T): void {
-        if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-        if (index < 0 || index >= this._value.length) {
-            throw new Error("[PicoFlow] Index out of bounds");
-        }
-        this._value[index] = item;
-        this._notify();
-        this.$lastAction.set({ type: "setItem", index: index, item: item });
-    }
-
-    /**
-     * Appends an item to the end of the array.
-     * @param item - The item to append.
-     * @public
-     */
-    push(item: T): void {
-        if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-        this._value.push(item);
-        this._notify();
-        this.$lastAction.set({ type: "push", item: item });
-    }
-
-    /**
-     * Removes the last item from the array.
-     * @public
-     */
-    pop(): void {
-        if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-        const item = this._value.pop();
-        if (isDisposable(item)) {
-            item.dispose({ self: true });
-        }
-        this._notify();
-        this.$lastAction.set({ type: "pop" });
-    }
-
-    /**
-     * Inserts an item at the beginning of the array.
-     * @param item - The item to insert.
-     * @public
-     */
-    unshift(item: T): void {
-        if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-        this._value.unshift(item);
-        this._notify();
-        this.$lastAction.set({ type: "unshift", item: item });
-    }
-
-    /**
-     * Removes the first item from the array.
-     * @public
-     */
-    shift(): void {
-        if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-        const item = this._value.shift();
-        if (isDisposable(item)) {
-            item.dispose({ self: true });
-        }
-        this._notify();
-        this.$lastAction.set({ type: "shift" });
-    }
-
-    /**
-     * Changes the content of the array.
-     * @param start - The starting index.
-     * @param deleteCount - Number of items to remove.
-     * @param newItems - New items to add.
-     * @public
-     */
-    splice(start: number, deleteCount: number, ...newItems: T[]): void {
-        if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-        const items = this._value.splice(start, deleteCount, ...newItems);
-        items.forEach((item) => {
-            if (isDisposable(item)) item.dispose({ self: true });
-        });
-        this._notify();
-        this.$lastAction.set({
-            type: "splice",
-            start: start,
-            deleteCount: deleteCount,
-            items: newItems,
-        });
-    }
-
-    /**
-     * Clears all items from the array.
-     * @public
-     */
-    clear(): void {
-        if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-        const items = [...this._value];
-        items.forEach((item) => {
-            if (isDisposable(item)) item.dispose({ self: true });
-        });
-        this._value = [];
-        this._notify();
-        this.$lastAction.set({ type: "clear" });
-    }
-
-    /**
-     * Disposes the FlowArray and its items.
-     * @param options - Disposal options.
-     * @public
-     */
-    override dispose(options?: { self: boolean }): void {
-        super.dispose(options);
-        this._value.forEach((item) => {
-            if (isDisposable(item)) item.dispose(options);
-        });
-        this._value = [];
-    }
-
-    /* INTERNAL */
-
-    /*@internal*/ protected override _value: T[] = [];
+	/**
+	 * Last action performed on the FlowArray.
+	 * @public
+	 */
+	$lastAction: FlowState<FlowArrayAction<T>>;
+
+	/**
+	 * Creates an instance of FlowArray.
+	 * @param value - Initial array value.
+	 * @public
+	 */
+	constructor(value: T[] = []) {
+		super();
+		this._value = value;
+		this.$lastAction = state<FlowArrayAction<T>>({
+			type: "set",
+			items: value,
+		});
+	}
+
+	/**
+	 * Gets the current length of the array.
+	 * @returns The length of the array.
+	 * @public
+	 */
+	get length(): number {
+		if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+		return this._value.length;
+	}
+
+	/**
+	 * Internal method to get the raw value.
+	 * @internal
+	 */
+	protected _getRaw(): T[] {
+		if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+		return [...this._value]; // Ensure nobody can modify the original array
+	}
+
+	/**
+	 * Replaces the entire array with new items.
+	 * @param items - The new array of items.
+	 * @public
+	 */
+	set(items: T[]): void {
+		if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+		this._value.forEach((item) => {
+			if (isDisposable(item)) item.dispose({ self: true });
+		});
+		this._value = items;
+		this._notify();
+		this.$lastAction.set({ type: "set", items: items });
+	}
+
+	/**
+	 * Replaces an item at a specific index.
+	 * @param index - The index of the item to replace.
+	 * @param item - The new item.
+	 * @public
+	 */
+	setItem(index: number, item: T): void {
+		if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+		if (index < 0 || index >= this._value.length) {
+			throw new Error("[PicoFlow] Index out of bounds");
+		}
+		this._value[index] = item;
+		this._notify();
+		this.$lastAction.set({ type: "setItem", index: index, item: item });
+	}
+
+	/**
+	 * Appends an item to the end of the array.
+	 * @param item - The item to append.
+	 * @public
+	 */
+	push(item: T): void {
+		if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+		this._value.push(item);
+		this._notify();
+		this.$lastAction.set({ type: "push", item: item });
+	}
+
+	/**
+	 * Removes the last item from the array.
+	 * @public
+	 */
+	pop(): void {
+		if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+		const item = this._value.pop();
+		if (isDisposable(item)) {
+			item.dispose({ self: true });
+		}
+		this._notify();
+		this.$lastAction.set({ type: "pop" });
+	}
+
+	/**
+	 * Inserts an item at the beginning of the array.
+	 * @param item - The item to insert.
+	 * @public
+	 */
+	unshift(item: T): void {
+		if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+		this._value.unshift(item);
+		this._notify();
+		this.$lastAction.set({ type: "unshift", item: item });
+	}
+
+	/**
+	 * Removes the first item from the array.
+	 * @public
+	 */
+	shift(): void {
+		if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+		const item = this._value.shift();
+		if (isDisposable(item)) {
+			item.dispose({ self: true });
+		}
+		this._notify();
+		this.$lastAction.set({ type: "shift" });
+	}
+
+	/**
+	 * Changes the content of the array.
+	 * @param start - The starting index.
+	 * @param deleteCount - Number of items to remove.
+	 * @param newItems - New items to add.
+	 * @public
+	 */
+	splice(start: number, deleteCount: number, ...newItems: T[]): void {
+		if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+		const items = this._value.splice(start, deleteCount, ...newItems);
+		items.forEach((item) => {
+			if (isDisposable(item)) item.dispose({ self: true });
+		});
+		this._notify();
+		this.$lastAction.set({
+			type: "splice",
+			start: start,
+			deleteCount: deleteCount,
+			items: newItems,
+		});
+	}
+
+	/**
+	 * Clears all items from the array.
+	 * @public
+	 */
+	clear(): void {
+		if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+		const items = [...this._value];
+		items.forEach((item) => {
+			if (isDisposable(item)) item.dispose({ self: true });
+		});
+		this._value = [];
+		this._notify();
+		this.$lastAction.set({ type: "clear" });
+	}
+
+	/**
+	 * Disposes the FlowArray and its items.
+	 * @param options - Disposal options.
+	 * @public
+	 */
+	override dispose(options?: { self: boolean }): void {
+		super.dispose(options);
+		this._value.forEach((item) => {
+			if (isDisposable(item)) item.dispose(options);
+		});
+		this._value = [];
+	}
+
+	/* INTERNAL */
+
+	/** @internal */ protected override _value: T[] = [];
 }

package/src/advanced/index.ts

@@ -1,12 +1,12 @@
+export type { FlowArrayAction } from "./array";
+export { FlowArray } from "./array";
 export { FlowMap } from "./map";
-export { FlowStream } from "./stream";
-export { FlowStreamAsync } from "./streamAsync";
 export { FlowResource } from "./resource";
 export { FlowResourceAsync } from "./resourceAsync";
 export type {
-    FlowStreamUpdater,
-    FlowStreamDisposer,
-    FlowStreamSetter,
+	FlowStreamDisposer,
+	FlowStreamSetter,
+	FlowStreamUpdater,
 } from "./stream";
-export { FlowArray } from "./array";
-export type { FlowArrayAction } from "./array";
+export { FlowStream } from "./stream";
+export { FlowStreamAsync } from "./streamAsync";