@zeix/cause-effect 0.17.2 → 0.18.0

package/.ai-context.md

@@ -6,102 +6,157 @@ Cause & Effect is a modern reactive state management library for JavaScript/Type
 
 ## Core Architecture
 
+### Graph-Based Reactivity (`src/graph.ts`)
+
+The reactive engine is a linked graph of source and sink nodes connected by `Edge` entries:
+- **Sources** (StateNode) maintain a linked list of sink edges
+- **Sinks** (MemoNode, TaskNode, EffectNode) maintain a linked list of source edges
+- `link()` creates edges between sources and sinks during `.get()` calls
+- `propagate()` flags sinks as dirty when sources change
+- `flush()` processes queued effects after propagation
+- `trimSources()` removes stale edges after recomputation
+
+### Node Types
+```
+StateNode<T>  — source-only with equality + guard (State, Sensor)
+MemoNode<T>   — source + sink (Memo, Store, List, Collection)
+TaskNode<T>   — source + sink + async (Task)
+EffectNode    — sink + owner (Effect)
+Scope         — owner-only (createScope)
+```
+
 ### Signal Types
-- **Signal**: Base interface with `.get()` method for value access
-- **State**: Mutable signals for primitive values (numbers, strings, booleans)
-- **Ref**: Signal wrappers for external objects that change outside the reactive system (DOM elements, Map, Set, Date, third-party objects)
-- **Computed**: Read-only derived signals with automatic memoization, reducer capabilities and async handling
-- **Store**: Mutable signals for objects with individually reactive properties
-- **List**: Mutable signals for arrays with individually reactive items
-- **Collection**: Interface for reactive array-like collections (implemented by DerivedCollection)
-- **Effect**: Side effect handlers that react to signal changes
+- **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
+- **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
+- **Effect** (`createEffect`): Side effect handlers that react to signal changes
 
 ### Key Principles
-1. **Functional Programming**: Immutable by default, pure functions
-2. **Type Safety**: Full TypeScript support with strict type constraints
-3. **Performance**: Minimal re-computations through dependency tracking
-4. **Async Support**: Built-in cancellation with AbortSignal
-5. **Tree-shaking**: Optimized for minimal bundle size
+1. **Functional API**: All signals created via `create*()` factory functions (no classes)
+2. **Type Safety**: Full TypeScript support with strict type constraints (`T extends {}`)
+3. **Performance**: Flag-based dirty checking, linked-list edge traversal, batched flushing
+4. **Async Support**: Built-in cancellation with AbortSignal in Tasks
+5. **Tree-shaking**: Optimized for minimal bundle size with `/*#__PURE__*/` annotations
 
 ## Project Structure
 
 ```
 cause-effect/
 ├── src/
-│   ├── classes/
-│   │   ├── state.ts       # Mutable state signals (State)
-│   │   ├── ref.ts         # Signal wrapper for external objects (Ref)
-│   │   ├── store.ts       # Object stores with reactive properties
-│   │   ├── list.ts        # Array stores with stable keys (List)
-│   │   ├── collection.ts  # Collection interface and DerivedCollection
-│   │   └── computed.ts    # Computed/derived signals (Memo and Task)
-|   ├── signal.ts      # Base signal types and utilities
-│   ├── effect.ts      # Effect system (createEffect)
-│   ├── system.ts      # Core reactivity (watchers, batching, subscriptions)
-│   ├── resolve.ts     # Helper for extracting signal values
-│   ├── match.ts       # Pattern matching utility
-│   ├── diff.ts        # Object comparison utilities
-│   ├── errors.ts      # Custom error classes
-│   └── util.ts        # Utilities and constants
-├── index.ts           # Main export file
-├── types/index.d.ts   # TypeScript declarations
-└── package.json       # NPM package configuration
+│   ├── graph.ts           # Core reactive engine (nodes, edges, link, propagate, flush, batch)
+│   ├── nodes/
+│   │   ├── state.ts       # createState — mutable state signals
+│   │   ├── sensor.ts      # createSensor — external input tracking (also covers mutable object observation)
+│   │   ├── memo.ts        # createMemo — synchronous derived computations
+│   │   ├── task.ts        # createTask — async derived computations
+│   │   ├── effect.ts      # createEffect, match — side effects
+│   │   ├── store.ts       # createStore — reactive object stores
+│   │   ├── list.ts        # createList — reactive arrays with stable keys
+│   │   └── collection.ts  # createCollection — externally-driven and derived collections
+│   ├── util.ts            # Utility functions and type checks
+│   └── ...
+├── index.ts           # Entry point / main export file
+├── test/
+│   ├── state.test.ts
+│   ├── memo.test.ts
+│   ├── task.test.ts
+│   ├── effect.test.ts
+│   ├── store.test.ts
+│   ├── list.test.ts
+│   └── collection.test.ts
+└── package.json
 ```
 
 ## API Patterns
 
 ### Signal Creation
 ```typescript
-// State signals for primitives
-const count = new State(42)
-const name = new State('Alice')
-const actions = new State<'increment' | 'decrement' | 'reset'>('reset')
+// State for primitives and objects
+const count = createState(42)
+const name = createState('Alice')
+
+// Sensor for external input
+const mousePos = createSensor<{ x: number; y: number }>((set) => {
+  const handler = (e: MouseEvent) => set({ x: e.clientX, y: e.clientY })
+  window.addEventListener('mousemove', handler)
+  return () => window.removeEventListener('mousemove', handler)
+})
 
-// Ref signals for external objects
-const elementRef = new Ref(document.getElementById('status'))
-const cacheRef = new Ref(new Map([['key', 'value']]))
+// Sensor for mutable object observation (SKIP_EQUALITY)
+const element = createSensor<HTMLElement>((set) => {
+  const node = document.getElementById('box')!
+  set(node)
+  const obs = new MutationObserver(() => set(node))
+  obs.observe(node, { attributes: true })
+  return () => obs.disconnect()
+}, { value: node, equals: SKIP_EQUALITY })
 
-// Store signals for objects  
+// Store for objects with reactive properties
 const user = createStore({ name: 'Alice', age: 30 })
 
 // List with stable keys for arrays
-const items = new List(['apple', 'banana', 'cherry'])
-const users = new List([{ id: 'alice', name: 'Alice' }], user => user.id)
+const items = createList(['apple', 'banana', 'cherry'])
+const users = createList(
+  [{ id: 'alice', name: 'Alice' }],
+  { keyConfig: user => user.id }
+)
 
-// Computed signals for derived values
-const doubled = new Memo(() => count.get() * 2)
+// Memo for synchronous derived values
+const doubled = createMemo(() => count.get() * 2)
 
-// Computed with reducer capabilities (access to previous value)
-const counter = new Memo((prev) => {
+// Memo with reducer capabilities (access to previous value)
+const counter = createMemo(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
+  return action === 'increment' ? prev + 1 : prev - 1
+}, { value: 0 })
 
-// Async computed with access to previous value
-const userData = new Task(async (prev, abort) => {
+// Task for async derived values with cancellation
+const userData = createTask(async (prev, abort) => {
   const id = userId.get()
-  if (!id) return prev // Keep previous data if no user ID
+  if (!id) return prev
   const response = await fetch(`/users/${id}`, { signal: abort })
   return response.json()
 })
+
+// Collection for derived transformations
+const doubled = numbers.deriveCollection((value: number) => value * 2)
+const enriched = users.deriveCollection(async (user, abort) => {
+  const res = await fetch(`/api/${user.id}`, { signal: abort })
+  return { ...user, details: await res.json() }
+})
+
+// Collection for externally-driven data
+const feed = createCollection<{ id: string; text: string }>((applyChanges) => {
+  const ws = new WebSocket('/feed')
+  ws.onmessage = (e) => applyChanges(JSON.parse(e.data))
+  return () => ws.close()
+}, { keyConfig: item => item.id })
 ```
 
 ### Reactivity
 ```typescript
-// Effects react to signal changes
-createEffect(() => {
+// Effects run when dependencies change
+const dispose = createEffect(() => {
   console.log(`Count: ${count.get()}`)
 })
 
-// Async effects with automatic cancellation
-createEffect(async (abort) => {
-  const response = await fetch('/api', { signal: abort })
-  return response.json()
+// Effects can return cleanup functions
+createEffect(() => {
+  const timer = setInterval(() => console.log(count.get()), 1000)
+  return () => clearInterval(timer)
+})
+
+// match() for ergonomic signal value extraction inside effects
+createEffect(() => {
+  match([userData], {
+    ok: ([data]) => updateUI(data),
+    nil: () => showLoading(),
+    err: errors => showError(errors[0].message)
+  })
 })
 ```
 
@@ -110,21 +165,24 @@ createEffect(async (abort) => {
 // All signals use .get() for value access
 const value = signal.get()
 
-// Mutable signals have .set() and .update()
+// State has .set() and .update()
 state.set(newValue)
 state.update(current => current + 1)
 
-// Store properties are individually reactive
-user.name.set("Bob")          // Only name watchers trigger
+// Store properties are individually reactive via Proxy
+user.name.set('Bob')             // Only name watchers trigger
 user.age.update(age => age + 1)  // Only age watchers trigger
 
-// List with stable keys for arrays
-const items = new List(['apple', 'banana'], 'fruit')
-const appleSignal = items.byKey('fruit0')  // Access by stable key
-const firstKey = items.keyAt(0)            // Get key at position
-const appleIndex = items.indexOfKey('fruit0') // Get position of key
-items.splice(1, 0, 'cherry')               // Insert at position 1
-items.sort()                               // Sort while preserving keys
+// List with stable keys
+const items = createList(['apple', 'banana'], { keyConfig: 'fruit' })
+const appleSignal = items.byKey('fruit0')
+const firstKey = items.keyAt(0)
+const appleIndex = items.indexOfKey('fruit0')
+items.splice(1, 0, 'cherry')
+items.sort()
+
+// Collections via deriveCollection
+const processed = items.deriveCollection(item => item.toUpperCase())
 ```
 
 ## Coding Conventions
@@ -132,194 +190,73 @@ items.sort()                               // Sort while preserving keys
 ### TypeScript Style
 - Generic constraints: `T extends {}` to exclude null/undefined
 - Use `const` for immutable values
-- Function overloads for complex type scenarios
+- Function overloads for complex type scenarios (e.g., `createCollection`, `deriveCollection`)
 - JSDoc comments on all public APIs
 - Pure function annotations: `/*#__PURE__*/` for tree-shaking
 
 ### Naming Conventions
-- Factory functions: `create*` prefix (createEffect, createStore, createComputed)
-- Type predicates: `is*` prefix (isSignal, isState, isComputed)
-- Type constants: `TYPE_*` format (TYPE_STATE, TYPE_STORE, TYPE_COMPUTED)
-- Utility constants: UPPER_CASE (UNSET)
+- Factory functions: `create*` prefix (createState, createMemo, createEffect, createStore, createList, createCollection, createSensor)
+- Type predicates: `is*` prefix (isState, isMemo, isTask, isStore, isList, isCollection, isSensor)
+- Type constants: `TYPE_*` format (TYPE_STATE, TYPE_STORE, TYPE_SENSOR, TYPE_COLLECTION)
+- Callback types: `*Callback` suffix (MemoCallback, TaskCallback, EffectCallback, SensorCallback, CollectionCallback, DeriveCollectionCallback)
 
 ### Error Handling
-- Custom error classes in `src/errors.ts`
-- Descriptive error messages with context
-- Input validation at public API boundaries
-- Use `UNSET` symbol for uninitialized/pending states
+- Custom error classes in `src/errors.ts`: CircularDependencyError, NullishSignalValueError, InvalidSignalValueError, InvalidCallbackError, RequiredOwnerError, UnsetSignalValueError
+- Descriptive error messages with `[TypeName]` prefix
+- Input validation via `validateSignalValue()` and `validateCallback()`
+- Optional type guards via `guard` option in SignalOptions
 
 ## Performance Considerations
 
 ### Optimization Patterns
-- Dependency tracking with `Set<Watcher>` for O(1) operations
-- Batched updates to minimize effect re-runs
-- Shallow equality checks with `isEqual()` utility
-- Memoization in computed signals prevents unnecessary recalculations
-- Tree-shaking friendly with pure function annotations
+- Linked-list edges for O(1) link/unlink operations
+- Flag-based dirty checking: FLAG_CLEAN, FLAG_CHECK, FLAG_DIRTY, FLAG_RUNNING
+- Batched updates via `batch()` to minimize effect re-runs
+- Lazy evaluation: Memos only recompute when accessed and dirty
+- Automatic abort of in-flight Tasks when sources change
 
 ### Memory Management
-- Automatic cleanup of watchers when effects are disposed
-- WeakMap usage for object-to-signal mappings where appropriate
+- `trimSources()` removes stale edges after each recomputation
+- `unlink()` calls `source.stop()` when last sink disconnects (auto-cleanup for Sensor/Collection/Store/List)
 - AbortSignal integration for canceling async operations
+- `createScope()` for hierarchical cleanup of nested effects
 
-## Common Implementation Patterns
+## Resource Management
 
-### State Management
+**Sensor and Collection** use a start callback that returns a Cleanup function:
 ```typescript
-// Simple state
-const loading = new State(false)
-const error = new State('') // Empty string means no error
-
-// Nested state with stores
-const appState = createStore({
-  user: { id: 1, name: "Alice" },
-  settings: { theme: "dark", notifications: true }
-})
-
-// Lists with stable keys for arrays
-const todoList = new List([
-  { id: 'task1', text: 'Learn signals', completed: false },
-  { id: 'task2', text: 'Build app', completed: false }
-], todo => todo.id) // Use ID as stable key
-
-// Access todos by stable key for consistent references
-const firstTodo = todoList.byKey('task1')
-firstTodo?.completed.set(true) // Mark completed
-
-// Collections for read-only derived data
-const completedTodos = new DerivedCollection(todoList, todo => 
-  todo.completed ? { ...todo, status: 'done' } : null
-).filter(Boolean) // Remove null values
-
-// Async collections for enhanced data
-const todoWithDetails = new DerivedCollection(todoList, async (todo, abort) => {
-  const response = await fetch(`/todos/${todo.id}/details`, { signal: abort })
-  return { ...todo, details: await response.json() }
+const sensor = createSensor<T>((set) => {
+  // setup input tracking, call set(value) to update
+  return () => { /* cleanup */ }
 })
 
-// Element collections for DOM reactivity
-const buttons = createElementCollection(document.body, 'button')
-const inputs = createElementCollection(form, 'input[type="text"]')
+const feed = createCollection<T>((applyChanges) => {
+  // setup external data source, call applyChanges(diffResult) on changes
+  return () => { /* cleanup */ }
+}, { keyConfig: item => item.id })
 ```
 
-### Derived State
+**Store and List** use an optional `watched` callback in options:
 ```typescript
-// Reducer pattern for state machines
-const appState = new Memo((prev) => {
-  const event = events.get()
-  switch (prev) {
-    case 'idle':
-      return event === 'start' ? 'loading' : 'idle'
-    case 'loading':
-      return event === 'success' ? 'loaded' : event === 'error' ? 'error' : 'loading'
-    case 'loaded':
-      return event === 'refresh' ? 'loading' : 'loaded'
-    case 'error':
-      return event === 'retry' ? 'loading' : 'error'
-    default:
-      return 'idle'
+const store = createStore(initialValue, {
+  watched: () => {
+    // setup resources
+    return () => { /* cleanup */ }
   }
-}, 'idle') // Initial state
-```
-
-### Async Operations
-```typescript
-// Computed with async data fetching
-const userData = new Task(async (prev, abort) => {
-  const id = userId.get()
-  if (!id) return prev // Retain previous data when no ID
-  const response = await fetch(`/users/${id}`, { signal: abort })
-  if (!response.ok) throw new Error('Failed to fetch user')
-  return response.json()
 })
 ```
 
-### Error Handling
-```typescript
-// Handle loading/error states
-createEffect(() => {
-  match(resolve({ userData }), {
-    ok: ({ userData }) => console.log('User:', userData),
-    nil: () => console.log('Loading...'),
-    err: (errors) => console.error('Error:', errors[0])
-  })
-})
-```
-
-### Helper Functions Usage
-```typescript
-// Extract values from multiple signals
-const result = resolve({ name, age, email })
-
-// Pattern matching for discriminated unions
-match(result, {
-  ok: (values) => console.log('Success:', values),
-  nil: () => console.log('Some values pending'),
-  err: (errors) => console.error('Errors:', errors)
-})
-
-// Object diffing
-const changes = diff(oldUser, newUser)
-console.log('Changed:', changes.change)
-console.log('Added:', changes.add)
-console.log('Removed:', changes.remove)
-
-// Collection transformations
-const processedItems = items.deriveCollection(item => ({
-  ...item,
-  processed: true,
-  timestamp: Date.now()
-}))
-
-// Chained collections for data pipelines
-const finalResults = processedItems.deriveCollection(item => 
-  item.processed ? { summary: `${item.name} at ${item.timestamp}` } : null
-).filter(Boolean)
-
-// Ref signal manual notifications
-elementRef.notify() // Notify when DOM element changes externally
-cacheRef.notify()   // Notify when Map/Set changes externally
-
-// Resource management with watch hooks
-signal.on('watch', () => {
-  console.log('Setting up resource...')
-  const resource = createResource()
-  return () => resource.cleanup() // Called when no effects watch this signal
-})
-```
+Resources activate on first sink link and cleanup when last sink unlinks.
 
 ## Build and Development
 
 ### Tools
 - **Runtime**: Bun (also works with Node.js)
 - **Build**: Bun build with TypeScript compilation
-- **Testing**: Bun test runner
+- **Testing**: Bun test runner (`bun test`)
 - **Linting**: Biome for code formatting and linting
 
 ### Package Configuration
 - ES modules only (`"type": "module"`)
-- Dual exports: TypeScript source and compiled JavaScript
-- Tree-shaking friendly with proper sideEffects configuration
 - TypeScript declarations generated automatically
-
-## Key Design Decisions
-
-### Why Signals?
-- Fine-grained reactivity (update only what changed)
-- Explicit dependency tracking (no hidden dependencies)
-- Composable and testable
-- Framework agnostic
-
-### Why TypeScript-First?
-- Better developer experience with autocomplete
-- Compile-time error catching
-- Self-documenting APIs
-- Better refactoring support
-
-### Why Functional Approach?
-- Predictable behavior
-- Easier testing
-- Better composition
-- Minimal API surface
-
-When working with this codebase, focus on maintaining the established patterns, ensuring type safety, and optimizing for performance while keeping the API simple and predictable.
+- Tree-shaking friendly with proper sideEffects configuration

package/.cursorrules

@@ -1,58 +1,64 @@
-# Cause & Effect - Reactive State Management Library
+# Cause & Effect - Reactive State Management Primitives
 
 ## Project Type
-TypeScript/JavaScript reactive state management library using signals pattern
+TypeScript reactive state management primitives library using a unified signal graph
 
 ## Core Concepts
-- Signals: Base reactive primitives with .get() method
-- State: new State() for primitives/simple values  
-- Ref: new Ref() for external objects (DOM, Map, Set) requiring manual .notify()
-- Computed: new Memo() for derived/memoized values and new Task() for asynchronous computations
-- Store: createStore() for objects with reactive properties
-- List: new List() for arrays with stable keys and reactive items
-- Collection: Interface for reactive collections (DerivedCollection, ElementCollection)
-- Effects: createEffect() for side effects
+- Signals: Reactive primitives with .get() method for dependency tracking
+- State: createState() for mutable source values
+- Sensor: createSensor() for external input with lazy lifecycle
+- Memo: createMemo() for synchronous memoized derivations
+- Task: createTask() for asynchronous derivations with cancellation
+- Store: createStore() for reactive objects with per-property signals
+- List: createList() for reactive arrays with stable keys
+- Collection: createCollection() for reactive collections (external source or derived, item-level memoization)
+- Effect: createEffect() for side-effect sinks
 
 ## Code Style
 - Use const for immutable values
 - Generic constraints: T extends {} (excludes null/undefined)
 - Factory functions: create* prefix
-- Type predicates: is* prefix  
+- Type predicates: is* prefix
 - Constants: TYPE_* or UPPER_CASE
 - Pure functions marked with /*#__PURE__*/ comment
 
 ## Key Patterns
 - All signals have .get() method
 - Mutable signals have .set(value) and .update(fn)
-- Store properties auto-become reactive signals
-- Computed callbacks receive oldValue as first parameter for reducer patterns
-- Async computed and effect callbacks receive AbortSignal for async cancellation
-- Use UNSET symbol for uninitialized states
-- Batch updates for performance
-- JSDoc comments on all public APIs
+- Store properties auto-become reactive signals via Proxy
+- Memo callbacks receive previous value as first parameter for reducer patterns
+- Task callbacks receive (next, AbortSignal)
+- Sensor and Collection use start callbacks for lazy resource management
+- Store and List support optional watched callbacks
+- batch() for grouping multiple updates
+- untrack() for reading signals without creating edges
 
 ## File Structure
-- src/signal.ts - Base signal types
-- src/classes/state.ts - Mutable state signals
-- src/classes/ref.ts - Signal wrappers for external objects
-- src/classes/store.ts - Object stores
-- src/classes/list.ts - Array stores with stable keys
-- src/classes/collection.ts - Collection interface and DerivedCollection
-- src/classes/computed.ts - Computed signals
-- src/effect.ts - Effect system
-- src/system.ts - Core reactivity (watchers, batching)
-- index.ts - Main exports
-
-## Error Handling  
+- src/graph.ts - Core reactive engine (nodes, edges, propagation, flush)
+- src/nodes/state.ts - Mutable state signals
+- src/nodes/sensor.ts - External input tracking
+- src/nodes/memo.ts - Synchronous derived signals
+- src/nodes/task.ts - Asynchronous derived signals
+- src/nodes/effect.ts - Side-effect system
+- src/nodes/store.ts - Reactive objects
+- src/nodes/list.ts - Reactive arrays with stable keys
+- src/nodes/collection.ts - Externally-driven and derived collections
+- next.ts - Public API exports
+
+## Error Handling
 - Custom error classes in src/errors.ts
-- Validate inputs, throw descriptive errors
-- Support AbortSignal in async operations
+- Validate inputs with validateSignalValue() and validateCallback()
+- AbortSignal integration for async cancellation in Task and Collection
 
 ## Performance
-- Use Set<Watcher> for subscriptions
-- Shallow equality with isEqual() utility
-- Tree-shaking friendly code
-- Minimize effect re-runs
+- Linked-list edges for O(1) dependency tracking
+- Flag-based dirty checking (CLEAN, CHECK, DIRTY)
+- Tree-shaking friendly, zero dependencies
+- Minimize effect re-runs via equality checks
+
+## Testing
+- bun:test with describe/test/expect
+- Test files: test/*.test.ts
 
 ## Build
 - Bun build tool and runtime