@zeix/cause-effect 0.17.0 → 0.17.2

package/README.md

@@ -1,8 +1,8 @@
 # Cause & Effect
 
-Version 0.17.0
+Version 0.17.2
 
-**Cause & Effect** is a lightweight, reactive state management library for JavaScript applications. It uses fine-grained reactivity with signals to create predictable and efficient data flow in your app.
+**Cause & Effect** is a tiny (~5kB gzipped), dependency-free reactive state library for JavaScript. It uses fine-grained signals so derived values and side effects update automatically when their dependencies change.
 
 ## What is Cause & Effect?
 
@@ -10,23 +10,33 @@ Version 0.17.0
 
 ### Core Concepts
 
-- **State signals**: Hold values that can be directly modified: `new State()`
-- **Memo signals**: Derive memoized values from other signals: `new Memo()`
-- **Task signals**: Execute asynchronous functions of other signals: `new Task()`
-- **Store signals**: Hold objects of nested reactive properties: `createStore()`
-- **List signals**: Create keyed lists with reactive items: `new List()`
-- **Collection signals**: Read-only derived array transformations: `new Collection()`
-- **Effects**: Run side effects when signals change: `createEffect()`
+- **State**: mutable value (`new State()`)
+- **Memo**: derived & memoized value (`new Memo()`)
+- **Effect**: runs when dependencies change (`createEffect()`)
+- **Task**: async derived value with cancellation (`new Task()`)
+- **Store**: object with reactive nested props (`createStore()`)
+- **List**: mutable array with stable keys & reactive items (`new List()`)
+- **Collection**: read-only derived arrays from Lists (`new DerivedCollection()`)
+- **Ref**: external mutable objects + manual .notify() (`new Ref()`)
 
 ## Key Features
 
-- ⚡ **Reactive States**: Automatic updates when dependencies change
-- 🧩 **Composable**: Create a complex signal graph with a minimal API
-- ⏱️ **Async Ready**: Built-in `Promise` and `AbortController` support
-- 🛡️ **Error Handling**: Built-in helper functions for declarative error handling
-- 🔧 **Helper Functions**: `resolve()` and `match()` for type-safe value extraction and pattern matching for suspense and error boundaries
-- 🚀 **Performance**: Batching and efficient dependency tracking
-- 📦 **Tiny**: Less than 3kB gzipped, tree-shakable, zero dependencies
+- ⚡ **Fine-grained reactivity** with automatic dependency tracking
+- 🧩 **Composable signal graph** with a small API
+- ⏱️ **Async ready** (`Task`, `AbortController`, async `DerivedCollection`)
+- 🛡️ **Declarative error handling** (`resolve()` + `match()`)
+- 🚀 **Batching** and efficient dependency tracking
+- 📦 **Tree-shakable**, zero dependencies
+
+## Installation
+
+```bash
+# with npm
+npm install @zeix/cause-effect
+
+# or with bun
+bun add @zeix/cause-effect
+```
 
 ## Quick Start
 
@@ -37,7 +47,7 @@ import { createEffect, Memo, State } from '@zeix/cause-effect'
 const user = new State({ name: 'Alice', age: 30 })
 
 // 2. Create computed values
