@zeix/cause-effect 0.16.1 → 0.17.1

package/.ai-context.md

@@ -9,8 +9,11 @@ Cause & Effect is a modern reactive state management library for JavaScript/Type
 ### 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
-- **Computed**: Read-only derived signals with automatic memoization, reducer-like capabilities and asyc handling
+- **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
 
 ### Key Principles
@@ -25,10 +28,14 @@ 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)
+│   │   ├── 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
@@ -46,18 +53,26 @@ 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')
+
+// Ref signals for external objects
+const elementRef = new Ref(document.getElementById('status'))
+const cacheRef = new Ref(new Map([['key', 'value']]))
 
 // 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 +83,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 +117,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 +137,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 +167,47 @@ 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 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() }
+})
+
+// Element collections for DOM reactivity
+const buttons = createElementCollection(document.body, 'button')
+const inputs = createElementCollection(form, 'input[type="text"]')
 ```
 
 ### 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 +225,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 +263,22 @@ 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
 ```
 
 ## Build and Development

package/.cursorrules

@@ -5,9 +5,12 @@ 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  
+- 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
-- Computed: createComputed() for derived/memoized values
+- List: new List() for arrays with stable keys and reactive items
+- Collection: Interface for reactive collections (DerivedCollection, ElementCollection)
 - Effects: createEffect() for side effects
 
 ## Code Style
@@ -30,9 +33,12 @@ TypeScript/JavaScript reactive state management library using signals pattern
 
 ## File Structure
 - src/signal.ts - Base signal types
-- src/state.ts - Mutable state signals  
-- src/store.ts - Object stores
-- src/computed.ts - Computed signals
+- 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

package/.github/copilot-instructions.md

@@ -7,17 +7,23 @@ 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()`)
+- **Ref**: Signal wrappers for external objects that change outside reactive system (`new Ref()`)
+- **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**: Interface for reactive collections (implemented by `DerivedCollection`)
 - **Effects**: Side effect handlers that react to signal changes (`createEffect()`)
 
 ## Key Files Structure
 
+- `src/classes/state.ts` - Mutable state signals
+- `src/classes/ref.ts` - Signal wrappers for external objects (DOM, Map, Set, etc.)
+- `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` - Collection interface and DerivedCollection implementation
+- `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 +39,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 +75,26 @@ 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')
+
+// Ref for external objects
+const elementRef = new Ref(document.getElementById('status'))
+const cacheRef = new Ref(new Map())
 
 // 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 +114,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 +136,43 @@ 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
+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 DerivedCollection(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