@zeix/cause-effect 0.18.0 → 0.18.2

package/test/list.test.ts

@@ -3,10 +3,18 @@ import {
 	createEffect,
 	createList,
 	createMemo,
+	createScope,
+	createState,
+	createTask,
 	isList,
 	isMemo,
+	match,
 } from '../index.ts'
 
+/* === Utility Functions === */
+
+const wait = (ms: number) => new Promise(resolve => setTimeout(resolve, ms))
+
 describe('List', () => {
 	describe('createList', () => {
 		test('should return initial values from get()', () => {
@@ -437,6 +445,190 @@ describe('List', () => {
 			expect(watchedCalled).toBe(true)
 			dispose()
 		})
+
+		test('should activate watched via sync deriveCollection', () => {
+			let watchedCalled = false
+			let unwatchedCalled = false
+			const list = createList([1, 2, 3], {
+				watched: () => {
+					watchedCalled = true
+					return () => {
+						unwatchedCalled = true
+					}
+				},
+			})
+
+			const derived = list.deriveCollection((v: number) => v * 2)
+
+			expect(watchedCalled).toBe(false)
+
+			const dispose = createEffect(() => {
+				derived.get()
+			})
+
+			expect(watchedCalled).toBe(true)
+			expect(unwatchedCalled).toBe(false)
+
+			dispose()
+			expect(unwatchedCalled).toBe(true)
+		})
+
+		test('should activate watched via async deriveCollection', async () => {
+			let watchedCalled = false
+			let unwatchedCalled = false
+			const list = createList([1, 2, 3], {
+				watched: () => {
+					watchedCalled = true
+					return () => {
+						unwatchedCalled = true
+					}
+				},
+			})
+
+			const derived = list.deriveCollection(
+				async (v: number, _abort: AbortSignal) => v * 2,
+			)
+
+			expect(watchedCalled).toBe(false)
+
+			const dispose = createEffect(() => {
+				derived.get()
+			})
+
+			expect(watchedCalled).toBe(true)
+
+			await wait(10)
+
+			expect(unwatchedCalled).toBe(false)
+
+			dispose()
+			expect(unwatchedCalled).toBe(true)
+		})
+
+		test('should not tear down watched during list mutation via deriveCollection', () => {
+			let activations = 0
+			let deactivations = 0
+			const list = createList([1, 2], {
+				watched: () => {
+					activations++
+					return () => {
+						deactivations++
+					}
+				},
+			})
+
+			const derived = list.deriveCollection((v: number) => v * 2)
+
+			let result: number[] = []
+			const dispose = createEffect(() => {
+				result = derived.get()
+			})
+
+			expect(activations).toBe(1)
+			expect(deactivations).toBe(0)
+			expect(result).toEqual([2, 4])
+
+			// Add item — should NOT tear down and restart watched
+			list.add(3)
+			expect(result).toEqual([2, 4, 6])
+			expect(activations).toBe(1)
+			expect(deactivations).toBe(0)
+
+			// Remove item — should NOT tear down and restart watched
+			list.remove(0)
+			expect(activations).toBe(1)
+			expect(deactivations).toBe(0)
+
+			dispose()
+			expect(deactivations).toBe(1)
+		})
+
+		test('should delay watched activation for conditional reads', () => {
+			let watchedCalled = false
+			const list = createList([1, 2], {
+				watched: () => {
+					watchedCalled = true
+					return () => {}
+				},
+			})
+
+			const show = createState(false)
+
+			const dispose = createScope(() => {
+				createEffect(() => {
+					if (show.get()) {
+						list.get()
+					}
+				})
+			})
+
+			// Conditional read — list not accessed, watched should not fire
+			expect(watchedCalled).toBe(false)
+
+			// Flip condition — list is now accessed
+			show.set(true)
+			expect(watchedCalled).toBe(true)
+
+			dispose()
+		})
+
+		test('should activate watched via chained deriveCollection', () => {
+			let watchedCalled = false
+			const list = createList([1, 2, 3], {
+				watched: () => {
+					watchedCalled = true
+					return () => {}
+				},
+			})
+
+			const doubled = list.deriveCollection((v: number) => v * 2)
+			const quadrupled = doubled.deriveCollection((v: number) => v * 2)
+
+			expect(watchedCalled).toBe(false)
+
+			const dispose = createEffect(() => {
+				quadrupled.get()
+			})
+
+			expect(watchedCalled).toBe(true)
+			dispose()
+		})
+
+		test('should activate watched via deriveCollection read inside match()', async () => {
+			let watchedCalled = false
+			const list = createList([1, 2], {
+				watched: () => {
+					watchedCalled = true
+					return () => {}
+				},
+			})
+
+			const derived = list.deriveCollection((v: number) => v * 10)
+
+			const task = createTask(async () => {
+				await wait(10)
+				return 'done'
+			})
+
+			const dispose = createScope(() => {
+				createEffect(() => {
+					// Read derived BEFORE match to ensure subscription
+					const values = derived.get()
+					match([task], {
+						ok: () => {
+							void values
+						},
+						nil: () => {},
+					})
+				})
+			})
+
+			// watched should activate synchronously even though task is pending
+			expect(watchedCalled).toBe(true)
+
+			await wait(50)
+			dispose()
+		})
 	})
 
 	describe('Input Validation', () => {

package/test/memo.test.ts

@@ -1,6 +1,9 @@
 import { describe, expect, test } from 'bun:test'
 import {
+	batch,
+	createEffect,
 	createMemo,
+	createScope,
 	createState,
 	isMemo,
 	isState,
@@ -377,4 +380,195 @@ describe('Memo', () => {
 			}).toThrow('[Memo] Signal value cannot be null or undefined')
 		})
 	})
+
+	describe('options.watched', () => {
+		test('should call watched on first effect access', () => {
+			let watchedCount = 0
+			const externalValue = 1
+
+			const memo = createMemo(() => externalValue, {
+				value: 0,
+				watched: _invalidate => {
+					watchedCount++
+					return () => {}
+				},
+			})
+
+			expect(watchedCount).toBe(0)
+
+			const dispose = createScope(() => {
+				createEffect(() => {
+					void memo.get()
+				})
+			})
+
+			expect(watchedCount).toBe(1)
+			dispose()
+		})
+
+		test('should call cleanup when last effect stops watching', () => {
+			let cleanedUp = false
+			const externalValue = 1
+
+			const memo = createMemo(() => externalValue, {
+				value: 0,
+				watched: _invalidate => {
+					return () => {
+						cleanedUp = true
+					}
+				},
+			})
+
+			const dispose = createScope(() => {
+				createEffect(() => {
+					void memo.get()
+				})
+			})
+
+			expect(cleanedUp).toBe(false)
+			dispose()
+			expect(cleanedUp).toBe(true)
+		})
+
+		test('should recompute memo when invalidate is called', () => {
+			let externalValue = 10
+			let computeCount = 0
+			let invalidate!: () => void
+
+			const memo = createMemo(
+				() => {
+					computeCount++
+					return externalValue
+				},
+				{
+					value: 0,
+					watched: inv => {
+						invalidate = inv
+						return () => {}
+					},
+				},
+			)
+
+			let observed = 0
+			const dispose = createScope(() => {
+				createEffect(() => {
+					observed = memo.get()
+				})
+			})
+
+			expect(observed).toBe(10)
+			expect(computeCount).toBe(1)
+
+			externalValue = 20
+			invalidate()
+			expect(observed).toBe(20)
+			expect(computeCount).toBe(2)
+
+			dispose()
+		})
+
+		test('should defer flush when invalidate is called inside batch', () => {
+			let externalValue = 1
+			let invalidate!: () => void
+
+			const memo = createMemo(() => externalValue, {
+				value: 0,
+				watched: inv => {
+					invalidate = inv
+					return () => {}
+				},
+			})
+
+			let observed = 0
+			const dispose = createScope(() => {
+				createEffect(() => {
+					observed = memo.get()
+				})
+			})
+
+			expect(observed).toBe(1)
+
+			batch(() => {
+				externalValue = 2
+				invalidate()
+				expect(observed).toBe(1) // not yet flushed
+			})
+			expect(observed).toBe(2) // flushed after batch
+
+			dispose()
+		})
+
+		test('should re-activate watched after cleanup and new effect access', () => {
+			let watchedCount = 0
+			const externalValue = 1
+
+			const memo = createMemo(() => externalValue, {
+				value: 0,
+				watched: _invalidate => {
+					watchedCount++
+					return () => {}
+				},
+			})
+
+			const dispose1 = createScope(() => {
+				createEffect(() => {
+					void memo.get()
+				})
+			})
+			expect(watchedCount).toBe(1)
+			dispose1()
+
+			const dispose2 = createScope(() => {
+				createEffect(() => {
+					void memo.get()
+				})
+			})
+			expect(watchedCount).toBe(2)
+			dispose2()
+		})
+
+		test('should work with both tracked dependencies and watched', () => {
+			const source = createState(1)
+			let externalValue = 100
+			let computeCount = 0
+			let invalidate!: () => void
+
+			const memo = createMemo(
+				() => {
+					computeCount++
+					return source.get() + externalValue
+				},
+				{
+					value: 0,
+					watched: inv => {
+						invalidate = inv
+						return () => {}
+					},
+				},
+			)
+
+			let observed = 0
+			const dispose = createScope(() => {
+				createEffect(() => {
+					observed = memo.get()
+				})
+			})
+
+			expect(observed).toBe(101)
+			expect(computeCount).toBe(1)
+
+			// Tracked dependency triggers recomputation
+			source.set(2)
+			expect(observed).toBe(102)
+			expect(computeCount).toBe(2)
+
+			// External invalidation triggers recomputation
+			externalValue = 200
+			invalidate()
+			expect(observed).toBe(202)
+			expect(computeCount).toBe(3)
+
+			dispose()
+		})
+	})
 })

package/test/task.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, test } from 'bun:test'
 import {
 	createEffect,
 	createMemo,
+	createScope,
 	createState,
 	createTask,
 	isMemo,
@@ -392,4 +393,137 @@ describe('Task', () => {
 			}).toThrow('[Task] Signal value cannot be null or undefined')
 		})
 	})
