@zeix/cause-effect 0.16.1 → 0.17.1

package/CLAUDE.md

@@ -6,20 +6,20 @@ Cause & Effect is a reactive state management library that implements the signal
 
 ### Core Philosophy
 - **Granular Reactivity**: Changes propagate only to dependent computations, minimizing unnecessary work
-- **Explicit Dependencies**: No hidden subscriptions or magic - dependencies are tracked through `.get()` calls
-- **Functional Design**: Immutable by default, with pure functions and predictable state updates
-- **Type Safety First**: Comprehensive TypeScript support with strict generic constraints
+- **Explicit Dependencies**: Dependencies are tracked through `.get()` calls, no hidden subscriptions
+- **Type Safety First**: Comprehensive TypeScript support with strict generic constraints (`T extends {}`)
 - **Performance Conscious**: Minimal overhead through efficient dependency tracking and batching
 
 ## Mental Model for Understanding the System
 
 Think of signals as **observable cells** in a spreadsheet:
-- **State signals** are like input cells where you can directly enter values
-- **Computed signals** are like formula cells that automatically recalculate when their dependencies change
-- **Store signals** are like structured data tables where individual columns (properties) are reactive
-- **Effects** are like event handlers that trigger side effects when cells change
-
-The key insight is that the system tracks which cells (signals) are read during computation, creating an automatic dependency graph that ensures minimal and correct updates.
+- **State signals** are input cells for primitive values and objects
+- **Ref signals** are cells that reference external objects (DOM, Map, Set) requiring manual notification
+- **Computed signals** are formula cells that automatically recalculate when dependencies change
+- **Store signals** are structured tables where individual columns (properties) are reactive
+- **List signals** are tables with stable row IDs that survive sorting and reordering
+- **Collection signals** are read-only derived tables with item-level memoization
+- **Effects** are event handlers that trigger side effects when cells change
 
 ## Architectural Deep Dive
 
@@ -43,24 +43,53 @@ interface MutableSignal<T extends {}> extends Signal<T> {
   set(value: T): void
   update(fn: (current: T) => T): void
 }
+
+// Collection interface - implemented by various collection types
+interface Collection<T extends {}> {
+  get(): T[]
+  at(index: number): Signal<T> | undefined
+  byKey(key: string): Signal<T> | undefined
+  deriveCollection<R extends {}>(callback: CollectionCallback<R, T>): Collection<R>
+}
 ```
 
 The generic constraint `T extends {}` is crucial - it excludes `null` and `undefined` at the type level, preventing common runtime errors and making the API more predictable.
 
-### Store Signal Deep Dive
+### Collection Architecture
+
+Collections are an interface implemented by different reactive array types:
+
+**DerivedCollection**: Read-only transformations of Lists or other Collections
+- Item-level memoization with Computed signals
+- Async support with automatic cancellation
+- Chainable for data pipelines
+
+**ElementCollection**: DOM element collections with MutationObserver
+- Uses Ref signals for elements that change externally
+- Watches attributes and childList mutations
+- Stable keys for persistent element identity
+
+Key patterns:
+- Collections return arrays of values via `.get()`
+- Individual items accessed as signals via `.at()` and `.byKey()`
+- All collections support `.deriveCollection()` for chaining
 
-Store signals are the most complex part of the system. They transform plain objects into reactive data structures:
+### Store and List Architecture
 
-1. **Property Proxification**: Each property becomes its own signal
-2. **Nested Reactivity**: Objects within objects recursively become stores
-3. **Array Support**: Arrays get special treatment with length tracking and efficient sorting
-4. **Dynamic Properties**: Runtime addition/removal of properties with proper reactivity
+**Store signals** (`createStore`): Transform objects into reactive data structures
+- Each property becomes its own signal via Proxy
+- Built on `Composite` class for signal management
+- Dynamic property addition/removal with proper reactivity
 
-Key implementation details:
-- Uses Proxy to intercept property access
-- Maintains internal signal instances for each property
-- Supports change notifications for fine-grained updates
-- Handles edge cases like symbol properties and prototype chain
+**List signals** (`new List`): Arrays with stable keys and reactive items
+- Maintains stable keys that survive sorting and reordering
+- Built on `Composite` class for consistent signal management
+- Provides `byKey()`, `keyAt()`, `indexOfKey()` for key-based access
+
+**Composite Architecture**: Shared foundation for Store and List
+- `Map<string, Signal>` for property/item signals
+- Event system for granular add/change/remove notifications
+- Lazy signal creation and automatic cleanup
 
 ### Computed Signal Memoization Strategy
 
@@ -69,61 +98,92 @@ Computed signals implement smart memoization:
 - **Stale Detection**: Only recalculates when dependencies actually change
 - **Async Support**: Handles Promise-based computations with automatic cancellation
 - **Error Handling**: Preserves error states and prevents cascade failures
-- **Reducer-like Capabilities**: Access to previous value enables state accumulation and transitions
+- **Reducer Capabilities**: Access to previous value enables state accumulation and transitions
 
 ## Advanced Patterns and Best Practices
 
 ### When to Use Each Signal Type
 
-**State Signals (`createState`)**:
+**State Signals (`State`)**:
 - Primitive values (numbers, strings, booleans)
 - Objects that you replace entirely rather than mutating properties
 - Simple toggles and flags
 - Values with straightforward update patterns
 
 ```typescript
