@zeix/cause-effect 0.18.1 → 0.18.3

package/src/nodes/collection.ts

@@ -9,6 +9,7 @@ import {
 	type Cleanup,
 	FLAG_CLEAN,
 	FLAG_DIRTY,
+	FLAG_RELINK,
 	link,
 	type MemoNode,
 	propagate,
@@ -99,10 +100,6 @@ function deriveCollection<T extends {}, U extends {}>(
 	callback: DeriveCollectionCallback<T, U>,
 ): Collection<T> {
 	validateCallback(TYPE_COLLECTION, callback)
-	if (!isCollectionSource(source))
-		throw new TypeError(
-			`[${TYPE_COLLECTION}] Invalid collection source: expected a List or Collection`,
-		)
 
 	const isAsync = isAsyncFunction(callback)
 	const signals = new Map<string, Memo<T>>()
@@ -129,13 +126,10 @@ function deriveCollection<T extends {}, U extends {}>(
 		signals.set(key, signal as Memo<T>)
 	}
 
-	// Sync signals map with source keys, reading source.keys()
-	// to establish a graph edge from source → this node.
+	// Sync signals map with the given keys.
 	// Intentionally side-effectful: mutates the private signals map and keys
-	// array. The side effects are idempotent and scoped to private state.
-	function syncKeys(): void {
-		const nextKeys = Array.from(source.keys())
-
+	// array. Sets FLAG_RELINK on the node if keys changed.
+	function syncKeys(nextKeys: string[]): void {
 		if (!keysEqual(keys, nextKeys)) {
 			const a = new Set(keys)
 			const b = new Set(nextKeys)
@@ -143,19 +137,15 @@ function deriveCollection<T extends {}, U extends {}>(
 			for (const key of keys) if (!b.has(key)) signals.delete(key)
 			for (const key of nextKeys) if (!a.has(key)) addSignal(key)
 			keys = nextKeys
-
-			// Force re-establishment of edges on next refresh() so new
-			// child signals are properly linked to this node
-			node.sources = null
-			node.sourcesTail = null
+			node.flags |= FLAG_RELINK
 		}
 	}
 
-	// Build current value from child signals; syncKeys runs first to
-	// ensure the signals map is up to date and — during refresh() —
-	// to establish the graph edge from source → this node.
+	// Build current value from child signals.
+	// Reads source.keys() to sync the signals map and — during refresh() —
+	// to establish a graph edge from source → this node.
 	function buildValue(): T[] {
-		syncKeys()
+		syncKeys(Array.from(source.keys()))
 		const result: T[] = []
 		for (const key of keys) {
 			try {
@@ -196,26 +186,40 @@ function deriveCollection<T extends {}, U extends {}>(
 		if (node.sources) {
 			if (node.flags) {
 				node.value = untrack(buildValue)
-				node.flags = FLAG_CLEAN
-				// syncKeys may have nulled sources if keys changed —
-				// re-run with refresh() to establish edges to new child signals
-				if (!node.sources) {
+				if (node.flags & FLAG_RELINK) {
+					// Keys changed — new child signals need graph edges.
+					// 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 {
+		} else if (node.sinks) {
+			// First access with a downstream subscriber — use refresh()
+			// to establish graph edges via recomputeMemo
 			refresh(node as unknown as SinkNode)
 			if (node.error) throw node.error
+		} else {
+			// No subscribers yet (e.g., chained deriveCollection init) —
+			// compute value without establishing graph edges to prevent
+			// premature watched activation on upstream sources.
+			// Keep FLAG_DIRTY so the first refresh() with a real subscriber
+			// will establish proper graph edges.
+			node.value = untrack(buildValue)
 		}
 	}
 
-	// Initialize signals for current source keys
-	const initialKeys = Array.from(source.keys())
+	// Initialize signals for current source keys — untrack to prevent
+	// triggering watched callbacks on upstream sources during construction.
+	// The first refresh() (triggered by an effect) will establish proper
+	// graph edges; this just populates the signals map for direct access.
+	const initialKeys = Array.from(untrack(() => source.keys()))
 	for (const key of initialKeys) addSignal(key)
 	keys = initialKeys
-	// Keep FLAG_DIRTY so the first refresh() establishes edges
+	// Keep FLAG_DIRTY so the first refresh() establishes edges.
 
 	const collection: Collection<T> = {
 		[Symbol.toStringTag]: TYPE_COLLECTION,
@@ -392,12 +396,8 @@ function createCollection<T extends {}>(
 							}
 						}
 
-						if (structural) {
-							node.sources = null
-							node.sourcesTail = null
-						}
 						// Mark DIRTY so next get() rebuilds; propagate to sinks
-						node.flags = FLAG_DIRTY
+						node.flags = FLAG_DIRTY | (structural ? FLAG_RELINK : 0)
 						for (let e = node.sinks; e; e = e.nextSink)
 							propagate(e.sink)
 					})
@@ -431,8 +431,18 @@ function createCollection<T extends {}>(
 			subscribe()
 			if (node.sources) {
 				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 {
 				refresh(node as unknown as SinkNode)

package/src/nodes/effect.ts

@@ -22,7 +22,7 @@ import {
 
 type MaybePromise<T> = T | Promise<T>
 
-type MatchHandlers<T extends Signal<unknown & {}>[]> = {
+type MatchHandlers<T extends readonly Signal<unknown & {}>[]> = {
 	ok: (values: {
 		[K in keyof T]: T[K] extends Signal<infer V> ? V : never
 	}) => MaybePromise<MaybeCleanup>
@@ -94,8 +94,8 @@ function createEffect(fn: EffectCallback): Cleanup {
  * @since 0.15.0
  * @throws RequiredOwnerError If called without an active owner.
  */
-function match<T extends Signal<unknown & {}>[]>(
-	signals: T,
+function match<T extends readonly Signal<unknown & {}>[]>(
+	signals: readonly [...T],
 	handlers: MatchHandlers<T>,
 ): MaybeCleanup {
 	if (!activeOwner) throw new RequiredOwnerError('match')

package/src/nodes/list.ts

@@ -10,6 +10,7 @@ import {
 	type Cleanup,
 	FLAG_CLEAN,
 	FLAG_DIRTY,
+	FLAG_RELINK,
 	flush,
 	link,
 	type MemoNode,
@@ -263,7 +264,7 @@ 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,
@@ -325,10 +326,7 @@ function createList<T extends {}>(
 			structural = true
 		}
 
-		if (structural) {
-			node.sources = null
-			node.sourcesTail = null
-		}
+		if (structural) node.flags |= FLAG_RELINK
 
 		return changes.changed
 	}
@@ -380,8 +378,18 @@ function createList<T extends {}>(
 			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
@@ -441,9 +449,7 @@ 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
-			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,9 +465,7 @@ function createList<T extends {}>(
 						? keyOrIndex
 						: keys.indexOf(key)
 				if (index >= 0) keys.splice(index, 1)
-				node.sources = null
-				node.sourcesTail = null
-				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()
 			}

package/src/nodes/slot.ts

@@ -0,0 +1,134 @@
+import { ReadonlySignalError, validateSignalValue } from '../errors'
+import {
+	activeSink,
+	batchDepth,
+	DEFAULT_EQUALITY,
+	FLAG_DIRTY,
+	flush,
+	link,
+	type MemoNode,
+	propagate,
+	refresh,
+	type Signal,
+	type SignalOptions,
+	type SinkNode,
+	TYPE_SLOT,
+} from '../graph'
+import { isMutableSignal, isSignal } from '../signal'
+import { isObjectOfType } from '../util'
+
+/* === Types === */
+
+/**
+ * A signal that delegates its value to a swappable backing signal.
+ *
+ * Slots provide a stable reactive source at a fixed position (e.g. an object property)
+ * while allowing the backing signal to be replaced without breaking subscribers.
+ * The object shape is compatible with `Object.defineProperty()` descriptors:
+ * `get`, `set`, `configurable`, and `enumerable` are used by the property definition;
+ * `replace()` and `current()` are kept on the slot object for integration-layer control.
+ *
+ * @template T - The type of value held by the delegated signal.
+ */
+type Slot<T extends {}> = {
+	readonly [Symbol.toStringTag]: 'Slot'
+	/** Descriptor field: allows the property to be redefined or deleted. */
+	configurable: true
+	/** Descriptor field: the property shows up during enumeration. */
+	enumerable: true
+	/** Reads the current value from the delegated signal, tracking dependencies. */
+	get(): T
+	/** Writes a value to the delegated signal. Throws `ReadonlySignalError` if the delegated signal is read-only. */
+	set(next: T): void
+	/** Swaps the backing signal, invalidating all downstream subscribers. Narrowing (`U extends T`) is allowed. */
+	replace<U extends T>(next: Signal<U>): void
+	/** Returns the currently delegated signal. */
+	current(): Signal<T>
+}
+
+/* === Exported Functions === */
+
+/**
+ * Creates a slot signal that delegates its value to a swappable backing signal.
+ *
+ * A slot acts as a stable reactive source that can be used as a property descriptor
+ * via `Object.defineProperty(target, key, slot)`. Subscribers link to the slot itself,
+ * so replacing the backing signal with `replace()` invalidates them without breaking
+ * existing edges. Setter calls forward to the current backing signal when it is writable.
+ *
+ * @since 0.18.3
+ * @template T - The type of value held by the delegated signal.
+ * @param initialSignal - The initial signal to delegate to.
+ * @param options - Optional configuration for the slot.
+ * @param options.equals - Custom equality function. Defaults to strict equality (`===`).
+ * @param options.guard - Type guard to validate values passed to `set()`.
+ * @returns A `Slot<T>` object usable both as a property descriptor and as a reactive signal.
+ */
+function createSlot<T extends {}>(
+	initialSignal: Signal<T>,
+	options?: SignalOptions<T>,
+): Slot<T> {
+	validateSignalValue(TYPE_SLOT, initialSignal, isSignal)
+
+	let delegated = initialSignal as Signal<T>
+	const guard = options?.guard
+
+	const node: MemoNode<T> = {
+		fn: () => delegated.get(),
+		value: undefined as unknown as T,
+		flags: FLAG_DIRTY,
+		sources: null,
+		sourcesTail: null,
+		sinks: null,
+		sinksTail: null,
+		equals: options?.equals ?? DEFAULT_EQUALITY,
+		error: undefined,
+	}
+
+	const get = (): T => {
+		if (activeSink) link(node, activeSink)
+		refresh(node as unknown as SinkNode)
+		if (node.error) throw node.error
+		return node.value
+	}
+
+	const set = (next: T): void => {
+		if (!isMutableSignal(delegated))
+			throw new ReadonlySignalError(TYPE_SLOT)
+		validateSignalValue(TYPE_SLOT, next, guard)
+
+		delegated.set(next)
+	}
+
+	const replace = <U extends T>(next: Signal<U>): void => {
+		validateSignalValue(TYPE_SLOT, next, isSignal)
+
+		delegated = next
+		node.flags |= FLAG_DIRTY
+		for (let e = node.sinks; e; e = e.nextSink) propagate(e.sink)
+		if (batchDepth === 0) flush()
+	}
+
+	return {
+		[Symbol.toStringTag]: TYPE_SLOT,
+		configurable: true,
+		enumerable: true,
+		get,
+		set,
+		replace,
+		current: () => delegated,
+	}
+}
+
+/**
+ * Checks if a value is a Slot signal.
+ *
+ * @since 0.18.3
+ * @param value - The value to check
+ * @returns True if the value is a Slot
+ */
+function isSlot<T extends {} = unknown & {}>(value: unknown): value is Slot<T> {
+	return isObjectOfType(value, TYPE_SLOT)
+}
+
+export { createSlot, isSlot, type Slot }

package/src/nodes/store.ts

@@ -6,6 +6,7 @@ import {
 	type Cleanup,
 	FLAG_CLEAN,
 	FLAG_DIRTY,
+	FLAG_RELINK,
 	flush,
 	link,
 	type MemoNode,
@@ -168,7 +169,7 @@ function createStore<T extends UnknownRecord>(
 	// 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) 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,
@@ -214,10 +215,7 @@ function createStore<T extends UnknownRecord>(
 			structural = true
 		}
 
-		if (structural) {
-			node.sources = null
-			node.sourcesTail = null
-		}
+		if (structural) node.flags |= FLAG_RELINK
 
 		return changes.changed
 	}
@@ -280,8 +278,18 @@ function createStore<T extends UnknownRecord>(
 				// from child signals using untrack to avoid creating spurious
 				// edges to the current effect/memo consumer
 				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 → store edges
@@ -311,9 +319,7 @@ function createStore<T extends UnknownRecord>(
 			if (signals.has(key))
 				throw new DuplicateKeyError(TYPE_STORE, key, value)
 			addSignal(key, value)
-			node.sources = null
-			node.sourcesTail = null
-			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
@@ -322,9 +328,7 @@ function createStore<T extends UnknownRecord>(
 		remove(key: string) {
 			const ok = signals.delete(key)
 			if (ok) {
-				node.sources = null
-				node.sourcesTail = null
-				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()
 			}

package/src/signal.ts

@@ -8,6 +8,7 @@ import {
 	TYPE_LIST,
 	TYPE_MEMO,
 	TYPE_SENSOR,
+	TYPE_SLOT,
 	TYPE_STATE,
 	TYPE_STORE,
 	TYPE_TASK,
@@ -122,6 +123,7 @@ function isSignal<T extends {}>(value: unknown): value is Signal<T> {
 		TYPE_MEMO,
 		TYPE_TASK,
 		TYPE_SENSOR,
+		TYPE_SLOT,
 		TYPE_LIST,
 		TYPE_COLLECTION,
 		TYPE_STORE,

package/test/effect.test.ts

@@ -249,6 +249,23 @@ describe('match', () => {
 		}
 	})
 
+	test('should preserve tuple types in ok handler', () => {
+		const a = createState(1)
+		const b = createState('hello')
+		createEffect(() =>
+			match([a, b], {
+				ok: ([aVal, bVal]) => {
+					// If tuple types are preserved, aVal is number and bVal is string
+					// If widened, both would be string | number
+					const num: number = aVal
+					const str: string = bVal
+					expect(num).toBe(1)
+					expect(str).toBe('hello')
+				},
+			}),
+		)
+	})
+
 	test('should throw RequiredOwnerError when called outside an owner', () => {
 		expect(() => match([], { ok: () => {} })).toThrow(RequiredOwnerError)
 	})

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', () => {