+
+	describe('options.watched', () => {
+		test('should call watched on first effect access', () => {
+			let watchedCount = 0
+
+			const task = createTask(
+				async () => {
+					await wait(10)
+					return 1
+				},
+				{
+					value: 0,
+					watched: _invalidate => {
+						watchedCount++
+						return () => {}
+					},
+				},
+			)
+
+			expect(watchedCount).toBe(0)
+
+			const dispose = createScope(() => {
+				createEffect(() => {
+					void task.get()
+				})
+			})
+
+			expect(watchedCount).toBe(1)
+			dispose()
+		})
+
+		test('should call cleanup when last effect stops watching', () => {
+			let cleanedUp = false
+
+			const task = createTask(
+				async () => {
+					await wait(10)
+					return 1
+				},
+				{
+					value: 0,
+					watched: _invalidate => {
+						return () => {
+							cleanedUp = true
+						}
+					},
+				},
+			)
+
+			const dispose = createScope(() => {
+				createEffect(() => {
+					void task.get()
+				})
+			})
+
+			expect(cleanedUp).toBe(false)
+			dispose()
+			expect(cleanedUp).toBe(true)
+		})
+
+		test('should re-execute task when invalidate is called', async () => {
+			let externalValue = 10
+			let computeCount = 0
+			let invalidate!: () => void
+
+			const task = createTask(
+				async () => {
+					computeCount++
+					await wait(10)
+					return externalValue
+				},
+				{
+					value: 0,
+					watched: inv => {
+						invalidate = inv
+						return () => {}
+					},
+				},
+			)
+
+			let observed = 0
+			const dispose = createScope(() => {
+				createEffect(() => {
+					observed = task.get()
+				})
+			})
+
+			await wait(20)
+			expect(observed).toBe(10)
+			expect(computeCount).toBe(1)
+
+			externalValue = 20
+			invalidate()
+			await wait(20)
+			expect(observed).toBe(20)
+			expect(computeCount).toBe(2)
+
+			dispose()
+		})
+
+		test('should abort in-flight task when invalidate is called', async () => {
+			let wasAborted = false
+			let invalidate!: () => void
+
+			const task = createTask(
+				async (_prev, signal) => {
+					await wait(100)
+					if (signal.aborted) wasAborted = true
+					return 1
+				},
+				{
+					value: 0,
+					watched: inv => {
+						invalidate = inv
+						return () => {}
+					},
+				},
+			)
+
+			const dispose = createScope(() => {
+				createEffect(() => {
+					void task.get()
+				})
+			})
+
+			await wait(10) // task is in-flight
+			invalidate() // should trigger re-execution, aborting the current one
+			await wait(110)
+			expect(wasAborted).toBe(true)
+
+			dispose()
+		})
+	})
 })

