@ersbeth/picoflow 1.1.2 → 2.0.0

package/docs/guide/primitives/signal.md

@@ -2,15 +2,6 @@
 
 A **signal** is a reactive primitive that represents an event or notification. Unlike state or derivations, signals don't hold values - they simply notify watchers that something has happened.
 
-Imagine a refresh button on a web page. When clicked, it doesn't need to pass data - it just needs to tell the system "hey, refresh now!" That's exactly what signals do.
-
-### Key Characteristics
-
-- **No value**: Signals don't store or return data
-- **Pure notification**: They exist solely to trigger reactions
-- **Lightweight**: Perfect for events that don't need to carry information
-- **Explicit tracking**: Use `.watch(t)` to track them in effects
-
 ## When to Use Signals
 
 Use signals when you need to:
@@ -23,8 +14,6 @@ Use signals when you need to:
 Don't use signals when:
 
 - ❌ You need to pass data (use state instead)
-- ❌ You're tracking continuous streams of events (use streams instead)
-- ❌ The value itself matters (use state or derivation)
 
 ## Creating Signals
 
@@ -44,38 +33,38 @@ Signals don't take any parameters since they don't hold values.
 
 Signals have three main operations: watching, triggering, and disposing.
 
-### Watching Signals with `.watch(t)`
+### Watch
 
-Inside an effect or derivation, use `.watch(t)` to track a signal:
+Inside a subscription or derivation, use `.watch(t)` to track a signal:
 
 ```typescript
-import { signal, effect } from '@ersbeth/picoflow'
+import { signal, subscribe } from '@ersbeth/picoflow'
 
 const $refresh = signal()
 
-effect((t) => {
-  $refresh.watch(t)
-  console.log('Refresh triggered!')
-})
+subscribe(
+  (t) => { $refresh.watch(t) },
+  () => { console.log('Refresh triggered!') }
+)
 
 $refresh.trigger() // Logs: "Refresh triggered!"
 $refresh.trigger() // Logs: "Refresh triggered!" again
 ```
 
-Every time the signal is triggered, the effect re-executes.
+Every time the signal is triggered, the subscription re-executes.
 
-### Triggering Signals with `.trigger()`
+### Trigger
 
 Call `.trigger()` to notify all watchers:
 
 ```typescript
 const $notification = signal()
 
-// Setup an effect that watches the signal
-effect((t) => {
-  $notification.watch(t)
-  showNotification('New activity!')
-})
+// Setup a subscription that watches the signal
+subscribe(
+  (t) => { $notification.watch(t) },
+  () => { showNotification('New activity!') }
+)
 
 // Trigger from anywhere
 function onNewMessage() {
@@ -87,7 +76,7 @@ function onNewLike() {
 }
 ```
 
-### Disposing Signals with `.dispose()`
+### Dispose
 
 Signals can be disposed to free resources and prevent memory leaks:
 
@@ -95,10 +84,10 @@ Signals can be disposed to free resources and prevent memory leaks:
 const $mySignal = signal()
 
 // Use the signal
-effect((t) => {
-  $mySignal.watch(t)
-  console.log('Signal triggered!')
-})
+subscribe(
+  (t) => { $mySignal.watch(t) },
+  () => { console.log('Signal triggered!') }
+)
 
 // Later, clean up
 $mySignal.dispose()
@@ -109,41 +98,41 @@ $mySignal.trigger() // Error: Primitive is disposed
 
 ## Lifecyle
 
-When you create an effect that watches a signal:
+When you create a subscription that watches a signal:
 
-1. **Registration**: The signal registers the effect as a watcher
+1. **Registration**: The signal registers the subscription as a watcher
 2. **Waiting**: The signal waits for `.trigger()` to be called
