@zeix/cause-effect 0.16.1 → 0.17.0

package/.ai-context.md

@@ -10,7 +10,9 @@ Cause & Effect is a modern reactive state management library for JavaScript/Type
 - **Signal**: Base interface with `.get()` method for value access
 - **State**: Mutable signals for primitive values (numbers, strings, booleans)
 - **Store**: Mutable signals for objects with individually reactive properties
-- **Computed**: Read-only derived signals with automatic memoization, reducer-like capabilities and asyc handling
+- **List**: Mutable signals for arrays with individually reactive items
+- **Collection**: Read-only derived arrays with item-level memoization and async support
+- **Computed**: Read-only derived signals with automatic memoization, reducer capabilities and asyc handling
 - **Effect**: Side effect handlers that react to signal changes
 
 ### Key Principles
@@ -25,10 +27,13 @@ Cause & Effect is a modern reactive state management library for JavaScript/Type
 ```
 cause-effect/
 ├── src/
-│   ├── signal.ts      # Base signal types and utilities
-│   ├── state.ts       # Mutable state signals (createState)
-│   ├── store.ts       # Object stores with reactive properties
-│   ├── computed.ts    # Computed/derived signals (createComputed)
+│   ├── classes/
+│   │   ├── state.ts       # Mutable state signals (State)
+│   │   ├── store.ts       # Object stores with reactive properties
+│   │   ├── list.ts        # Array stores with stable keys (List)
+│   │   ├── collection.ts  # Read-only derived arrays (Collection)
+│   │   └── 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
@@ -46,18 +51,22 @@ cause-effect/
 ### Signal Creation
 ```typescript
 // State signals for primitives
-const count = createState(42)
-const name = createState('Alice')
-const actions = createState<'increment' | 'decrement' | 'reset'>('reset')
+const count = new State(42)
+const name = new State('Alice')
+const actions = new State<'increment' | 'decrement' | 'reset'>('reset')
 
 // Store signals for objects  
 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)
+
 // Computed signals for derived values
-const doubled = createComputed(() => count.get() * 2)
+const doubled = new Memo(() => count.get() * 2)
 
