@zeix/cause-effect 0.17.2 → 0.17.3

package/.ai-context.md

@@ -280,12 +280,18 @@ const finalResults = processedItems.deriveCollection(item =>
 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
+// Resource management with watch callbacks
+const endpoint = new State('https://api.example.com', {
+  watched: () => {
+    console.log('Setting up API client...')
+    const resource = createResource(endpoint.get())
+  }, 
+  unwatched: () => {
+    console.log('Cleaning up API client...')
+    resource.cleanup()
+  }
 })
+
 ```
 
 ## Build and Development

package/.github/copilot-instructions.md

@@ -175,7 +175,7 @@ const activeUserSummaries = users
 
 ## 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.
+All signals support `watched` and `unwatched` callbacks in signal configuration (optional second parameter) 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

package/.zed/settings.json

@@ -0,0 +1,3 @@
+{
+  "project_name": "Cause & Effect"
+}

package/CLAUDE.md

@@ -78,19 +78,14 @@ Key patterns:
 
 **Store signals** (`createStore`): Transform objects into reactive data structures
 - Each property becomes its own signal via Proxy
-- Built on `Composite` class for signal management
+- Lazy signal creation and automatic cleanup
 - Dynamic property addition/removal with proper reactivity
 
 **List signals** (`new List`): Arrays with stable keys and reactive items
-- Maintains stable keys that survive sorting and reordering
+- Maintains stable keys that survive sorting and splicing
 - 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
-- Hook system for granular add/change/remove notifications
-- Lazy signal creation and automatic cleanup
-
 ### Computed Signal Memoization Strategy
 
 Computed signals implement smart memoization:
@@ -100,84 +95,29 @@ Computed signals implement smart memoization:
 - **Error Handling**: Preserves error states and prevents cascade failures
 - **Reducer Capabilities**: Access to previous value enables state accumulation and transitions
 
-## Resource Management with Watch Hooks
+## Resource Management with Watch Callbacks
 
-All signals support the `watch` hook for lazy resource management. Resources are allocated only when a signal is first accessed by an effect and automatically cleaned up when no effects are watching:
+All signals support the `watched` and `unwatched` callbacks for lazy resource management. Resources are allocated only when a signal is first accessed by an effect and automatically cleaned up when no effects are watching:
 
 ```typescript
-// Basic watch hook pattern
-const config = new State({ apiUrl: 'https://api.example.com' })
-
-config.on('watch', () => {
-  console.log('Setting up API client...')
-  const client = new ApiClient(config.get().apiUrl)
-  
-  return () => {
+// Basic watch callbacks pattern
+const config = new State({ apiUrl: 'https://api.example.com' }, {
+  watched: () => {
+    console.log('Setting up API client...')
+    const client = new ApiClient(config.get().apiUrl)
+  },
+  unwatched: () => {
     console.log('Cleaning up API client...')
     client.disconnect()
   }
 })
 
 // Resource is only created when effect runs
-createEffect(() => {
-  console.log('API URL:', config.get().apiUrl) // Triggers hook
-})
-```
-
-**Store Watch Hooks**: Monitor entire store or nested properties
-
-```typescript
-const database = createStore({ host: 'localhost', port: 5432 })
-
-// Watch entire store - triggers when any property accessed
-database.on('watch', () => {
-  console.log('Database connection needed')
-  const connection = connect(database.host.get(), database.port.get())
-  return () => connection.close()
-})
-
-// Watch specific property
-database.host.on('watch', () => {
-  console.log('Host property being watched')
-  return () => console.log('Host watching stopped')
-})
-```
-
-**List Watch Hooks**: Two-tier system for collection and item resources
-
-```typescript
-const items = new List(['apple', 'banana'])
-
-// List-level resource (entire collection)
-items.on('watch', () => {
-  console.log('List observer started')
-  return () => console.log('List observer stopped')
-})
-
-// Item-level resource (individual items)
-const firstItem = items.at(0)
-firstItem.on('watch', () => {
-  console.log('First item being watched')
-  return () => console.log('First item watch stopped')
-})
-```
-
-**Collection Watch Hooks**: Propagate to source List items
-
-```typescript
-const numbers = new List([1, 2, 3])
-const doubled = numbers.deriveCollection(x => x * 2)
-
-// Set up source item hook
-numbers.at(0).on('watch', () => {
-  console.log('Source item accessed through collection')
-  return () => console.log('Source item no longer watched')
+const cleanup = createEffect(() => {
+  console.log('API URL:', config.get().apiUrl) // Triggers watched callback
 })
 
-// Accessing collection item triggers source item hook
-createEffect(() => {
-  const value = doubled.at(0).get() // Triggers source item hook
-})
+cleanup() // Triggers unwatched callback
 ```
 
 **Practical Use Cases**:
@@ -187,11 +127,10 @@ createEffect(() => {
 - External subscriptions (WebSocket, Server-Sent Events)
 - Database connections tied to data access patterns
 
-**Hook Lifecycle**:
-1. First effect accesses signal → `watch` hook callback executed
-2. Hook callback can return cleanup function
-3. Last effect stops watching → cleanup function called
-4. New effect accesses signal → hook callback executed again
+**Watch Lifecycle**:
+1. First effect accesses signal → `watched` callback executed
+3. Last effect stops watching → `unwatched` callback executed
+4. New effect accesses signal → `watched` callback executed again
 
 This pattern enables **lazy resource allocation** - resources are only consumed when actually needed and automatically freed when no longer used.
 

package/README.md

@@ -1,8 +1,8 @@
 # Cause & Effect
 
-Version 0.17.2
+Version 0.17.3
 
-**Cause & Effect** is a tiny (~5kB gzipped), dependency-free reactive state library for JavaScript. It uses fine-grained signals so derived values and side effects update automatically when their dependencies change.
+**Cause & Effect** is a tiny (~5kB gzipped), dependency-free reactive state management library for JavaScript. It uses fine-grained signals so derived values and side effects update automatically when their dependencies change.
 
 ## What is Cause & Effect?
 
@@ -159,36 +159,23 @@ user.preferences.theme.set('light')
 createEffect(() => console.log('User:', user.get()))
 ```
 
-Dynamic properties using the `add()` and `remove()` methods:
+Iterator for keys using reactive `.keys()` method to observe structural changes:
 
 ```js
-const settings = createStore({ autoSave: true })
-
-settings.add('timeout', 5000)
-settings.remove('timeout')
+for (const key of user.keys()) {
+  console.log(key)
+}
 ```
 
-Subscribe to hooks using the `.on()` method:
+Access items by key using `.byKey()` or via direct property access like `user.name` (enabled by the Proxy `createStore()` returns).
 
-```js
-const user = createStore({ name: 'Alice', age: 30 })
-
-const offChange = user.on('change', changed => console.log(changed))
-const offAdd = user.on('add', added => console.log(added))
-const offRemove = user.on('remove', removed => console.log(removed))
-
-// These will trigger the respective hooks:
-user.add('email', 'alice@example.com') // Logs: "Added properties: ['email']"
-user.age.set(31)                       // Logs: "Changed properties: ['age']"
-user.remove('email')                   // Logs: "Removed properties: ['email']"
-```
-
-To unregister hooks, call the returned cleanup functions:
+Dynamic properties using the `.add()` and `.remove()` methods:
 
 ```js
-offAdd() // Stop listening to add hook
-offChange() // Stop listening to change hook
-offRemove() // Stop listening to remove hook
+const settings = createStore({ autoSave: true })
+
+settings.add('timeout', 5000)
+settings.remove('timeout')
 ```
 
 ### List
@@ -207,6 +194,8 @@ items.splice(1, 1, 'orange')
 items.sort()
 ```
 
+Access items by key using `.byKey()` or by index using `.at()`. `.indexOfKey()` returns the current index of an item in the list, while `.keyAt()` returns the key of an item at a given position.
+
 Keys are stable across reordering:
 
 ```js
@@ -218,7 +207,7 @@ console.log(items.byKey(key))     // 'orange'
 console.log(items.indexOfKey(key)) // current index
 ```
 
-Lists have `.add()`, `.remove()` and `.on()` methods like stores. In addition, they have `.sort()` and `.splice()` methods. But unlike stores, deeply nested properties in items are not converted to individual signals.
+Lists have `.keys()`, `.add()`, and `.remove()` methods like stores. Additionally, they have `.sort()`, `.splice()`, and a reactive `.length` property. But unlike stores, deeply nested properties in items are not converted to individual signals. Lists have no Proxy layer and don't support direct property access like `items[0].name`.
 
 ### Collection
 
@@ -399,22 +388,19 @@ cleanup() // Logs: 'Cleanup' and unsubscribes from signal `user`
 user.set({ name: 'Bob', age: 28 }) // Won't trigger the effect anymore
 ```
 
-### Resource Management with Hooks
+### Resource Management with Watch Callbacks
 
-All signals support the `watch` hook for lazy resource management. Resources are only allocated when the signal is first accessed by an effect, and automatically cleaned up when no effects are watching:
+All signals support a options object with `watched` and `unwatched` callbacks for lazy resource management. Resources are only allocated when the signal is first accessed by an effect, and automatically cleaned up when no effects are watching:
 
 ```js
 import { State, createEffect } from '@zeix/cause-effect'
 
-const config = new State({ apiUrl: 'https://api.example.com' })
-
-// Set up lazy resource management
-config.on('watch', () => {
-  console.log('Setting up API client...')
-  const client = new ApiClient(config.get().apiUrl)
-  
-  // Return cleanup function
-  return () => {
+const config = new State({ apiUrl: 'https://api.example.com' }, {
+  watched: () => {
+    console.log('Setting up API client...')
+    const client = new ApiClient(config.get().apiUrl)
+  },
+  unwatched: () => {
     console.log('Cleaning up API client...')
     client.disconnect()
   }

package/archive/benchmark.ts

@@ -159,7 +159,6 @@ const benchmarkFactory = async () => {
 	const memoryStores = await measureMemory('Factory Memory Usage', () => {
 		const tempStores = []
 		for (let i = 0; i < ITERATIONS; i++)
-			// @ts-expect-error ignore
 			tempStores.push(createFactoryStore({ ...testData, id: i }))
 		return tempStores
 	})
@@ -226,7 +225,6 @@ const benchmarkFactoryList = async () => {
 		const tempLists = []
 		for (let i = 0; i < ITERATIONS; i++) {
 			tempLists.push(
-				// @ts-expect-error ignore
 				createFactoryList([
 					...testListData.map(item => ({
 						...item,
@@ -305,7 +303,6 @@ const benchmarkDirectClassList = async () => {
 			const tempLists = []
 			for (let i = 0; i < ITERATIONS; i++) {
 				tempLists.push(
-					// @ts-expect-error ignore
 					new List([
 						...testListData.map(item => ({
 							...item,
@@ -375,7 +372,6 @@ const benchmarkClass = async () => {
 	const memoryStores = await measureMemory('Class Memory Usage', () => {
 		const tempStores = []
 		for (let i = 0; i < ITERATIONS; i++)
-			// @ts-expect-error ignore
 			tempStores.push(createClassStore({ ...testData, id: i }))
 		return tempStores
 	})
@@ -436,7 +432,6 @@ const benchmarkDirectClass = async () => {
 		() => {
 			const tempStores = []
 			for (let i = 0; i < ITERATIONS; i++)
-				// @ts-expect-error ignore
 				tempStores.push(new BaseStore({ ...testData, id: i }))
 			return tempStores
 		},

package/archive/collection.ts

@@ -3,17 +3,11 @@ import { match } from '../src/match'
 import { resolve } from '../src/resolve'
 import type { Signal } from '../src/signal'
 import {
-	type Cleanup,
 	createWatcher,
-	triggerHook,
-	type HookCallback,
-	type HookCallbacks,
-	type Hook,
 	notifyWatchers,
 	subscribeActiveWatcher,
-	trackSignalReads,
-	type Watcher,
 	UNSET,
+	type Watcher,
 } from '../src/system'
 import { isAsyncFunction, isObjectOfType, isSymbol } from '../src/util'
 import { type Computed, createComputed } from './computed'
@@ -40,7 +34,6 @@ type Collection<T extends {}> = {
 	get(): T[]
 	keyAt(index: number): string | undefined
 	indexOfKey(key: string): number
-	on(type: Hook, callback: HookCallback): Cleanup
 	sort(compareFn?: (a: T, b: T) => number): void
 }
 
@@ -67,7 +60,6 @@ const createCollection = <T extends {}, O extends {}>(
 	callback: CollectionCallback<T, O>,
 ): Collection<T> => {
 	const watchers = new Set<Watcher>()
-	const hookCallbacks: HookCallbacks = {}
 	const signals = new Map<string, Signal<T>>()
 	const signalWatchers = new Map<string, Watcher>()
 
@@ -114,64 +106,23 @@ const createCollection = <T extends {}, O extends {}>(
 		// Set internal states
 		signals.set(key, signal)
 		if (!order.includes(key)) order.push(key)
-		const watcher = createWatcher(() =>
-			trackSignalReads(watcher, () => {
+		const watcher = createWatcher(
+			() => {
 				signal.get() // Subscribe to the signal
-				triggerHook(hookCallbacks.change, [key])
-			}),
+			},
+			() => {},
 		)
 		watcher()
 		signalWatchers.set(key, watcher)
 		return true
 	}
 
-	// Remove nested signal and effect
-	const removeProperty = (key: string) => {
-		// Remove signal for key
-		const ok = signals.delete(key)
-		if (!ok) return
-
-		// Clean up internal states
-		const index = order.indexOf(key)
-		if (index >= 0) order.splice(index, 1)
-		const watcher = signalWatchers.get(key)
-		if (watcher) {
-			watcher.stop()
-			signalWatchers.delete(key)
-		}
-	}
-
 	// Initialize properties
 	for (let i = 0; i < origin.length; i++) {
 		const key = origin.keyAt(i)
 		if (!key) continue
 		addProperty(key)
 	}
-	origin.on('add', additions => {
-		if (!additions?.length) return
-		for (const key of additions) {
-			if (!signals.has(key)) addProperty(key)
-		}
-		notifyWatchers(watchers)
-		triggerHook(hookCallbacks.add, additions)
-	})
-	origin.on('remove', removals => {
-		if (!removals?.length) return
-		for (const key of Object.keys(removals)) {
-			if (!signals.has(key)) continue
-			removeProperty(key)
-		}
-		order = order.filter(() => true) // Compact array
-		notifyWatchers(watchers)
-		triggerHook(hookCallbacks.remove, removals)
-	})
-	origin.on('sort', newOrder => {
-		if (newOrder) {
-			order = [...newOrder]
-			notifyWatchers(watchers)
-			triggerHook(hookCallbacks.sort, newOrder)
-		}
-	})
 
 	// Get signal by key or index
 	const getSignal = (prop: string): Signal<T> | undefined => {
@@ -247,14 +198,6 @@ const createCollection = <T extends {}, O extends {}>(
 				order = entries.map(([_, key]) => key)
 
 				notifyWatchers(watchers)
-				triggerHook(hookCallbacks.sort, order)
-			},
-		},
-		on: {
-			value: (type: Hook, callback: HookCallback): Cleanup => {
-				hookCallbacks[type] ||= new Set()
-				hookCallbacks[type].add(callback)
-				return () => hookCallbacks[type]?.delete(callback)
 			},
 		},
 		length: {

package/archive/composite.ts

@@ -0,0 +1,85 @@
+import type { DiffResult, UnknownRecord } from '../src/diff'
+import { guardMutableSignal } from '../src/errors'
+import type { Signal } from '../src/signal'
+import { batch } from '../src/system'
+
+/* === Class Definitions === */
+
+class Composite<T extends UnknownRecord, S extends Signal<T[keyof T] & {}>> {
+	signals = new Map<string, S>()
+	#validate: <K extends keyof T & string>(
+		key: K,
+		value: unknown,
+	) => value is T[K] & {}
+	#create: <V extends T[keyof T] & {}>(value: V) => S
+
+	constructor(
+		values: T,
+		validate: <K extends keyof T & string>(
+			key: K,
+			value: unknown,
+		) => value is T[K] & {},
+		create: <V extends T[keyof T] & {}>(value: V) => S,
+	) {
+		this.#validate = validate
+		this.#create = create
+		this.change({
+			add: values,
+			change: {},
+			remove: {},
+			changed: true,
+		})
+	}
+
+	add<K extends keyof T & string>(key: K, value: T[K]): boolean {
+		if (!this.#validate(key, value)) return false
+
+		this.signals.set(key, this.#create(value))
+		return true
+	}
+
+	remove<K extends keyof T & string>(key: K): boolean {
+		return this.signals.delete(key)
+	}
+
+	change(changes: DiffResult): boolean {
+		// Additions
+		if (Object.keys(changes.add).length) {
+			for (const key in changes.add)
+				this.add(
+					key as Extract<keyof T, string>,
+					changes.add[key] as T[Extract<keyof T, string>] & {},
+				)
+		}
+
+		// Changes
+		if (Object.keys(changes.change).length) {
+			batch(() => {
+				for (const key in changes.change) {
+					const value = changes.change[key]
+					if (!this.#validate(key as keyof T & string, value))
+						continue
+
+					const signal = this.signals.get(key)
+					if (guardMutableSignal(`list item "${key}"`, value, signal))
+						signal.set(value)
+				}
+			})
+		}
+
+		// Removals
+		if (Object.keys(changes.remove).length) {
+			for (const key in changes.remove)
+				this.remove(key as keyof T & string)
+		}
+
+		return changes.changed
+	}
+
+	clear(): boolean {
+		this.signals.clear()
+		return true
+	}
+}
+
+export { Composite }

package/archive/computed.ts

@@ -7,11 +7,9 @@ import {
 } from '../src/errors'
 import {
 	createWatcher,
-	flushPendingReactions,
-	HOOK_CLEANUP,
+	flush,
 	notifyWatchers,
 	subscribeActiveWatcher,
-	trackSignalReads,
 	UNSET,
 	type Watcher,
 } from '../src/system'
@@ -97,19 +95,14 @@ const createComputed = <T extends {}>(
 		}
 
 	// Own watcher: called when notified from sources (push)
-	const watcher = createWatcher(() => {
-		dirty = true
-		controller?.abort()
-		if (watchers.size) notifyWatchers(watchers)
-		else watcher.stop()
-	})
-	watcher.on(HOOK_CLEANUP, () => {
-		controller?.abort()
-	})
-
-	// Called when requested by dependencies (pull)
-	const compute = () =>
-		trackSignalReads(watcher, () => {
+	const watcher = createWatcher(
+		() => {
+			dirty = true
+			controller?.abort()
+			if (watchers.size) notifyWatchers(watchers)
+			else watcher.stop()
+		},
+		() => {
 			if (computing) throw new CircularDependencyError('computed')
 			changed = false
 			if (isAsyncFunction(callback)) {
@@ -121,7 +114,7 @@ const createComputed = <T extends {}>(
 					() => {
 						computing = false
 						controller = undefined
-						compute() // Retry computation with updated state
+						watcher.run() // Retry computation with updated state
 					},
 					{
 						once: true,
@@ -144,7 +137,11 @@ const createComputed = <T extends {}>(
 			else if (null == result || UNSET === result) nil()
 			else ok(result)
 			computing = false
-		})
+		},
+	)
+	watcher.onCleanup(() => {
+		controller?.abort()
+	})
 
 	const computed: Record<PropertyKey, unknown> = {}
 	Object.defineProperties(computed, {
@@ -154,8 +151,8 @@ const createComputed = <T extends {}>(
 		get: {
 			value: (): T => {
 				subscribeActiveWatcher(watchers)
-				flushPendingReactions()
-				if (dirty) compute()
+				flush()
+				if (dirty) watcher.run()
 				if (error) throw error
 				return value
 			},