@zeix/cause-effect 0.17.2 → 0.18.0

package/README.md

@@ -1,32 +1,40 @@
 # Cause & Effect
 
-Version 0.17.2
+Version 0.18.0
 
-**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.
+**Cause & Effect** is a reactive state management primitives library for TypeScript. It provides the foundational building blocks for managing complex, dynamic, composite, and asynchronous state — correctly and performantly — in a unified signal graph.
 
-## What is Cause & Effect?
+It is deliberately **not a framework**. It has no opinions about rendering, persistence, or application architecture. It is a thin, trustworthy layer over JavaScript that provides the comfort and guarantees of fine-grained reactivity while avoiding the common pitfalls of imperative code.
 
-**Cause & Effect** provides a simple way to manage application state using signals. Signals are containers for values that can change over time. When a signal's value changes, it automatically updates all dependent computations and effects, ensuring your UI stays in sync with your data without manual intervention.
+## Who Is This For?
 
-### Core Concepts
+**Library authors** building on TypeScript — frontend or backend — who need a solid reactive foundation. The library is designed so that consuming libraries do not have to implement their own reactive primitives. Patterns like external data feeds, async derivations, and keyed collections are handled correctly within a unified graph rather than bolted on as ad-hoc extensions.
 
-- **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()`)
+**Experienced developers** who want to write framework-agnostic applications with explicit dependencies, predictable updates, and type safety. If you are comfortable composing your own rendering and application layers on top of reactive primitives, this library gives you the guarantees without the opinions.
 
-## Key Features
+Cause & Effect is open source, built to power **Le Truc** (a Web Component library) by [Zeix AG](https://zeix.com).
 
-- ⚡ **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
+## Signal Types
+
+Every signal type participates in the same dependency graph with the same propagation, batching, and cleanup semantics. Each type is justified by a distinct role in the graph and the data structure it manages:
+
+| Type | Role | Create with |
+|------|------|-------------|
+| **State** | Mutable source | `createState()` |
+| **Sensor** | External input source (lazy lifecycle) | `createSensor()` |
+| **Memo** | Synchronous derivation (memoized) | `createMemo()` |
+| **Task** | Asynchronous derivation (memoized, cancellable) | `createTask()` |
+| **Store** | Reactive object (keyed properties, proxy-based) | `createStore()` |
+| **List** | Reactive array (keyed items, stable identity) | `createList()` |
+| **Collection** | Reactive collection (external source or derived, item-level memoization) | `createCollection()` |
+| **Effect** | Side-effect sink (terminal) | `createEffect()` |
+
+## Design Principles
+
+- **Explicit reactivity**: Dependencies are tracked through `.get()` calls — the graph always reflects the true dependency structure, with no hidden subscriptions
+- **Non-nullable types**: All signals enforce `T extends {}`, excluding `null` and `undefined` at the type level — you can trust returned values without null checks
+- **Unified graph**: Composite signals (Store, List, Collection) and async signals (Task) are first-class citizens, not afterthoughts — all derivable state can be derived
+- **Tree-shakable, zero dependencies**: Import only what you use — core signals (State, Memo, Task, Effect) stay below 5 kB gzipped, the full library below 10 kB
 
 ## Installation
 
@@ -41,13 +49,13 @@ bun add @zeix/cause-effect
 ## Quick Start
 
 ```js
-import { createEffect, Memo, State } from '@zeix/cause-effect'
+import { createState, createMemo, createEffect } from '@zeix/cause-effect'
 
 // 1. Create state
-const user = new State({ name: 'Alice', age: 30 })
+const user = createState({ name: 'Alice', age: 30 })
 
 // 2. Create computed values
