@zeix/cause-effect 0.17.1 → 0.17.3

package/src/system.ts

@@ -1,26 +1,24 @@
+import { assert, type Guard } from './errors'
+import type { UnknownSignal } from './signal'
+
 /* === Types === */
 
 type Cleanup = () => void
 
+// biome-ignore lint/suspicious/noConfusingVoidType: optional Cleanup return type
+type MaybeCleanup = Cleanup | undefined | void
+
 type Watcher = {
 	(): void
+	run(): void
 	onCleanup(cleanup: Cleanup): void
 	stop(): void
 }
 
-type Notifications = {
-	add: readonly string[]
-	change: readonly string[]
-	remove: readonly string[]
-	sort: readonly string[]
-}
-
-type Listener<K extends keyof Notifications> = (
-	payload: Notifications[K],
-) => void
-
-type Listeners = {
-	[K in keyof Notifications]: Set<Listener<K>>
+type SignalOptions<T extends unknown & {}> = {
+	guard?: Guard<T>
+	watched?: () => void
+	unwatched?: () => void
 }
 
 /* === Internal === */
@@ -28,94 +26,206 @@ type Listeners = {
 // Currently active watcher
 let activeWatcher: Watcher | undefined
 
+const watchersMap = new WeakMap<UnknownSignal, Set<Watcher>>()
+const watchedCallbackMap = new WeakMap<object, () => void>()
+const unwatchedCallbackMap = new WeakMap<object, () => void>()
+
 // Queue of pending watcher reactions for batched change notifications
 const pendingReactions = new Set<() => void>()
 let batchDepth = 0
 
+/* === Constants === */
+
+// biome-ignore lint/suspicious/noExplicitAny: Deliberately using any to be used as a placeholder value in any signal
+const UNSET: any = Symbol()
+
 /* === Functions === */
 
 /**
- * Create a watcher that can be used to observe changes to a signal
+ * Create a watcher to observe changes in signals.
  *
- * A watcher is a reaction function with onCleanup and stop methods
+ * A watcher combines push and pull reaction functions with onCleanup and stop methods
  *
- * @since 0.14.1
- * @param {() => void} react - Function to be called when the state changes
+ * @since 0.17.3
+ * @param {() => void} push - Function to be called when the state changes (push)
+ * @param {() => void} pull - Function to be called on demand from consumers (pull)
  * @returns {Watcher} - Watcher object with off and cleanup methods
  */
-const createWatcher = (react: () => void): Watcher => {
+const createWatcher = (push: () => void, pull: () => void): Watcher => {
 	const cleanups = new Set<Cleanup>()
-	const watcher = react as Partial<Watcher>
+	const watcher = push as Partial<Watcher>
+	watcher.run = () => {
+		const prev = activeWatcher
+		activeWatcher = watcher as Watcher
+		try {
+			pull()
+		} finally {
+			activeWatcher = prev
+		}
+	}
 	watcher.onCleanup = (cleanup: Cleanup) => {
 		cleanups.add(cleanup)
 	}
 	watcher.stop = () => {
-		for (const cleanup of cleanups) cleanup()
-		cleanups.clear()
+		try {
+			for (const cleanup of cleanups) cleanup()
+		} finally {
+			cleanups.clear()
+		}
 	}
 	return watcher as Watcher
 }
 
 /**
- * Subscribe by adding active watcher to the Set of watchers of a signal
+ * Run a function with signal reads in a non-tracking context.
  *
- * @param {Set<Watcher>} watchers - Watchers of the signal
+ * @param {() => void} callback - Callback
  */
+const untrack = (callback: () => void): void => {
+	const prev = activeWatcher
+	activeWatcher = undefined
+	try {
+		callback()
+	} finally {
+		activeWatcher = prev
+	}
+}
+
+const registerWatchCallbacks = (
+	signal: UnknownSignal,
+	watched: () => void,
+	unwatched?: () => void,
+) => {
+	watchedCallbackMap.set(signal, watched)
+	if (unwatched) unwatchedCallbackMap.set(signal, unwatched)
+}
+
+/**
+ * Subscribe active watcher to a signal.
+ *
+ * @param {UnknownSignal} signal - Signal to subscribe to
+ * @returns {boolean} - true if the active watcher was subscribed,
+ *                      false if the watcher was already subscribed or there was no active watcher
+ */
+const subscribeTo = (signal: UnknownSignal): boolean => {
+	if (!activeWatcher || watchersMap.get(signal)?.has(activeWatcher))
+		return false
+
+	const watcher = activeWatcher
+	if (!watchersMap.has(signal)) watchersMap.set(signal, new Set<Watcher>())
+
+	const watchers = watchersMap.get(signal)
+	assert(watchers)
+	if (!watchers.size) {
+		const watchedCallback = watchedCallbackMap.get(signal)
+		if (watchedCallback) untrack(watchedCallback)
+	}
+	watchers.add(watcher)
+	watcher.onCleanup(() => {
+		watchers.delete(watcher)
+		if (!watchers.size) {
+			const unwatchedCallback = unwatchedCallbackMap.get(signal)
+			if (unwatchedCallback) untrack(unwatchedCallback)
+		}
+	})
+	return true
+}
+
 const subscribeActiveWatcher = (watchers: Set<Watcher>) => {
-	if (activeWatcher && !watchers.has(activeWatcher)) {
-		const watcher = activeWatcher
-		watcher.onCleanup(() => watchers.delete(watcher))
-		watchers.add(watcher)
+	if (!activeWatcher || watchers.has(activeWatcher)) return false
+
+	const watcher = activeWatcher
+	watchers.add(watcher)
+	if (!watchers.size) {
+		const watchedCallback = watchedCallbackMap.get(watchers)
+		if (watchedCallback) untrack(watchedCallback)
 	}
+	watcher.onCleanup(() => {
+		watchers.delete(watcher)
+		if (!watchers.size) {
+			const unwatchedCallback = unwatchedCallbackMap.get(watchers)
+			if (unwatchedCallback) untrack(unwatchedCallback)
+		}
+	})
+	return true
 }
 
 /**
- * Notify watchers of a signal change
+ * Unsubscribe all watchers from a signal so it can be garbage collected.
  *
- * @param {Set<Watcher>} watchers - Watchers of the signal
+ * @param {UnknownSignal} signal - Signal to unsubscribe from
+ * @returns {void}
  */
-const notifyWatchers = (watchers: Set<Watcher>) => {
+const unsubscribeAllFrom = (signal: UnknownSignal): void => {
+	const watchers = watchersMap.get(signal)
+	if (!watchers) return
+
+	for (const watcher of watchers) watcher.stop()
+	watchers.clear()
+}
+
+/**
+ * Notify watchers of a signal change.
+ *
+ * @param {UnknownSignal} signal - Signal to notify watchers of
+ * @returns {boolean} - Whether any watchers were notified
+ */
+const notifyOf = (signal: UnknownSignal): boolean => {
+	const watchers = watchersMap.get(signal)
+	if (!watchers?.size) return false
+
 	for (const react of watchers) {
 		if (batchDepth) pendingReactions.add(react)
 		else react()
 	}
+	return true
+}
+
+const notifyWatchers = (watchers: Set<Watcher>): boolean => {
+	if (!watchers.size) return false
+
+	for (const react of watchers) {
+		if (batchDepth) pendingReactions.add(react)
+		else react()
+	}
+	return true
 }
 
 /**
- * Flush all pending reactions of enqueued watchers
+ * Flush all pending reactions of enqueued watchers.
  */
-const flushPendingReactions = () => {
+const flush = () => {
 	while (pendingReactions.size) {
 		const watchers = Array.from(pendingReactions)
 		pendingReactions.clear()
-		for (const watcher of watchers) watcher()
+		for (const react of watchers) react()
 	}
 }
 
 /**
- * Batch multiple signal writes
+ * Batch multiple signal writes.
  *
  * @param {() => void} callback - Function with multiple signal writes to be batched
  */
-const batchSignalWrites = (callback: () => void) => {
+const batch = (callback: () => void) => {
 	batchDepth++
 	try {
 		callback()
 	} finally {
-		flushPendingReactions()
+		flush()
 		batchDepth--
 	}
 }
 
 /**
- * Run a function with signal reads in a tracking context (or temporarily untrack)
+ * Run a function with signal reads in a tracking context (or temporarily untrack).
  *
  * @param {Watcher | false} watcher - Watcher to be called when the signal changes
  *                                    or false for temporary untracking while inserting auto-hydrating DOM nodes
  *                                    that might read signals (e.g., Web Components)
  * @param {() => void} run - Function to run the computation or effect
  */
-const trackSignalReads = (watcher: Watcher | false, run: () => void): void => {
+const track = (watcher: Watcher | false, run: () => void): void => {
 	const prev = activeWatcher
 	activeWatcher = watcher || undefined
 	try {
@@ -125,35 +235,23 @@ const trackSignalReads = (watcher: Watcher | false, run: () => void): void => {
 	}
 }
 
-/**
- * Emit a notification to listeners
- *
- * @param {Set<Listener>} listeners - Listeners to be notified
- * @param {Notifications[K]} payload - Payload to be sent to listeners
- */
-const emitNotification = <T extends keyof Notifications>(
-	listeners: Set<Listener<T>>,
-	payload: Notifications[T],
-) => {
-	for (const listener of listeners) {
-		if (batchDepth) pendingReactions.add(() => listener(payload))
-		else listener(payload)
-	}
-}
-
 /* === Exports === */
 
 export {
 	type Cleanup,
+	type MaybeCleanup,
 	type Watcher,
-	type Notifications,
-	type Listener,
-	type Listeners,
+	type SignalOptions,
+	UNSET,
 	createWatcher,
+	registerWatchCallbacks,
+	subscribeTo,
 	subscribeActiveWatcher,
+	unsubscribeAllFrom,
+	notifyOf,
 	notifyWatchers,
-	flushPendingReactions,
-	batchSignalWrites,
-	trackSignalReads,
-	emitNotification,
+	flush,
+	batch,
+	track,
+	untrack,
 }

package/src/util.ts

@@ -1,8 +1,3 @@
-/* === Constants === */
-
-// biome-ignore lint/suspicious/noExplicitAny: Deliberately using any to be used as a placeholder value in any signal
-const UNSET: any = Symbol()
-
 /* === Utility Functions === */
 
 const isString = /*#__PURE__*/ (value: unknown): value is string =>
@@ -73,7 +68,6 @@ const valueString = /*#__PURE__*/ (value: unknown): string =>
 /* === Exports === */
 
 export {
-	UNSET,
 	isString,
 	isNumber,
 	isSymbol,

package/test/batch.test.ts

@@ -1,12 +1,5 @@
 import { describe, expect, test } from 'bun:test'
-import {
-	batchSignalWrites,
-	createEffect,
-	Memo,
-	match,
-	resolve,
-	State,
-} from '../index.ts'
+import { batch, createEffect, Memo, match, resolve, State } from '../index.ts'
 
 /* === Tests === */
 
@@ -19,7 +12,7 @@ describe('Batch', () => {
 			result = cause.get()
 			count++
 		})
-		batchSignalWrites(() => {
+		batch(() => {
 			for (let i = 1; i <= 10; i++) cause.set(i)
 		})
 		expect(result).toBe(10)
@@ -43,7 +36,7 @@ describe('Batch', () => {
 				err: () => {},
 			})
 		})
-		batchSignalWrites(() => {
+		batch(() => {
 			a.set(6)
 			b.set(8)
 			c.set(10)
@@ -87,7 +80,7 @@ describe('Batch', () => {
 		expect(result).toBe(10)
 
 		// Batch: apply changes to all signals in a single transaction
-		batchSignalWrites(() => {
+		batch(() => {
 			signals.forEach(signal => signal.update(v => v * 2))
 		})
 

package/test/benchmark.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, mock, test } from 'bun:test'
-import { batchSignalWrites, createEffect, Memo, State } from '../index.ts'
+import { batch, createEffect, Memo, State } from '../index.ts'
 import { Counter, makeGraph, runGraph } from './util/dependency-graph'
 import type { Computed, ReactiveFramework } from './util/reactive-framework'
 
@@ -28,7 +28,7 @@ const framework = {
 		}
 	},
 	effect: (fn: () => undefined) => createEffect(fn),
-	withBatch: (fn: () => undefined) => batchSignalWrites(fn),
+	withBatch: (fn: () => undefined) => batch(fn),
 	withBuild: <T>(fn: () => T) => fn(),
 }
 const testPullCounts = true
@@ -449,6 +449,7 @@ describe('$mol_wire tests', () => {
 	const name = framework.name
 
 	test(`${name} | $mol_wire benchmark`, () => {
+		// @ts-expect-error test
 		const fib = (n: number) => {
 			if (n < 2) return 1
 			return fib(n - 1) + fib(n - 2)
@@ -618,6 +619,7 @@ describe('CellX tests', () => {
 		for (const layers in expected) {
 			// @ts-expect-error - Framework object has incompatible type constraints with ReactiveFramework
 			const [before, after] = cellx(framework, layers)
+			// @ts-expect-error - Framework object has incompatible type constraints with ReactiveFramework
 			const [expectedBefore, expectedAfter] = expected[layers]
 			expect(before.toString()).toBe(expectedBefore.toString())
 			expect(after.toString()).toBe(expectedAfter.toString())

package/test/collection.test.ts

@@ -104,7 +104,7 @@ describe('collection', () => {
 		test('returns undefined for non-existent properties', () => {
 			const items = new List([1, 2])
 			const collection = new DerivedCollection(items, (x: number) => x)
-			expect(collection[5]).toBeUndefined()
+			expect(collection.at(5)).toBeUndefined()
 		})
 
 		test('supports numeric key access', () => {
@@ -230,50 +230,6 @@ describe('collection', () => {
 		})
 	})
 
-	describe('change notifications', () => {
-		test('emits add notifications', () => {
-			const numbers = new List([1, 2])
-			const doubled = new DerivedCollection(numbers, (x: number) => x * 2)
-
-			let arrayAddNotification: readonly string[] = []
-			doubled.on('add', keys => {
-				arrayAddNotification = keys
-			})
-
-			numbers.add(3)
-			expect(arrayAddNotification).toHaveLength(1)
-			// biome-ignore lint/style/noNonNullAssertion: test
-			expect(doubled.byKey(arrayAddNotification[0]!)?.get()).toBe(6)
-		})
-
-		test('emits remove notifications when items are removed', () => {
-			const items = new List([1, 2, 3])
-			const doubled = new DerivedCollection(items, (x: number) => x * 2)
-
-			let arrayRemoveNotification: readonly string[] = []
-			doubled.on('remove', keys => {
-				arrayRemoveNotification = keys
-			})
-
-			items.remove(1)
-			expect(arrayRemoveNotification).toHaveLength(1)
-		})
-
-		test('emits sort notifications when source is sorted', () => {
-			const numbers = new List([3, 1, 2])
-			const doubled = new DerivedCollection(numbers, (x: number) => x * 2)
-
-			let sortNotification: readonly string[] = []
-			doubled.on('sort', newOrder => {
-				sortNotification = newOrder
-			})
-
-			numbers.sort((a, b) => a - b)
-			expect(sortNotification).toHaveLength(3)
-			expect(doubled.get()).toEqual([2, 4, 6])
-		})
-	})
-
 	describe('edge cases', () => {
 		test('handles empty collections correctly', () => {
 			const empty = new List<number>([])
@@ -721,68 +677,6 @@ describe('collection', () => {
 			})
 		})
 
-		describe('derived collection event handling', () => {
-			test('emits add events when source adds items', () => {
-				const numbers = new List([1, 2])
-				const doubled = new DerivedCollection(
-					numbers,
-					(x: number) => x * 2,
-				)
-				const quadrupled = doubled.deriveCollection(
-					(x: number) => x * 2,
-				)
-
-				let addedKeys: readonly string[] = []
-				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)
-			})
-
-			test('emits remove events when source removes items', () => {
-				const numbers = new List([1, 2, 3])
-				const doubled = new DerivedCollection(
-					numbers,
-					(x: number) => x * 2,
-				)
-				const quadrupled = doubled.deriveCollection(
-					(x: number) => x * 2,
-				)
-
-				let removedKeys: readonly string[] = []
-				quadrupled.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 = new DerivedCollection(
-					numbers,
-					(x: number) => x * 2,
-				)
-				const quadrupled = doubled.deriveCollection(
-					(x: number) => x * 2,
-				)
-
-				let sortedKeys: readonly string[] = []
-				quadrupled.on('sort', newOrder => {
-					sortedKeys = newOrder
-				})
-
-				numbers.sort((a, b) => a - b)
-				expect(sortedKeys).toHaveLength(3)
-				expect(quadrupled.get()).toEqual([4, 8, 12])
-			})
-		})
-
 		describe('edge cases', () => {
 			test('handles empty collection derivation', () => {
 				const empty = new List<number>([])
@@ -850,4 +744,109 @@ describe('collection', () => {
 			})
 		})
 	})
+
+	describe('Watch Callbacks', () => {
+		test('Collection watched callback is called when effect accesses collection.get()', () => {
+			const numbers = new List([10, 20, 30])
+
+			let collectionWatchedCalled = false
+			let collectionUnwatchCalled = false
+			const doubled = numbers.deriveCollection(x => x * 2, {
+				watched: () => {
+					collectionWatchedCalled = true
+				},
+				unwatched: () => {
+					collectionUnwatchCalled = true
+				},
+			})
+
+			expect(collectionWatchedCalled).toBe(false)
+
+			// Access collection via collection.get() - this should trigger collection's watched callback
+			let effectValue: number[] = []
+			const cleanup = createEffect(() => {
+				effectValue = doubled.get()
+			})
+
+			expect(collectionWatchedCalled).toBe(true)
+			expect(effectValue).toEqual([20, 40, 60])
+			expect(collectionUnwatchCalled).toBe(false)
+
+			// Cleanup effect - should trigger unwatch
+			cleanup()
+			expect(collectionUnwatchCalled).toBe(true)
+		})
+
+		test('Collection and List watched callbacks work independently', () => {
+			let sourceWatchedCalled = false
+			const items = new List(['hello', 'world'], {
+				watched: () => {
+					sourceWatchedCalled = true
+				},
+			})
+
+			let collectionWatchedCalled = false
+			let collectionUnwatchedCalled = false
+			const uppercased = items.deriveCollection(x => x.toUpperCase(), {
+				watched: () => {
+					collectionWatchedCalled = true
+				},
+				unwatched: () => {
+					collectionUnwatchedCalled = true
+				},
+			})
+
+			// Effect 1: Access collection-level data - triggers both watched callbacks
+			let collectionValue: string[] = []
+			const collectionCleanup = createEffect(() => {
+				collectionValue = uppercased.get()
+			})
+
+			expect(collectionWatchedCalled).toBe(true)
+			expect(sourceWatchedCalled).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(collectionUnwatchedCalled).toBe(true)
+
+			itemCleanup()
+		})
+
+		test('Collection length access triggers Collection watched callback', () => {
+			const numbers = new List([1, 2, 3])
+
+			let collectionWatchedCalled = false
+			let collectionUnwatchedCalled = false
+			const doubled = numbers.deriveCollection(x => x * 2, {
+				watched: () => {
+					collectionWatchedCalled = true
+				},
+				unwatched: () => {
+					collectionUnwatchedCalled = true
+				},
+			})
+
+			// Access via collection.length - this should trigger collection's watched callback
+			let effectValue: number = 0
+			const cleanup = createEffect(() => {
+				effectValue = doubled.length
+			})
+
+			expect(collectionWatchedCalled).toBe(true)
+			expect(effectValue).toBe(3)
+			expect(collectionUnwatchedCalled).toBe(false)
+
+			cleanup()
+			expect(collectionUnwatchedCalled).toBe(true)
+		})
+	})
 })