-// Computed with reducer-like capabilities (access to previous value)
-const counter = createComputed((prev) => {
+// Computed with reducer capabilities (access to previous value)
+const counter = new Memo((prev) => {
   const action = actions.get()
   switch (action) {
     case 'increment': return prev + 1
@@ -68,7 +77,7 @@ const counter = createComputed((prev) => {
 }, 0) // Initial value
 
 // Async computed with access to previous value
-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 user ID
   const response = await fetch(`/users/${id}`, { signal: abort })
@@ -102,6 +111,14 @@ state.update(current => current + 1)
 // Store properties are individually reactive
 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
 ```
 
 ## Coding Conventions
@@ -114,7 +131,7 @@ user.age.update(age => age + 1)  // Only age watchers trigger
 - Pure function annotations: `/*#__PURE__*/` for tree-shaking
 
 ### Naming Conventions
-- Factory functions: `create*` prefix (createState, createStore, createComputed)
+- 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)
@@ -144,22 +161,43 @@ user.age.update(age => age + 1)  // Only age watchers trigger
 ### State Management
 ```typescript
 // Simple state
-const loading = createState(false)
-const error = createState('') // Empty string means no error
+const loading = new State(false)
+const error = new State('') // Empty string means no error
 
-// Complex state with stores
+// 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 Collection(todoList, todo => 
+  todo.completed ? { ...todo, status: 'done' } : null
+).filter(Boolean) // Remove null values
+
+// Async collections for enhanced data
+const todoWithDetails = new Collection(todoList, async (todo, abort) => {
+  const response = await fetch(`/todos/${todo.id}/details`, { signal: abort })
+  return { ...todo, details: await response.json() }
+})
 ```
 
 ### Derived State
 ```typescript
-// Reducer-like pattern for state machines
-const appState = createComputed((currentState) => {
+// Reducer pattern for state machines
+const appState = new Memo((prev) => {
   const event = events.get()
-  switch (currentState) {
+  switch (prev) {
     case 'idle':
       return event === 'start' ? 'loading' : 'idle'
     case 'loading':
@@ -177,9 +215,9 @@ const appState = createComputed((currentState) => {
 ### Async Operations
 ```typescript
 // Computed with async data fetching
-const userData = createComputed(async (oldValue, abort) => {
+const userData = new Task(async (prev, abort) => {
   const id = userId.get()
-  if (!id) return oldValue // Retain previous data when no ID
+  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()
@@ -215,6 +253,18 @@ 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)
 ```
 
 ## Build and Development

package/.cursorrules

@@ -5,9 +5,10 @@ TypeScript/JavaScript reactive state management library using signals pattern
 
 ## Core Concepts
 - Signals: Base reactive primitives with .get() method
-- State: createState() for primitives/simple values  
+- State: new State() for primitives/simple values  
+- Computed: new Memo() for derived/memoized values and new Task() for asynchronous computations
 - Store: createStore() for objects with reactive properties
-- Computed: createComputed() for derived/memoized values
+- List: new List() for arrays with stable keys and reactive items
 - Effects: createEffect() for side effects
 
 ## Code Style

package/.github/copilot-instructions.md

@@ -7,17 +7,21 @@ Cause & Effect is a reactive state management library for JavaScript/TypeScript
 ## Core Architecture
 
 - **Signals**: Base reactive primitives with `.get()` method
-- **State**: Mutable signals for primitive values (`createState()`)
+- **State**: Mutable signals for primitive values (`new State()`)
+- **Computed**: Derived read-only signals with memoization, reducer capabilities and async support (`new Memo()`, `new Task()`)
 - **Store**: Mutable signals for objects with reactive properties (`createStore()`)
-- **Computed**: Derived read-only signals with memoization, reducer-like capabilities and async support (`createComputed()`)
+- **List**: Mutable signals for arrays with stable keys and reactive entries (`new List()`)
+- **Collection**: Read-only derived arrays with item-level memoization and async support (`new Collection()`)
 - **Effects**: Side effect handlers that react to signal changes (`createEffect()`)
 
 ## Key Files Structure
 
+- `src/classes/state.ts` - Mutable state signals
+- `src/classes/store.ts` - Object stores with reactive properties
+- `src/classes/list.ts` - Array stores with stable keys and reactive items
+- `src/classes/collection.ts` - Read-only derived arrays with memoization
+- `src/classes/computed.ts` - Computed/derived signals
 - `src/signal.ts` - Base signal types and utilities
-- `src/state.ts` - Mutable state signals
-- `src/store.ts` - Object stores with reactive properties
-- `src/computed.ts` - Computed/derived signals
 - `src/effect.ts` - Effect system
 - `src/system.ts` - Core reactivity system (watchers, batching)
 - `src/util.ts` - Utility functions and constants
@@ -33,7 +37,7 @@ Cause & Effect is a reactive state management library for JavaScript/TypeScript
 - JSDoc comments for all public APIs
 
 ### Naming Conventions
-- Factory functions: `create*` (e.g., `createState`, `createStore`)
+- Factory functions: `create*` (e.g., `createEffect`, `createStore`)
 - Type predicates: `is*` (e.g., `isSignal`, `isState`)
 - Constants: `TYPE_*` for type tags, `UPPER_CASE` for values
 - Private variables: use descriptive names, no underscore prefix
@@ -69,18 +73,22 @@ Cause & Effect is a reactive state management library for JavaScript/TypeScript
 ### Creating Signals
 ```typescript
 // State for primitives
-const count = createState(42)
-const name = createState('Alice')
-const actions = createState<'increment' | 'decrement'>('increment')
+const count = new State(42)
+const name = new State('Alice')
+const actions = new State<'increment' | 'decrement'>('increment')
 
 // Store for objects
 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)
+
 // Computed for derived values
-const doubled = createComputed(() => count.get() * 2)
+const doubled = new Memo(() => count.get() * 2)
 
-// Computed with reducer-like capabilities
-const counter = createComputed((prev) => {
+// Computed with reducer capabilities
+const counter = new Memo(prev => {
   const action = actions.get()
   return action === 'increment' ? prev + 1 : prev - 1
 }, 0) // Initial value
@@ -100,7 +108,7 @@ createEffect(async (abort) => {
 })
 
 // Async computed with old value access
-const userData = createComputed(async (prev, abort) => {
+const userData = new Task(async (prev, abort) => {
   if (!userId.get()) return prev // Keep previous data if no user
   const response = await fetch(`/users/${userId.get()}`, { signal: abort })
   return response.json()
@@ -122,6 +130,44 @@ function isSignal<T extends {}>(value: unknown): value is Signal<T>
 - Minified production build
 - ES modules only (`"type": "module"`)
 
+## Store Methods and Stable Keys
+
+### List Methods
+- `byKey(key)` - Access signals by stable key instead of index
+- `keyAt(index)` - Get stable key at specific position
+- `indexOfKey(key)` - Get position of stable key in current order
+- `splice(start, deleteCount, ...items)` - Array-like splicing with stable key preservation
+- `sort(compareFn)` - Sort items while maintaining stable key associations
+
+### Stable Keys Usage
+```typescript
+// Default auto-incrementing keys
+const items = new List(['a', 'b', 'c'])
+
+// String prefix keys
+// Lists with stable keys
+const items = new List(['apple', 'banana'], 'fruit')
+// Creates keys: 'fruit0', 'fruit1'
+
+// Function-based keys
+const users = new List([
+  { id: 'user1', name: 'Alice' },
+  { id: 'user2', name: 'Bob' }
+], user => user.id) // Uses user.id as stable key
+
+// Collections derived from lists
+const userProfiles = new Collection(users, user => ({
+  ...user,
+  displayName: `${user.name} (ID: ${user.id})`
+}))
+
+// Chained collections for data pipelines
+const activeUserSummaries = users
+  .deriveCollection(user => ({ ...user, active: user.lastLogin > Date.now() - 86400000 }))
+  .deriveCollection(user => user.active ? `Active: ${user.name}` : null)
+  .filter(Boolean)
+```
+
 ## When suggesting code:
 1. Follow the established patterns for signal creation and usage
 2. Use proper TypeScript types and generics

package/CLAUDE.md

@@ -17,6 +17,7 @@ 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
+- **List signals** with stable keys are like tables with persistent row IDs that survive sorting and reordering
 - **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.
@@ -43,13 +44,44 @@ interface MutableSignal<T extends {}> extends Signal<T> {
   set(value: T): void
   update(fn: (current: T) => T): void
 }
+
+// Collection signals are read-only derived arrays
+interface Collection<T extends {}, U extends {}> extends Signal<T[]> {
+  at(index: number): Computed<T> | undefined
+  byKey(key: string): Computed<T> | undefined
+  deriveCollection<R extends {}>(callback: CollectionCallback<R, T>): Collection<R, T>
+}
 ```
 
 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.
 
+### Collection Signal Deep Dive
+
+Collection signals provide read-only derived array transformations with automatic memoization:
+
+1. **Source Dependency**: Collections derive from Lists or other Collections
+2. **Item-level Memoization**: Each item transformation is individually memoized
+3. **Async Support**: Supports Promise-based transformations with cancellation
+4. **Stable Keys**: Maintains the same stable key system as source Lists
+5. **Chainable**: Collections can derive from other Collections for data pipelines
+
+Key implementation details:
+- Individual items are Computed signals, not mutable signals
+- Automatically handles source List changes (add, remove, sort)
+- Supports both sync and async transformation callbacks
+- Lazy evaluation - transformations only run when accessed
+- Smart watcher management - only creates watchers when change listeners are active
+- Order preservation through internal `#order` array synchronized with source
+
+Collection Architecture:
+- **BaseCollection**: Core implementation with signal management and event handling
+- **Computed Creation**: Each source item gets its own computed signal with transformation callback
+- **Source Synchronization**: Listens to source events and maintains parallel structure
+- **Memory Efficiency**: Automatically cleans up computed signals when source items are removed
+
 ### Store Signal Deep Dive
 
-Store signals are the most complex part of the system. They transform plain objects into reactive data structures:
+Store signals are the most complex part of the system. They transform plain objects or arrays into reactive data structures:
 
 1. **Property Proxification**: Each property becomes its own signal
 2. **Nested Reactivity**: Objects within objects recursively become stores
@@ -61,6 +93,24 @@ Key implementation details:
 - Maintains internal signal instances for each property
 - Supports change notifications for fine-grained updates
 - Handles edge cases like symbol properties and prototype chain
+- For lists: maintains stable keys that persist through sorting, splicing, and reordering
+- Provides specialized methods: `byKey()`, `keyAt()`, `indexOfKey()`, `splice()` for array manipulation
+
+### MutableComposite Architecture
+
+Both Store and List signals are built on top of `MutableComposite`, which provides the common reactive property management:
+
+1. **Signal Management**: Maintains a `Map<string, MutableSignal>` of property signals
+2. **Change Detection**: Uses `diff()` to detect actual changes before triggering updates
+3. **Event System**: Emits granular notifications for add/change/remove operations
+4. **Validation**: Enforces type constraints and prevents invalid mutations
+5. **Performance**: Only creates signals when properties are first accessed or added
+
+Key implementation details:
+- Lazy signal creation for better memory usage
+- Efficient batch updates through change detection
+- Support for both object and array data structures
+- Automatic cleanup when properties are removed
 
 ### Computed Signal Memoization Strategy
 
@@ -69,22 +119,22 @@ 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')
+const user = new State<User>({ id: 1, name: 'John Doe', email: 'john@example.com' }) // Replace entire user object
 ```
 
 **Store Signals (`createStore`)**:
@@ -102,28 +152,69 @@ const form = createStore({
 // form.email.set('user@example.com') // Only email subscribers react
 ```
 
-**Computed Signals (`createComputed`)**:
+**List Signals (`new List`)**:
+
+```ts
+// Lists with stable keys
+const todoList = new List([
+  { id: 'task1', text: 'Learn signals' },
+  { id: 'task2', text: 'Build app' }
+], todo => todo.id) // Use todo.id as stable key
+
+// Access by stable key instead of index
+const firstTodo = todoList.byKey('task1')
+firstTodo?.text.set('Learn signals deeply')
+
+// Sort while maintaining stable references
+todoList.sort((a, b) => a.text.localeCompare(b.text))
+```
+
+**Collection Signals (`new Collection`)**:
+
+```ts
+// Read-only derived arrays with memoization
+const completedTodos = new Collection(todoList, todo => 
+  todo.completed ? { ...todo, status: 'done' } : null
+)
+
+// Async transformations with cancellation
+const todoDetails = new Collection(todoList, async (todo, abort) => {
+  const response = await fetch(`/todos/${todo.id}`, { signal: abort })
+  return { ...todo, details: await response.json() }
+})
+
+// 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 (`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 +229,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
@@ -155,13 +246,13 @@ The library provides several layers of error handling:
 
 ```typescript
 // Robust async data fetching with error handling
-const apiData = createComputed(async (abort) => {
+const apiData = new Task(async (prev, 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
+    if (abort.aborted) return prev // Cancelled, not an error
     throw error // Real error
   }
 })
@@ -178,7 +269,7 @@ createEffect(() => {
 
 ### Performance Optimization Techniques
 
-1. **Batching Updates**: Use `batch()` for multiple synchronous updates
+1. **Batching Updates**: Use `batchSignalWrites()` 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
@@ -192,20 +283,20 @@ const user = createStore<{ id: number, name: string, email: string, age?: number
 })
 
 // Batch multiple updates to prevent intermediate states
-batch(() => {
+batchSignalWrites(() => {
   user.name.set('Alice Doe')
   user.age.set(30)
   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
+const userDisplay = new Memo(() => {
+  const { name, email } = user.get() // Gets entire object, will rerun also if age changes
   return `${name} <${email}>`
 })
 
 // Better: more granular dependencies
-const userDisplay = createComputed(() => {
+const userDisplay = new Memo(() => {
   return `${user.name.get()} <${user.email.get()}>` // Only depends on name/email
 })
 ```
@@ -244,18 +335,18 @@ The library is framework-agnostic but integrates well with:
 ### Building Reactive Data Structures
 ```typescript
 // Reactive list with computed properties
-const todos = createStore<Todo[]>([])
-const completedCount = createComputed(() => 
+const todos = new List<Todo[]>([])
+const completedCount = new Memo(() => 
   todos.get().filter(todo => todo.completed).length
 )
-const remainingCount = createComputed(() => 
+const remainingCount = new Memo(() => 
   todos.get().length - completedCount.get()
 )
 ```
 
 ### Reactive State Machines
 ```typescript
-const state = createState<'idle' | 'loading' | 'success' | 'error'>('idle')
+const state = new State<'idle' | 'loading' | 'success' | 'error'>('idle')
 const canRetry = () => state.get() === 'error'
 const isLoading = () => state.get() === 'loading'
 ```
@@ -305,6 +396,61 @@ on('userLogin', (data) => {
 eventBus.userLogin.set({ userId: 123, timestamp: Date.now() })
 ```
 
+### Reactive Data Processing Pipelines
+
+```typescript
+// Build complex data processing with Collections
+const rawData = new List([
+  { id: 1, value: 10, category: 'A' },
+  { id: 2, value: 20, category: 'B' },
+  { id: 3, value: 15, category: 'A' }
+])
+
+// Multi-step transformation pipeline
+const processedData = rawData
+  .deriveCollection(item => ({ ...item, doubled: item.value * 2 }))
+  .deriveCollection(item => ({ ...item, category: item.category.toLowerCase() }))
+
+const categoryTotals = new Collection(processedData, async (item, abort) => {
+  // Simulate async processing
+  await new Promise(resolve => setTimeout(resolve, 100))
+  return { category: item.category, contribution: item.doubled }
+})
+
+// Aggregation can be done with computed signals
+const totals = new Memo(() => {
+  const items = categoryTotals.get()
+  return items.reduce((acc, item) => {
+    acc[item.category] = (acc[item.category] || 0) + item.contribution
+    return acc
+  }, {} as Record<string, number>)
+})
+```
+
+### Stable Keys for Persistent Item Identity
+```typescript
+// Managing a list of items where order matters but identity persists
+const playlist = new List([
+  { id: 'track1', title: 'Song A', duration: 180 },
+  { id: 'track2', title: 'Song B', duration: 210 }
+], track => track.id)
+
+// Get persistent reference to a specific track
+const firstTrackSignal = playlist.byKey('track1')
+const firstTrack = firstTrackSignal?.get()
+
+// Reorder playlist while maintaining references
+playlist.sort((a, b) => a.title.localeCompare(b.title))
+// firstTrackSignal still points to the same track!
+
+// Insert new track at specific position
+playlist.splice(1, 0, { id: 'track3', title: 'Song C', duration: 195 })
+
+// Find current position of a track by its stable key
+const track1Position = playlist.indexOfKey('track1')
+const keyAtPosition2 = playlist.keyAt(2)
+```
+
 **Component ownership principle**: The component that emits events should own and initialize the event store. This creates clear boundaries and prevents coupling issues.
 
 **Why this pattern?**: By having the owning component (Component B) initialize all known events with `UNSET`, we get:

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