-const count = createState(0)
-const theme = createState<'light' | 'dark'>('light')
-const user = createState<User>({ id: 1, name: 'John Doe', email: 'john@example.com' }) // Replace entire user object
+const count = new State(0)
+const theme = new State<'light' | 'dark'>('light')
+```
+
+**Ref Signals (`new Ref`)**:
+- External objects that change outside the reactive system
+- DOM elements, Map, Set, Date objects, third-party APIs
+- Requires manual `.notify()` when external object changes
+
+```typescript
+const elementRef = new Ref(document.getElementById('status'))
+const cacheRef = new Ref(new Map())
+// When external change occurs: cacheRef.notify()
 ```
 
 **Store Signals (`createStore`)**:
 - Objects where individual properties change independently
-- Nested data structures
-- Form state where fields update individually
-- Configuration objects with multiple settings
 
 ```typescript
-const form = createStore({
-  email: '',
-  password: '',
-  errors: { email: null, password: null }
+const user = createStore({ name: 'Alice', email: 'alice@example.com' })
+user.name.set('Bob') // Only name subscribers react
+```
+
+**List Signals (`new List`)**:
+```typescript
+const todoList = new List([
+  { id: 'task1', text: 'Learn signals' }
+], todo => todo.id)
+const firstTodo = todoList.byKey('task1') // Access by stable key
+```
+
+**Collection Signals (`new DerivedCollection`)**:
+```typescript
+const completedTodos = new DerivedCollection(todoList, todo => 
+  todo.completed ? { ...todo, status: 'done' } : null
+)
+const todoDetails = new DerivedCollection(todoList, async (todo, abort) => {
+  const response = await fetch(`/todos/${todo.id}`, { signal: abort })
+  return { ...todo, details: await response.json() }
 })
-// form.email.set('user@example.com') // Only email subscribers react
+
+// Chain collections for data pipelines
+const urgentTodoSummaries = todoList
+  .deriveCollection(todo => ({ ...todo, urgent: todo.priority > 8 }))
+  .deriveCollection(todo => todo.urgent ? `URGENT: ${todo.text}` : todo.text)
+
+// Collections maintain stable references through List changes
+const firstTodoDetail = todoDetails.byKey('task1') // Computed signal
+todoList.sort() // Reorders list but collection signals remain stable
 ```
 
-**Computed Signals (`createComputed`)**:
+**Computed Signals (`Memo` and `Task`)**:
 - Expensive calculations that should be memoized
 - Derived data that depends on multiple signals
 - Async operations that need automatic cancellation
 - Cross-cutting concerns that multiple components need
 
 ```typescript
-const expensiveCalc = createComputed(() => {
+const expensiveCalc = new Memo(() => {
   return heavyComputation(data1.get(), data2.get()) // Memoized
 })
 
-const userData = createComputed(async (prev, abort) => {
+const userData = new Task(async (prev, abort) => {
   const id = userId.get()
   if (!id) return prev // Keep previous data if no ID
   const response = await fetch(`/users/${id}`, { signal: abort })
   return response.json()
 })
 
-// Reducer-like pattern for state machines
-const gameState = createComputed((currentState) => {
+// Reducer pattern for state machines
+const gameState = new Memo(prev => {
   const action = playerAction.get()
-  switch (currentState) {
+  switch (prev) {
     case 'menu':
       return action === 'start' ? 'playing' : 'menu'
     case 'playing':
@@ -138,7 +198,7 @@ const gameState = createComputed((currentState) => {
 }, 'menu') // Initial state
 
 // Accumulating values over time
-const runningTotal = createComputed((previous) => {
+const runningTotal = new Memo(prev => {
   const newValue = currentValue.get()
   return previous + newValue
 }, 0) // Start with 0
@@ -154,19 +214,13 @@ The library provides several layers of error handling:
 4. **Helper Functions**: `resolve()` and `match()` for ergonomic error handling
 
 ```typescript
-// Robust async data fetching with error handling
-const apiData = createComputed(async (abort) => {
-  try {
-    const response = await fetch('/api/data', { signal: abort })
-    if (!response.ok) throw new Error(`HTTP ${response.status}`)
-    return response.json()
-  } catch (error) {
-    if (abort.aborted) return UNSET // Cancelled, not an error
-    throw error // Real error
-  }
+// Error handling with resolve() and match()
+const apiData = new Task(async (prev, abort) => {
+  const response = await fetch('/api/data', { signal: abort })
+  if (!response.ok) throw new Error(`HTTP ${response.status}`)
+  return response.json()
 })
 
-// Pattern matching for comprehensive state handling
 createEffect(() => {
   match(resolve({ apiData }), {
     ok: ({ apiData }) => updateUI(apiData),
@@ -176,144 +230,70 @@ createEffect(() => {
 })
 ```
 
-### Performance Optimization Techniques
-
-1. **Batching Updates**: Use `batch()` for multiple synchronous updates
-2. **Selective Dependencies**: Structure computed signals to minimize dependencies
-3. **Cleanup Management**: Properly dispose of effects to prevent memory leaks
-4. **Shallow vs Deep Equality**: Use appropriate comparison strategies
+### Performance Optimization
 
+**Batching**: Use `batchSignalWrites()` for multiple updates
 ```typescript
-// Create a user store
-const user = createStore<{ id: number, name: string, email: string, age?: number }>({
-	id: 1,
-	name: 'John Doe',
-	email: 'john@example.com'
-})
-
-// Batch multiple updates to prevent intermediate states
-batch(() => {
-  user.name.set('Alice Doe')
-  user.age.set(30)
+batchSignalWrites(() => {
+  user.name.set('Alice')
   user.email.set('alice@example.com')
-}) // Only triggers effects once at the end
-
-// Optimize computed dependencies
-const userDisplay = createComputed(() => {
-  const { name, email } = user.get() // Gets entire object
-  return `${name} <${email}>`
-})
-
-// Better: more granular dependencies
-const userDisplay = createComputed(() => {
-  return `${user.name.get()} <${user.email.get()}>` // Only depends on name/email
-})
+}) // Single effect trigger
 ```
 
-## Integration Patterns
-
-### Framework Integration
-The library is framework-agnostic but integrates well with:
-- **React**: Use effects to trigger re-renders
-- **Vue**: Integrate with Vue's reactivity system
-- **Svelte**: Use effects to update Svelte stores
-- **Vanilla JS**: Direct DOM manipulation in effects
-
-### Testing Strategies
-- **Unit Testing**: Test signal logic in isolation
-- **Integration Testing**: Test effect chains and async operations
-- **Mock Testing**: Mock external dependencies in computed signals
-- **Property Testing**: Use random inputs to verify invariants
-
-### Debugging Techniques
-- Use `resolve()` to inspect multiple signal states at once
-- Add logging effects for debugging reactivity chains
-- Use AbortSignal inspection for async operation debugging
-- Leverage TypeScript for compile-time dependency analysis
+**Granular Dependencies**: Structure computed signals to minimize dependencies
+```typescript
+// Bad: depends on entire user object
+const display = new Memo(() => user.get().name + user.get().email)
+// Good: only depends on specific properties  
+const display = new Memo(() => user.name.get() + user.email.get())
+```
 
-## Common Pitfalls and How to Avoid Them
+## Common Pitfalls
 
 1. **Infinite Loops**: Don't update signals within their own computed callbacks
-2. **Stale Closures**: Be careful with captured values in async operations
-3. **Memory Leaks**: Always clean up effects when components unmount
-4. **Over-reactivity**: Structure data to minimize unnecessary updates
-5. **Async Race Conditions**: Trust the automatic cancellation, don't fight it
+2. **Memory Leaks**: Clean up effects when components unmount  
+3. **Over-reactivity**: Structure data to minimize unnecessary updates
+4. **Async Race Conditions**: Trust automatic cancellation with AbortSignal
 
-## Advanced Use Cases
+## Advanced Patterns
 
-### Building Reactive Data Structures
+### Event Bus with Type Safety
 ```typescript
-// Reactive list with computed properties
-const todos = createStore<Todo[]>([])
-const completedCount = createComputed(() => 
-  todos.get().filter(todo => todo.completed).length
-)
-const remainingCount = createComputed(() => 
-  todos.get().length - completedCount.get()
-)
-```
-
-### Reactive State Machines
-```typescript
-const state = createState<'idle' | 'loading' | 'success' | 'error'>('idle')
-const canRetry = () => state.get() === 'error'
-const isLoading = () => state.get() === 'loading'
-```
-
-### Cross-Component Communication
-```typescript
-// Component ownership pattern: The component that emits events owns the store
-// Component B (the emitter) declares the shape of events it will emit upfront
-type EventBusSchema = {
+type Events = {
   userLogin: { userId: number; timestamp: number }
   userLogout: { userId: number }
-  userUpdate: { userId: number; profile: { name: string } }
 }
 
-// Initialize the event bus with proper typing
-const eventBus = createStore<EventBusSchema>({
+const eventBus = createStore<Events>({
   userLogin: UNSET,
-  userLogout: UNSET,
-  userUpdate: UNSET,
+  userLogout: UNSET
 })
 
-// Type-safe emit function
-const emit = <K extends keyof EventBusSchema>(
-  event: K,
-  data: EventBusSchema[K],
-) => {
+const emit = <K extends keyof Events>(event: K, data: Events[K]) => {
   eventBus[event].set(data)
 }
 
-// Type-safe on function with proper callback typing
-const on = <K extends keyof EventBusSchema>(
-  event: K,
-  callback: (data: EventBusSchema[K]) => void,
-) =>
+const on = <K extends keyof Events>(event: K, callback: (data: Events[K]) => void) =>
   createEffect(() => {
     const data = eventBus[event].get()
     if (data !== UNSET) callback(data)
   })
-
-// Usage example:
-// Component A listens for user events
-on('userLogin', (data) => {
-  console.log('User logged in:', data) // data is properly typed
-})
-
-// Component B emits user events
-eventBus.userLogin.set({ userId: 123, timestamp: Date.now() })
 ```
 
-**Component ownership principle**: The component that emits events should own and initialize the event store. This creates clear boundaries and prevents coupling issues.
+### Data Processing Pipelines
+```typescript
+const rawData = new List([{ id: 1, value: 10 }])
+const processed = rawData
+  .deriveCollection(item => ({ ...item, doubled: item.value * 2 }))
+  .deriveCollection(item => ({ ...item, formatted: `$${item.doubled}` }))
+```
 
-**Why this pattern?**: By having the owning component (Component B) initialize all known events with `UNSET`, we get:
-1. **Fine-grained reactivity**: Each `on()` call establishes a direct dependency on the specific event signal
-2. **Full type safety**: Event names and data shapes are constrained at compile time
-3. **Simple logic**: No conditional updates, no store-wide watching in `on()`
-4. **Clear ownership**: Component B declares its event contract upfront with a schema
-5. **Better performance**: Only the specific event listeners trigger, not all listeners
-6. **Explicit dependencies**: Effects track exactly which events they care about
-7. **IntelliSense support**: IDEs can provide autocomplete for event names and data structures
+### Stable List Keys
+```typescript
+const playlist = new List([
+  { id: 'track1', title: 'Song A' }
+], track => track.id)
 
-This context should help you understand not just what the code does, but why it's structured this way and how to use it effectively in real-world applications.
+const firstTrack = playlist.byKey('track1') // Persists through sorting
+playlist.sort((a, b) => a.title.localeCompare(b.title))
+```

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 - 2025 Zeix AG
+Copyright (c) 2024 - 2026 Zeix AG
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal