@zeix/cause-effect 0.17.1 → 0.17.3

package/test/list.test.ts

@@ -1,11 +1,11 @@
 import { describe, expect, test } from 'bun:test'
 import {
 	createEffect,
-	List,
 	createStore,
 	isCollection,
 	isList,
 	isStore,
+	List,
 	Memo,
 	State,
 	UNSET,
@@ -130,17 +130,6 @@ describe('list', () => {
 			expect(names.get()).toEqual(['Alice', 'Bob', 'Charlie'])
 		})
 
-		test('emits sort notification with new order', () => {
-			const numbers = new List([3, 1, 2])
-			let sortNotification: readonly string[] = []
-			numbers.on('sort', sort => {
-				sortNotification = sort
-			})
-			numbers.sort()
-			expect(sortNotification).toHaveLength(3)
-			expect(sortNotification).toEqual(['1', '2', '0'])
-		})
-
 		test('sort is reactive - watchers are notified', () => {
 			const numbers = new List([3, 1, 2])
 			let effectCount = 0
@@ -302,47 +291,6 @@ describe('list', () => {
 		})
 	})
 
-	describe('change notifications', () => {
-		test('emits add notifications', () => {
-			const numbers = new List([1, 2])
-			let arrayAddNotification: readonly string[] = []
-			let newArray: number[] = []
-			numbers.on('add', add => {
-				arrayAddNotification = add
-				newArray = numbers.get()
-			})
-			numbers.add(3)
-			expect(arrayAddNotification).toHaveLength(1)
-			expect(newArray).toEqual([1, 2, 3])
-		})
-
-		test('emits change notifications when properties are modified', () => {
-			const items = new List([{ value: 10 }])
-			let arrayChangeNotification: readonly string[] = []
-			let newArray: { value: number }[] = []
-			items.on('change', change => {
-				arrayChangeNotification = change
-				newArray = items.get()
-			})
-			items.at(0)?.set({ value: 20 })
-			expect(arrayChangeNotification).toHaveLength(1)
-			expect(newArray).toEqual([{ value: 20 }])
-		})
-
-		test('emits remove notifications when items are removed', () => {
-			const items = new List([1, 2, 3])
-			let arrayRemoveNotification: readonly string[] = []
-			let newArray: number[] = []
-			items.on('remove', remove => {
-				arrayRemoveNotification = remove
-				newArray = items.get()
-			})
-			items.remove(1)
-			expect(arrayRemoveNotification).toHaveLength(1)
-			expect(newArray).toEqual([1, 3])
-		})
-	})
-
 	describe('edge cases', () => {
 		test('handles empty lists correctly', () => {
 			const empty = new List([])
@@ -482,7 +430,10 @@ describe('list', () => {
 				])
 
 				const enrichedUsers = users.deriveCollection(
-					async (user, abort: AbortSignal) => {
+					async (
+						user: { id: number; name: string },
+						abort: AbortSignal,
+					) => {
 						// Simulate API call
 						await new Promise(resolve => setTimeout(resolve, 10))
 						if (abort.aborted) throw new Error('Aborted')
@@ -663,54 +614,6 @@ describe('list', () => {
 			})
 		})
 
-		describe('collection event handling', () => {
-			test('emits add events when source adds items', () => {
-				const numbers = new List([1, 2])
-				const doubled = numbers.deriveCollection(
-					(value: number) => value * 2,
-				)
-
-				let addedKeys: readonly string[] = []
-				doubled.on('add', keys => {
-					addedKeys = keys
-				})
-
-				numbers.add(3)
-				expect(addedKeys).toHaveLength(1)
-			})
-
-			test('emits remove events when source removes items', () => {
-				const numbers = new List([1, 2, 3])
-				const doubled = numbers.deriveCollection(
-					(value: number) => value * 2,
-				)
-
-				let removedKeys: readonly string[] = []
-				doubled.on('remove', keys => {
-					removedKeys = keys
-				})
-
-				numbers.remove(1)
-				expect(removedKeys).toHaveLength(1)
-			})
-
-			test('emits sort events when source is sorted', () => {
-				const numbers = new List([3, 1, 2])
-				const doubled = numbers.deriveCollection(
-					(value: number) => value * 2,
-				)
-
-				let sortedKeys: readonly string[] = []
-				doubled.on('sort', keys => {
-					sortedKeys = keys
-				})
-
-				numbers.sort()
-				expect(sortedKeys).toHaveLength(3)
-				expect(doubled.get()).toEqual([2, 4, 6]) // Sorted and doubled
-			})
-		})
-
 		describe('edge cases', () => {
 			test('handles empty list derivation', () => {
 				const empty = new List<number>([])
@@ -751,4 +654,61 @@ describe('list', () => {
 			})
 		})
 	})
+
+	describe('Watch Callbacks', () => {
+		test('List watched callback is called when effect accesses list.get()', () => {
+			let linkWatchedCalled = false
+			let listUnwatchedCalled = false
+			const numbers = new List([10, 20, 30], {
+				watched: () => {
+					linkWatchedCalled = true
+				},
+				unwatched: () => {
+					listUnwatchedCalled = true
+				},
+			})
+
+			expect(linkWatchedCalled).toBe(false)
+
+			// Access list via list.get() - this should trigger list's watched callback
+			let effectValue: number[] = []
+			const cleanup = createEffect(() => {
+				effectValue = numbers.get()
+			})
+
+			expect(linkWatchedCalled).toBe(true)
+			expect(effectValue).toEqual([10, 20, 30])
+			expect(listUnwatchedCalled).toBe(false)
+
+			// Cleanup effect - should trigger unwatch
+			cleanup()
+			expect(listUnwatchedCalled).toBe(true)
+		})
+
+		test('List length access triggers List watched callback', () => {
+			let listWatchedCalled = false
+			let listUnwatchedCalled = false
+			const numbers = new List([1, 2, 3], {
+				watched: () => {
+					listWatchedCalled = true
+				},
+				unwatched: () => {
+					listUnwatchedCalled = true
+				},
+			})
+
+			// Access via list.length - this should trigger list's watched callback
+			let effectValue: number = 0
+			const cleanup = createEffect(() => {
+				effectValue = numbers.length
+			})
+
+			expect(listWatchedCalled).toBe(true)
+			expect(effectValue).toBe(3)
+			expect(listUnwatchedCalled).toBe(false)
+
+			cleanup()
+			expect(listUnwatchedCalled).toBe(true)
+		})
+	})
 })

package/test/ref.test.ts

@@ -34,8 +34,8 @@ test('Ref - validation with guard function', () => {
 	const validConfig = { host: 'localhost', port: 3000 }
 	const invalidConfig = { host: 'localhost' } // missing port
 
-	expect(() => new Ref(validConfig, isConfig)).not.toThrow()
-	expect(() => new Ref(invalidConfig, isConfig)).toThrow()
+	expect(() => new Ref(validConfig, { guard: isConfig })).not.toThrow()
+	expect(() => new Ref(invalidConfig, { guard: isConfig })).toThrow()
 })
 
 test('Ref - reactive subscriptions', () => {
@@ -225,3 +225,129 @@ test('Ref - handles complex nested objects', () => {
 
 	expect(userCount).toBe(2)
 })
+
+test('Ref - options.watched lazy resource management', async () => {
+	// 1. Create Ref with current Date
+	let counter = 0
+	let intervalId: Timer | undefined
+	const ref = new Ref(new Date(), {
+		watched: () => {
+			intervalId = setInterval(() => {
+				counter++
+			}, 10)
+		},
+		unwatched: () => {
+			if (intervalId) {
+				clearInterval(intervalId)
+				intervalId = undefined
+			}
+		},
+	})
+
+	// 2. Counter should not be running yet
+	expect(counter).toBe(0)
+
+	// Wait a bit to ensure counter doesn't increment
+	await new Promise(resolve => setTimeout(resolve, 50))
+	expect(counter).toBe(0)
+	expect(intervalId).toBeUndefined()
+
+	// 3. Effect subscribes by .get()ting the signal value
+	const effectCleanup = createEffect(() => {
+		ref.get()
+	})
+
+	// 4. Counter should now be running
+	await new Promise(resolve => setTimeout(resolve, 50))
+	expect(counter).toBeGreaterThan(0)
+	expect(intervalId).toBeDefined()
+
+	// 5. Call effect cleanup, which should stop internal watcher and unsubscribe
+	effectCleanup()
+	const counterAfterStop = counter
+
+	// 6. Ref signal should call #unwatch() and counter should stop incrementing
+	await new Promise(resolve => setTimeout(resolve, 50))
+	expect(counter).toBe(counterAfterStop) // Counter should not have incremented
+	expect(intervalId).toBeUndefined() // Interval should be cleared
+})
+
+test('Ref - options.watched exception handling', async () => {
+	const ref = new Ref(
+		{ test: 'value' },
+		{
+			watched: () => {
+				throwingCallbackCalled = true
+				throw new Error('Test error in watched callback')
+			},
+		},
+	)
+
+	// Mock console.error to capture error logs
+	const originalError = console.error
+	const errorSpy = mock(() => {})
+	console.error = errorSpy
+
+	let throwingCallbackCalled = false
+
+	// Subscribe to trigger watched callback
+	const effectCleanup = createEffect(() => {
+		ref.get()
+	})
+
+	// Both callbacks should have been called despite the exception
+	expect(throwingCallbackCalled).toBe(true)
+
+	// Error should have been logged
+	expect(errorSpy).toHaveBeenCalledWith(
+		'Error in effect callback:',
+		expect.any(Error),
+	)
+
+	// Cleanup
+	effectCleanup()
+	console.error = originalError
+})
+
+test('Ref - options.unwatched exception handling', async () => {
+	const ref = new Ref(
+		{ test: 'value' },
+		{
+			watched: () => {},
+			unwatched: () => {
+				cleanup1Called = true
+				throw new Error('Test error in cleanup function')
+			},
+		},
+	)
+
+	// Mock console.error to capture error logs
+	const originalError = console.error
+	const errorSpy = mock(() => {})
+	console.error = errorSpy
+
+	let cleanup1Called = false
+
+	// Subscribe and then unsubscribe to trigger cleanup
+	const effectCleanup = createEffect(() => {
+		ref.get()
+	})
+
+	// Unsubscribe to trigger cleanup functions
+	effectCleanup()
+
+	// Wait a bit for cleanup to complete
+	await new Promise(resolve => setTimeout(resolve, 10))
+
+	// Both cleanup functions should have been called despite the exception
+	expect(cleanup1Called).toBe(true)
+
+	// Error should have been logged
+	expect(errorSpy).toHaveBeenCalledWith(
+		'Error in effect cleanup:',
+		expect.any(Error),
+	)
+
+	// Cleanup
+	console.error = originalError
+})

package/test/state.test.ts

@@ -125,12 +125,12 @@ describe('State', () => {
 				expect(() => {
 					// @ts-expect-error - Testing invalid input
 					new State(null)
-				}).toThrow('Nullish signal values are not allowed in state')
+				}).toThrow('Nullish signal values are not allowed in State')
 
 				expect(() => {
 					// @ts-expect-error - Testing invalid input
 					new State(undefined)
-				}).toThrow('Nullish signal values are not allowed in state')
+				}).toThrow('Nullish signal values are not allowed in State')
 			})
 
 			test('should throw NullishSignalValueError when newValue is nullish in set()', () => {
@@ -139,12 +139,12 @@ describe('State', () => {
 				expect(() => {
 					// @ts-expect-error - Testing invalid input
 					state.set(null)
-				}).toThrow('Nullish signal values are not allowed in state')
+				}).toThrow('Nullish signal values are not allowed in State')
 
 				expect(() => {
 					// @ts-expect-error - Testing invalid input
 					state.set(undefined)
-				}).toThrow('Nullish signal values are not allowed in state')
+				}).toThrow('Nullish signal values are not allowed in State')
 			})
 
 			test('should throw specific error types for nullish values', () => {
@@ -154,10 +154,8 @@ describe('State', () => {
 					expect(true).toBe(false) // Should not reach here
 				} catch (error) {
 					expect(error).toBeInstanceOf(TypeError)
-					expect(error.name).toBe('NullishSignalValueError')
-					expect(error.message).toBe(
-						'Nullish signal values are not allowed in state',
-					)
+					expect((error as Error).name).toBe('NullishSignalValueError')
+					expect((error as Error).message).toBe('Nullish signal values are not allowed in State')
 				}
 
 				const state = new State(42)
@@ -167,10 +165,8 @@ describe('State', () => {
 					expect(true).toBe(false) // Should not reach here
 				} catch (error) {
 					expect(error).toBeInstanceOf(TypeError)
-					expect(error.name).toBe('NullishSignalValueError')
-					expect(error.message).toBe(
-						'Nullish signal values are not allowed in state',
-					)
+					expect((error as Error).name).toBe('NullishSignalValueError')
+					expect((error as Error).message).toBe('Nullish signal values are not allowed in State')
 				}
 			})
 
@@ -213,22 +209,22 @@ describe('State', () => {
 				expect(() => {
 					// @ts-expect-error - Testing invalid input
 					state.update(null)
-				}).toThrow('Invalid state update callback null')
+				}).toThrow('Invalid State update callback null')
 
 				expect(() => {
 					// @ts-expect-error - Testing invalid input
 					state.update(undefined)
-				}).toThrow('Invalid state update callback undefined')
+				}).toThrow('Invalid State update callback undefined')
 
 				expect(() => {
 					// @ts-expect-error - Testing invalid input
 					state.update('not a function')
-				}).toThrow('Invalid state update callback "not a function"')
+				}).toThrow('Invalid State update callback "not a function"')
 
 				expect(() => {
 					// @ts-expect-error - Testing invalid input
 					state.update(42)
-				}).toThrow('Invalid state update callback 42')
+				}).toThrow('Invalid State update callback 42')
 			})
 
 			test('should throw specific error type for non-function updater', () => {
@@ -240,10 +236,8 @@ describe('State', () => {
 					expect(true).toBe(false) // Should not reach here
 				} catch (error) {
 					expect(error).toBeInstanceOf(TypeError)
-					expect(error.name).toBe('InvalidCallbackError')
-					expect(error.message).toBe(
-						'Invalid state update callback null',
-					)
+					expect((error as Error).name).toBe('InvalidCallbackError')
+					expect((error as Error).message).toBe('Invalid State update callback null')
 				}
 			})
 
@@ -266,12 +260,12 @@ describe('State', () => {
 				expect(() => {
 					// @ts-expect-error - Testing invalid return value
 					state.update(() => null)
-				}).toThrow('Nullish signal values are not allowed in state')
+				}).toThrow('Nullish signal values are not allowed in State')
 
 				expect(() => {
 					// @ts-expect-error - Testing invalid return value
 					state.update(() => undefined)
-				}).toThrow('Nullish signal values are not allowed in state')
+				}).toThrow('Nullish signal values are not allowed in State')
 
 				// State should remain unchanged after error
 				expect(state.get()).toBe(42)

