@ersbeth/picoflow 0.2.3 → 1.0.0

package/README.md

@@ -1,6 +1,8 @@
 # Picoflow
 
-**Picoflow** is a lightweight reactive dataflow library that provides fine-grained reactive primitives. It gives you an intuitive API for signals, state, asynchronous resources, streams, derivations, effects, and reactive maps. Instead of using traditional subscriptions, Picoflow uses effects to automatically track reactive dependencies.
+**Picoflow** is a lightweight reactive dataflow library that provides fine-grained reactive primitives. It gives you an intuitive API for signals, state, asynchronous resources, streams, derivations, effects, and reactive maps. Picoflow uses an explicit tracking context to automatically track reactive dependencies.
+
+> **Upgrading from v0.x?** See the [Upgrade Guide](UPGRADING.md) for migration instructions.
 
 ## Features
 
@@ -13,6 +15,7 @@
   - **Lazy Evaluation:** Derivations are evaluated lazily—that is, the computation only runs if and when an effect actually uses the derived value.
 - **Reactive Maps:** Manage collections reactively with granular update notifications.
 - **Effects:** Automatically run side-effect functions when dependencies change.
+- **Explicit Control:** Choose between reactive (`.get(t)`) and non-reactive (`.pick()`) reads for fine-grained control.
 
 ## Installation
 
@@ -24,18 +27,18 @@ npm install @ersbeth/picoflow
 
 ## Usage
 
-In Picoflow, we advise to prefix all reactive primitives and effects with `$` for improved readability. Rather than using a subscribe method, you always create an effect that "watches" a primitive. Below are some examples:
+In Picoflow, we advise to prefix all reactive primitives and effects with `$` for improved readability. Rather than using a subscribe method, you always create an effect that tracks dependencies using a tracking context. Below are some examples:
 
 ### Creating a Signal
 
 ```ts
-import { signal, effect } from 'picoflow';
+import { signal, effect } from '@ersbeth/picoflow';
 
 const $signal = signal();
 
-const $effect = effect((get, watch) => {
+const $effect = effect((t) => {
   // Automatically tracks $signal
-  watch($signal);
+  $signal.watch(t);
   console.log('$signal has been triggered');
 });
 
@@ -48,25 +51,25 @@ $signal.trigger();
 ### Creating Reactive State
 
 ```ts
-import { state, effect } from 'picoflow';
+import { state, effect } from '@ersbeth/picoflow';
 
 const $count = state(0);
 