package/types/index.d.ts

@@ -1,15 +1,15 @@
 /**
  * @name Cause & Effect
- * @version 0.18.0
+ * @version 0.18.1
  * @author Esther Brunner
  */
 export { CircularDependencyError, type Guard, InvalidCallbackError, InvalidSignalValueError, NullishSignalValueError, RequiredOwnerError, UnsetSignalValueError, } from './src/errors';
-export { batch, type Cleanup, type ComputedOptions, createScope, type EffectCallback, type MemoCallback, type Signal, type SignalOptions, SKIP_EQUALITY, type TaskCallback, untrack, } from './src/graph';
-export { type Collection, type CollectionCallback, type CollectionOptions, createCollection, type DeriveCollectionCallback, isCollection, } from './src/nodes/collection';
+export { batch, type Cleanup, type ComputedOptions, createScope, type EffectCallback, type MaybeCleanup, type MemoCallback, type Signal, type SignalOptions, SKIP_EQUALITY, type TaskCallback, untrack, } from './src/graph';
+export { type Collection, type CollectionCallback, type CollectionChanges, type CollectionOptions, createCollection, type DeriveCollectionCallback, isCollection, } from './src/nodes/collection';
 export { createEffect, type MatchHandlers, type MaybePromise, match, } from './src/nodes/effect';
