@zeix/cause-effect 0.17.1 → 0.17.2

package/test/effect.test.ts

@@ -223,7 +223,7 @@ describe('Effect', () => {
 
 			// Check if console.error was called with the error message
 			expect(mockConsoleError).toHaveBeenCalledWith(
-				'Effect callback error:',
+				'Error in effect callback:',
 				expect.any(Error),
 			)
 		} finally {
@@ -507,7 +507,7 @@ describe('Effect - Async with AbortSignal', () => {
 
 			// Should have logged the async error
 			expect(mockConsoleError).toHaveBeenCalledWith(
-				'Async effect error:',
+				'Error in async effect callback:',
 				expect.any(Error),
 			)
 		} finally {

package/test/list.test.ts

@@ -130,15 +130,15 @@ describe('list', () => {
 			expect(names.get()).toEqual(['Alice', 'Bob', 'Charlie'])
 		})
 
-		test('emits sort notification with new order', () => {
+		test('triggers HOOK_SORT with new order', () => {
 			const numbers = new List([3, 1, 2])
-			let sortNotification: readonly string[] = []
+			let order: readonly string[] | undefined
 			numbers.on('sort', sort => {
-				sortNotification = sort
+				order = sort
 			})
 			numbers.sort()
-			expect(sortNotification).toHaveLength(3)
-			expect(sortNotification).toEqual(['1', '2', '0'])
+			expect(order).toHaveLength(3)
+			expect(order).toEqual(['1', '2', '0'])
 		})
 
 		test('sort is reactive - watchers are notified', () => {
@@ -302,43 +302,43 @@ describe('list', () => {
 		})
 	})
 
-	describe('change notifications', () => {
-		test('emits add notifications', () => {
+	describe('Hooks', () => {
+		test('trigger HOOK_ADD when adding items', () => {
 			const numbers = new List([1, 2])
-			let arrayAddNotification: readonly string[] = []
+			let addedKeys: readonly string[] | undefined
 			let newArray: number[] = []
 			numbers.on('add', add => {
-				arrayAddNotification = add
+				addedKeys = add
 				newArray = numbers.get()
 			})
 			numbers.add(3)
-			expect(arrayAddNotification).toHaveLength(1)
+			expect(addedKeys).toHaveLength(1)
 			expect(newArray).toEqual([1, 2, 3])
 		})
 
-		test('emits change notifications when properties are modified', () => {
+		test('triggers HOOK_CHANGE when properties are modified', () => {
 			const items = new List([{ value: 10 }])
-			let arrayChangeNotification: readonly string[] = []
+			let changedKeys: readonly string[] | undefined
 			let newArray: { value: number }[] = []
 			items.on('change', change => {
-				arrayChangeNotification = change
+				changedKeys = change
 				newArray = items.get()
 			})
 			items.at(0)?.set({ value: 20 })
-			expect(arrayChangeNotification).toHaveLength(1)
+			expect(changedKeys).toHaveLength(1)
 			expect(newArray).toEqual([{ value: 20 }])
 		})
 
-		test('emits remove notifications when items are removed', () => {
+		test('triggers HOOK_REMOVE when items are removed', () => {
 			const items = new List([1, 2, 3])
-			let arrayRemoveNotification: readonly string[] = []
+			let removedKeys: readonly string[] | undefined
 			let newArray: number[] = []
 			items.on('remove', remove => {
-				arrayRemoveNotification = remove
+				removedKeys = remove
 				newArray = items.get()
 			})
 			items.remove(1)
-			expect(arrayRemoveNotification).toHaveLength(1)
+			expect(removedKeys).toHaveLength(1)
 			expect(newArray).toEqual([1, 3])
 		})
 	})
@@ -670,7 +670,7 @@ describe('list', () => {
 					(value: number) => value * 2,
 				)
 
-				let addedKeys: readonly string[] = []
+				let addedKeys: readonly string[] | undefined
 				doubled.on('add', keys => {
 					addedKeys = keys
 				})
@@ -685,7 +685,7 @@ describe('list', () => {
 					(value: number) => value * 2,
 				)
 
-				let removedKeys: readonly string[] = []
+				let removedKeys: readonly string[] | undefined
 				doubled.on('remove', keys => {
 					removedKeys = keys
 				})
@@ -700,7 +700,7 @@ describe('list', () => {
 					(value: number) => value * 2,
 				)
 
-				let sortedKeys: readonly string[] = []
+				let sortedKeys: readonly string[] | undefined
 				doubled.on('sort', keys => {
 					sortedKeys = keys
 				})
@@ -751,4 +751,232 @@ describe('list', () => {
 			})
 		})
 	})
+
+	describe('hooks system', () => {
+		test('List HOOK_WATCH is called when effect accesses list.get()', () => {
+			const numbers = new List([10, 20, 30])
+			let listHookWatchCalled = false
+			let listUnwatchCalled = false
+
+			// Set up HOOK_WATCH callback on the list itself
+			numbers.on('watch', () => {
+				listHookWatchCalled = true
+				return () => {
+					listUnwatchCalled = true
+				}
+			})
+
+			expect(listHookWatchCalled).toBe(false)
+
+			// Access list via list.get() - this should trigger list's HOOK_WATCH
+			let effectValue: number[] = []
+			const cleanup = createEffect(() => {
+				effectValue = numbers.get()
+			})
+
+			expect(listHookWatchCalled).toBe(true)
+			expect(effectValue).toEqual([10, 20, 30])
+			expect(listUnwatchCalled).toBe(false)
+
+			// Cleanup effect - should trigger unwatch
+			cleanup()
+			expect(listUnwatchCalled).toBe(true)
+		})
+
+		test('individual State signals have independent HOOK_WATCH when accessed via list.at().get()', () => {
+			const items = new List(['first', 'second'])
+			let firstItemHookCalled = false
+			let firstItemUnwatchCalled = false
+
+			// Get the first item signal and set up its HOOK_WATCH
+			// biome-ignore lint/style/noNonNullAssertion: test
+			const firstItemSignal = items.at(0)!
+			firstItemSignal.on('watch', () => {
+				firstItemHookCalled = true
+				return () => {
+					firstItemUnwatchCalled = true
+				}
+			})
+
+			expect(firstItemHookCalled).toBe(false)
+
+			// Access first item via signal.get() - this should trigger the State signal's HOOK_WATCH
+			let effectValue: string | undefined
+			const cleanup = createEffect(() => {
+				effectValue = firstItemSignal.get()
+			})
+
+			expect(firstItemHookCalled).toBe(true)
+			expect(effectValue).toBe('first')
+			expect(firstItemUnwatchCalled).toBe(false)
+
+			// Cleanup effect - should trigger State signal's unwatch
+			cleanup()
+			expect(firstItemUnwatchCalled).toBe(true)
+		})
+
+		test('State signal unwatch is called when item gets removed from list', () => {
+			const items = new List(['first', 'second'])
+			let firstItemUnwatchCalled = false
+
+			// Get the first item signal and set up its HOOK_WATCH
+			// biome-ignore lint/style/noNonNullAssertion: test
+			const firstItemSignal = items.at(0)!
+			firstItemSignal.on('watch', () => {
+				return () => {
+					firstItemUnwatchCalled = true
+				}
+			})
+
+			let effectValue: string | undefined
+			const cleanup = createEffect(() => {
+				effectValue = firstItemSignal.get()
+			})
+
+			expect(effectValue).toBe('first')
+			expect(firstItemUnwatchCalled).toBe(false)
+
+			// Remove the first item (index 0) - the State signal still exists but the list changed
+			items.remove(0)
+
+			// The State signal should still work (it's not automatically cleaned up)
+			expect(effectValue).toBe('first') // State signal retains its value
+			expect(firstItemUnwatchCalled).toBe(false) // Unwatch only happens when effect cleanup
+
+			// Cleanup the effect - this should call the State signal's unwatch
+			cleanup()
+			expect(firstItemUnwatchCalled).toBe(true)
+		})
+
+		test('new items added to list get independent State signals with their own hooks', () => {
+			const numbers = new List<number>([])
+
+			// Start with empty list - create effect that tries to access first item
+			let effectValue: number | undefined
+			const cleanup = createEffect(() => {
+				const firstItem = numbers.at(0)
+				effectValue = firstItem?.get()
+			})
+
+			// No items yet
+			expect(effectValue).toBe(undefined)
+
+			// Add first item
+			const key = numbers.add(42)
+			// biome-ignore lint/style/noNonNullAssertion: test
+			const newItemSignal = numbers.byKey(key)!
+
+			let newItemHookCalled = false
+			let newItemUnwatchCalled = false
+			newItemSignal.on('watch', () => {
+				newItemHookCalled = true
+				return () => {
+					newItemUnwatchCalled = true
+				}
+			})
+
+			// Create new effect to access the new item
+			let newEffectValue: number | undefined
+			const newCleanup = createEffect(() => {
+				newEffectValue = newItemSignal.get()
+			})
+
+			expect(newItemHookCalled).toBe(true)
+			expect(newEffectValue).toBe(42)
+			expect(newItemUnwatchCalled).toBe(false)
+
+			// Cleanup should trigger unwatch
+			newCleanup()
+			expect(newItemUnwatchCalled).toBe(true)
+
+			cleanup()
+		})
+
+		test('List length access triggers List HOOK_WATCH', () => {
+			const numbers = new List([1, 2, 3])
+			let listHookWatchCalled = false
+			let listUnwatchCalled = false
+
+			numbers.on('watch', () => {
+				listHookWatchCalled = true
+				return () => {
+					listUnwatchCalled = true
+				}
+			})
+
+			// Access via list.length - this should trigger list's HOOK_WATCH
+			let effectValue: number = 0
+			const cleanup = createEffect(() => {
+				effectValue = numbers.length
+			})
+
+			expect(listHookWatchCalled).toBe(true)
+			expect(effectValue).toBe(3)
+			expect(listUnwatchCalled).toBe(false)
+
+			cleanup()
+			expect(listUnwatchCalled).toBe(true)
+		})
+
+		test('exact scenario: List HOOK_WATCH triggered by list.at(0).get(), unwatch on item removal, restart on new item', () => {
+			const list = new List<number>([42])
+			let listHookWatchCallCount = 0
+			let listUnwatchCallCount = 0
+
+			// Set up List's HOOK_WATCH (this is triggered by list-level access like get() or length)
+			list.on('watch', () => {
+				listHookWatchCallCount++
+				return () => {
+					listUnwatchCallCount++
+				}
+			})
+
+			// Scenario 1: The list's HOOK_WATCH is called when an effect accesses the first item
+			// Note: list.at(0).get() accesses the State signal, not the list itself
+			// But if we access list.get() or list.length, it triggers the list's HOOK_WATCH
+			let effectValue: number | undefined
+			const cleanup1 = createEffect(() => {
+				// Access list first to trigger list HOOK_WATCH
+				const length = list.length
+				if (length > 0) {
+					effectValue = list.at(0)?.get()
+				} else {
+					effectValue = undefined
+				}
+			})
+
+			expect(listHookWatchCallCount).toBe(1) // List HOOK_WATCH called due to list.length access
+			expect(effectValue).toBe(42)
+
+			// Scenario 2: The list's unwatch callback is called when the only item with active subscription gets removed
+			list.remove(0)
+			// The effect should re-run due to list.length change and effectValue should now be undefined
+			expect(effectValue).toBe(undefined)
+
+			// The list unwatch is not called yet because the effect is still active (watching an empty list)
+			expect(listUnwatchCallCount).toBe(0)
+
+			// Clean up the first effect
+			cleanup1()
+			expect(listUnwatchCallCount).toBe(1) // Now unwatch is called
+
+			// Scenario 3: The list's HOOK_WATCH is restarted after a new item has been added that gets accessed by an effect
+			list.add(100)
+
+			const cleanup2 = createEffect(() => {
+				const length = list.length
+				if (length > 0) {
+					effectValue = list.at(0)?.get()
+				} else {
+					effectValue = undefined
+				}
+			})
+
+			expect(listHookWatchCallCount).toBe(2) // List HOOK_WATCH called again
+			expect(effectValue).toBe(100)
+
+			cleanup2()
+			expect(listUnwatchCallCount).toBe(2) // Second unwatch called
+		})
+	})
 })

package/test/ref.test.ts

@@ -1,6 +1,7 @@
 import { expect, mock, test } from 'bun:test'
 import { isRef, Ref } from '../src/classes/ref'
 import { createEffect } from '../src/effect'
+import { HOOK_WATCH } from '../src/system'
 
 test('Ref - basic functionality', () => {
 	const obj = { name: 'test', value: 42 }
@@ -225,3 +226,156 @@ test('Ref - handles complex nested objects', () => {
 
 	expect(userCount).toBe(2)
 })
+
+test('Ref - HOOK_WATCH lazy resource management', async () => {
+	// 1. Create Ref with current Date
+	const currentDate = new Date()
+	const ref = new Ref(currentDate)
+
+	let counter = 0
+	let intervalId: Timer | undefined
+
+	// 2. Add HOOK_WATCH callback that starts setInterval and returns cleanup
+	const cleanupHookCallback = ref.on(HOOK_WATCH, () => {
+		intervalId = setInterval(() => {
+			counter++
+		}, 10) // Use short interval for faster test
+
+		// Return cleanup function to clear interval
+		return () => {
+			if (intervalId) {
+				clearInterval(intervalId)
+				intervalId = undefined
+			}
+		}
+	})
+
+	// 3. 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()
+
+	// 4. Effect subscribes by .get()ting the signal value
+	const effectCleanup = createEffect(() => {
+		ref.get()
+	})
+
+	// 5. Counter should now be running
+	await new Promise(resolve => setTimeout(resolve, 50))
+	expect(counter).toBeGreaterThan(0)
+	expect(intervalId).toBeDefined()
+
+	// 6. Call effect cleanup, which should stop internal watcher and unsubscribe
+	effectCleanup()
+	const counterAfterStop = counter
+
+	// 7. 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
+
+	// Clean up hook callback registration
+	cleanupHookCallback()
+})
+
+test('Ref - HOOK_WATCH exception handling', async () => {
+	const ref = new Ref({ test: 'value' })
+
+	// Mock console.error to capture error logs
+	const originalError = console.error
+	const errorSpy = mock(() => {})
+	console.error = errorSpy
+
+	let successfulCallbackCalled = false
+	let throwingCallbackCalled = false
+
+	// Add callback that throws an exception
+	const cleanup1 = ref.on(HOOK_WATCH, () => {
+		throwingCallbackCalled = true
+		throw new Error('Test error in HOOK_WATCH callback')
+	})
+
+	// Add callback that works normally
+	const cleanup2 = ref.on(HOOK_WATCH, () => {
+		successfulCallbackCalled = true
+		return () => {
+			// cleanup function
+		}
+	})
+
+	// Subscribe to trigger HOOK_WATCH callbacks
+	const effectCleanup = createEffect(() => {
+		ref.get()
+	})
+
+	// Both callbacks should have been called despite the exception
+	expect(throwingCallbackCalled).toBe(true)
+	expect(successfulCallbackCalled).toBe(true)
+
+	// Error should have been logged
+	expect(errorSpy).toHaveBeenCalledWith(
+		'Error in effect callback:',
+		expect.any(Error),
+	)
+
+	// Cleanup
+	effectCleanup()
+	cleanup1()
+	cleanup2()
+	console.error = originalError
+})
+
+test('Ref - cleanup function exception handling', async () => {
+	const ref = new Ref({ test: 'value' })
+
+	// Mock console.error to capture error logs
+	const originalError = console.error
+	const errorSpy = mock(() => {})
+	console.error = errorSpy
+
+	let cleanup1Called = false
+	let cleanup2Called = false
+
+	// Add callbacks with cleanup functions, one throws
+	const hookCleanup1 = ref.on(HOOK_WATCH, () => {
+		return () => {
+			cleanup1Called = true
+			throw new Error('Test error in cleanup function')
+		}
+	})
+
+	const hookCleanup2 = ref.on(HOOK_WATCH, () => {
+		return () => {
+			cleanup2Called = true
+		}
+	})
+
+	// 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)
+	expect(cleanup2Called).toBe(true)
+
+	// Error should have been logged
+	expect(errorSpy).toHaveBeenCalledWith(
+		'Error in effect cleanup:',
+		expect.any(Error),
+	)
+
+	// Cleanup
+	hookCleanup1()
+	hookCleanup2()
+	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', () => {
@@ -156,7 +156,7 @@ describe('State', () => {
 					expect(error).toBeInstanceOf(TypeError)
 					expect(error.name).toBe('NullishSignalValueError')
 					expect(error.message).toBe(
-						'Nullish signal values are not allowed in state',
+						'Nullish signal values are not allowed in State',
 					)
 				}
 
@@ -169,7 +169,7 @@ describe('State', () => {
 					expect(error).toBeInstanceOf(TypeError)
 					expect(error.name).toBe('NullishSignalValueError')
 					expect(error.message).toBe(
-						'Nullish signal values are not allowed in state',
+						'Nullish signal values are not allowed in State',
 					)
 				}
 			})
@@ -213,22 +213,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', () => {
@@ -242,7 +242,7 @@ describe('State', () => {
 					expect(error).toBeInstanceOf(TypeError)
 					expect(error.name).toBe('InvalidCallbackError')
 					expect(error.message).toBe(
-						'Invalid state update callback null',
+						'Invalid State update callback null',
 					)
 				}
 			})
@@ -266,12 +266,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)