-const greeting = Memo(() => `Hello ${user.get().name}!`)
+const greeting = new Memo(() => `Hello ${user.get().name}!`)
 
 // 3. React to changes
 createEffect(() => {
@@ -48,521 +58,333 @@ createEffect(() => {
 user.update(u => ({ ...u, age: 31 })) // Logs: "Hello Alice! You are 31 years old"
 ```
 
-## Installation
-
-```bash
-# with npm
-npm install @zeix/cause-effect
-
-# or with bun
-bun add @zeix/cause-effect
-```
-
 ## Usage of Signals
 
-### State Signals
+### State
 
-`new State()` creates a mutable signal. Every signal has a `.get()` method to access its current value. State signals also provide `.set()` to directly assign a new value and `.update()` to modify the value with a function.
+A `State` is a mutable signal. Every signal has a `.get()` method to access its current value. State signals also provide `.set()` to directly assign a new value and `.update()` to modify the value with a function.
 
 ```js
 import { createEffect, State } from '@zeix/cause-effect'
 
 const count = new State(42)
-createEffect(() => {
-  console.log(count.get()) // logs '42'
-})
-count.set(24) // logs '24'
+
+createEffect(() => console.log(count.get()))
+count.set(24)
+
 document.querySelector('.increment').addEventListener('click', () => {
   count.update(v => ++v)
 })
-// Click on button logs '25', '26', and so on
 ```
 
-### Store Signals
+Use `State` for primitives or for objects you typically replace entirely.
 
-`createStore()` creates a mutable signal that holds an object with nested reactive properties. Each property automatically becomes its own signal with `.get()`, `.set()`, and `.update()` methods. Nested objects recursively become nested stores.
+### Memo
 
-```js
-import { createStore, createEffect } from '@zeix/cause-effect'
-
-const user = createStore({
-  name: 'Alice',
-  age: 30,
-  preferences: {
-    theme: 'dark',
-    notifications: true
-  }
-})
-
-// Individual properties are reactive
-createEffect(() => {
-  console.log(`${user.name.get()} is ${user.age.get()} years old`)
-})
+A `Memo` is a memoized read-only signal that automatically tracks dependencies and updates only when those dependencies change.
 
-// Nested properties work the same way
-createEffect(() => {
-  console.log(`Theme: ${user.preferences.theme.get()}`)
-})
+```js
+import { State, Memo, createEffect } from '@zeix/cause-effect'
 
-// Update individual properties
-user.age.update(v => v + 1) // Logs: "Alice is 31 years old"
-user.preferences.theme.set('light') // Logs: "Theme: light"
+const count = new State(42)
+const isEven = new Memo(() => !(count.get() % 2))
 
-// Watch the entire store
-createEffect(() => {
-  console.log('User data:', user.get()) // Triggers on any nested change
-})
+createEffect(() => console.log(isEven.get()))
+count.set(24) // no log; still even
 ```
 
-#### When to Use
-
-**When to use stores vs states:**
-
-- **Use `createStore()`** for objects with properties that you want to access and modify individually.
-- **Use `new State()`** for primitive values (numbers, strings, booleans) or objects you access and replace entirely.
-
-#### Dynamic Properties
-
-Stores support dynamic property addition and removal at runtime using the `add()` and `remove()` methods:
+**Tip**: For simple derivations, a plain function can be faster:
 
 ```js
-import { createStore, createEffect } from '@zeix/cause-effect'
-
-const settings = store({ autoSave: true })
-
-// Add new properties at runtime
-settings.add('timeout', 5000)
-console.log(settings.timeout.get()) // 5000
+const isEven = () => !(count.get() % 2)
+```
 
-// Adding an existing property has no effect
-settings.add('autoSave', false) // Ignored - autoSave remains true
+**Advanced**: Reducer-style memos:
 
-// Remove properties
-settings.remove('timeout')
-console.log(settings.timeout) // undefined
+```js
+import { State, Memo } from '@zeix/cause-effect'
 
-// Removing non-existent properties has no effect
-settings.remove('nonExistent') // Safe - no error thrown
+const actions = new State('reset')
+const counter = new Memo((prev) => {
+  switch (actions.get()) {
+    case 'increment': return prev + 1
+    case 'decrement': return prev - 1
+    case 'reset': return 0
+    default: return prev
+  }
+}, 0)
 ```
 
-The `add()` and `remove()` methods are optimized for performance:
-- They bypass the full reconciliation process used by `set()` and `update()`
-- They're perfect for frequent single-property additions/removals
-- They trigger the same events and reactivity as other store operations
+### Task
 
-### List Signals
-
-`new List()` creates a mutable signal for arrays with individually reactive items and stable keys. Each item becomes its own signal while maintaining persistent identity through sorting and reordering:
+A `Task` handles asynchronous computations with cancellation support:
 
 ```js
-import { List, createEffect } from '@zeix/cause-effect'
-
-const items = new List(['banana', 'apple', 'cherry'])
+import { State, Task } from '@zeix/cause-effect'
 
-// Duck-typing: behaves like an array
-console.log(items.length) // 3
-console.log(typeof items.length) // 'number'
+const id = new State(1)
 
-// Individual items are reactive
-createEffect(() => {
-  console.log(`First item: ${items[0].get()}`)
+const data = new Task(async (oldValue, abort) => {
+  const response = await fetch(`/api/users/${id.get()}`, { signal: abort })
+  if (!response.ok) throw new Error('Failed to fetch')
+  return response.json()
 })
 
-// Single-parameter add() appends to end
-items.add('date') // Adds at index 3
-console.log(items.get()) // ['banana', 'apple', 'cherry', 'date']
-
-// Splice allows removal and insertion at specific indices
-items.splice(1, 1, 'orange') // Removes 'apple' and inserts 'orange' at index 1
-console.log(items.get()) // ['banana', 'orange', 'cherry', 'date']
-
-// Efficient sorting preserves signal references
-items.sort() // Default: string comparison
-console.log(items.get()) // ['apple', 'banana', 'cherry', 'date', 'orange']
-
-// Custom sorting
-items.sort((a, b) => b.localeCompare(a)) // Reverse alphabetical
-console.log(items.get()) // ['orange', 'date', 'cherry', 'banana', 'apple']
+id.set(2) // cancels previous fetch automatically
 ```
 
-List signals have stable unique keys for entries. This means that the keys for each item in the list will not change even if the items are reordered. Keys default to a string representation of an auto-incrementing number. You can customize keys by passing a prefix string or a function to derive the key from the entry value as the second argument to `new List()`:
-
-```js
-const items = new List(['banana', 'apple', 'cherry', 'date'], 'item-')
-
-// Add returns the key of the added item
-const orangeKey = items.add('orange')
-
-// Sort preserves signal references
-items.sort()
-console.log(items.get()) // ['apple', 'banana', 'cherry', 'date', 'orange']
-
-// Access items by key
-console.log(items.byKey(orangeKey)) // 'orange'
+**Note**: Use Task (not plain async functions) when you want memoization + cancellation + reactive pending/error states.
 
-const users = new List(
-  [{ id: 'bob', name: 'Bob' }, { id: 'alice', name: 'Alice' }],
-  user => user.id
-)
+### Store
 
-// Sort preserves signal references
-users.sort((a, b) => a.name.localeCompare(b.name)) // Alphabetical by name
-console.log(users.get()) // [{ id: 'alice', name: 'Alice' }, { id: 'bob', name: 'Bob' }]
-
-// Get current positional index for an item
-console.log(users.indexOfKey('alice')) // 0
-
-// Get key at index
-console.log(users.keyAt(1)) // 'bob'
-```
-
-### Collection Signals
-
-`new Collection()` creates read-only derived arrays that transform items from Lists with automatic memoization and async support:
+A `Store` is a reactive object. Each property automatically becomes its own signal with `.get()`, `.set()`, and `.update()` methods. Nested objects recursively become nested stores.
 
 ```js
-import { List, Collection, createEffect } from '@zeix/cause-effect'
-
-// Source list
-const users = new List([
-  { id: 1, name: 'Alice', role: 'admin' },
-  { id: 2, name: 'Bob', role: 'user' }
-])
+import { createStore, createEffect } from '@zeix/cause-effect'
 
-// Derived collection - transforms each user
-const userProfiles = new Collection(users, user => ({
-  ...user,
-  displayName: `${user.name} (${user.role})`
-}))
+const user = createStore({
+  name: 'Alice',
+  age: 30,
+  preferences: { theme: 'dark', notifications: true }
+})
 
-// Collections are reactive and memoized
 createEffect(() => {
-  console.log('Profiles:', userProfiles.get())
-  // [{ id: 1, name: 'Alice', role: 'admin', displayName: 'Alice (admin)' }, ...]
+  console.log(`${user.name.get()} is ${user.age.get()} years old`)
 })
 
-// Individual items are computed signals
-console.log(userProfiles.at(0).get().displayName) // 'Alice (admin)'
-
-// Collections support async transformations
-const userDetails = new Collection(users, async (user, abort) => {
-  const response = await fetch(`/users/${user.id}`, { signal: abort })
-  return { ...user, details: await response.json() }
-})
+user.age.update(v => v + 1)
+user.preferences.theme.set('light')
 
-// Collections can be chained
-const adminProfiles = new Collection(userProfiles, profile => 
-  profile.role === 'admin' ? profile : null
-).filter(Boolean) // Remove null values
+// Watch the full object
+createEffect(() => console.log('User:', user.get()))
 ```
 
-Collections support access by index or key:
+Dynamic properties using the `add()` and `remove()` methods:
 
 ```js
-// Access by index or key (read-only)
-const firstProfile = userProfiles.at(0) // Returns computed signal
-const profileByKey = userProfiles.byKey('user1') // Access by stable key
-
-// Array methods work
-console.log(userProfiles.length) // Reactive length
-for (const profile of userProfiles) {
-  console.log(profile.get()) // Each item is a computed signal
-}
-
-// Lists can derive collections directly
-const userSummaries = users.deriveCollection(user => ({
-  id: user.id,
-  summary: `${user.name} is a ${user.role}`
-}))
-```
-
-#### When to Use Collections vs Lists
-
-- **Use `new List()`** for mutable arrays where you add, remove, sort, or modify items
-- **Use `new Collection()`** for read-only transformations, filtering, or async processing of Lists
-- **Chain Collections** to create multi-step data pipelines with automatic memoization
+const settings = createStore({ autoSave: true })
 
-#### Store Change Notifications
+settings.add('timeout', 5000)
+settings.remove('timeout')
+```
 
-Stores emit notifications (sort of light-weight events) when properties are added, changed, or removed. You can listen to these notications using the `.on()` method:
+Subscribe to hooks using the `.on()` method:
 
 ```js
-import { createStore } from '@zeix/cause-effect'
-
 const user = createStore({ name: 'Alice', age: 30 })
 
-// Listen for property additions
-const offAdd = user.on('add', (added) => {
-  console.log('Added properties:', added)
-})
-
-// Listen for property changes
-const offChange = user.on('change', (changed) => {
-  console.log('Changed properties:', changed)
-})
-
-// Listen for property removals
-const offRemove = user.on('remove', (removed) => {
-  console.log('Removed properties:', removed)
-})
-
-// These will trigger the respective notifications:
-user.add('email', 'alice@example.com') // Logs: "Added properties: { email: 'alice@example.com' }"
-user.age.set(31)                       // Logs: "Changed properties: { age: 31 }"
-user.remove('email')                   // Logs: "Removed properties: { email: UNSET }"
+const offChange = user.on('change', changed => console.log(changed))
+const offAdd = user.on('add', added => console.log(added))
+const offRemove = user.on('remove', removed => console.log(removed))
 
-// Listen for sort notifications (useful for UI animations)
-const items = new List(['banana', 'apple', 'cherry'])
-items.sort((a, b) => b.localeCompare(a)) // Reverse alphabetical
-const offSort = items.on('sort', (newOrder) => {
-  console.log('Items reordered:', newOrder) // ['2', '1', '0']
-})
+// These will trigger the respective hooks:
+user.add('email', 'alice@example.com') // Logs: "Added properties: ['email']"
+user.age.set(31)                       // Logs: "Changed properties: ['age']"
+user.remove('email')                   // Logs: "Removed properties: ['email']"
 ```
 
-Notifications are also fired when using `set()`, `update()`, or `splice()` methods:
+To unregister hooks, call the returned cleanup functions:
 
 ```js
-// This will fire multiple notifications based on what changed
-user.update(u => ({ ...u, name: 'Bob', city: 'New York' }))
-// Logs: "Changed properties: { name: 'Bob' }"
-// Logs: "Added properties: { city: 'New York' }"
+offAdd() // Stop listening to add hook
+offChange() // Stop listening to change hook
+offRemove() // Stop listening to remove hook
 ```
 
-To stop listening to notifications, call the returned cleanup function:
+### List
 
-```js
-offAdd() // Stops listening to add notifications
-offChange() // Stops listening to change notifications
-offRemove() // Stops listening to remove notifications
-offSort() // Stops listening to sort notifications
-```
+A `List` is a mutable signal for arrays with individually reactive items and stable keys. Each item becomes its own signal while maintaining persistent identity through sorting and reordering:
 
-### Computed Signals
+```js
+import { List, createEffect } from '@zeix/cause-effect'
 
-`new Memo()` creates a memoized read-only signal that automatically tracks dependencies and updates only when those dependencies change.
+const items = new List(['banana', 'apple', 'cherry'])
 
-```js
-import { createEffect, Memo, State } from '@zeix/cause-effect'
+createEffect(() => console.log(`First: ${items[0].get()}`))
 
-const count = new State(42)
-const isEven = new Memo(() => !(count.get() % 2))
-createEffect(() => console.log(isEven.get())) // logs 'true'
-count.set(24) // logs nothing because 24 is also an even number
-document.querySelector('button.increment').addEventListener('click', () => {
-  count.update(v => ++v)
-})
-// Click on button logs 'false', 'true', and so on
+items.add('date')
+items.splice(1, 1, 'orange')
+items.sort()
 ```
 
-#### When to Use
-
-**Performance tip**: For simple derivations, plain functions often outperform computed signals:
+Keys are stable across reordering:
 
 ```js
-// More performant for simple calculations
-const isEven = () => !(count.get() % 2)
+const items = new List(['banana', 'apple'], 'item-')
+const key = items.add('orange')
+
+items.sort()
+console.log(items.byKey(key))     // 'orange'
+console.log(items.indexOfKey(key)) // current index
 ```
 
-**When to use which approach:**
+Lists have `.add()`, `.remove()` and `.on()` methods like stores. In addition, they have `.sort()` and `.splice()` methods. But unlike stores, deeply nested properties in items are not converted to individual signals.
 
-- **Use functions when**: The calculation is simple, inexpensive, or called infrequently.
-- **Use new Memo() when**:
-  - The calculation is expensive
-  - You need to share the result between multiple consumers
-  - You're working with asynchronous operations
-  - You need to track specific error states
-  
-#### Reducer Capabilities
+### Collection
 
-`new Memo()` supports reducer patterns by accepting an initial value and providing access to the previous value in the callback:
+A `Collection` is a read-only derived reactive list from `List` or another `Collection`:
 
 ```js
-import { createEffect, Memo, State } from '@zeix/cause-effect'
-
-const actions = new State('increment')
-const counter = new Memo((prev) => {
-  const action = actions.get()
-  switch (action) {
-    case 'increment':
-      return prev + 1
-    case 'decrement':
-      return prev - 1
-    case 'reset':
-      return 0
-    default:
-      return prev
-  }
-}, 0) // Initial value of 0
+import { List, createEffect } from '@zeix/cause-effect'
 
-createEffect(() => console.log('Counter:', counter.get()))
+const users = new List([
+  { id: 1, name: 'Alice', role: 'admin' },
+  { id: 2, name: 'Bob', role: 'user' }
+])
+const profiles = users.deriveCollection(user => ({
+  ...user,
+  displayName: `${user.name} (${user.role})`
+}))
 
-// Dispatch actions
-actions.set('increment') // Counter: 1
-actions.set('increment') // Counter: 2
-actions.set('decrement') // Counter: 1
-actions.set('reset')     // Counter: 0
+createEffect(() => console.log('Profiles:', profiles.get()))
+console.log(userProfiles.at(0).get().displayName)
 ```
 
-This pattern is particularly useful for:
-- State machines with transitions based on current state
-- Accumulating values over time
-- Complex state updates that depend on previous state
-- Building reactive reducers similar to Redux patterns
+Async mapping is supported: 
 
-#### Asynchronous Computations with Automatic Cancellation
+```js
+const details = users.derivedCollection(async (user, abort) => {
+  const response = await fetch(`/users/${user.id}`, { signal: abort })
+  return { ...user, details: await response.json() }
+})
+```
 
-`new Task()` seamlessly handles asynchronous operations with built-in cancellation support. When used with an async function, it:
+### Ref
 
-1. Provides an `abort` signal parameter you can pass to fetch or other cancelable APIs
-2. Automatically cancels pending operations when dependencies change
-3. Returns `UNSET` while the Promise is pending
-4. Properly handles errors from failed requests
+A `Ref` is a signal that holds a reference to an external object that can change outside the reactive system.
 
 ```js
-import { createEffect, match, resolve, State, Task } from '@zeix/cause-effect'
+import { createEffect, Ref } from '@zeix/cause-effect'
 
-const id = new State(42)
-const data = new Task(async (_, abort) => {
-  // The abort signal is automatically managed by the computed signal
-  const response = await fetch(`/api/entries/${id.get()}`, { signal: abort })
-  if (!response.ok) throw new Error(`Failed to fetch data: ${response.statusText}`)
-  return response.json()
-})
+const elementRef = new Ref(document.getElementById('status'))
 
-// Handle all possible states using resolve and match helpers
-createEffect(() => {
-  match(resolve({ data }), {
-    ok: ({ data: json }) => console.log('Data loaded:', json),
-    nil: () => console.log('Loading...'),
-    err: errors => console.error('Error:', errors[0])
-  })
-})
+createEffect(() => console.log(elementRef.get().className))
 
-// When id changes, the previous request is automatically canceled
-document.querySelector('button.next').addEventListener('click', () => {
-  id.update(v => ++v)
-})
+// external mutation happened
+elementRef.notify()
 ```
 
-**Note**: Always use `new Task()` (not plain functions) for async operations to benefit from automatic cancellation, memoization, and error handling.
-
-## Effects and Error Handling
+Use `Ref` for DOM nodes, Maps/Sets, sockets, third-party objects, etc.
 
-The `createEffect()` function supports both synchronous and asynchronous callbacks:
+## Effects
 
-### Synchronous Effects
+The `createEffect()` callback runs whenever the signals it reads change. It supports sync or async callbacks and returns a cleanup function.
 
 ```js
-import { createEffect, State } from '@zeix/cause-effect'
+import { State, createEffect } from '@zeix/cause-effect'
 
 const count = new State(42)
-createEffect(() => {
-  console.log('Count changed:', count.get())
+
+const cleanup = createEffect(() => {
+  console.log(count.get())
+  return () => console.log('Cleanup')
 })
-```
 
-### Asynchronous Effects with AbortSignal
+cleanup()
+```
 
-Async effect callbacks receive an `AbortSignal` parameter that automatically cancels when the effect re-runs or is cleaned up:
+Async effects receive an AbortSignal that cancels on rerun or cleanup:
 
 ```js
-import { createEffect, State } from '@zeix/cause-effect'
-
-const userId = new State(1)
-createEffect(async (abort) => {
-  try {
-    const response = await fetch(`/api/users/${userId.get()}`, { signal: abort })
-    const user = await response.json()
-    console.log('User loaded:', user)
-  } catch (error) {
-    if (!abort.aborted) {
-      console.error('Failed to load user:', error)
-    }
-  }
+createEffect(async abort => {
+  const res = await fetch('/api', { signal: abort })
+  if (res.ok) console.log(await res.json())
 })
 ```
 
-### Error Handling with Helper Functions
+### Error Handling: resolve() + match()
 
-For more sophisticated error handling, use the `resolve()` and `match()` helper functions:
+Use `resolve()` to extract values from signals (including pending/err states) and `match()` to handle them declaratively:
 
 ```js
-import { createEffect, resolve, match, State } from '@zeix/cause-effect'
+import { State, Task, createEffect, resolve, match } from '@zeix/cause-effect'
 
 const userId = new State(1)
-const userData = createEffect(async (abort) => {
-  const response = await fetch(`/api/users/${userId.get()}`, { signal: abort })
-  if (!response.ok) throw new Error(`HTTP ${response.status}`)
-  return response.json()
+const userData = new Task(async (_, abort) => {
+  const res = await fetch(`/api/users/${userId.get()}`, { signal: abort })
+  if (!res.ok) throw new Error(`HTTP ${res.status}`)
+  return res.json()
 })
 
 createEffect(() => {
   match(resolve({ userData }), {
-    ok: ({ userData: user }) => console.log('User loaded:', user),
-    nil: () => console.log('Loading user...'),
-    err: errors => console.error('Error loading user:', errors[0])
+    ok: ({ userData: user }) => console.log('User:', user),
+    nil: () => console.log('Loading...'),
+    err: errors => console.error(errors[0])
   })
 })
 ```
 
-The `resolve()` function extracts values from signals and returns a discriminated union result, while `match()` provides pattern matching for handling different states declaratively.
+## Signal Type Decision Tree
+
+```
+Is the value managed *inside* the reactive system?
+│
+├─ No → Use `Ref`
+│        (DOM nodes, Map/Set, Date, sockets, 3rd-party objects)
+│        Remember: call `.notify()` when it changes externally.
+│
+└─ Yes? What kind of data is it?
+    │
+    ├─ *Primitive* (number/string/boolean)
+    │   │
+    │   ├─ Do you want to mutate it directly?
+    │   │     └─ Yes → `State`
+    │   │
+    │   └─ Is it derived from other signals?
+    │         │
+    │         ├─ Sync derived
+    │         │     ├─ Simple/cheap → plain function (preferred)
+    │         │     └─ Expensive/shared/stateful → `Memo`
+    │         │     
+    │         └─ Async derived → `Task`
+    │            (cancellation + memoization + pending/error state)
+    │
+    ├─ *Plain Object*
+    │   │
+    │   ├─ Do you want to mutate individual properties?
+    │   │     ├─ Yes → `Store`
+    │   │     └─ No, whole object mutations only → `State`
+    │   │
+    │   └─ Is it derived from other signals?
+    │         ├─ Sync derived → plain function or `Memo`
+    │         └─ Async derived → `Task`
+    │
+    └─ *Array*
+        │
+        ├─ Do you need to mutate it (add/remove/sort) with stable item identity?
+        │     ├─ Yes → `List`
+        │     └─ No, whole array mutations only → `State`
+        │
+        └─ Is it derived / read-only transformation of a `List` or `Collection`?
+              └─ Yes → `Collection`
+                 (memoized + supports async mapping + chaining)
+```
 
 ## Advanced Usage
 
-### Batching Updates
+### Batching
 
-Use `batchSignalWrites()` to group multiple signal updates, ensuring effects run only once after all changes are applied:
+Group multiple signal updates, ensuring effects run only once after all changes are applied:
 
 ```js
-import {
-  createEffect,
-  batchSignalWrites,
-  resolve,
-  match,
-  Memo
-  State
-} from '@zeix/cause-effect'
-
-// State: define an Array<State<number>>
-const signals = [new State(2), new State(3), new State(5)]
-
-// Compute the sum of all signals
-const sum = new Memo(() => {
-  const v = signals.reduce((total, signal) => total + signal.get(), 0)
-  // Validate the result
-  if (!Number.isFinite(v)) throw new Error('Invalid value')
-  return v
-})
+import { batchSignalWrites, State } from '@zeix/cause-effect'
 
-// Effect: handle the result with error handling
-createEffect(() => {
-  match(resolve({ sum }), {
-    ok: ({ sum: v }) => console.log('Sum:', v),
-    err: errors => console.error('Error:', errors[0])
-  })
-})
+const a = new State(2)
+const b = new State(3)
 
-// Batch: apply changes to all signals in a single transaction
-document.querySelector('.double-all').addEventListener('click', () => {
-  batch(() => {
-    signals.forEach(signal => {
-      signal.update(v => v * 2)
-    })
-  })
+batchSignalWrites(() => {
+  a.set(4)
+  b.set(5)
 })
-// Click on button logs '20' only once
-// (instead of first '12', then '15' and then '20' without batch)
-
-// Provoke an error - but no worries: it will be handled fine
-signals[0].set(NaN)
 ```
 
-### Cleanup Functions
+### Cleanup
 
 Effects return a cleanup function. When executed, it will unsubscribe from signals and run cleanup functions returned by effect callbacks, for example to remove event listeners.
 
 ```js
-import { createEffect, State } from '@zeix/cause-effect'
+import { State, createEffect } from '@zeix/cause-effect'
 
 const user = new State({ name: 'Alice', age: 30 })
 const greeting = () => `Hello ${user.get().name}!`
@@ -577,31 +399,61 @@ cleanup() // Logs: 'Cleanup' and unsubscribes from signal `user`
 user.set({ name: 'Bob', age: 28 }) // Won't trigger the effect anymore
 ```
 
-## Helper Functions
+### Resource Management with Hooks
+
+All signals support the `watch` hook for lazy resource management. Resources are only allocated when the signal is first accessed by an effect, and automatically cleaned up when no effects are watching:
 
-### `resolve()` - Extract Signal Values
+```js
+import { State, createEffect } from '@zeix/cause-effect'
 
-The `resolve()` function extracts values from multiple signals and returns a discriminated union result:
+const config = new State({ apiUrl: 'https://api.example.com' })
+
+// Set up lazy resource management
+config.on('watch', () => {
+  console.log('Setting up API client...')
+  const client = new ApiClient(config.get().apiUrl)
+  
+  // Return cleanup function
+  return () => {
+    console.log('Cleaning up API client...')
+    client.disconnect()
+  }
+})
+
+// Resource is created only when effect runs
+const cleanup = createEffect(() => {
+  console.log('API URL:', config.get().apiUrl)
+})
+
+// Resource is cleaned up when effect stops
+cleanup()
+```
+
+This pattern is ideal for:
+- Event listeners that should only be active when data is being watched
+- Network connections that can be lazily established
+- Expensive computations that should pause when not needed
+- External subscriptions (WebSocket, Server-Sent Events, etc.)
+
+### resolve()
+
+Extract signal values:
 
 ```js
-import { Memo, resolve, State } from '@zeix/cause-effect'
+import { State, Memo, resolve } from '@zeix/cause-effect'
 
 const name = new State('Alice')
 const age = new Memo(() => 30)
 const result = resolve({ name, age })
 
-if (result.ok) {
-  console.log(result.values.name, result.values.age) // Type-safe access
-} else if (result.pending) {
-  console.log('Loading...')
-} else {
-  console.error('Errors:', result.errors)
-}
+if (result.ok) console.log(result.values.name, result.values.age)
+else if (result.pending) console.log('Loading...')
+else console.error('Errors:', result.errors)
 ```
 
-### `match()` - Pattern Matching for Side Effects
+### match()
 
-The `match()` function provides pattern matching on resolve results for side effects:
+Pattern matching on resolved results for side effects:
 
 ```js
 import { resolve, match } from '@zeix/cause-effect'
@@ -613,9 +465,9 @@ match(resolve({ name, age }), {
 })
 ```
 
-### `diff()` - Compare Object Changes
+### diff()
 
-The `diff()` function compares two objects and returns detailed information about what changed:
+Compare object changes:
 
 ```js
 import { diff } from '@zeix/cause-effect'
@@ -630,11 +482,9 @@ console.log(changes.change)   // { age: 31 }
 console.log(changes.remove)   // { city: UNSET }
 ```
 
-This function is used internally by stores to efficiently determine what changed and emit appropriate events.
+### isEqual()
 
-### `isEqual()` - Deep Equality Comparison
-
-The `isEqual()` function performs deep equality comparison with circular reference detection:
+Deep equality comparison with circular reference detection:
 
 ```js
 import { isEqual } from '@zeix/cause-effect'
@@ -652,12 +502,10 @@ console.log(isEqual('hello', 'hello'))               // true
 console.log(isEqual({ a: [1, 2] }, { a: [1, 2] }))   // true
 ```
 
-Both `diff()` and `isEqual()` include built-in protection against circular references and will throw a `CircularDependencyError` if cycles are detected.
-
 ## Contributing & License
 
 Feel free to contribute, report issues, or suggest improvements.
 
 License: [MIT](LICENSE)
 
-(c) 2024 – 2026 [Zeix AG](https://zeix.com)
+(c) 2024 - 2026 [Zeix AG](https://zeix.com)