-export { createList, type DiffResult, isEqual, isList, type KeyConfig, type List, type ListOptions, } from './src/nodes/list';
+export { createList, isEqual, isList, type KeyConfig, type List, type ListOptions, } from './src/nodes/list';
 export { createMemo, isMemo, type Memo } from './src/nodes/memo';
-export { createSensor, isSensor, type Sensor, type SensorCallback, } from './src/nodes/sensor';
+export { createSensor, isSensor, type Sensor, type SensorCallback, type SensorOptions, } from './src/nodes/sensor';
 export { createState, isState, type State, type UpdateCallback, } from './src/nodes/state';
 export { createStore, isStore, type Store, type StoreOptions, } from './src/nodes/store';
 export { createTask, isTask, type Task } from './src/nodes/task';

package/types/src/graph.d.ts

@@ -76,6 +76,16 @@ type ComputedOptions<T extends {}> = SignalOptions<T> & {
      * Useful for reducer patterns so that calculations start with a value of correct type.
      */
     value?: T;
+    /**
+     * Optional callback invoked when the signal is first watched by an effect.
+     * Receives an `invalidate` function that marks the signal dirty and triggers re-evaluation.
+     * Must return a cleanup function that is called when the signal is no longer watched.
+     *
+     * This enables lazy resource activation for computed signals that need to
+     * react to external events (e.g. DOM mutations, timers) in addition to
+     * tracked signal dependencies.
+     */
+    watched?: (invalidate: () => void) => Cleanup;
 };
 /**
  * A callback function for memos that computes a value based on the previous value.
@@ -97,7 +107,7 @@ type TaskCallback<T extends {}> = (prev: T | undefined, signal: AbortSignal) =>
 /**
  * A callback function for effects that can perform side effects.
  *
- * @param match - A function to register cleanup callbacks that will be called before the effect re-runs or is disposed
+ * @returns An optional cleanup function that will be called before the effect re-runs or is disposed
  */
 type EffectCallback = () => MaybeCleanup;
 declare const TYPE_STATE = "State";