-const $effect = effect((get, watch) => {
+const $effect = effect((t) => {
   // Automatically tracks $count
-  console.log('Count changed:', get($count));
+  console.log('Count changed:', $count.get(t));
 });
 
 // Update the state
 $count.set(42);
 
-// LOG -> $Count changed: 42
+// LOG -> Count changed: 42
 ```
 
 ### Creating an Asynchronous Resource
 
 ```ts
-import { resource, effect } from 'picoflow';
+import { resource, effect } from '@ersbeth/picoflow';
 
 async function fetchData() {
   const response = await fetch('https://api.example.com/data');
@@ -76,8 +79,8 @@ async function fetchData() {
 const $data = resource(fetchData, {});
 
 // Create an effect to watch for updates
-const $effect = effect((get, watch) => {
-  console.log('Resource updated:', get($data));
+const $effect = effect((t) => {
+  console.log('Resource updated:', $data.get(t));
 });
 
 // Later, you can trigger a new fetch
@@ -87,7 +90,7 @@ $data.fetch();
 ### Creating a Reactive Stream
 
 ```ts
-import { stream, effect } from 'picoflow';
+import { stream, effect } from '@ersbeth/picoflow';
 
 const $ticker = stream(
   (set) => {
@@ -98,26 +101,26 @@ const $ticker = stream(
   Date.now()
 );
 
-const $effect = effect((get, watch) => {
-  console.log('Current time:', get($ticker));
+const $effect = effect((t) => {
+  console.log('Current time:', $ticker.get(t));
 });
 ```
 
 ### Creating a Derived Value
 
 ```ts
-import { state, derivation, effect } from 'picoflow';
+import { state, derivation, effect } from '@ersbeth/picoflow';
 
 const $a = state(10);
 const $b = state(20);
 
 // Create a derived value that sums $a and $b.
-const $sum = derivation((get, watch) => {
-  return get($a) + get($b);
+const $sum = derivation((t) => {
+  return $a.get(t) + $b.get(t);
 });
 
-const $effect = effect((get, watch) => {
-  console.log('Sum:', get($sum));
+const $effect = effect((t) => {
+  console.log('Sum:', $sum.get(t));
 });
 
 // Update a dependency to see the derivation update.
@@ -129,12 +132,12 @@ $a.set(15);
 Reactive maps allow fine-grained tracking of collection updates.
 
 ```ts
-import { map, effect } from 'picoflow';
+import { map, effect } from '@ersbeth/picoflow';
 
 const $map = map({ foo: 'bar' });
 
-const $effect = effect((get, watch) => {
-  console.log('Map updated:', get($map));
+const $effect = effect((t) => {
+  console.log('Map updated:', $map.get(t));
 });
 
 // Update the map to trigger updates
@@ -142,9 +145,43 @@ $map.setAt('baz', 'qux');
 $map.delete('foo');
 ```
 
-## API Documentation
+### Non-Reactive Reads
+
+Sometimes you need to read a value without creating a dependency. Use `pick()` for this:
+
+```ts
+import { state, signal, effect } from '@ersbeth/picoflow';
+
+const $data = state({ count: 0 });
+const $trigger = signal();
+
+const $effect = effect((t) => {
+  // React to $trigger changes only
+  $trigger.watch(t);
+  
+  // Read $data without creating a dependency
+  const snapshot = $data.pick();
+  console.log('Triggered! Current data:', snapshot);
+});
+
+$data.set({ count: 1 });  // Does NOT trigger the effect
+$trigger.trigger();        // Triggers the effect, logs: { count: 1 }
+```
+
+## Documentation
+
+For comprehensive guides and API documentation, visit:
+
+- **[Getting Started](docs/guide/getting-started.md)** - Quick introduction to PicoFlow
+- **[API Reference](docs/api/index.md)** - Complete API documentation
+
+Or run the documentation locally:
+
+```bash
+pnpm docs:dev
+```
 
-For detailed API documentation, please refer to the [API Reference](./api/doc/index.md).
+Then open [http://localhost:5173](http://localhost:5173) in your browser.
 
 ## License
 

package/biome.json

@@ -1,34 +1,34 @@
 {
-    "$schema": "https://biomejs.dev/schemas/1.9.4/schema.json",
-    "files": {
-        "ignore": [
-            "dist",
-            "node_modules",
-            "doc/.vitepress/dist",
-            "doc/.vitepress/cache"
-        ]
-    },
-    "organizeImports": {
-        "enabled": true
-    },
-    "formatter": {
-        "enabled": true,
-        "indentStyle": "space",
-        "indentWidth": 4,
-        "lineEnding": "lf"
-    },
-    "linter": {
-        "rules": {
-            "suspicious": {
-                "noExplicitAny": "off",
-                "useIsArray": "off"
-            },
-            "complexity": {
-                "noForEach": "off"
-            },
-            "style": {
-                "noNonNullAssertion": "off"
-            }
-        }
-    }
+	"$schema": "https://biomejs.dev/schemas/2.3.8/schema.json",
+	"vcs": {
+		"enabled": true,
+		"clientKind": "git",
+		"useIgnoreFile": true
+	},
+	"files": {
+		"includes": ["**", "!!**/dist"]
+	},
+	"formatter": {
+		"enabled": true,
+		"indentStyle": "tab"
+	},
+	"linter": {
+		"enabled": true,
+		"rules": {
+			"recommended": true
+		}
+	},
+	"javascript": {
+		"formatter": {
+			"quoteStyle": "double"
+		}
+	},
+	"assist": {
+		"enabled": true,
+		"actions": {
+			"source": {
+				"organizeImports": "on"
+			}
+		}
+	}
 }