@zeix/cause-effect 0.17.1 → 0.17.2

package/test/collection.test.ts

@@ -230,46 +230,46 @@ describe('collection', () => {
 		})
 	})
 
-	describe('change notifications', () => {
-		test('emits add notifications', () => {
+	describe('Hooks', () => {
+		test('triggers HOOK_ADD when items are added', () => {
 			const numbers = new List([1, 2])
 			const doubled = new DerivedCollection(numbers, (x: number) => x * 2)
 
-			let arrayAddNotification: readonly string[] = []
+			let addedKeys: readonly string[] | undefined
 			doubled.on('add', keys => {
-				arrayAddNotification = keys
+				addedKeys = keys
 			})
 
 			numbers.add(3)
-			expect(arrayAddNotification).toHaveLength(1)
-			// biome-ignore lint/style/noNonNullAssertion: test
-			expect(doubled.byKey(arrayAddNotification[0]!)?.get()).toBe(6)
+			expect(addedKeys).toHaveLength(1)
+			const doubledKey = addedKeys?.[0]
+			if (doubledKey) expect(doubled.byKey(doubledKey)?.get()).toBe(6)
 		})
 
-		test('emits remove notifications when items are removed', () => {
+		test('triggers HOOK_REMOVE when items are removed', () => {
 			const items = new List([1, 2, 3])
 			const doubled = new DerivedCollection(items, (x: number) => x * 2)
 
-			let arrayRemoveNotification: readonly string[] = []
+			let removedKeys: readonly string[] | undefined
 			doubled.on('remove', keys => {
-				arrayRemoveNotification = keys
+				removedKeys = keys
 			})
 
 			items.remove(1)
-			expect(arrayRemoveNotification).toHaveLength(1)
+			expect(removedKeys).toHaveLength(1)
 		})
 
-		test('emits sort notifications when source is sorted', () => {
+		test('triggers HOOK_SORT when source is sorted', () => {
 			const numbers = new List([3, 1, 2])
 			const doubled = new DerivedCollection(numbers, (x: number) => x * 2)
 
-			let sortNotification: readonly string[] = []
+			let order: readonly string[] | undefined
 			doubled.on('sort', newOrder => {
-				sortNotification = newOrder
+				order = newOrder
 			})
 
 			numbers.sort((a, b) => a - b)
-			expect(sortNotification).toHaveLength(3)
+			expect(order).toHaveLength(3)
 			expect(doubled.get()).toEqual([2, 4, 6])
 		})
 	})
@@ -732,15 +732,16 @@ describe('collection', () => {
 					(x: number) => x * 2,
 				)
 
-				let addedKeys: readonly string[] = []
+				let addedKeys: readonly string[] | undefined
 				quadrupled.on('add', keys => {
 					addedKeys = keys
 				})
 
 				numbers.add(3)
 				expect(addedKeys).toHaveLength(1)
-				// biome-ignore lint/style/noNonNullAssertion: test
-				expect(quadrupled.byKey(addedKeys[0]!)?.get()).toBe(12)
+				const quadrupledKey = addedKeys?.[0]
+				if (quadrupledKey)
+					expect(quadrupled.byKey(quadrupledKey)?.get()).toBe(12)
 			})
 
 			test('emits remove events when source removes items', () => {
@@ -753,7 +754,7 @@ describe('collection', () => {
 					(x: number) => x * 2,
 				)
 
-				let removedKeys: readonly string[] = []
+				let removedKeys: readonly string[] | undefined
 				quadrupled.on('remove', keys => {
 					removedKeys = keys
 				})
@@ -772,7 +773,7 @@ describe('collection', () => {
 					(x: number) => x * 2,
 				)
 
-				let sortedKeys: readonly string[] = []
+				let sortedKeys: readonly string[] | undefined
 				quadrupled.on('sort', newOrder => {
 					sortedKeys = newOrder
 				})
@@ -850,4 +851,262 @@ describe('collection', () => {
 			})
 		})
 	})
+
+	describe('hooks system', () => {
+		test('Collection HOOK_WATCH is called when effect accesses collection.get()', () => {
+			const numbers = new List([10, 20, 30])
+			const doubled = numbers.deriveCollection(x => x * 2)
+
+			let collectionHookWatchCalled = false
+			let collectionUnwatchCalled = false
+
+			// Set up HOOK_WATCH callback on the collection itself
+			doubled.on('watch', () => {
+				collectionHookWatchCalled = true
+				return () => {
+					collectionUnwatchCalled = true
+				}
+			})
+
+			expect(collectionHookWatchCalled).toBe(false)
+
+			// Access collection via collection.get() - this should trigger collection's HOOK_WATCH
+			let effectValue: number[] = []
+			const cleanup = createEffect(() => {
+				effectValue = doubled.get()
+			})
+
+			expect(collectionHookWatchCalled).toBe(true)
+			expect(effectValue).toEqual([20, 40, 60])
+			expect(collectionUnwatchCalled).toBe(false)
+
+			// Cleanup effect - should trigger unwatch
+			cleanup()
+			expect(collectionUnwatchCalled).toBe(true)
+		})
+
+		test('List item HOOK_WATCH is triggered when accessing collection items via collection.at().get()', () => {
+			const numbers = new List([42, 84])
+			const doubled = numbers.deriveCollection(x => x * 2)
+
+			// Set up hook on source item BEFORE creating the effect
+			// biome-ignore lint/style/noNonNullAssertion: test
+			const firstSourceItem = numbers.at(0)!
+			let sourceItemHookCalled = false
+
+			firstSourceItem.on('watch', () => {
+				sourceItemHookCalled = true
+				return () => {
+					// Note: Unwatch behavior in computed signals is complex and depends on
+					// internal watcher management. We focus on verifying hook triggering.
+				}
+			})
+
+			expect(sourceItemHookCalled).toBe(false)
+
+			// Access collection item - the computed signal internally calls sourceItem.get()
+			let effectValue: number | undefined
+			const cleanup = createEffect(() => {
+				const firstCollectionItem = doubled.at(0)
+				effectValue = firstCollectionItem?.get()
+			})
+
+			expect(sourceItemHookCalled).toBe(true) // Source item HOOK_WATCH triggered
+			expect(effectValue).toBe(84) // 42 * 2
+
+			cleanup()
+		})
+
+		test('Collection and List item hooks work independently', () => {
+			const items = new List(['hello', 'world'])
+			const uppercased = items.deriveCollection(x => x.toUpperCase())
+
+			let collectionHookCalled = false
+			let collectionUnwatchCalled = false
+			let sourceItemHookCalled = false
+
+			// Set up hooks on both collection and source item
+			uppercased.on('watch', () => {
+				collectionHookCalled = true
+				return () => {
+					collectionUnwatchCalled = true
+				}
+			})
+
+			// biome-ignore lint/style/noNonNullAssertion: test
+			const firstSourceItem = items.at(0)!
+			firstSourceItem.on('watch', () => {
+				sourceItemHookCalled = true
+				return () => {
+					// Source item unwatch behavior is complex in computed context
+				}
+			})
+
+			// Effect 1: Access collection-level data - triggers both hooks
+			let collectionValue: string[] = []
+			const collectionCleanup = createEffect(() => {
+				collectionValue = uppercased.get()
+			})
+
+			expect(collectionHookCalled).toBe(true)
+			expect(sourceItemHookCalled).toBe(true) // Source items accessed by collection.get()
+			expect(collectionValue).toEqual(['HELLO', 'WORLD'])
+
+			// Effect 2: Access individual collection item independently
+			let itemValue: string | undefined
+			const itemCleanup = createEffect(() => {
+				itemValue = uppercased.at(0)?.get()
+			})
+
+			expect(itemValue).toBe('HELLO')
+
+			// Clean up effects
+			collectionCleanup()
+			expect(collectionUnwatchCalled).toBe(true)
+
+			itemCleanup()
+		})
+
+		test('source List item hooks are properly managed when items are removed', () => {
+			const items = new List(['first', 'second', 'third'])
+			const processed = items.deriveCollection(x => x.toUpperCase())
+
+			let firstItemHookCalled = false
+			let secondItemHookCalled = false
+
+			// Set up hooks on multiple source items
+			// biome-ignore lint/style/noNonNullAssertion: test
+			const firstSourceItem = items.at(0)!
+			// biome-ignore lint/style/noNonNullAssertion: test
+			const secondSourceItem = items.at(1)!
+
+			firstSourceItem.on('watch', () => {
+				firstItemHookCalled = true
+				return () => {
+					// Collection computed signals manage source watching internally
+				}
+			})
+
+			secondSourceItem.on('watch', () => {
+				secondItemHookCalled = true
+				return () => {
+					// Collection computed signals manage source watching internally
+				}
+			})
+
+			// Access both collection items to trigger source hooks
+			let firstValue: string | undefined
+			let secondValue: string | undefined
+
+			const cleanup1 = createEffect(() => {
+				firstValue = processed.at(0)?.get()
+			})
+
+			const cleanup2 = createEffect(() => {
+				secondValue = processed.at(1)?.get()
+			})
+
+			// Both source item hooks should be triggered
+			expect(firstItemHookCalled).toBe(true)
+			expect(secondItemHookCalled).toBe(true)
+			expect(firstValue).toBe('FIRST')
+			expect(secondValue).toBe('SECOND')
+
+			cleanup1()
+			cleanup2()
+		})
+
+		test('newly added source List items have hooks triggered through collection access', () => {
+			const numbers = new List<number>([])
+			const squared = numbers.deriveCollection(x => x * x)
+
+			// Add first item to source list
+			numbers.add(5)
+
+			// Set up hook on the newly added source item
+			// biome-ignore lint/style/noNonNullAssertion: test
+			const sourceItem = numbers.at(0)!
+			let sourceHookCalled = false
+
+			sourceItem.on('watch', () => {
+				sourceHookCalled = true
+				return () => {
+					// Hook cleanup managed by computed signal system
+				}
+			})
+
+			expect(sourceHookCalled).toBe(false)
+
+			// Access the collection item - should trigger source item hook
+			let effectValue: number | undefined
+			const cleanup = createEffect(() => {
+				effectValue = squared.at(0)?.get()
+			})
+
+			expect(sourceHookCalled).toBe(true) // Source hook triggered through collection
+			expect(effectValue).toBe(25) // 5 * 5
+
+			cleanup()
+		})
+
+		test('Collection length access triggers Collection HOOK_WATCH', () => {
+			const numbers = new List([1, 2, 3])
+			const doubled = numbers.deriveCollection(x => x * 2)
+
+			let collectionHookWatchCalled = false
+			let collectionUnwatchCalled = false
+
+			doubled.on('watch', () => {
+				collectionHookWatchCalled = true
+				return () => {
+					collectionUnwatchCalled = true
+				}
+			})
+
+			// Access via collection.length - this should trigger collection's HOOK_WATCH
+			let effectValue: number = 0
+			const cleanup = createEffect(() => {
+				effectValue = doubled.length
+			})
+
+			expect(collectionHookWatchCalled).toBe(true)
+			expect(effectValue).toBe(3)
+			expect(collectionUnwatchCalled).toBe(false)
+
+			cleanup()
+			expect(collectionUnwatchCalled).toBe(true)
+		})
+
+		test('chained collections maintain proper hook propagation to original source', () => {
+			const numbers = new List([2, 3])
+			const doubled = numbers.deriveCollection(x => x * 2)
+			const quadrupled = doubled.deriveCollection(x => x * 2)
+
+			// Set up hook on original source item
+			// biome-ignore lint/style/noNonNullAssertion: test
+			const sourceItem = numbers.at(0)!
+			let sourceHookCalled = false
+
+			sourceItem.on('watch', () => {
+				sourceHookCalled = true
+				return () => {
+					// Chained computed signals manage cleanup through dependency chain
+				}
+			})
+
+			expect(sourceHookCalled).toBe(false)
+
+			// Access chained collection item - should trigger original source hook
+			// Chain: quadrupled.at(0).get() -> doubled.at(0).get() -> numbers.at(0).get()
+			let effectValue: number | undefined
+			const cleanup = createEffect(() => {
+				effectValue = quadrupled.at(0)?.get()
+			})
+
+			expect(sourceHookCalled).toBe(true) // Original source hook triggered through chain
+			expect(effectValue).toBe(8) // 2 * 2 * 2
+
+			cleanup()
+		})
+	})
 })

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