@@ -205,4 +215,4 @@ declare function untrack<T>(fn: () => T): T;
  * ```
  */
 declare function createScope(fn: () => MaybeCleanup): Cleanup;
-export { type Cleanup, type ComputedOptions, type EffectCallback, type EffectNode, type MaybeCleanup, type MemoCallback, type MemoNode, type Scope, type Signal, type SignalOptions, type SinkNode, type StateNode, type TaskCallback, type TaskNode, activeOwner, activeSink, batch, batchDepth, createScope, DEFAULT_EQUALITY as defaultEquals, SKIP_EQUALITY, FLAG_CLEAN, FLAG_DIRTY, flush, link, propagate, refresh, registerCleanup, runCleanup, runEffect, setState, trimSources, TYPE_COLLECTION, TYPE_LIST, TYPE_MEMO, TYPE_SENSOR, TYPE_STATE, TYPE_STORE, TYPE_TASK, unlink, untrack, };
+export { type Cleanup, type ComputedOptions, type EffectCallback, type EffectNode, type MaybeCleanup, type MemoCallback, type MemoNode, type Scope, type Signal, type SignalOptions, type SinkNode, type StateNode, type TaskCallback, type TaskNode, activeOwner, activeSink, batch, batchDepth, createScope, DEFAULT_EQUALITY, SKIP_EQUALITY, FLAG_CLEAN, FLAG_DIRTY, flush, link, propagate, refresh, registerCleanup, runCleanup, runEffect, setState, trimSources, TYPE_COLLECTION, TYPE_LIST, TYPE_MEMO, TYPE_SENSOR, TYPE_STATE, TYPE_STORE, TYPE_TASK, unlink, untrack, };

package/types/src/nodes/collection.d.ts

@@ -1,5 +1,5 @@
 import { type Cleanup, type Signal } from '../graph';
-import { type DiffResult, type KeyConfig, type List } from './list';
+import { type KeyConfig, type List } from './list';
 type CollectionSource<T extends {}> = List<T> | Collection<T>;
 type DeriveCollectionCallback<T extends {}, U extends {}> = ((sourceValue: U) => T) | ((sourceValue: U, abort: AbortSignal) => Promise<T>);
 type Collection<T extends {}> = {
@@ -16,12 +16,17 @@ type Collection<T extends {}> = {
     deriveCollection<R extends {}>(callback: (sourceValue: T, abort: AbortSignal) => Promise<R>): Collection<R>;
     readonly length: number;
 };
+type CollectionChanges<T> = {
+    add?: T[];
+    change?: T[];
+    remove?: T[];
+};
 type CollectionOptions<T extends {}> = {
     value?: T[];
     keyConfig?: KeyConfig<T>;
-    createItem?: (key: string, value: T) => Signal<T>;
+    createItem?: (value: T) => Signal<T>;
 };
-type CollectionCallback = (applyChanges: (changes: DiffResult) => void) => Cleanup;
+type CollectionCallback<T extends {}> = (apply: (changes: CollectionChanges<T>) => void) => Cleanup;
 /**
  * Creates a derived Collection from a List or another Collection with item-level memoization.
  * Sync callbacks use createMemo, async callbacks use createTask.
@@ -36,15 +41,15 @@ declare function deriveCollection<T extends {}, U extends {}>(source: Collection
 declare function deriveCollection<T extends {}, U extends {}>(source: CollectionSource<U>, callback: (sourceValue: U, abort: AbortSignal) => Promise<T>): Collection<T>;
 /**
  * Creates an externally-driven Collection with a watched lifecycle.
- * Items are managed by the start callback via `applyChanges(diffResult)`.
+ * Items are managed via the `applyChanges(changes)` helper passed to the watched callback.
  * The collection activates when first accessed by an effect and deactivates when no longer watched.
  *
  * @since 0.18.0
- * @param start - Callback invoked when the collection starts being watched, receives applyChanges helper
+ * @param watched - Callback invoked when the collection starts being watched, receives applyChanges helper
  * @param options - Optional configuration including initial value, key generation, and item signal creation
  * @returns A read-only Collection signal
  */
-declare function createCollection<T extends {}>(start: CollectionCallback, options?: CollectionOptions<T>): Collection<T>;
+declare function createCollection<T extends {}>(watched: CollectionCallback<T>, options?: CollectionOptions<T>): Collection<T>;
 /**
  * Checks if a value is a Collection signal.
  *
@@ -61,4 +66,4 @@ declare function isCollection<T extends {}>(value: unknown): value is Collection
  * @returns True if the value is a List or Collection
  */
 declare function isCollectionSource<T extends {}>(value: unknown): value is CollectionSource<T>;
-export { createCollection, deriveCollection, isCollection, isCollectionSource, type Collection, type CollectionCallback, type CollectionOptions, type CollectionSource, type DeriveCollectionCallback, };
+export { createCollection, deriveCollection, isCollection, isCollectionSource, type Collection, type CollectionCallback, type CollectionChanges, type CollectionOptions, type CollectionSource, type DeriveCollectionCallback, };