package/test/store.test.ts

@@ -225,114 +225,6 @@ describe('store', () => {
 		})
 	})
 
-	describe('change tracking and notifications', () => {
-		test('emits add notifications', () => {
-			let addNotification: readonly string[] = []
-			const user = createStore<{ name: string; email?: string }>({
-				name: 'John',
-			})
-			user.on('add', add => {
-				addNotification = add
-			})
-			user.add('email', 'john@example.com')
-			expect(addNotification).toContain('email')
-		})
-
-		test('emits change notifications when properties are modified', () => {
-			const user = createStore({ name: 'John' })
-			let changeNotification: readonly string[] = []
-			user.on('change', change => {
-				changeNotification = change
-			})
-			user.name.set('Jane')
-			expect(changeNotification).toContain('name')
-		})
-
-		test('emits change notifications for nested property changes', () => {
-			const user = createStore({
-				preferences: {
-					theme: 'light',
-				},
-			})
-			let changeNotification: readonly string[] = []
-			user.on('change', change => {
-				changeNotification = change
-			})
-			user.preferences.theme.set('dark')
-			expect(changeNotification).toContain('preferences')
-		})
-
-		test('emits remove notifications when properties are removed', () => {
-			const user = createStore({
-				name: 'John',
-				email: 'john@example.com',
-			})
-			let removeNotification: readonly string[] = []
-			user.on('remove', remove => {
-				removeNotification = remove
-			})
-			user.remove('email')
-			expect(removeNotification).toContain('email')
-		})
-
-		test('set() correctly handles mixed changes, additions, and removals', () => {
-			const user = createStore<{
-				name: string
-				email?: string
-				preferences: { theme?: string }
-				age?: number
-			}>({
-				name: 'John',
-				email: 'john@example.com',
-				preferences: {
-					theme: 'light',
-				},
-			})
-
-			let changeNotification: readonly string[] = []
-			let addNotification: readonly string[] = []
-			let removeNotification: readonly string[] = []
-
-			user.on('change', change => {
-				changeNotification = change
-			})
-			user.on('add', add => {
-				addNotification = add
-			})
-			user.on('remove', remove => {
-				removeNotification = remove
-			})
-
-			user.set({
-				name: 'Jane',
-				preferences: {
-					theme: 'dark',
-				},
-				age: 30,
-			})
-
-			expect(changeNotification).toContain('name')
-			expect(changeNotification).toContain('preferences')
-			expect(addNotification).toContain('age')
-			expect(removeNotification).toContain('email')
-		})
-
-		test('notification listeners can be removed', () => {
-			const user = createStore({ name: 'John' })
-			let notificationCount = 0
-			const listener = () => {
-				notificationCount++
-			}
-			const off = user.on('change', listener)
-			user.name.set('Jane')
-			expect(notificationCount).toBe(1)
-
-			off()
-			user.name.set('Bob')
-			expect(notificationCount).toBe(1)
-		})
-	})
-
 	describe('reactivity', () => {
 		test('store-level get() is reactive', () => {
 			const user = createStore({
@@ -660,4 +552,105 @@ describe('store', () => {
 			expect(config.database.port.get()).toBe(5432)
 		})
 	})
+
+	describe('Watch Callbacks', () => {
+		test('Root store watched callback triggered only by direct store access', async () => {
+			let rootStoreCounter = 0
+			let intervalId: Timer | undefined
+			const store = createStore(
+				{
+					user: {
+						name: 'John',
+						profile: {
+							email: 'john@example.com',
+						},
+					},
+				},
+				{
+					watched: () => {
+						intervalId = setInterval(() => {
+							rootStoreCounter++
+						}, 10)
+					},
+					unwatched: () => {
+						if (intervalId) {
+							clearInterval(intervalId)
+							intervalId = undefined
+						}
+					},
+				},
+			)
+
+			expect(rootStoreCounter).toBe(0)
+			await new Promise(resolve => setTimeout(resolve, 50))
+			expect(rootStoreCounter).toBe(0)
+
+			// Access nested property directly - should NOT trigger root watched callback
+			const nestedEffectCleanup = createEffect(() => {
+				store.user.name.get()
+			})
+
+			await new Promise(resolve => setTimeout(resolve, 50))
+			expect(rootStoreCounter).toBe(0) // Still 0 - nested access doesn't trigger root
+			expect(intervalId).toBeUndefined()
+
+			// Access root store directly - should trigger watched callback
+			const rootEffectCleanup = createEffect(() => {
+				store.get()
+			})
+
+			await new Promise(resolve => setTimeout(resolve, 50))
+			expect(rootStoreCounter).toBeGreaterThan(0) // Now triggered
+			expect(intervalId).toBeDefined()
+
+			// Cleanup
+			rootEffectCleanup()
+			nestedEffectCleanup()
+			await new Promise(resolve => setTimeout(resolve, 50))
+			expect(intervalId).toBeUndefined()
+		})
+
+		test('Store property addition/removal affects store watched callback', async () => {
+			let usersStoreCounter = 0
+			const store = createStore(
+				{
+					users: {} as Record<string, { name: string }>,
+				},
+				{
+					watched: () => {
+						usersStoreCounter++
+					},
+					unwatched: () => {
+						usersStoreCounter--
+					},
+				},
+			)
+
+			expect(usersStoreCounter).toBe(0)
+
+			// Watch the entire store
+			const usersEffect = createEffect(() => {
+				store.get()
+			})
+			expect(usersStoreCounter).toBe(1)
+
+			// Add a user - this modifies the users store content but doesn't affect watched callback
+			store.users.add('user1', { name: 'Alice' })
+			expect(usersStoreCounter).toBe(1) // Still 1
+
+			// Watch a specific user property - this doesn't trigger users store watched callback
+			const userEffect = createEffect(() => {
+				store.users.user1?.name.get()
+			})
+			expect(usersStoreCounter).toBe(1) // Still 1
+
+			// Cleanup user effect
+			userEffect()
+			expect(usersStoreCounter).toBe(1) // Still active due to usersEffect
+
+			// Cleanup users effect
+			usersEffect()
+			expect(usersStoreCounter).toBe(0) // Now cleaned up
+		})
+	})
 })

package/test/util/dependency-graph.ts

@@ -124,7 +124,7 @@ function makeDependentRows(
 ): Computed<number>[][] {
 	let prevRow = sources
 	const rand = new Random('seed')
-	const rows = []
+	const rows: Computed<number>[][] = []
 	for (let l = 0; l < numRows; l++) {
 		const row = makeRow(
 			prevRow,
@@ -135,7 +135,7 @@ function makeDependentRows(
 			l,
 			rand,
 		)
-		rows.push(row as never)
+		rows.push(row)
 		prevRow = row
 	}
 	return rows

package/tsconfig.build.json

@@ -0,0 +1,11 @@
+{
+	"extends": "./tsconfig.json",
+	"compilerOptions": {
+		"noEmit": false,
+		"declaration": true,
+		"declarationDir": "./types",
+		"emitDeclarationOnly": true,
+	},
+	"include": ["./index.ts", "./src/**/*.ts"],
+	"exclude": ["node_modules", "types", "test", "archive"],
+}