@zeix/cause-effect 0.17.1 → 0.17.2

package/.ai-context.md

@@ -279,6 +279,13 @@ const finalResults = processedItems.deriveCollection(item =>
 // 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/.github/copilot-instructions.md

@@ -173,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

package/CLAUDE.md

@@ -88,7 +88,7 @@ Key patterns:
 
 **Composite Architecture**: Shared foundation for Store and List
 - `Map<string, Signal>` for property/item signals
-- Event system for granular add/change/remove notifications
+- Hook system for granular add/change/remove notifications
 - Lazy signal creation and automatic cleanup
 
 ### Computed Signal Memoization Strategy
@@ -100,6 +100,101 @@ 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
+
+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:
+
+```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 () => {
+    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')
+})
+
+// Accessing collection item triggers source item hook
+createEffect(() => {
+  const value = doubled.at(0).get() // Triggers source item hook
+})
+```
+
+**Practical Use Cases**:
+- Event listeners that activate only when data is watched
+- Network connections established on-demand
+- Expensive computations that pause when not needed
+- 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
+
+This pattern enables **lazy resource allocation** - resources are only consumed when actually needed and automatically freed when no longer used.
+
 ## Advanced Patterns and Best Practices
 
 ### When to Use Each Signal Type

package/README.md

@@ -1,6 +1,6 @@
 # Cause & Effect
 
-Version 0.17.1
+Version 0.17.2
 
 **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.
 
@@ -168,7 +168,7 @@ settings.add('timeout', 5000)
 settings.remove('timeout')
 ```
 
-Change Notifications using the `.on()` method:
+Subscribe to hooks using the `.on()` method:
 
 ```js
 const user = createStore({ name: 'Alice', age: 30 })
@@ -177,17 +177,18 @@ 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 notifications:
+// 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 stop listening to notifications, call the returned cleanup functions:
+To unregister hooks, call the returned cleanup functions:
 
 ```js
-offAdd() // Stop listening to add notifications
-offChange() // Stop listening to change notifications
-offRemove() // Stop listening to remove notifications
+offAdd() // Stop listening to add hook
+offChange() // Stop listening to change hook
+offRemove() // Stop listening to remove hook
 ```
 
 ### List
@@ -398,6 +399,42 @@ cleanup() // Logs: 'Cleanup' and unsubscribes from signal `user`
 user.set({ name: 'Bob', age: 28 }) // Won't trigger the effect anymore
 ```
 
+### Resource Management with Hooks
+
+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:
+
+```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 () => {
+    console.log('Cleaning up API client...')
+    client.disconnect()
+  }
+})
+
+// Resource is created only when effect runs
+const cleanup = createEffect(() => {
+  console.log('API URL:', config.get().apiUrl)
+})
+
+// Resource is cleaned up when effect stops
+cleanup()
+```
+
+This pattern is ideal for:
+- Event listeners that should only be active when data is being watched
+- Network connections that can be lazily established
+- Expensive computations that should pause when not needed
+- External subscriptions (WebSocket, Server-Sent Events, etc.)
+
 ### resolve()
 
 Extract signal values:

package/archive/collection.ts

@@ -5,16 +5,17 @@ import type { Signal } from '../src/signal'
 import {
 	type Cleanup,
 	createWatcher,
-	emitNotification,
-	type Listener,
-	type Listeners,
-	type Notifications,
+	triggerHook,
+	type HookCallback,
+	type HookCallbacks,
+	type Hook,
 	notifyWatchers,
 	subscribeActiveWatcher,
 	trackSignalReads,
 	type Watcher,
+	UNSET,
 } from '../src/system'
-import { isAsyncFunction, isObjectOfType, isSymbol, UNSET } from '../src/util'
+import { isAsyncFunction, isObjectOfType, isSymbol } from '../src/util'
 import { type Computed, createComputed } from './computed'
 import type { List } from './list'
 
@@ -39,7 +40,7 @@ type Collection<T extends {}> = {
 	get(): T[]
 	keyAt(index: number): string | undefined
 	indexOfKey(key: string): number
-	on<K extends keyof Notifications>(type: K, listener: Listener<K>): Cleanup
+	on(type: Hook, callback: HookCallback): Cleanup
 	sort(compareFn?: (a: T, b: T) => number): void
 }
 
@@ -66,12 +67,7 @@ const createCollection = <T extends {}, O extends {}>(
 	callback: CollectionCallback<T, O>,
 ): Collection<T> => {
 	const watchers = new Set<Watcher>()
-	const listeners: Listeners = {
-		add: new Set<Listener<'add'>>(),
-		change: new Set<Listener<'change'>>(),
-		remove: new Set<Listener<'remove'>>(),
-		sort: new Set<Listener<'sort'>>(),
-	}
+	const hookCallbacks: HookCallbacks = {}
 	const signals = new Map<string, Signal<T>>()
 	const signalWatchers = new Map<string, Watcher>()
 
@@ -121,7 +117,7 @@ const createCollection = <T extends {}, O extends {}>(
 		const watcher = createWatcher(() =>
 			trackSignalReads(watcher, () => {
 				signal.get() // Subscribe to the signal
-				emitNotification(listeners.change, [key])
+				triggerHook(hookCallbacks.change, [key])
 			}),
 		)
 		watcher()
@@ -152,25 +148,29 @@ const createCollection = <T extends {}, O extends {}>(
 		addProperty(key)
 	}
 	origin.on('add', additions => {
+		if (!additions?.length) return
 		for (const key of additions) {
 			if (!signals.has(key)) addProperty(key)
 		}
 		notifyWatchers(watchers)
-		emitNotification(listeners.add, additions)
+		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)
-		emitNotification(listeners.remove, removals)
+		triggerHook(hookCallbacks.remove, removals)
 	})
 	origin.on('sort', newOrder => {
-		order = [...newOrder]
-		notifyWatchers(watchers)
-		emitNotification(listeners.sort, newOrder)
+		if (newOrder) {
+			order = [...newOrder]
+			notifyWatchers(watchers)
+			triggerHook(hookCallbacks.sort, newOrder)
+		}
 	})
 
 	// Get signal by key or index
@@ -247,16 +247,14 @@ const createCollection = <T extends {}, O extends {}>(
 				order = entries.map(([_, key]) => key)
 
 				notifyWatchers(watchers)
-				emitNotification(listeners.sort, order)
+				triggerHook(hookCallbacks.sort, order)
 			},
 		},
 		on: {
-			value: <K extends keyof Listeners>(
-				type: K,
-				listener: Listener<K>,
-			): Cleanup => {
-				listeners[type].add(listener)
-				return () => listeners[type].delete(listener)
+			value: (type: Hook, callback: HookCallback): Cleanup => {
+				hookCallbacks[type] ||= new Set()
+				hookCallbacks[type].add(callback)
+				return () => hookCallbacks[type]?.delete(callback)
 			},
 		},
 		length: {

package/archive/computed.ts

@@ -8,9 +8,11 @@ import {
 import {
 	createWatcher,
 	flushPendingReactions,
+	HOOK_CLEANUP,
 	notifyWatchers,
 	subscribeActiveWatcher,
 	trackSignalReads,
+	UNSET,
 	type Watcher,
 } from '../src/system'
 import {
@@ -18,7 +20,6 @@ import {
 	isAsyncFunction,
 	isFunction,
 	isObjectOfType,
-	UNSET,
 } from '../src/util'
 
 /* === Types === */
@@ -102,7 +103,7 @@ const createComputed = <T extends {}>(
 		if (watchers.size) notifyWatchers(watchers)
 		else watcher.stop()
 	})
-	watcher.onCleanup(() => {
+	watcher.on(HOOK_CLEANUP, () => {
 		controller?.abort()
 	})
 

package/archive/list.ts

@@ -10,13 +10,14 @@ import {
 	batchSignalWrites,
 	type Cleanup,
 	createWatcher,
-	emitNotification,
-	type Listener,
-	type Listeners,
-	type Notifications,
+	type Hook,
+	type HookCallback,
+	type HookCallbacks,
 	notifyWatchers,
 	subscribeActiveWatcher,
 	trackSignalReads,
+	triggerHook,
+	UNSET,
 	type Watcher,
 } from '../src/system'
 import {
@@ -26,7 +27,6 @@ import {
 	isRecord,
 	isString,
 	isSymbol,
-	UNSET,
 } from '../src/util'
 import {
 	type Collection,
@@ -63,7 +63,7 @@ type List<T extends {}> = {
 	update(fn: (value: T) => T): void
 	sort<U = T>(compareFn?: (a: U, b: U) => number): void
 	splice(start: number, deleteCount?: number, ...items: T[]): T[]
-	on<K extends keyof Notifications>(type: K, listener: Listener<K>): Cleanup
+	on(type: Hook, callback: HookCallback): Cleanup
 	remove(index: number): void
 }
 
@@ -90,12 +90,7 @@ const createList = <T extends {}>(
 	if (initialValue == null) throw new NullishSignalValueError('store')
 
 	const watchers = new Set<Watcher>()
-	const listeners: Listeners = {
-		add: new Set<Listener<'add'>>(),
-		change: new Set<Listener<'change'>>(),
-		remove: new Set<Listener<'remove'>>(),
-		sort: new Set<Listener<'sort'>>(),
-	}
+	const hookCallbacks: HookCallbacks = {}
 	const signals = new Map<string, MutableSignal<T>>()
 	const ownWatchers = new Map<string, Watcher>()
 
@@ -163,7 +158,7 @@ const createList = <T extends {}>(
 		const watcher = createWatcher(() => {
 			trackSignalReads(watcher, () => {
 				signal.get() // Subscribe to the signal
-				emitNotification(listeners.change, [key])
+				triggerHook(hookCallbacks.change, [key])
 			})
 		})
 		ownWatchers.set(key, watcher)
@@ -191,11 +186,11 @@ const createList = <T extends {}>(
 		signals.set(key, signal)
 		if (!order.includes(key)) order.push(key)
 		// @ts-expect-error ignore
-		if (listeners.change.size) addOwnWatcher(key, signal)
+		if (hookCallbacks.change?.size) addOwnWatcher(key, signal)
 
 		if (single) {
 			notifyWatchers(watchers)
-			emitNotification(listeners.add, [key])
+			triggerHook(hookCallbacks.add, [key])
 		}
 		return true
 	}
@@ -218,7 +213,7 @@ const createList = <T extends {}>(
 		if (single) {
 			order = order.filter(() => true) // Compact array
 			notifyWatchers(watchers)
-			emitNotification(listeners.remove, [key])
+			triggerHook(hookCallbacks.remove, [key])
 		}
 	}
 
@@ -233,9 +228,9 @@ const createList = <T extends {}>(
 			// Queue initial additions event to allow listeners to be added first
 			if (initialRun)
 				setTimeout(() => {
-					emitNotification(listeners.add, Object.keys(changes.add))
+					triggerHook(hookCallbacks.add, Object.keys(changes.add))
 				}, 0)
-			else emitNotification(listeners.add, Object.keys(changes.add))
+			else triggerHook(hookCallbacks.add, Object.keys(changes.add))
 		}
 
 		// Changes
@@ -249,7 +244,7 @@ const createList = <T extends {}>(
 					if (isMutableSignal(signal)) signal.set(value)
 					else throw new ReadonlySignalError(key, value)
 				}
-				emitNotification(listeners.change, Object.keys(changes.change))
+				triggerHook(hookCallbacks.change, Object.keys(changes.change))
 			})
 		}
 
@@ -257,7 +252,7 @@ const createList = <T extends {}>(
 		if (Object.keys(changes.remove).length) {
 			for (const key in changes.remove) removeProperty(key)
 			order = order.filter(() => true)
-			emitNotification(listeners.remove, Object.keys(changes.remove))
+			triggerHook(hookCallbacks.remove, Object.keys(changes.remove))
 		}
 
 		return changes.changed
@@ -401,7 +396,7 @@ const createList = <T extends {}>(
 				if (!isEqual(newOrder, order)) {
 					order = newOrder
 					notifyWatchers(watchers)
-					emitNotification(listeners.sort, order)
+					triggerHook(hookCallbacks.sort, order)
 				}
 			},
 		},
@@ -473,18 +468,16 @@ const createList = <T extends {}>(
 			},
 		},
 		on: {
-			value: <K extends keyof Notifications>(
-				type: K,
-				listener: Listener<K>,
-			): Cleanup => {
-				listeners[type].add(listener)
+			value: (type: Hook, callback: HookCallback): Cleanup => {
+				hookCallbacks[type] ||= new Set()
+				hookCallbacks[type].add(callback)
 				if (type === 'change' && !ownWatchers.size) {
 					for (const [key, signal] of signals)
 						addOwnWatcher(key, signal)
 				}
 				return () => {
-					listeners[type].delete(listener)
-					if (type === 'change' && !listeners.change.size) {
+					hookCallbacks[type]?.delete(callback)
+					if (type === 'change' && !hookCallbacks.change?.size) {
 						if (ownWatchers.size) {
 							for (const watcher of ownWatchers.values())
 								watcher.stop()

package/archive/memo.ts

@@ -10,9 +10,10 @@ import {
 	notifyWatchers,
 	subscribeActiveWatcher,
 	trackSignalReads,
+	UNSET,
 	type Watcher,
 } from '../src/system'
-import { isObjectOfType, isSyncFunction, UNSET } from '../src/util'
+import { isObjectOfType, isSyncFunction } from '../src/util'
 
 /* === Types === */
 

package/archive/state.ts

@@ -3,9 +3,10 @@ import { InvalidCallbackError, NullishSignalValueError } from '../src/errors'
 import {
 	notifyWatchers,
 	subscribeActiveWatcher,
+	UNSET,
 	type Watcher,
 } from '../src/system'
-import { isFunction, isObjectOfType, UNSET } from '../src/util'
+import { isFunction, isObjectOfType } from '../src/util'
 
 /* === Types === */
 

package/archive/store.ts

@@ -10,22 +10,17 @@ import {
 	batchSignalWrites,
 	type Cleanup,
 	createWatcher,
-	emitNotification,
-	type Listener,
-	type Listeners,
-	type Notifications,
+	type HookCallback,
+	type HookCallbacks,
+	type Hook,
 	notifyWatchers,
 	subscribeActiveWatcher,
 	trackSignalReads,
 	type Watcher,
-} from '../src/system'
-import {
-	isFunction,
-	isObjectOfType,
-	isRecord,
-	isSymbol,
 	UNSET,
-} from '../src/util'
+	triggerHook,
+} from '../src/system'
+import { isFunction, isObjectOfType, isRecord, isSymbol } from '../src/util'
 import { isComputed } from './computed'
 import { createList, isList, type List } from './list'
 import { createState, isState, type State } from './state'
@@ -62,7 +57,7 @@ type Store<T extends UnknownRecord> = {
 	sort<U = T[Extract<keyof T, string>]>(
 		compareFn?: (a: U, b: U) => number,
 	): void
-	on<K extends keyof Notifications>(type: K, listener: Listener<K>): Cleanup
+	on(type: Hook, callback: HookCallback): Cleanup
 	remove<K extends Extract<keyof T, string>>(key: K): void
 }
 
@@ -92,11 +87,7 @@ const createStore = <T extends UnknownRecord>(initialValue: T): Store<T> => {
 	if (initialValue == null) throw new NullishSignalValueError('store')
 
 	const watchers = new Set<Watcher>()
-	const listeners: Omit<Listeners, 'sort'> = {
-		add: new Set<Listener<'add'>>(),
-		change: new Set<Listener<'change'>>(),
-		remove: new Set<Listener<'remove'>>(),
-	}
+	const hookCallbacks: HookCallbacks = {}
 	const signals = new Map<
 		string,
 		MutableSignal<T[Extract<keyof T, string>] & {}>
@@ -131,7 +122,7 @@ const createStore = <T extends UnknownRecord>(initialValue: T): Store<T> => {
 		const watcher = createWatcher(() => {
 			trackSignalReads(watcher, () => {
 				signal.get() // Subscribe to the signal
-				emitNotification(listeners.change, [key])
+				triggerHook(hookCallbacks.change, [key])
 			})
 		})
 		ownWatchers.set(key, watcher)
@@ -159,11 +150,11 @@ const createStore = <T extends UnknownRecord>(initialValue: T): Store<T> => {
 		// Set internal states
 		// @ts-expect-error non-matching signal types
 		signals.set(key, signal)
-		if (listeners.change.size) addOwnWatcher(key, signal)
+		if (hookCallbacks.change?.size) addOwnWatcher(key, signal)
 
 		if (single) {
 			notifyWatchers(watchers)
-			emitNotification(listeners.add, [key])
+			triggerHook(hookCallbacks.add, [key])
 		}
 		return true
 	}
@@ -183,7 +174,7 @@ const createStore = <T extends UnknownRecord>(initialValue: T): Store<T> => {
 
 		if (single) {
 			notifyWatchers(watchers)
-			emitNotification(listeners.remove, [key])
+			triggerHook(hookCallbacks.remove, [key])
 		}
 	}
 
@@ -201,9 +192,9 @@ const createStore = <T extends UnknownRecord>(initialValue: T): Store<T> => {
 			// Queue initial additions event to allow listeners to be added first
 			if (initialRun)
 				setTimeout(() => {
-					emitNotification(listeners.add, Object.keys(changes.add))
+					triggerHook(hookCallbacks.add, Object.keys(changes.add))
 				}, 0)
-			else emitNotification(listeners.add, Object.keys(changes.add))
+			else triggerHook(hookCallbacks.add, Object.keys(changes.add))
 		}
 
 		// Changes
@@ -220,14 +211,14 @@ const createStore = <T extends UnknownRecord>(initialValue: T): Store<T> => {
 					if (isMutableSignal(signal)) signal.set(value)
 					else throw new ReadonlySignalError(key, value)
 				}
-				emitNotification(listeners.change, Object.keys(changes.change))
+				triggerHook(hookCallbacks.change, Object.keys(changes.change))
 			})
 		}
 
 		// Removals
 		if (Object.keys(changes.remove).length) {
 			for (const key in changes.remove) removeProperty(key)
-			emitNotification(listeners.remove, Object.keys(changes.remove))
+			triggerHook(hookCallbacks.remove, Object.keys(changes.remove))
 		}
 
 		return changes.changed
@@ -296,19 +287,17 @@ const createStore = <T extends UnknownRecord>(initialValue: T): Store<T> => {
 			},
 		},
 		on: {
-			value: <K extends keyof Omit<Listeners, 'sort'>>(
-				type: K,
-				listener: Listener<K>,
-			): Cleanup => {
-				listeners[type].add(listener)
+			value: (type: Hook, callback: HookCallback): Cleanup => {
+				hookCallbacks[type] ||= new Set()
+				hookCallbacks[type].add(callback)
 				if (type === 'change' && !ownWatchers.size) {
 					for (const [key, signal] of signals)
 						// @ts-expect-error ignore
 						addOwnWatcher(key, signal)
 				}
 				return () => {
-					listeners[type].delete(listener)
-					if (type === 'change' && !listeners.change.size) {
+					hookCallbacks[type]?.delete(callback)
+					if (type === 'change' && !hookCallbacks.change?.size) {
 						if (ownWatchers.size) {
 							for (const watcher of ownWatchers.values())
 								watcher.stop()