-3. **Notification**: When triggered, all watching effects are scheduled to run
-4. **Re-execution**: Each watching effect re-executes its function
+3. **Notification**: When triggered, all watching subscriptions are scheduled to run
+4. **Re-execution**: Each watching subscription re-executes its function
 
 ```mermaid
 sequenceDiagram
     participant User
     participant Signal as $refresh (Signal)
-    participant Effect
+    participant Subscription
     
-    Note over User,Effect: 1. Setup Phase
-    User->>Effect: Create effect
-    activate Effect
-    Effect->>Signal: watch(t)
-    Note over Signal: Register Effect as watcher
-    Signal-->>Effect: Registered
-    Effect->>Effect: Execute function
-    Note over Effect: Log: "Ready to refresh"
-    deactivate Effect
+    Note over User,Subscription: 1. Setup Phase
+    User->>Subscription: Create subscription
+    activate Subscription
+    Subscription->>Signal: watch(t)
+    Note over Signal: Register Subscription as watcher
+    Signal-->>Subscription: Registered
+    Subscription->>Subscription: Execute function
+    Note over Subscription: Log: "Ready to refresh"
+    deactivate Subscription
     
-    Note over User,Effect: 2. Trigger Phase
+    Note over User,Subscription: 2. Trigger Phase
     User->>Signal: trigger()
     activate Signal
     Note over Signal: Notify all watchers
-    Signal->>Effect: Schedule execution
+    Signal->>Subscription: Schedule execution
     deactivate Signal
     
-    activate Effect
-    Note over Effect: Re-execute function
-    Effect->>Effect: Perform refresh
-    Note over Effect: Log: "Refreshing..."
-    deactivate Effect
+    activate Subscription
+    Note over Subscription: Re-execute function
+    Subscription->>Subscription: Perform refresh
+    Note over Subscription: Log: "Refreshing..."
+    deactivate Subscription
 ```
 
 ## Best Practices
@@ -174,12 +163,17 @@ const $handleSave = signal()
 const $userUpdated = signal()
 let currentUser: User | null = null
 
