@zeix/cause-effect 0.17.0 → 0.17.2

package/test/computed.test.ts

@@ -10,6 +10,7 @@ import {
 	Task,
 	UNSET,
 } from '../index.ts'
+import { HOOK_WATCH } from '../src/system'
 
 /* === Utility Functions === */
 
@@ -429,49 +430,49 @@ describe('Computed', () => {
 			expect(() => {
 				// @ts-expect-error - Testing invalid input
 				new Memo(null)
-			}).toThrow('Invalid memo callback null')
+			}).toThrow('Invalid Memo callback null')
 
 			expect(() => {
 				// @ts-expect-error - Testing invalid input
 				new Memo(undefined)
-			}).toThrow('Invalid memo callback undefined')
+			}).toThrow('Invalid Memo callback undefined')
 
 			expect(() => {
 				// @ts-expect-error - Testing invalid input
 				new Memo(42)
-			}).toThrow('Invalid memo callback 42')
+			}).toThrow('Invalid Memo callback 42')
 
 			expect(() => {
 				// @ts-expect-error - Testing invalid input
 				new Memo('not a function')
-			}).toThrow('Invalid memo callback "not a function"')
+			}).toThrow('Invalid Memo callback "not a function"')
 
 			expect(() => {
 				// @ts-expect-error - Testing invalid input
 				new Memo({ not: 'a function' })
-			}).toThrow('Invalid memo callback {"not":"a function"}')
+			}).toThrow('Invalid Memo callback {"not":"a function"}')
 
 			expect(() => {
 				// @ts-expect-error - Testing invalid input
 				new Memo((_a: unknown, _b: unknown, _c: unknown) => 42)
-			}).toThrow('Invalid memo callback (_a, _b, _c) => 42')
+			}).toThrow('Invalid Memo callback (_a, _b, _c) => 42')
 
 			expect(() => {
 				// @ts-expect-error - Testing invalid input
 				new Memo(async (_a: unknown, _b: unknown) => 42)
-			}).toThrow('Invalid memo callback async (_a, _b) => 42')
+			}).toThrow('Invalid Memo callback async (_a, _b) => 42')
 
 			expect(() => {
 				// @ts-expect-error - Testing invalid input
 				new Task((_a: unknown) => 42)
-			}).toThrow('Invalid task callback (_a) => 42')
+			}).toThrow('Invalid Task callback (_a) => 42')
 		})
 
 		test('should throw NullishSignalValueError when initialValue is null', () => {
 			expect(() => {
 				// @ts-expect-error - Testing invalid input
 				new Memo(() => 42, null)
-			}).toThrow('Nullish signal values are not allowed in memo')
+			}).toThrow('Nullish signal values are not allowed in Memo')
 		})
 
 		test('should throw specific error types for invalid inputs', () => {
@@ -482,7 +483,7 @@ describe('Computed', () => {
 			} catch (error) {
 				expect(error).toBeInstanceOf(TypeError)
 				expect(error.name).toBe('InvalidCallbackError')
-				expect(error.message).toBe('Invalid memo callback null')
+				expect(error.message).toBe('Invalid Memo callback null')
 			}
 
 			try {
@@ -493,7 +494,7 @@ describe('Computed', () => {
 				expect(error).toBeInstanceOf(TypeError)
 				expect(error.name).toBe('NullishSignalValueError')
 				expect(error.message).toBe(
-					'Nullish signal values are not allowed in memo',
+					'Nullish signal values are not allowed in Memo',
 				)
 			}
 		})
@@ -866,4 +867,260 @@ describe('Computed', () => {
 			expect(accumulator.get()).toBe(115) // Final accumulated value
 		})
 	})
+
+	describe('HOOK_WATCH - Lazy Resource Management', () => {
+		test('Memo - should manage external resources lazily', async () => {
+			const source = new State(1)
+			let counter = 0
+			let intervalId: Timer | undefined
+
+			// Create memo that depends on source
+			const computed = new Memo((oldValue: number) => {
+				return source.get() * 2 + (oldValue || 0)
+			}, 0)
+
+			// Add HOOK_WATCH callback that starts interval
+			const cleanupHookCallback = computed.on(HOOK_WATCH, () => {
+				intervalId = setInterval(() => {
+					counter++
+				}, 10) // Fast interval for testing
+
+				// Return cleanup function
+				return () => {
+					if (intervalId) {
+						clearInterval(intervalId)
+						intervalId = undefined
+					}
+				}
+			})
+
+			// Counter should not be running yet
+			expect(counter).toBe(0)
+			await wait(50)
+			expect(counter).toBe(0)
+			expect(intervalId).toBeUndefined()
+
+			// Effect subscribes to computed, triggering HOOK_WATCH
+			const effectCleanup = createEffect(() => {
+				computed.get()
+			})
+
+			// Counter should now be running
+			await wait(50)
+			expect(counter).toBeGreaterThan(0)
+			expect(intervalId).toBeDefined()
+
+			// Stop effect, should cleanup resources
+			effectCleanup()
+			const counterAfterStop = counter
+
+			// Counter should stop incrementing
+			await wait(50)
+			expect(counter).toBe(counterAfterStop)
+			expect(intervalId).toBeUndefined()
+
+			// Cleanup
+			cleanupHookCallback()
+		})
+
+		test('Task - should manage external resources lazily', async () => {
+			const source = new State('initial')
+			let counter = 0
+			let intervalId: Timer | undefined
+
+			// Create task that depends on source
+			const computed = new Task(
+				async (oldValue: string, abort: AbortSignal) => {
+					const value = source.get()
+					await wait(10) // Simulate async work
+
+					if (abort.aborted) throw new Error('Aborted')
+
+					return `${value}-processed-${oldValue || 'none'}`
+				},
+				'default',
+			)
+
+			// Add HOOK_WATCH callback
+			const cleanupHookCallback = computed.on(HOOK_WATCH, () => {
+				intervalId = setInterval(() => {
+					counter++
+				}, 10)
+
+				return () => {
+					if (intervalId) {
+						clearInterval(intervalId)
+						intervalId = undefined
+					}
+				}
+			})
+
+			// Counter should not be running yet
+			expect(counter).toBe(0)
+			await wait(50)
+			expect(counter).toBe(0)
+			expect(intervalId).toBeUndefined()
+
+			// Effect subscribes to computed
+			const effectCleanup = createEffect(() => {
+				computed.get()
+			})
+
+			// Wait for async computation and counter to start
+			await wait(100)
+			expect(counter).toBeGreaterThan(0)
+			expect(intervalId).toBeDefined()
+
+			// Stop effect
+			effectCleanup()
+			const counterAfterStop = counter
+
+			// Counter should stop incrementing
+			await wait(50)
+			expect(counter).toBe(counterAfterStop)
+			expect(intervalId).toBeUndefined()
+
+			// Cleanup
+			cleanupHookCallback()
+		})
+
+		test('Memo - multiple watchers should share resources', async () => {
+			const source = new State(10)
+			let subscriptionCount = 0
+
+			const computed = new Memo((oldValue: number) => {
+				return source.get() + (oldValue || 0)
+			}, 0)
+
+			// HOOK_WATCH should only be called once for multiple watchers
+			const cleanupHookCallback = computed.on(HOOK_WATCH, () => {
+				subscriptionCount++
+				return () => {
+					subscriptionCount--
+				}
+			})
+
+			expect(subscriptionCount).toBe(0)
+
+			// Create multiple effects
+			const effect1 = createEffect(() => {
+				computed.get()
+			})
+			const effect2 = createEffect(() => {
+				computed.get()
+			})
+
+			// Should only increment once
+			expect(subscriptionCount).toBe(1)
+
+			// Stop first effect
+			effect1()
+			expect(subscriptionCount).toBe(1) // Still active due to second watcher
+
+			// Stop second effect
+			effect2()
+			expect(subscriptionCount).toBe(0) // Now cleaned up
+
+			// Cleanup
+			cleanupHookCallback()
+		})
+
+		test('Task - should handle abort signals in external resources', async () => {
+			const source = new State('test')
+			const abortedControllers: AbortController[] = []
+
+			const computed = new Task(
+				async (oldValue: string, abort: AbortSignal) => {
+					await wait(20)
+					if (abort.aborted) throw new Error('Aborted')
+					return `${source.get()}-${oldValue || 'initial'}`
+				},
+				'default',
+			)
+
+			// HOOK_WATCH that creates external resources with abort handling
+			const cleanupHookCallback = computed.on(HOOK_WATCH, () => {
+				const controller = new AbortController()
+
+				// Simulate external async operation (catch rejections to avoid unhandled errors)
+				new Promise(resolve => {
+					const timeout = setTimeout(() => {
+						if (controller.signal.aborted) {
+							resolve('External operation aborted')
+						} else {
+							resolve('External operation completed')
+						}
+					}, 50)
+
+					controller.signal.addEventListener('abort', () => {
+						clearTimeout(timeout)
+						resolve('External operation aborted')
+					})
+				}).catch(() => {
+					// Ignore promise rejections in test
+				})
+
+				return () => {
+					controller.abort()
+					abortedControllers.push(controller)
+				}
+			})
+
+			const effect1 = createEffect(() => {
+				computed.get()
+			})
+
+			// Change source to trigger recomputation
+			source.set('updated')
+
+			// Stop effect to trigger cleanup
+			effect1()
+
+			// Wait for cleanup to complete
+			await wait(100)
+
+			// Should have aborted external controllers
+			expect(abortedControllers.length).toBeGreaterThan(0)
+			expect(abortedControllers[0].signal.aborted).toBe(true)
+
+			// Cleanup
+			cleanupHookCallback()
+		})
+
+		test('Exception handling in computed HOOK_WATCH callbacks', async () => {
+			const source = new State(1)
+			const computed = new Memo(() => source.get() * 2)
+
+			let successfulCallbackCalled = false
+			let throwingCallbackCalled = false
+
+			// Add throwing callback
+			const cleanup1 = computed.on(HOOK_WATCH, () => {
+				throwingCallbackCalled = true
+				throw new Error('Test error in computed HOOK_WATCH')
+			})
+
+			// Add successful callback
+			const cleanup2 = computed.on(HOOK_WATCH, () => {
+				successfulCallbackCalled = true
+				return () => {
+					// cleanup
+				}
+			})
+
+			// Trigger callbacks - should throw due to exception in callback
+			expect(() => computed.get()).toThrow(
+				'Test error in computed HOOK_WATCH',
+			)
+
+			// Throwing callback should have been called
+			expect(throwingCallbackCalled).toBe(true)
+			// Successful callback should also have been called (resilient collection)
+			expect(successfulCallbackCalled).toBe(true)
+
+			// Cleanup
+			cleanup1()
+			cleanup2()
+		})
+	})
 })

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
+		})
+	})
 })