@zeix/cause-effect 0.18.0 → 0.18.2

package/src/nodes/list.ts

@@ -10,6 +10,7 @@ import {
 	type Cleanup,
 	FLAG_CLEAN,
 	FLAG_DIRTY,
+	FLAG_RELINK,
 	flush,
 	link,
 	type MemoNode,
@@ -39,7 +40,7 @@ type DiffResult = {
 	remove: UnknownRecord
 }
 
-type KeyConfig<T> = string | ((item: T) => string)
+type KeyConfig<T> = string | ((item: T) => string | undefined)
 
 type ListOptions<T extends {}> = {
 	keyConfig?: KeyConfig<T>
@@ -52,8 +53,8 @@ type List<T extends {}> = {
 	[Symbol.iterator](): IterableIterator<State<T>>
 	readonly length: number
 	get(): T[]
-	set(newValue: T[]): void
-	update(fn: (oldValue: T[]) => T[]): void
+	set(next: T[]): void
+	update(fn: (prev: T[]) => T[]): void
 	at(index: number): State<T> | undefined
 	keys(): IterableIterator<string>
 	byKey(key: string): State<T> | undefined
@@ -77,19 +78,11 @@ type List<T extends {}> = {
  * Checks if two values are equal with cycle detection
  *
  * @since 0.15.0
- * @param {T} a - First value to compare
- * @param {T} b - Second value to compare
- * @param {WeakSet<object>} visited - Set to track visited objects for cycle detection
- * @returns {boolean} Whether the two values are equal
+ * @param a - First value to compare
+ * @param b - Second value to compare
+ * @param visited - Set to track visited objects for cycle detection
+ * @returns Whether the two values are equal
  */
-
-/** Shallow equality check for string arrays */
-function keysEqual(a: string[], b: string[]): boolean {
-	if (a.length !== b.length) return false
-	for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false
-	return true
-}
-
 function isEqual<T>(a: T, b: T, visited?: WeakSet<object>): boolean {
 	// Fast paths
 	if (Object.is(a, b)) return true
@@ -117,9 +110,8 @@ function isEqual<T>(a: T, b: T, visited?: WeakSet<object>): boolean {
 			const aa = a as unknown[]
 			const ba = b as unknown[]
 			if (aa.length !== ba.length) return false
-			for (let i = 0; i < aa.length; i++) {
+			for (let i = 0; i < aa.length; i++)
 				if (!isEqual(aa[i], ba[i], visited)) return false
-			}
 			return true
 		}
 
@@ -144,23 +136,45 @@ function isEqual<T>(a: T, b: T, visited?: WeakSet<object>): boolean {
 	}
 }
 
+/** Shallow equality check for string arrays */
+function keysEqual(a: string[], b: string[]): boolean {
+	if (a.length !== b.length) return false
+	for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false
+	return true
+}
+
+function getKeyGenerator<T extends {}>(
+	keyConfig?: KeyConfig<T>,
+): [(item: T) => string, boolean] {
+	let keyCounter = 0
+	const contentBased = typeof keyConfig === 'function'
+	return [
+		typeof keyConfig === 'string'
+			? () => `${keyConfig}${keyCounter++}`
+			: contentBased
+				? (item: T) => keyConfig(item) || String(keyCounter++)
+				: () => String(keyCounter++),
+		contentBased,
+	]
+}
+
 /**
  * Compares two arrays using existing keys and returns differences as a DiffResult.
  * Avoids object conversion by working directly with arrays and keys.
  *
  * @since 0.18.0
- * @param {T[]} oldArray - The old array
- * @param {T[]} newArray - The new array
- * @param {string[]} currentKeys - Current keys array (may be sparse or shorter than oldArray)
- * @param {(item: T) => string} generateKey - Function to generate keys for new items
- * @param {boolean} contentBased - When true, always use generateKey (content-based keys);
+ * @param prev - The old array
+ * @param next - The new array
+ * @param prevKeys - Current keys array (may be sparse or shorter than oldArray)
+ * @param generateKey - Function to generate keys for new items
+ * @param contentBased - When true, always use generateKey (content-based keys);
  *   when false, reuse positional keys from currentKeys (synthetic keys)
- * @returns {DiffResult & { newKeys: string[] }} The differences in DiffResult format plus updated keys array
+ * @returns The differences in DiffResult format plus updated keys array
  */
 function diffArrays<T>(
-	oldArray: T[],
-	newArray: T[],
-	currentKeys: string[],
+	prev: T[],
+	next: T[],
+	prevKeys: string[],
 	generateKey: (item: T) => string,
 	contentBased: boolean,
 ): DiffResult & { newKeys: string[] } {
@@ -168,50 +182,46 @@ function diffArrays<T>(
 	const add = {} as UnknownRecord
 	const change = {} as UnknownRecord
 	const remove = {} as UnknownRecord
-	const newKeys: string[] = []
+	const nextKeys: string[] = []
 	let changed = false
 
 	// Build a map of old values by key for quick lookup
-	const oldByKey = new Map<string, T>()
-	for (let i = 0; i < oldArray.length; i++) {
-		const key = currentKeys[i]
-		if (key && oldArray[i]) oldByKey.set(key, oldArray[i])
+	const prevByKey = new Map<string, T>()
+	for (let i = 0; i < prev.length; i++) {
+		const key = prevKeys[i]
+		if (key && prev[i]) prevByKey.set(key, prev[i])
 	}
 
 	// Track which old keys we've seen
 	const seenKeys = new Set<string>()
 
 	// Process new array and build new keys array
-	for (let i = 0; i < newArray.length; i++) {
-		const newValue = newArray[i]
-		if (newValue === undefined) continue
+	for (let i = 0; i < next.length; i++) {
+		const val = next[i]
+		if (val === undefined) continue
 
 		// Content-based keys: always derive from item; synthetic keys: reuse by position
 		const key = contentBased
-			? generateKey(newValue)
-			: (currentKeys[i] ?? generateKey(newValue))
+			? generateKey(val)
+			: (prevKeys[i] ?? generateKey(val))
 
-		if (seenKeys.has(key))
-			throw new DuplicateKeyError(TYPE_LIST, key, newValue)
+		if (seenKeys.has(key)) throw new DuplicateKeyError(TYPE_LIST, key, val)
 
-		newKeys.push(key)
+		nextKeys.push(key)
 		seenKeys.add(key)
 
 		// Check if this key existed before
-		if (!oldByKey.has(key)) {
-			add[key] = newValue
+		if (!prevByKey.has(key)) {
+			add[key] = val
+			changed = true
+		} else if (!isEqual(prevByKey.get(key), val, visited)) {
+			change[key] = val
 			changed = true
-		} else {
-			const oldValue = oldByKey.get(key)
-			if (!isEqual(oldValue, newValue, visited)) {
-				change[key] = newValue
-				changed = true
-			}
 		}
 	}
 
 	// Find removed keys (existed in old but not in new)
-	for (const [key] of oldByKey) {
+	for (const [key] of prevByKey) {
 		if (!seenKeys.has(key)) {
 			remove[key] = null
 			changed = true
@@ -219,37 +229,29 @@ function diffArrays<T>(
 	}
 
 	// Detect reorder even when no values changed
-	if (!changed && !keysEqual(currentKeys, newKeys)) changed = true
+	if (!changed && !keysEqual(prevKeys, nextKeys)) changed = true
 
-	return { add, change, remove, newKeys, changed }
+	return { add, change, remove, newKeys: nextKeys, changed }
 }
 
 /**
  * Creates a reactive list with stable keys and per-item reactivity.
  *
  * @since 0.18.0
- * @param initialValue - Initial array of items
+ * @param value - Initial array of items
  * @param options - Optional configuration for key generation and watch lifecycle
  * @returns A List signal
  */
 function createList<T extends {}>(
-	initialValue: T[],
+	value: T[],
 	options?: ListOptions<T>,
 ): List<T> {
-	validateSignalValue(TYPE_LIST, initialValue, Array.isArray)
+	validateSignalValue(TYPE_LIST, value, Array.isArray)
 
 	const signals = new Map<string, State<T>>()
 	let keys: string[] = []
 
-	let keyCounter = 0
-	const keyConfig = options?.keyConfig
-	const contentBased = isFunction<string>(keyConfig)
-	const generateKey: (item: T) => string =
-		typeof keyConfig === 'string'
-			? () => `${keyConfig}${keyCounter++}`
-			: contentBased
-				? (item: T) => keyConfig(item)
-				: () => String(keyCounter++)
+	const [generateKey, contentBased] = getKeyGenerator(options?.keyConfig)
 
 	// --- Internal helpers ---
 
@@ -262,10 +264,10 @@ function createList<T extends {}>(
 	// Structural tracking node — not a general-purpose Memo.
 	// On first get(): refresh() establishes edges from child signals.
 	// On subsequent get(): untrack(buildValue) rebuilds without re-linking.
-	// Mutation methods (add/remove/set/splice) null out sources to force re-establishment.
+	// Mutation methods set FLAG_RELINK to force re-establishment on next read.
 	const node: MemoNode<T[]> = {
 		fn: buildValue,
-		value: initialValue,
+		value,
 		flags: FLAG_DIRTY,
 		sources: null,
 		sourcesTail: null,
@@ -278,14 +280,14 @@ function createList<T extends {}>(
 	const toRecord = (array: T[]): Record<string, T> => {
 		const record = {} as Record<string, T>
 		for (let i = 0; i < array.length; i++) {
-			const value = array[i]
-			if (value === undefined) continue
+			const val = array[i]
+			if (val === undefined) continue
 			let key = keys[i]
 			if (!key) {
-				key = generateKey(value)
+				key = generateKey(val)
 				keys[i] = key
 			}
-			record[key] = value
+			record[key] = val
 		}
 		return record
 	}
@@ -295,9 +297,9 @@ function createList<T extends {}>(
 
 		// Additions
 		for (const key in changes.add) {
-			const value = changes.add[key] as T
-			validateSignalValue(`${TYPE_LIST} item for key "${key}"`, value)
-			signals.set(key, createState(value))
+			const val = changes.add[key] as T
+			validateSignalValue(`${TYPE_LIST} item for key "${key}"`, val)
+			signals.set(key, createState(val))
 			structural = true
 		}
 
@@ -305,13 +307,13 @@ function createList<T extends {}>(
 		if (Object.keys(changes.change).length) {
 			batch(() => {
 				for (const key in changes.change) {
-					const value = changes.change[key]
+					const val = changes.change[key]
 					validateSignalValue(
 						`${TYPE_LIST} item for key "${key}"`,
-						value,
+						val,
 					)
 					const signal = signals.get(key)
-					if (signal) signal.set(value as T)
+					if (signal) signal.set(val as T)
 				}
 			})
 		}
@@ -324,25 +326,34 @@ function createList<T extends {}>(
 			structural = true
 		}
 
-		if (structural) {
-			node.sources = null
-			node.sourcesTail = null
-		}
+		if (structural) node.flags |= FLAG_RELINK
 
 		return changes.changed
 	}
 
+	const watched = options?.watched
+	const subscribe = watched
+		? () => {
+				if (activeSink) {
+					if (!node.sinks) node.stop = watched()
+					link(node, activeSink)
+				}
+			}
+		: () => {
+				if (activeSink) link(node, activeSink)
+			}
+
 	// --- Initialize ---
-	const initRecord = toRecord(initialValue)
+	const initRecord = toRecord(value)
 	for (const key in initRecord) {
-		const value = initRecord[key]
-		validateSignalValue(`${TYPE_LIST} item for key "${key}"`, value)
-		signals.set(key, createState(value))
+		const val = initRecord[key]
+		validateSignalValue(`${TYPE_LIST} item for key "${key}"`, val)
+		signals.set(key, createState(val))
 	}
 
 	// Starts clean: mutation methods (add/remove/set/splice) explicitly call
 	// propagate() + invalidate edges, so refresh() on first get() is not needed.
-	node.value = initialValue
+	node.value = value
 	node.flags = 0
 
 	// --- List object ---
@@ -358,25 +369,27 @@ function createList<T extends {}>(
 		},
 
 		get length() {
-			if (activeSink) {
-				if (!node.sinks && options?.watched)
-					node.stop = options.watched()
-				link(node, activeSink)
-			}
+			subscribe()
 			return keys.length
 		},
 
 		get() {
-			if (activeSink) {
-				if (!node.sinks && options?.watched)
-					node.stop = options.watched()
-				link(node, activeSink)
-			}
+			subscribe()
 			if (node.sources) {
 				// Fast path: edges already established, rebuild value directly
 				if (node.flags) {
+					const relink = node.flags & FLAG_RELINK
 					node.value = untrack(buildValue)
-					node.flags = FLAG_CLEAN
+					if (relink) {
+						// Structural mutation added/removed child signals —
+						// tracked recompute so link() adds new edges and
+						// trimSources() removes stale ones without orphaning.
+						node.flags = FLAG_DIRTY
+						refresh(node as unknown as SinkNode)
+						if (node.error) throw node.error
+					} else {
+						node.flags = FLAG_CLEAN
+					}
 				}
 			} else {
 				// First access: use refresh() to establish child → list edges
@@ -386,12 +399,11 @@ function createList<T extends {}>(
 			return node.value
 		},
 
-		set(newValue: T[]) {
-			const currentValue =
-				node.flags & FLAG_DIRTY ? buildValue() : node.value
+		set(next: T[]) {
+			const prev = node.flags & FLAG_DIRTY ? buildValue() : node.value
 			const changes = diffArrays(
-				currentValue,
-				newValue,
+				prev,
+				next,
 				keys,
 				generateKey,
 				contentBased,
@@ -399,13 +411,13 @@ function createList<T extends {}>(
 			if (changes.changed) {
 				keys = changes.newKeys
 				applyChanges(changes)
-				propagate(node as unknown as SinkNode)
 				node.flags |= FLAG_DIRTY
+				for (let e = node.sinks; e; e = e.nextSink) propagate(e.sink)
 				if (batchDepth === 0) flush()
 			}
 		},
 
-		update(fn: (oldValue: T[]) => T[]) {
+		update(fn: (prev: T[]) => T[]) {
 			list.set(fn(list.get()))
 		},
 
@@ -414,11 +426,7 @@ function createList<T extends {}>(
 		},
 
 		keys() {
-			if (activeSink) {
-				if (!node.sinks && options?.watched)
-					node.stop = options.watched()
-				link(node, activeSink)
-			}
+			subscribe()
 			return keys.values()
 		},
 
@@ -441,10 +449,8 @@ function createList<T extends {}>(
 			if (!keys.includes(key)) keys.push(key)
 			validateSignalValue(`${TYPE_LIST} item for key "${key}"`, value)
 			signals.set(key, createState(value))
-			node.sources = null
-			node.sourcesTail = null
-			propagate(node as unknown as SinkNode)
-			node.flags |= FLAG_DIRTY
+			node.flags |= FLAG_DIRTY | FLAG_RELINK
+			for (let e = node.sinks; e; e = e.nextSink) propagate(e.sink)
 			if (batchDepth === 0) flush()
 			return key
 		},
@@ -459,10 +465,8 @@ function createList<T extends {}>(
 						? keyOrIndex
 						: keys.indexOf(key)
 				if (index >= 0) keys.splice(index, 1)
-				node.sources = null
-				node.sourcesTail = null
-				propagate(node as unknown as SinkNode)
-				node.flags |= FLAG_DIRTY
+				node.flags |= FLAG_DIRTY | FLAG_RELINK
+				for (let e = node.sinks; e; e = e.nextSink) propagate(e.sink)
 				if (batchDepth === 0) flush()
 			}
 		},
@@ -479,8 +483,8 @@ function createList<T extends {}>(
 
 			if (!keysEqual(keys, newOrder)) {
 				keys = newOrder
-				propagate(node as unknown as SinkNode)
 				node.flags |= FLAG_DIRTY
+				for (let e = node.sinks; e; e = e.nextSink) propagate(e.sink)
 				if (batchDepth === 0) flush()
 			}
 		},
@@ -538,8 +542,8 @@ function createList<T extends {}>(
 					changed,
 				})
 				keys = newOrder
-				propagate(node as unknown as SinkNode)
 				node.flags |= FLAG_DIRTY
+				for (let e = node.sinks; e; e = e.nextSink) propagate(e.sink)
 				if (batchDepth === 0) flush()
 			}
 
@@ -583,6 +587,7 @@ export {
 	createList,
 	isEqual,
 	isList,
+	getKeyGenerator,
 	keysEqual,
 	TYPE_LIST,
 }

package/src/nodes/memo.ts

@@ -5,12 +5,15 @@ import {
 } from '../errors'
 import {
 	activeSink,
+	batchDepth,
 	type ComputedOptions,
-	defaultEquals,
+	DEFAULT_EQUALITY,
 	FLAG_DIRTY,
+	flush,
 	link,
 	type MemoCallback,
 	type MemoNode,
+	propagate,
 	refresh,
 	type SinkNode,
 	TYPE_MEMO,
@@ -49,6 +52,12 @@ type Memo<T extends {}> = {
  * @template T - The type of value computed by the memo
  * @param fn - The computation function that receives the previous value
  * @param options - Optional configuration for the memo
+ * @param options.value - Optional initial value for reducer patterns
+ * @param options.equals - Optional equality function. Defaults to strict equality (`===`)
+ * @param options.guard - Optional type guard to validate values
+ * @param options.watched - Optional callback invoked when the memo is first watched by an effect.
+ *   Receives an `invalidate` function to mark the memo dirty and trigger recomputation.
+ *   Must return a cleanup function called when no effects are watching.
  * @returns A Memo object with a get() method
  *
  * @example
@@ -90,14 +99,33 @@ function createMemo<T extends {}>(
 		sourcesTail: null,
 		sinks: null,
 		sinksTail: null,
-		equals: options?.equals ?? defaultEquals,
+		equals: options?.equals ?? DEFAULT_EQUALITY,
 		error: undefined,
+		stop: undefined,
 	}
 
+	const watched = options?.watched
+	const subscribe = watched
+		? () => {
+				if (activeSink) {
+					if (!node.sinks)
+						node.stop = watched(() => {
+							node.flags |= FLAG_DIRTY
+							for (let e = node.sinks; e; e = e.nextSink)
+								propagate(e.sink)
+							if (batchDepth === 0) flush()
+						})
+					link(node, activeSink)
+				}
+			}
+		: () => {
+				if (activeSink) link(node, activeSink)
+			}
+
 	return {
 		[Symbol.toStringTag]: TYPE_MEMO,
 		get() {
-			if (activeSink) link(node, activeSink)
+			subscribe()
 			refresh(node as unknown as SinkNode)
 			if (node.error) throw node.error
 			validateReadValue(TYPE_MEMO, node.value)

package/src/nodes/sensor.ts

@@ -6,9 +6,9 @@ import {
 import {
 	activeSink,
 	type Cleanup,
-	type ComputedOptions,
-	defaultEquals,
+	DEFAULT_EQUALITY,
 	link,
+	type SignalOptions,
 	type StateNode,
 	setState,
 	TYPE_SENSOR,
@@ -27,7 +27,6 @@ type Sensor<T extends {}> = {
 
 	/**
 	 * Gets the current value of the sensor.
-	 * Updates its state value if the sensor is active.
 	 * When called inside another reactive context, creates a dependency.
 	 * @returns The sensor value
 	 * @throws UnsetSignalValueError If the sensor value is still unset when read.
@@ -42,6 +41,14 @@ type Sensor<T extends {}> = {
  * @param set - A function to set the observed value
  * @returns A cleanup function when the sensor stops being watched
  */
+type SensorOptions<T extends {}> = SignalOptions<T> & {
+	/**
+	 * Optional initial value. Avoids `UnsetSignalValueError` on first read
+	 * before the watched callback fires.
+	 */
+	value?: T
+}
+
 type SensorCallback<T extends {}> = (set: (next: T) => void) => Cleanup
 
 /* === Exported Functions === */
@@ -52,12 +59,12 @@ type SensorCallback<T extends {}> = (set: (next: T) => void) => Cleanup
  * no longer watched. This lazy activation pattern ensures resources are only consumed when needed.
  *
  * @since 0.18.0
- * @template T - The type of value stored in the state
- * @param start - The callback function that starts the sensor and returns a cleanup function.
- * @param options - Optional options for the sensor.
+ * @template T - The type of value produced by the sensor
+ * @param watched - The callback invoked when the sensor starts being watched, receives a `set` function and returns a cleanup function.
+ * @param options - Optional configuration for the sensor.
  * @param options.value - Optional initial value. Avoids `UnsetSignalValueError` on first read
- *   before the start callback fires. Essential for the mutable-object observation pattern.
- * @param options.equals - Optional equality function. Defaults to `Object.is`. Use `SKIP_EQUALITY`
+ *   before the watched callback fires. Essential for the mutable-object observation pattern.
+ * @param options.equals - Optional equality function. Defaults to strict equality (`===`). Use `SKIP_EQUALITY`
  *   for mutable objects where the reference stays the same but internal state changes.
  * @param options.guard - Optional type guard to validate values.
  * @returns A read-only sensor signal.
@@ -87,10 +94,10 @@ type SensorCallback<T extends {}> = (set: (next: T) => void) => Cleanup
  * ```
  */
 function createSensor<T extends {}>(
-	start: SensorCallback<T>,
-	options?: ComputedOptions<T>,
+	watched: SensorCallback<T>,
+	options?: SensorOptions<T>,
 ): Sensor<T> {
-	validateCallback(TYPE_SENSOR, start, isSyncFunction)
+	validateCallback(TYPE_SENSOR, watched, isSyncFunction)
 	if (options?.value !== undefined)
 		validateSignalValue(TYPE_SENSOR, options.value, options?.guard)
 
@@ -98,7 +105,7 @@ function createSensor<T extends {}>(
 		value: options?.value as T,
 		sinks: null,
 		sinksTail: null,
-		equals: options?.equals ?? defaultEquals,
+		equals: options?.equals ?? DEFAULT_EQUALITY,
 		guard: options?.guard,
 		stop: undefined,
 	}
@@ -107,11 +114,8 @@ function createSensor<T extends {}>(
 		[Symbol.toStringTag]: TYPE_SENSOR,
 		get(): T {
 			if (activeSink) {
-				// Start fires before link: synchronous set() inside start updates
-				// node.value without propagation (no sinks yet). The activating
-				// effect reads the updated value directly after link.
 				if (!node.sinks)
-					node.stop = start((next: T): void => {
+					node.stop = watched((next: T): void => {
 						validateSignalValue(TYPE_SENSOR, next, node.guard)
 						setState(node, next)
 					})
@@ -136,4 +140,10 @@ function isSensor<T extends {} = unknown & {}>(
 	return isObjectOfType(value, TYPE_SENSOR)
 }
 
-export { createSensor, isSensor, type Sensor, type SensorCallback }
+export {
+	createSensor,
+	isSensor,
+	type Sensor,
+	type SensorCallback,
+	type SensorOptions,
+}

package/src/nodes/state.ts

@@ -1,7 +1,7 @@
 import { validateCallback, validateSignalValue } from '../errors'
 import {
 	activeSink,
-	defaultEquals,
+	DEFAULT_EQUALITY,
 	link,
 	type SignalOptions,
 	type StateNode,
@@ -88,7 +88,7 @@ function createState<T extends {}>(
 		value,
 		sinks: null,
 		sinksTail: null,
-		equals: options?.equals ?? defaultEquals,
+		equals: options?.equals ?? DEFAULT_EQUALITY,
 		guard: options?.guard,
 	}