@zeix/cause-effect 0.17.1 → 0.17.3

package/.ai-context.md

@@ -279,6 +279,19 @@ 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 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

@@ -173,6 +173,10 @@ const activeUserSummaries = users
   .filter(Boolean)
 ```
 
+## Resource Management
+
+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
 2. Use proper TypeScript types and generics

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
-- Event system for granular add/change/remove notifications
-- Lazy signal creation and automatic cleanup
-
 ### Computed Signal Memoization Strategy
 
 Computed signals implement smart memoization:
@@ -100,6 +95,45 @@ 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 Callbacks
+
+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 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
+const cleanup = createEffect(() => {
+  console.log('API URL:', config.get().apiUrl) // Triggers watched callback
+})
+
+cleanup() // Triggers unwatched callback
+```
+
+**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
+
+**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.
+
 ## Advanced Patterns and Best Practices
 
 ### When to Use Each Signal Type

package/README.md

@@ -1,8 +1,8 @@
 # Cause & Effect
 
-Version 0.17.1
+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,35 +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)
+}
 ```
 
-Change Notifications using the `.on()` method:
-
-```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))
+Access items by key using `.byKey()` or via direct property access like `user.name` (enabled by the Proxy `createStore()` returns).
 
-// These will trigger the respective notifications:
-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:
+Dynamic properties using the `.add()` and `.remove()` methods:
 
 ```js
-offAdd() // Stop listening to add notifications
-offChange() // Stop listening to change notifications
-offRemove() // Stop listening to remove notifications
+const settings = createStore({ autoSave: true })
+
+settings.add('timeout', 5000)
+settings.remove('timeout')
 ```
 
 ### List
@@ -206,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
@@ -217,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
 
@@ -398,6 +388,39 @@ cleanup() // Logs: 'Cleanup' and unsubscribes from signal `user`
 user.set({ name: 'Bob', age: 28 }) // Won't trigger the effect anymore
 ```
 
+### Resource Management with Watch Callbacks
+
+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' }, {
+  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 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/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,18 +3,13 @@ import { match } from '../src/match'
 import { resolve } from '../src/resolve'
 import type { Signal } from '../src/signal'
 import {
-	type Cleanup,
 	createWatcher,
-	emitNotification,
-	type Listener,
-	type Listeners,
-	type Notifications,
 	notifyWatchers,
 	subscribeActiveWatcher,
-	trackSignalReads,
+	UNSET,
 	type Watcher,
 } 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 +34,6 @@ 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
 	sort(compareFn?: (a: T, b: T) => number): void
 }
 
@@ -66,12 +60,6 @@ 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 signals = new Map<string, Signal<T>>()
 	const signalWatchers = new Map<string, Watcher>()
 
@@ -118,60 +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
-				emitNotification(listeners.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 => {
-		for (const key of additions) {
-			if (!signals.has(key)) addProperty(key)
-		}
-		notifyWatchers(watchers)
-		emitNotification(listeners.add, additions)
-	})
-	origin.on('remove', removals => {
-		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)
-	})
-	origin.on('sort', newOrder => {
-		order = [...newOrder]
-		notifyWatchers(watchers)
-		emitNotification(listeners.sort, newOrder)
-	})
 
 	// Get signal by key or index
 	const getSignal = (prop: string): Signal<T> | undefined => {
@@ -247,16 +198,6 @@ const createCollection = <T extends {}, O extends {}>(
 				order = entries.map(([_, key]) => key)
 
 				notifyWatchers(watchers)
-				emitNotification(listeners.sort, order)
-			},
-		},
-		on: {
-			value: <K extends keyof Listeners>(
-				type: K,
-				listener: Listener<K>,
-			): Cleanup => {
-				listeners[type].add(listener)
-				return () => listeners[type].delete(listener)
 			},
 		},
 		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,10 +7,10 @@ import {
 } from '../src/errors'
 import {
 	createWatcher,
-	flushPendingReactions,
+	flush,
 	notifyWatchers,
 	subscribeActiveWatcher,
-	trackSignalReads,
+	UNSET,
 	type Watcher,
 } from '../src/system'
 import {
@@ -18,7 +18,6 @@ import {
 	isAsyncFunction,
 	isFunction,
 	isObjectOfType,
-	UNSET,
 } from '../src/util'
 
 /* === Types === */
@@ -96,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.onCleanup(() => {
-		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)) {
@@ -120,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,
@@ -143,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, {
@@ -153,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
 			},