@ersbeth/picoflow 2.2.0 → 2.3.0

package/README.md

@@ -4,6 +4,28 @@
 
 > **Upgrading from v1.x?** See the [Upgrade Guide](https://ersbeth-web.gitlab.io/picoflow/guide/advanced/migration-v2.html) for migration instructions.
 
+```typescript
+import { derivation, state, subscribe } from "@ersbeth/picoflow";
+
+const $count = state(0);
+const $isEven = derivation((t) => $count.get(t) % 2 === 0);
+
+const effect = subscribe(
+    (t) => ({ count: $count.get(t), even: $isEven.get(t) }),
+    ({ count, even }) => console.log(`${count} is ${even ? "even" : "odd"}`),
+);
+// logs "0 is even"
+
+$count.set(1); // logs "1 is odd"
+effect.dispose(); // stop reacting
+```
+
+Dependencies are tracked explicitly: `$count.get(t)` both reads the value and registers it as a
+dependency of the enclosing `derivation`/`subscribe`, using the `t` (tracker) each one receives. Nothing
+is tracked implicitly and there is no `untrack()` to opt back out of — if a read doesn't go through
+`.get(t)`, it isn't a dependency. That is the library's main departure from most reactive libraries, and
+its main safety property: what an effect depends on is always visible at the call site.
+
 ## Requirements
 
 The schedulers use `Promise.withResolvers()`, so picoflow needs **Node ≥ 22**, or Chrome ≥ 119, Safari ≥ 17.4, Firefox ≥ 121 in the browser. There is no fallback: on an older runtime the failure is immediate, on the first primitive you create.

package/SKILL.md

@@ -24,6 +24,11 @@ dependency, which is a common source of "why doesn't this update" bugs.
 
 Reactive values are named with a `$` prefix (`$count`, `$user`) by convention — keep this when writing
 new code in a PicoFlow codebase, and use it to tell reactive values apart from plain ones at a glance.
+Every factory also takes an optional trailing `{ name?: string }`, e.g. `state(0, { name: "$count" })` —
+pass the same `$`-prefixed name so it shows up in error messages (`[PicoFlow] Primitive "$count" is
+disposed`) instead of the unnamed generic message. Errors are also typed (`PicoFlowDisposedError`,
+`PicoFlowCycleError`, `PicoFlowInternalError`, all extending `PicoFlowError`), so `catch` blocks can
+discriminate with `instanceof` instead of matching on message text.
 
 ## Choosing a primitive