-const greeting = new Memo(() => `Hello ${user.get().name}!`)
+const greeting = createMemo(() => `Hello ${user.get().name}!`)
 
 // 3. React to changes
 createEffect(() => {
@@ -58,16 +66,16 @@ createEffect(() => {
 user.update(u => ({ ...u, age: 31 })) // Logs: "Hello Alice! You are 31 years old"
 ```
 
-## Usage of Signals
+## API
 
 ### State
 
-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.
+A mutable source signal. Every signal has a `.get()` method to read its current value. State signals also provide `.set()` to assign a new value and `.update()` to modify it with a function.
 
 ```js
-import { createEffect, State } from '@zeix/cause-effect'
+import { createState, createEffect } from '@zeix/cause-effect'
 
-const count = new State(42)
+const count = createState(42)
 
 createEffect(() => console.log(count.get()))
 count.set(24)
@@ -77,17 +85,54 @@ document.querySelector('.increment').addEventListener('click', () => {
 })
 ```
 
-Use `State` for primitives or for objects you typically replace entirely.
+Use State for primitives or for objects you replace entirely.
+
+### Sensor
+
+A read-only source that tracks external input. It activates lazily when first accessed by an effect and cleans up when no effects are watching:
+
+```js
+import { createSensor, createEffect } from '@zeix/cause-effect'
+
+const mousePos = createSensor((set) => {
+  const handler = (e) => set({ x: e.clientX, y: e.clientY })
+  window.addEventListener('mousemove', handler)
+  return () => window.removeEventListener('mousemove', handler)
+})
+
+createEffect(() => {
+  const pos = mousePos.get()
+  if (pos) console.log(`Mouse: ${pos.x}, ${pos.y}`)
+})
+```
+
+Use Sensor for mouse position, window size, media queries, geolocation, device orientation, or any external value stream.
+
+**Observing mutable objects**: Use `SKIP_EQUALITY` when the reference stays the same but internal state changes:
+
+```js
+import { createSensor, SKIP_EQUALITY, createEffect } from '@zeix/cause-effect'
+
+const el = document.getElementById('status')
+const element = createSensor((set) => {
+  set(el)
+  const observer = new MutationObserver(() => set(el))
+  observer.observe(el, { attributes: true, childList: true })
+  return () => observer.disconnect()
+}, { value: el, equals: SKIP_EQUALITY })
+
+createEffect(() => console.log(element.get().className))
+```
 
 ### Memo
 
-A `Memo` is a memoized read-only signal that automatically tracks dependencies and updates only when those dependencies change.
+A memoized read-only derivation. It automatically tracks dependencies and updates only when those dependencies actually change.
 
 ```js
-import { State, Memo, createEffect } from '@zeix/cause-effect'
+import { createState, createMemo, createEffect } from '@zeix/cause-effect'
 
-const count = new State(42)
-const isEven = new Memo(() => !(count.get() % 2))
+const count = createState(42)
+const isEven = createMemo(() => !(count.get() % 2))
 
 createEffect(() => console.log(isEven.get()))
 count.set(24) // no log; still even
@@ -99,32 +144,32 @@ count.set(24) // no log; still even
 const isEven = () => !(count.get() % 2)
 ```
 
-**Advanced**: Reducer-style memos:
+**Advanced**: Reducer-style memos with previous value access:
 
 ```js
-import { State, Memo } from '@zeix/cause-effect'
+import { createState, createMemo } from '@zeix/cause-effect'
 
-const actions = new State('reset')
-const counter = new Memo((prev) => {
+const actions = createState('reset')
+const counter = createMemo(prev => {
   switch (actions.get()) {
     case 'increment': return prev + 1
     case 'decrement': return prev - 1
     case 'reset': return 0
     default: return prev
   }
-}, 0)
+}, { value: 0 })
 ```
 
 ### Task
 
-A `Task` handles asynchronous computations with cancellation support:
+An asynchronous derivation with automatic cancellation. When dependencies change while a computation is in flight, the previous one is aborted:
 
 ```js
-import { State, Task } from '@zeix/cause-effect'
+import { createState, createTask } from '@zeix/cause-effect'
 
-const id = new State(1)
+const id = createState(1)
 
-const data = new Task(async (oldValue, abort) => {
+const data = createTask(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()
@@ -133,11 +178,13 @@ const data = new Task(async (oldValue, abort) => {
 id.set(2) // cancels previous fetch automatically
 ```
 
-**Note**: Use Task (not plain async functions) when you want memoization + cancellation + reactive pending/error states.
+Tasks also provide `.isPending()` to check if a computation is in progress and `.abort()` to manually cancel.
+
+Use Task (not plain async functions) when you need memoization, cancellation, and reactive pending/error states.
 
 ### Store
 
-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.
+A reactive object where each property becomes its own signal. Nested objects recursively become nested stores. A Proxy provides direct property access:
 
 ```js
 import { createStore, createEffect } from '@zeix/cause-effect'
@@ -159,121 +206,130 @@ user.preferences.theme.set('light')
 createEffect(() => console.log('User:', user.get()))
 ```
 
-Dynamic properties using the `add()` and `remove()` methods:
+Iterate keys using the reactive `.keys()` method to observe structural changes:
 
 ```js
-const settings = createStore({ autoSave: true })
-
-settings.add('timeout', 5000)
-settings.remove('timeout')
+for (const key of user.keys()) {
+  console.log(key)
+}
 ```
 
-Subscribe to hooks using the `.on()` method:
-
-```js
-const user = createStore({ name: 'Alice', age: 30 })
-
-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))
-
-// 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']"
-```
+Access properties by key using `.byKey()` or via direct property access like `user.name` (enabled by the Proxy).
 
-To unregister hooks, call the returned cleanup functions:
+Dynamic properties with `.add()` and `.remove()`:
 
 ```js
-offAdd() // Stop listening to add hook
-offChange() // Stop listening to change hook
-offRemove() // Stop listening to remove hook
+const settings = createStore({ autoSave: true })
+
+settings.add('timeout', 5000)
+settings.remove('timeout')
 ```
 
 ### List
 
-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:
+A reactive array with individually reactive items and stable keys. Each item becomes its own signal while maintaining persistent identity through sorting and reordering:
 
 ```js
-import { List, createEffect } from '@zeix/cause-effect'
+import { createList, createEffect } from '@zeix/cause-effect'
 
-const items = new List(['banana', 'apple', 'cherry'])
+const items = createList(['banana', 'apple', 'cherry'])
 
-createEffect(() => console.log(`First: ${items[0].get()}`))
+createEffect(() => console.log(`First: ${items.at(0)?.get()}`))
 
 items.add('date')
 items.splice(1, 1, 'orange')
 items.sort()
 ```
 
-Keys are stable across reordering:
+Access items by key using `.byKey()` or by index using `.at()`. `.indexOfKey()` returns the current index of an item in the list, while `.keyAt()` returns the key of an item at a given position.
+
+Keys are stable across reordering. Use `keyConfig` in options to control key generation:
 
 ```js
-const items = new List(['banana', 'apple'], 'item-')
-const key = items.add('orange')
+// String prefix keys
+const items = createList(['banana', 'apple'], { keyConfig: 'item-' })
+// Creates keys: 'item-0', 'item-1'
+
+// Function-based keys
+const users = createList(
+  [{ id: 'alice', name: 'Alice' }],
+  { keyConfig: user => user.id }
+)
 
+const key = items.add('orange')
 items.sort()
-console.log(items.byKey(key))     // 'orange'
-console.log(items.indexOfKey(key)) // current index
+console.log(items.byKey(key)?.get()) // 'orange'
+console.log(items.indexOfKey(key))   // current index
 ```
 
-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.
+Lists have `.keys()`, `.add()`, and `.remove()` methods like stores. Additionally, they have `.sort()`, `.splice()`, and a reactive `.length` property. But unlike stores, deeply nested properties in items are not converted to individual signals.
 
 ### Collection
 
-A `Collection` is a read-only derived reactive list from `List` or another `Collection`:
+A reactive collection with item-level memoization. Collections can be externally-driven (via a start callback) or derived from a List or another Collection.
+
+**Externally-driven collections** receive data from external sources (WebSocket, Server-Sent Events, etc.) via `applyChanges()`:
+
+```js
+import { createCollection, createEffect } from '@zeix/cause-effect'
+
+const items = createCollection((applyChanges) => {
+  const ws = new WebSocket('/items')
+  ws.onmessage = (e) => {
+    const { add, change, remove } = JSON.parse(e.data)
+    applyChanges({ changed: true, add, change, remove })
+  }
+  return () => ws.close()
+}, { keyConfig: item => item.id })
+
+createEffect(() => console.log('Items:', items.get()))
+```
+
+The start callback activates lazily when the collection is first accessed by an effect and cleans up when no effects are watching. Options include `value` for initial items (default `[]`) and `keyConfig` for key generation.
+
+**Derived collections** transform Lists or other Collections via `.deriveCollection()`:
 
 ```js
-import { List, createEffect } from '@zeix/cause-effect'
+import { createList } from '@zeix/cause-effect'
 
-const users = new List([
+const users = createList([
   { id: 1, name: 'Alice', role: 'admin' },
   { id: 2, name: 'Bob', role: 'user' }
-])
+], { keyConfig: u => String(u.id) })
+
 const profiles = users.deriveCollection(user => ({
   ...user,
   displayName: `${user.name} (${user.role})`
 }))
 
-createEffect(() => console.log('Profiles:', profiles.get()))
-console.log(userProfiles.at(0).get().displayName)
+console.log(profiles.at(0)?.get().displayName)
 ```
 
-Async mapping is supported: 
+Async mapping is supported:
 
 ```js
-const details = users.derivedCollection(async (user, abort) => {
+const details = users.deriveCollection(async (user, abort) => {
   const response = await fetch(`/users/${user.id}`, { signal: abort })
   return { ...user, details: await response.json() }
 })
 ```
 
-### Ref
-
-A `Ref` is a signal that holds a reference to an external object that can change outside the reactive system.
+Collections can be chained for data pipelines:
 
 ```js
-import { createEffect, Ref } from '@zeix/cause-effect'
-
-const elementRef = new Ref(document.getElementById('status'))
-
-createEffect(() => console.log(elementRef.get().className))
-
-// external mutation happened
-elementRef.notify()
+const processed = users
+  .deriveCollection(user => ({ ...user, active: user.lastLogin > threshold }))
+  .deriveCollection(user => user.active ? `Active: ${user.name}` : `Inactive: ${user.name}`)
 ```
 
-Use `Ref` for DOM nodes, Maps/Sets, sockets, third-party objects, etc.
-
-## Effects
+### Effect
 
-The `createEffect()` callback runs whenever the signals it reads change. It supports sync or async callbacks and returns a cleanup function.
+A side-effect sink that runs whenever the signals it reads change. Effects are terminal — they consume values but produce none. The returned function disposes the effect:
 
 ```js
-import { State, createEffect } from '@zeix/cause-effect'
+import { createState, createEffect } from '@zeix/cause-effect'
 
-const count = new State(42)
+const count = createState(42)
 
 const cleanup = createEffect(() => {
   console.log(count.get())
@@ -283,81 +339,84 @@ const cleanup = createEffect(() => {
 cleanup()
 ```
 
-Async effects receive an AbortSignal that cancels on rerun or cleanup:
+Effect callbacks can return a cleanup function that runs before the effect re-runs or when disposed:
 
 ```js
-createEffect(async abort => {
-  const res = await fetch('/api', { signal: abort })
-  if (res.ok) console.log(await res.json())
+createEffect(() => {
+  const timer = setInterval(() => console.log(count.get()), 1000)
+  return () => clearInterval(timer)
 })
 ```
 
-### Error Handling: resolve() + match()
+#### Error Handling: match()
 
-Use `resolve()` to extract values from signals (including pending/err states) and `match()` to handle them declaratively:
+Use `match()` inside effects to handle signal values declaratively, including pending and error states from Tasks:
 
 ```js
-import { State, Task, createEffect, resolve, match } from '@zeix/cause-effect'
+import { createState, createTask, createEffect, match } from '@zeix/cause-effect'
 
-const userId = new State(1)
-const userData = new Task(async (_, abort) => {
+const userId = createState(1)
+const userData = createTask(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:', user),
+  match([userData], {
+    ok: ([user]) => console.log('User:', user),
     nil: () => console.log('Loading...'),
     err: errors => console.error(errors[0])
   })
 })
 ```
 
-## Signal Type Decision Tree
+## Choosing the Right Signal
 
 ```
-Is the value managed *inside* the reactive system?
+Does the data come from *outside* the reactive system?
+│
+├─ Yes, single value → `createSensor(set => { ... })`
+│   (mouse position, window resize, media queries, DOM observers, etc.)
+│   Tip: Use `{ equals: SKIP_EQUALITY }` for mutable object observation
 │
-├─ No → Use `Ref`
-│        (DOM nodes, Map/Set, Date, sockets, 3rd-party objects)
-│        Remember: call `.notify()` when it changes externally.
+├─ Yes, keyed collection → `createCollection(applyChanges => { ... })`
+│   (WebSocket streams, Server-Sent Events, external data feeds, etc.)
 │
-└─ Yes? What kind of data is it?
+└─ No, managed internally? What kind of data is it?
     │
     ├─ *Primitive* (number/string/boolean)
     │   │
     │   ├─ Do you want to mutate it directly?
-    │   │     └─ Yes → `State`
+    │   │     └─ Yes → `createState()`
     │   │
     │   └─ Is it derived from other signals?
     │         │
     │         ├─ Sync derived
     │         │     ├─ Simple/cheap → plain function (preferred)
-    │         │     └─ Expensive/shared/stateful → `Memo`
-    │         │     
-    │         └─ Async derived → `Task`
+    │         │     └─ Expensive/shared/stateful → `createMemo()`
+    │         │
+    │         └─ Async derived → `createTask()`
     │            (cancellation + memoization + pending/error state)
     │
     ├─ *Plain Object*
     │   │
     │   ├─ Do you want to mutate individual properties?
-    │   │     ├─ Yes → `Store`
-    │   │     └─ No, whole object mutations only → `State`
+    │   │     ├─ Yes → `createStore()`
+    │   │     └─ No, whole object mutations only → `createState()`
     │   │
     │   └─ Is it derived from other signals?
-    │         ├─ Sync derived → plain function or `Memo`
-    │         └─ Async derived → `Task`
+    │         ├─ Sync derived → plain function or `createMemo()`
+    │         └─ Async derived → `createTask()`
     │
     └─ *Array*
         │
         ├─ Do you need to mutate it (add/remove/sort) with stable item identity?
-        │     ├─ Yes → `List`
-        │     └─ No, whole array mutations only → `State`
+        │     ├─ Yes → `createList()`
+        │     └─ No, whole array mutations only → `createState()`
         │
         └─ Is it derived / read-only transformation of a `List` or `Collection`?
-              └─ Yes → `Collection`
+              └─ Yes → `.deriveCollection()`
                  (memoized + supports async mapping + chaining)
 ```
 
@@ -368,12 +427,12 @@ Is the value managed *inside* the reactive system?
 Group multiple signal updates, ensuring effects run only once after all changes are applied:
 
 ```js
-import { batchSignalWrites, State } from '@zeix/cause-effect'
+import { batch, createState } from '@zeix/cause-effect'
 
-const a = new State(2)
-const b = new State(3)
+const a = createState(2)
+const b = createState(3)
 
-batchSignalWrites(() => {
+batch(() => {
   a.set(4)
   b.set(5)
 })
@@ -381,16 +440,16 @@ batchSignalWrites(() => {
 
 ### 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.
+Effects return a cleanup function. When executed, it will unsubscribe from signals and run cleanup functions returned by effect callbacks.
 
 ```js
-import { State, createEffect } from '@zeix/cause-effect'
+import { createState, createEffect } from '@zeix/cause-effect'
 
-const user = new State({ name: 'Alice', age: 30 })
+const user = createState({ name: 'Alice', age: 30 })
 const greeting = () => `Hello ${user.get().name}!`
 const cleanup = createEffect(() => {
-	console.log(`${greeting()} You are ${user.get().age} years old`)
-	return () => console.log('Cleanup') // Cleanup function
+  console.log(`${greeting()} You are ${user.get().age} years old`)
+  return () => console.log('Cleanup')
 })
 
 // When you no longer need the effect, execute the cleanup function
@@ -399,109 +458,71 @@ cleanup() // Logs: 'Cleanup' and unsubscribes from signal `user`
 user.set({ name: 'Bob', age: 28 }) // Won't trigger the effect anymore
 ```
 
-### Resource Management with Hooks
+### Scoped Cleanup
 
-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:
+Use `createScope()` for hierarchical cleanup of nested effects and resources. It returns a single cleanup function:
 
 ```js
-import { State, createEffect } from '@zeix/cause-effect'
-
-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()
-  }
-})
+import { createState, createEffect, createScope } from '@zeix/cause-effect'
 
-// Resource is created only when effect runs
-const cleanup = createEffect(() => {
-  console.log('API URL:', config.get().apiUrl)
+const dispose = createScope(() => {
+  const count = createState(0)
+  createEffect(() => console.log(count.get()))
+  return () => console.log('Scope disposed')
 })
 
-// Resource is cleaned up when effect stops
-cleanup()
+dispose() // Cleans up the effect and runs the returned 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()
+### Resource Management with Watch Callbacks
 
-Extract signal values:
+Sensor and Collection signals use a **start callback** for lazy resource management. The callback runs when the signal is first accessed by an effect and the returned cleanup function runs when no effects are watching:
 
 ```js
-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)
-else if (result.pending) console.log('Loading...')
-else console.error('Errors:', result.errors)
-```
-
-### match()
-
-Pattern matching on resolved results for side effects:
-
-```js
-import { resolve, match } from '@zeix/cause-effect'
-
-match(resolve({ name, age }), {
-  ok: ({ name, age }) => document.title = `${name} (${age})`,
-  nil: () => document.title = 'Loading...',
-  err: errors => document.title = `Error: ${errors[0].message}`
+import { createSensor, createCollection, createEffect } from '@zeix/cause-effect'
+
+// Sensor: track external input
+const windowSize = createSensor((set) => {
+  const update = () => set({ w: innerWidth, h: innerHeight })
+  update()
+  window.addEventListener('resize', update)
+  return () => window.removeEventListener('resize', update)
 })
-```
-
-### diff()
 
-Compare object changes:
+// Collection: receive external data
+const feed = createCollection((applyChanges) => {
+  const es = new EventSource('/feed')
+  es.onmessage = (e) => applyChanges(JSON.parse(e.data))
+  return () => es.close()
+}, { keyConfig: item => item.id })
 
-```js
-import { diff } from '@zeix/cause-effect'
-
-const oldUser = { name: 'Alice', age: 30, city: 'Boston' }
-const newUser = { name: 'Alice', age: 31, email: 'alice@example.com' }
+// Resources are created only when effect runs
+const cleanup = createEffect(() => {
+  console.log('Window size:', windowSize.get())
+  console.log('Feed items:', feed.get())
+})
 
-const changes = diff(oldUser, newUser)
-console.log(changes.changed)  // true - something changed
-console.log(changes.add)      // { email: 'alice@example.com' }
-console.log(changes.change)   // { age: 31 }
-console.log(changes.remove)   // { city: UNSET }
+// Resources are cleaned up when effect stops
+cleanup()
 ```
 
-### isEqual()
-
-Deep equality comparison with circular reference detection:
+Store and List signals support an optional `watched` callback in their options that returns a cleanup function:
 
 ```js
-import { isEqual } from '@zeix/cause-effect'
-
-const obj1 = { name: 'Alice', preferences: { theme: 'dark' } }
-const obj2 = { name: 'Alice', preferences: { theme: 'dark' } }
-const obj3 = { name: 'Bob', preferences: { theme: 'dark' } }
-
-console.log(isEqual(obj1, obj2)) // true - deep equality
-console.log(isEqual(obj1, obj3)) // false - names differ
-
-// Handles arrays, primitives, and complex nested structures
-console.log(isEqual([1, 2, 3], [1, 2, 3]))           // true
-console.log(isEqual('hello', 'hello'))               // true
-console.log(isEqual({ a: [1, 2] }, { a: [1, 2] }))   // true
+const user = createStore({ name: 'Alice' }, {
+  watched: () => {
+    const ws = new WebSocket('/updates')
+    return () => ws.close()
+  }
+})
 ```
 
+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.)
+
 ## Contributing & License
 
 Feel free to contribute, report issues, or suggest improvements.