Merge pull request #24 from zeixcom/feature/collection-changes

Improve Consistency for Lazy Lifecycle (watched) across API

Author: estherbrunner

.ai-context.md

@@ -28,8 +28,8 @@ Scope         — owner-only (createScope)
 ### Signal Types
 - **State** (`createState`): Mutable signals for primitive values and objects
 - **Sensor** (`createSensor`): Read-only signals for external input streams with automatic state updates. Use `SKIP_EQUALITY` for mutable object observation.
-- **Memo** (`createMemo`): Synchronous derived computations with memoization and reducer capabilities
-- **Task** (`createTask`): Async derived computations with automatic abort/cancellation
+- **Memo** (`createMemo`): Synchronous derived computations with memoization, reducer capabilities, and optional `watched(invalidate)` for external invalidation
+- **Task** (`createTask`): Async derived computations with automatic abort/cancellation and optional `watched(invalidate)` for external invalidation
 - **Store** (`createStore`): Mutable object signals with individually reactive properties via Proxy
 - **List** (`createList`): Mutable array signals with stable keys and reactive items
 - **Collection** (`createCollection`): Reactive collections — either externally-driven with watched lifecycle, or derived from List/Collection with item-level memoization
@@ -223,7 +223,7 @@ const processed = items.deriveCollection(item => item.toUpperCase())
 
 ## Resource Management
 
-**Sensor and Collection** use a start callback that returns a Cleanup function:
+**Sensor and Collection** use a watched callback that returns a Cleanup function:
 ```typescript
 const sensor = createSensor<T>((set) => {
   // setup input tracking, call set(value) to update
@@ -236,6 +236,17 @@ const feed = createCollection<T>((applyChanges) => {
 }, { keyConfig: item => item.id })
 ```
 
+**Memo and Task** use an optional `watched` callback in options that receives an `invalidate` function:
+```typescript
+const derived = createMemo(() => element.get().textContent ?? '', {
+  watched: (invalidate) => {
+    const obs = new MutationObserver(() => invalidate())
+    obs.observe(element.get(), { childList: true })
+    return () => obs.disconnect()
+  }
+})
+```
+
 **Store and List** use an optional `watched` callback in options:
 ```typescript
 const store = createStore(initialValue, {

.github/copilot-instructions.md

@@ -15,8 +15,8 @@ Cause & Effect is a reactive state management library for JavaScript/TypeScript
 ### Signal Types (all in `src/nodes/`)
 - **State** (`createState`): Mutable signals for values (`get`, `set`, `update`)
 - **Sensor** (`createSensor`): Read-only signals for external input with automatic state updates. Use `SKIP_EQUALITY` for mutable object observation.
-- **Memo** (`createMemo`): Synchronous derived computations with memoization and reducer capabilities
-- **Task** (`createTask`): Async derived computations with automatic AbortController cancellation
+- **Memo** (`createMemo`): Synchronous derived computations with memoization, reducer capabilities, and optional `watched(invalidate)` for external invalidation
+- **Task** (`createTask`): Async derived computations with automatic AbortController cancellation and optional `watched(invalidate)` for external invalidation
 - **Store** (`createStore`): Proxy-based reactive objects with per-property State/Store signals
 - **List** (`createList`): Reactive arrays with stable keys and per-item State signals
 - **Collection** (`createCollection`): Reactive collections — either externally-driven with watched lifecycle, or derived from List/Collection with item-level memoization
@@ -72,7 +72,8 @@ Cause & Effect is a reactive state management library for JavaScript/TypeScript
 - All signals have `.get()` for value access
 - Mutable signals (State) have `.set(value)` and `.update(fn)`
 - Store properties are automatically reactive signals via Proxy
-- Sensor/Collection use a start callback returning Cleanup (lazy activation)
+- Sensor/Collection use a watched callback returning Cleanup (lazy activation)
+- Memo/Task use optional `watched(invalidate)` callback in options for external invalidation
 - Store/List use optional `watched` callback in options returning Cleanup
 - Effects return a dispose function (Cleanup)
 
@@ -191,18 +192,27 @@ const count = createState(0, {
 ## Resource Management
 
 ```typescript
-// Sensor: lazy external input tracking
+// Sensor: lazy external input tracking (watched callback with set)
 const sensor = createSensor<T>((set) => {
   // setup — call set(value) to update
   return () => { /* cleanup — called when last effect stops watching */ }
 })
 
-// Collection: lazy external data source
+// Collection: lazy external data source (watched callback with applyChanges)
 const feed = createCollection<T>((applyChanges) => {
   // setup — call applyChanges(diffResult) on changes
   return () => { /* cleanup */ }
 }, { keyConfig: item => item.id })
 
