@zeix/cause-effect 0.17.0 → 0.17.2

package/.ai-context.md

@@ -9,10 +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
 - **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
+- **Collection**: Interface for reactive array-like collections (implemented by DerivedCollection)
 - **Effect**: Side effect handlers that react to signal changes
 
 ### Key Principles
@@ -29,9 +30,10 @@ 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  # Read-only derived arrays (Collection)
+│   │   ├── 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)
@@ -55,6 +57,10 @@ 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 })
 
@@ -181,15 +187,19 @@ const firstTodo = todoList.byKey('task1')
 firstTodo?.completed.set(true) // Mark completed
 
 // Collections for read-only derived data
-const completedTodos = new Collection(todoList, todo => 
+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 Collection(todoList, async (todo, abort) => {
+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
@@ -265,6 +275,17 @@ const processedItems = items.deriveCollection(item => ({
 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
+})
 ```
 
 ## Build and Development

package/.cursorrules

@@ -6,9 +6,11 @@ TypeScript/JavaScript reactive state management library using signals pattern
 ## 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
 
 ## Code Style
@@ -31,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

@@ -8,18 +8,20 @@ Cause & Effect is a reactive state management library for JavaScript/TypeScript
 
 - **Signals**: Base reactive primitives with `.get()` method
 - **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()`)
 - **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()`)
+- **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` - Read-only derived arrays with memoization
+- `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/effect.ts` - Effect system
@@ -77,6 +79,10 @@ 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 })
 
@@ -145,7 +151,6 @@ function isSignal<T extends {}>(value: unknown): value is Signal<T>
 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'
 
@@ -156,7 +161,7 @@ const users = new List([
 ], user => user.id) // Uses user.id as stable key
 
 // Collections derived from lists
-const userProfiles = new Collection(users, user => ({
+const userProfiles = new DerivedCollection(users, user => ({
   ...user,
   displayName: `${user.name} (ID: ${user.id})`
 }))
@@ -168,6 +173,10 @@ const activeUserSummaries = users
   .filter(Boolean)
 ```
 
+## Resource Management
+
+All signals support `.on('watch', callback)` for lazy resource allocation. Resources are only created when signals are accessed by effects and automatically cleaned up when no longer watched.
+
 ## When suggesting code:
 1. Follow the established patterns for signal creation and usage
 2. Use proper TypeScript types and generics