-effect((t) => {
-  $userUpdated.watch(t)
-  if (currentUser) {
-    renderUser(currentUser)
+subscribe(
+  (t) => {
+    $userUpdated.watch(t)
+    return currentUser
+  },
+  (user) => {
+    if (user) {
+      renderUser(user)
+    }
   }
-})
+)
 
 function setUser(user: User) {
   currentUser = user
@@ -193,8 +187,7 @@ function setUser(user: User) {
 // ✅ Good - state holds the value
 const $currentUser = state<User | null>(null)
 
-effect((t) => {
-  const user = $currentUser.get(t)
+$currentUser.subscribe((user) => {
   if (user) {
     renderUser(user)
   }
@@ -205,36 +198,6 @@ function setUser(user: User) {
 }
 ```
 
-### Forgetting to Watch the Signal
-
-**Problem**: Calling `.trigger()` without any watchers.
-
-```typescript
-// ❌ Bad - nothing watches the signal
-const $refresh = signal()
-
-effect((t) => {
-  // Forgot to watch!
-  performRefresh()
-})
-
-$refresh.trigger() // Effect won't run
-```
-
-**Solution**: Make sure to call `.watch(t)`:
-
-```typescript
-// ✅ Good - explicitly watch the signal
-const $refresh = signal()
-
-effect((t) => {
-  $refresh.watch(t) // Now it will react!
-  performRefresh()
-})
-
-$refresh.trigger() // Effect runs
-```
-
 ### Over-Triggering
 
 **Problem**: Triggering a signal in a loop or too frequently.

package/docs/guide/primitives/state.md

@@ -1,24 +1,18 @@
 # State
 
-**State** is a reactive primitive that holds a mutable value. When you update the state, all effects and derivations watching it automatically re-execute.
-
-Imagine a thermometer in your home. The temperature is state - it changes throughout the day, and your heating system watches it to decide when to turn on or off. That's exactly what state does in PicoFlow.
+**State** is a reactive primitive that holds a mutable value. 
 
 ### Key Characteristics
 
 - **Mutable**: Can be updated with `.set()`
 - **Reactive**: Automatically notifies watchers on changes
 - **Equality checking**: Only notifies if the new value differs from the current value
-- **Type-safe**: TypeScript ensures updates match the initial type
 
 ## When to Use State
 
 Use state when you need to:
 
 - ✅ Track values that change over time
-- ✅ Respond to user input or interactions
-- ✅ Store data fetched from APIs
-- ✅ Manage application state (UI state, form data, etc.)
 
 Don't use state when:
 
@@ -45,45 +39,35 @@ The value you pass becomes the initial value. It can be any type: numbers, strin
 
 State provides methods for reading, updating, and disposing.
 
-### Reading with `.get(t)`
+### Get
 
-Inside an effect or derivation, use `.get(t)` to read the value and create a dependency:
+Inside a subscription or derivation, use `.get(t)` to read the value and create a dependency:
 
 ```typescript
-import { state, effect } from '@ersbeth/picoflow'
-
 const $count = state(0)
+const $double = derivation((t) => $count.get(t) * 2)
 
-effect((t) => {
-  const value = $count.get(t) // Read and track
-  console.log('Count is:', value)
+$double.subscribe((value) => {
+  console.log('Double is:', value)
 })
 
-$count.set(1) // Console logs: "Count is: 1"
-$count.set(2) // Console logs: "Count is: 2"
+$count.set(1) // Console logs: "Double is: 2"
+$count.set(2) // Console logs: "Double is: 4"
 ```
 
-### Reading with `.pick()`
+### Pick
 
 Use `.pick()` when you want the current value without creating a dependency:
 
 ```typescript
 const $count = state(0)
 
-// Read without tracking (e.g., outside an effect)
-const currentValue = $count.pick()
+// Read without tracking (e.g., outside a subscription)
+const currentValue = await $count.pick()
 console.log(currentValue) // 0
-
-// Or inside an effect, when you don't want to track changes
-const $trigger = signal()
-effect((t) => {
-  $trigger.watch(t)           // Only track trigger
-  const snapshot = $count.pick() // Don't track count
-  console.log(snapshot)
-})
 ```
 
-### Updating with `.set(value)`
+### Update
 
 Pass the new value directly to `.set()`:
 
@@ -94,8 +78,6 @@ $count.set(5)   // Set to 5
 $count.set(10)  // Set to 10
 ```
 
-### Updating with `.set(updater)`
-
 Pass a function that receives the current value and returns the new value:
 
 ```typescript
@@ -111,7 +93,7 @@ $count.set(n => Math.max(0, n - 1)) // Decrement, min 0
 - To guarantee you're working with the latest value
 - For atomic updates (important in concurrent scenarios)
 
-### Disposing with `.dispose()`
+### Dispose
 
 State can be disposed to free resources and prevent memory leaks:
 
@@ -119,8 +101,8 @@ State can be disposed to free resources and prevent memory leaks:
 const $count = state(0)
 
 // Use the state
-effect((t) => {
-  console.log($count.get(t))
+$count.subscribe((value) => {
+  console.log(value)
 })
 
 // Later, clean up
@@ -134,16 +116,12 @@ $count.set(5) // Error: Primitive is disposed
 
 When you update state, a specific flow occurs to ensure efficiency and consistency.
 
-### Update Flow
-
-Here's what happens when you call `.set()`:
-
 ```mermaid
 sequenceDiagram
     participant User
     participant $count as $count (State)
     participant $double as $double (Derivation)
-    participant Effect
+    participant Subscription
     
     User->>$count: set(n => n + 1)
     activate $count
@@ -156,18 +134,18 @@ sequenceDiagram
     Note over $double: Mark as dirty<br/>NO recompute yet
     deactivate $double
     
-    $count->>Effect: Schedule execution
+    $count->>Subscription: Schedule execution
     deactivate $count
     
-    activate Effect
-    Note over Effect: Execute function
+    activate Subscription
+    Note over Subscription: Execute function
     
-    Effect->>$count: get(t)
+    Subscription->>$count: get(t)
     activate $count
-    $count-->>Effect: 1
+    $count-->>Subscription: 1
     deactivate $count
     
-    Effect->>$double: get(t)
+    Subscription->>$double: get(t)
     activate $double
     Note over $double: Dirty? YES<br/>Recompute now
     
@@ -177,11 +155,11 @@ sequenceDiagram
     deactivate $count
     
     Note over $double: Compute: 1 * 2 = 2
-    $double-->>Effect: 2
+    $double-->>Subscription: 2
     deactivate $double
     
-    Note over Effect: Log: "Count: 1, Double: 2"
-    deactivate Effect
+    Note over Subscription: Log: "Count: 1, Double: 2"
+    deactivate Subscription
 ```
 
 **How it works:**
@@ -192,8 +170,8 @@ sequenceDiagram
 4. **Update value**: Store the new value
 5. **Notify dependents**: 
    - Derivations are marked dirty (not recomputed yet)
-   - Effects are scheduled for execution
-6. **Pull-based recompute**: When effects run and read derivations, they recompute
+   - Subscriptions are scheduled for execution
+6. **Pull-based recompute**: When subscriptions run and read derivations, they recompute
 
 ### Equality Check Example
 
@@ -203,27 +181,27 @@ State only notifies when the value actually changes:
 sequenceDiagram
     participant User
     participant $count as $count (State)
-    participant Effect
+    participant Subscription
     
-    Note over User,Effect: Initial state: $count = 5
+    Note over User,Subscription: Initial state: $count = 5
     
     User->>$count: set(5)
     activate $count
     Note over $count: Check: 5 === 5?<br/>YES - no change
     Note over $count: Skip notification
     deactivate $count
-    Note over Effect: Effect does NOT run
+    Note over Subscription: Subscription does NOT run
     
     User->>$count: set(10)
     activate $count
     Note over $count: Check: 10 === 5?<br/>NO - value changed
     Note over $count: Update: 5 → 10
-    $count->>Effect: Notify & schedule
+    $count->>Subscription: Notify & schedule
     deactivate $count
     
-    activate Effect
-    Note over Effect: Effect runs
-    deactivate Effect
+    activate Subscription
+    Note over Subscription: Subscription runs
+    deactivate Subscription
 ```
 
 ## Best Practices
@@ -279,7 +257,6 @@ const form = {
 }
 ```
 
-### Name State Clearly
 
 Use the `$` prefix for all reactive values:
 
@@ -293,76 +270,3 @@ const $isLoading = state(false)
 const count = state(0)
 const user = state({...})
 ```
-
-## Common Pitfalls
-
-### Using `.pick()` in Effects
-
-**Problem**: Using `.pick()` inside effects prevents reactivity.
-
-```typescript
-// ❌ Wrong - will never update
-effect((t) => {
-  const count = $count.pick() // No dependency created!
-  console.log(count) // Only logs once
-})
-```
-
-**Solution**: Use `.get(t)` to create dependencies:
-
-```typescript
-// ✅ Correct - creates dependency
-effect((t) => {
-  const count = $count.get(t) // Creates dependency
-  console.log(count) // Logs on every change
-})
-```
-
-### Forgetting Updater Functions
-
-**Problem**: Reading and setting separately creates race conditions.
-
-```typescript
-// ❌ Potential race condition
-const current = $count.pick()
-$count.set(current + 1)
-// What if $count changes between pick() and set()?
-```
-
-**Solution**: Use updater functions:
-
-```typescript
-// ✅ Safe - uses latest value atomically
-$count.set(n => n + 1)
-```
-
-### Mutating State Directly
-
-**Problem**: Directly mutating arrays or objects doesn't trigger updates.
-
-```typescript
-const $items = state([1, 2, 3])
-
-// ❌ Wrong - mutates the array
-const items = $items.pick()
-items.push(4) // Doesn't trigger updates!
-
-// ❌ Also wrong - same array reference
-$items.set(items => {
-  items.push(4) // Mutation!
-  return items // Same reference, no notification!
-})
-```
-
-**Solution**: Create new arrays/objects (or use FlowArray/FlowMap):
-
-```typescript
-// ✅ Correct - creates new array
-$items.set(items => [...items, 4])
-
-// ✅ Also correct - for objects
-$user.set(user => ({
-  ...user,
-  age: user.age + 1
-}))
-```

package/package.json

@@ -1,61 +1,57 @@
 {
-  "name": "@ersbeth/picoflow",
-  "version": "1.1.2",
-  "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"
-  }
-}
+    "name": "@ersbeth/picoflow",
+    "version": "2.0.0",
+    "description": "Minimal Dataflow library for TypeScript",
+    "type": "module",
+    "exports": {
+        "types": "./dist/types/index.d.ts",
+        "default": "./dist/picoflow.js"
+    },
+    "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",
+        "test:browser": "pnpm exec vitest --config=vitest.browser.config.ts",
+        "docs:dev": "pnpm exec vitepress dev docs",
+        "docs:build": "pnpm docs:generate && pnpm exec vitepress build docs",
+        "docs:preview": "pnpm exec vitepress preview docs",
+        "docs:generate": "pnpm exec typedoc"
+    },
+    "peerDependencies": {
+        "solid-js": "^1.9.7"
+    },
+    "devDependencies": {
+        "@biomejs/biome": "2.3.8",
+        "@braintree/sanitize-url": "^7.1.1",
+        "@solidjs/testing-library": "^0.8.10",
+        "@vitest/browser-playwright": "^4.0.16",
+        "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": "^7.3.0",
+        "vite-plugin-dts": "^4.5.4",
+        "vite-plugin-solid": "^2.11.10",
+        "vite-tsconfig-paths": "^6.0.3",
+        "vitepress": "^1.6.4",
+        "vitepress-plugin-mermaid": "^2.0.17",
+        "vitest": "^4.0.16"
+    },
+    "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"
+}