+// Memo/Task: optional watched callback with invalidate
+const derived = createMemo(() => element.get().textContent ?? '', {
+  watched: (invalidate) => {
+    const obs = new MutationObserver(() => invalidate())
+    obs.observe(element.get(), { childList: true })
+    return () => obs.disconnect()
+  }
+})
+
 // Store/List: optional watched callback
 const store = createStore(initialValue, {
   watched: () => {

ARCHITECTURE.md

@@ -178,14 +178,14 @@ A mutable value container. The simplest signal type — `get()` links and return
 
 **Graph node**: `StateNode<T>` (source only)
 
-A read-only signal that tracks external input. The `start` callback receives a `set` function that updates the node's value via `setState()`. Sensors cover two patterns:
+A read-only signal that tracks external input. The `watched` callback receives a `set` function that updates the node's value via `setState()`. Sensors cover two patterns:
 
-1. **Tracking external values** (default): Receives replacement values from events (mouse position, resize events). Equality checking (`Object.is` by default) prevents unnecessary propagation.
+1. **Tracking external values** (default): Receives replacement values from events (mouse position, resize events). Equality checking (`===` by default) prevents unnecessary propagation.
 2. **Observing mutable objects** (with `SKIP_EQUALITY`): Holds a stable reference to a mutable object (DOM element, Map, Set). `set(sameRef)` with `equals: SKIP_EQUALITY` always propagates, notifying consumers that the object's internals have changed.
 
-The value starts undefined unless `options.value` is provided. Reading a sensor before its `start` callback has called `set()` (and without `options.value`) throws `UnsetSignalValueError`.
+The value starts undefined unless `options.value` is provided. Reading a sensor before its `watched` callback has called `set()` (and without `options.value`) throws `UnsetSignalValueError`.
 
-**Lazy lifecycle**: The `start` callback is invoked on first sink attachment. The returned cleanup is stored as `node.stop` and called when the last sink detaches (via `unlink()`).
+**Lazy lifecycle**: The `watched` callback is invoked on first sink attachment. The returned cleanup is stored as `node.stop` and called when the last sink detaches (via `unlink()`).
 
 ### Memo (`src/nodes/memo.ts`)
 
@@ -199,6 +199,8 @@ The `error` field preserves thrown errors: if `fn` throws, the error is stored a
 
 **Reducer pattern**: The `prev` parameter enables state accumulation across recomputations without writable state.
 
+**Watched lifecycle**: An optional `watched` callback in options provides lazy external invalidation. The callback receives an `invalidate` function and is invoked on first sink attachment. Calling `invalidate()` marks the node `FLAG_DIRTY`, propagates to sinks, and flushes — triggering re-evaluation of the memo's `fn` without changing any tracked dependency. The returned cleanup is stored as `node.stop` and called when the last sink detaches. This enables patterns like DOM observation (MutationObserver) where the memo re-derives its value in response to external events.
+
 ### Task (`src/nodes/task.ts`)
 
 **Graph node**: `TaskNode<T>` (source + sink)
@@ -209,6 +211,8 @@ During dependency tracking, only the synchronous preamble of `fn` is tracked (be
 
 `isPending()` returns `true` while a computation is in flight. `abort()` cancels the current computation manually. Errors are preserved like Memo, but old values are retained on errors (the last successful result remains accessible).
 
+**Watched lifecycle**: Same pattern as Memo — an optional `watched` callback receives `invalidate` and is invoked on first sink attachment. Calling `invalidate()` marks the node dirty and triggers re-execution, which aborts any in-flight computation via the existing `AbortController` mechanism before starting a new one.
+
 ### Effect (`src/nodes/effect.ts`)
 
 **Graph node**: `EffectNode` (sink only)
@@ -247,28 +251,26 @@ A reactive array with stable keys and per-item reactivity. Each item becomes a `
 
 Collection implements two creation patterns that share the same `Collection<T>` interface:
 
-#### `createCollection(start, options?)` — externally driven
+#### `createCollection(watched, options?)` — externally driven
 
 **Graph node**: `MemoNode<T[]>` (source + sink, tracks item values)
 
-An externally-driven reactive collection with a watched lifecycle, mirroring `createSensor(start, options?)`. The `start` callback receives an `applyChanges(diffResult)` function for granular add/change/remove operations. Initial items are provided via `options.value` (default `[]`).
+An externally-driven reactive collection with a watched lifecycle, mirroring `createSensor(watched, options?)`. The `watched` callback receives an `applyChanges(diffResult)` function for granular add/change/remove operations. Initial items are provided via `options.value` (default `[]`).
 
-**Lazy lifecycle**: Like Sensor, the `start` callback is invoked on first sink attachment. The returned cleanup is stored as `node.stop` and called when the last sink detaches (via `unlink()`). The `startWatching()` guard ensures `start` fires before `link()` so synchronous mutations inside `start` update `node.value` before the activating effect reads it.
+**Lazy lifecycle**: Like Sensor, the `watched` callback is invoked on first sink attachment. The returned cleanup is stored as `node.stop` and called when the last sink detaches (via `unlink()`). The `startWatching()` guard ensures `watched` fires before `link()` so synchronous mutations inside `watched` update `node.value` before the activating effect reads it.
 
 **External mutation via `applyChanges`**: Additions create new item signals (via configurable `createItem` factory, default `createState`). Changes update existing `State` signals. Removals delete signals and keys. Structural changes null out `node.sources` to force edge re-establishment. The node uses `equals: () => false` since structural changes are managed externally rather than detected by diffing.
 
 **Two-path access**: Same pattern as Store/List — first `get()` uses `refresh()` to establish edges from child signals to the collection node; subsequent reads use `untrack(buildValue)` to avoid re-linking.
 
 #### `deriveCollection(source, callback)` — internally derived
 
-**Graph node**: `MemoNode<string[]>` (source + sink, tracks keys not values)
+**Graph node**: `MemoNode<T[]>` (source + sink, tracks item values)
 
 An internal factory (not exported from the public API) that creates a read-only derived transformation of a List or another Collection. Exposed to users via the `.deriveCollection(callback)` method on List and Collection. Each source item is individually memoized: sync callbacks create `Memo` signals, async callbacks create `Task` signals.
 
-**Two-level reactivity**: The derived collection's `MemoNode` tracks structural changes only — its `fn` (`syncKeys`) reads `source.keys()` to detect additions and removals. Value-level changes flow through the individual per-item `Memo`/`Task` signals, which independently track their source item.
-
-**Key differences from Store/List**: The `MemoNode.value` is a `string[]` (the keys array), not the collection's actual values. The `equals` function is a shallow string array comparison (`keysEqual`). The node starts `FLAG_DIRTY` (unlike Store/List which start clean after initialization) to ensure the first `refresh()` establishes the edge from source to collection.
+**Consistent with Store/List/createCollection**: The `MemoNode.value` is a `T[]` (cached computed values), and keys are tracked in a separate local `string[]` variable. The `equals` function uses shallow reference equality on array elements to prevent unnecessary downstream propagation when re-evaluation produces the same item references. The node starts `FLAG_DIRTY` to ensure the first `refresh()` establishes edges.
 
-**No `invalidateEdges`**: Unlike Store/List, the derived collection never needs to re-establish its source edge because it has exactly one source (the parent List or Collection) that never changes identity. Structural changes (adding/removing per-item signals) happen inside `syncKeys` without affecting the source edge.
+**Two-path access with structural fallback**: Same pattern as Store/List — first `get()` uses `refresh()` to establish edges; subsequent reads use `untrack(buildValue)`. A `syncKeys()` step inside `buildValue` syncs the signals map with `source.keys()`. If keys changed, `syncKeys` nulls `node.sources` to force edge re-establishment via `refresh()`, ensuring new child signals are properly linked.
 
-**Chaining**: `.deriveCollection()` creates a new derived collection from an existing one, forming a pipeline. Each level in the chain has its own `MemoNode` for structural tracking and its own set of per-item derived signals.
+**Chaining**: `.deriveCollection()` creates a new derived collection from an existing one, forming a pipeline. Each level in the chain has its own `MemoNode` for value caching and its own set of per-item derived signals.

CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+## 0.18.1
+
+### Added
+
+- **Memo `watched(invalidate)` option**: `createMemo(fn, { watched })` accepts a lazy lifecycle callback that receives an `invalidate` function. Calling `invalidate()` marks the memo dirty and triggers re-evaluation. The callback is invoked on first sink attachment and cleaned up when the last sink detaches. This enables patterns like DOM observation where a memo re-derives its value in response to external events (e.g., MutationObserver) without needing a separate Sensor.
+- **Task `watched(invalidate)` option**: Same pattern as Memo. Calling `invalidate()` aborts any in-flight computation and triggers re-execution.
+- **`CollectionChanges<T>` type**: New typed interface for collection mutations with `add?: T[]`, `change?: T[]`, `remove?: T[]` arrays. Replaces the untyped `DiffResult` records previously used by `CollectionCallback`.
+- **`SensorOptions<T>` type**: Dedicated options type for `createSensor`, extending `SignalOptions<T>` with optional `value`.
+- **`CollectionChanges` export** from public API (`index.ts`).
+- **`SensorOptions` export** from public API (`index.ts`).
+
+### Changed
+
+- **`createSensor` parameter renamed**: `start` → `watched` for consistency with Store/List lifecycle terminology.
+- **`createSensor` options type**: `ComputedOptions<T>` → `SensorOptions<T>`. This decouples Sensor options from `ComputedOptions`, which now carries the `watched(invalidate)` field for Memo/Task.
+- **`createCollection` parameter renamed**: `start` → `watched` for consistency.
+- **`CollectionCallback` is now generic**: `CollectionCallback` → `CollectionCallback<T>`. The `applyChanges` parameter accepts `CollectionChanges<T>` instead of `DiffResult`.
+- **`CollectionOptions.createItem` signature**: `(key: string, value: T) => Signal<T>` → `(value: T) => Signal<T>`. Key generation is now handled internally.
+- **`KeyConfig<T>` return type relaxed**: Key functions may now return `string | undefined`. Returning `undefined` falls back to synthetic key generation.
+
+### Removed
+
+- **`DiffResult` removed from public API**: No longer re-exported from `index.ts`. The type remains available from `src/nodes/list.ts` for internal use but is superseded by `CollectionChanges<T>` for collection mutations.
+
+## 0.18.0
+
+Baseline release. Factory function API (`createState`, `createMemo`, `createTask`, `createEffect`, `createStore`, `createList`, `createCollection`, `createSensor`) with linked-list graph engine.

CLAUDE.md

@@ -86,10 +86,10 @@ The generic constraint `T extends {}` is crucial - it excludes `null` and `undef
 ### Collection Architecture
 
 **Collections** (`createCollection`): Externally-driven collections with watched lifecycle
-- Created via `createCollection(start, options?)` — mirrors `createSensor(start, options?)`
-- The `start` callback receives an `applyChanges(diffResult)` function for granular add/change/remove operations
+- Created via `createCollection(watched, options?)` — mirrors `createSensor(watched, options?)`
+- The `watched` callback receives an `applyChanges(diffResult)` function for granular add/change/remove operations
 - `options.value` provides initial items (default `[]`), `options.keyConfig` configures key generation
-- Lazy activation: `start` callback invoked on first effect access, cleanup when unwatched
+- Lazy activation: `watched` callback invoked on first effect access, cleanup when unwatched
 
 **Derived Collections** (`deriveCollection`): Transformed from Lists or other Collections
 - Created via `list.deriveCollection(callback)` or `collection.deriveCollection(callback)`
@@ -124,7 +124,7 @@ Computed signals implement smart memoization:
 
 ## Resource Management with Watch Callbacks
 
-Sensor and Collection signals use a **start callback** pattern for lazy resource management. Resources are allocated only when a signal is first accessed by an effect and automatically cleaned up when no effects are watching:
+Sensor, Collection, Memo (with `watched` option), and Task (with `watched` option) use a **watched callback** pattern for lazy resource management. Resources are allocated only when a signal is first accessed by an effect and automatically cleaned up when no effects are watching:
 
 ```typescript
 // Sensor: track external input with state updates
@@ -164,9 +164,9 @@ const user = createStore({ name: 'Alice', email: 'alice@example.com' }, {
 ```
 
 **Watch Lifecycle**:
-1. First effect accesses signal → start/watched callback executed
+1. First effect accesses signal → watched callback executed
 2. Last effect stops watching → returned cleanup function executed
-3. New effect accesses signal → start/watched callback executed again
+3. New effect accesses signal → watched callback executed again
 
 This pattern enables **lazy resource allocation** - resources are only consumed when actually needed and automatically freed when no longer used.
 
@@ -230,7 +230,7 @@ const firstTodo = todoList.byKey('task1') // Access by stable key
 
 **Collection (`createCollection`)**:
 - Externally-driven keyed collections (WebSocket streams, SSE, external data feeds)
-- Mirrors `createSensor(start, options?)` — start callback pattern with watched lifecycle
+- Mirrors `createSensor(watched, options?)` — watched callback pattern with lazy lifecycle
 - Same `Collection` interface — `.get()`, `.byKey()`, `.keys()`, `.deriveCollection()`
 
 ```typescript
@@ -263,6 +263,7 @@ const processed = todoList
 **Memo (`createMemo`)**:
 - Synchronous derived computations with memoization
 - Reducer pattern with previous value access
+- Optional `watched(invalidate)` callback for lazy external invalidation (e.g., MutationObserver)
 
 ```typescript
 const doubled = createMemo(() => count.get() * 2)
@@ -283,6 +284,7 @@ const runningTotal = createMemo(prev => prev + currentValue.get(), { value: 0 })
 
 **Task (`createTask`)**:
 - Async computations with automatic cancellation
+- Optional `watched(invalidate)` callback for lazy external invalidation
 
 ```typescript
 const userData = createTask(async (prev, abort) => {