@zeix/cause-effect 0.18.0 → 0.18.2

package/src/nodes/store.ts

@@ -6,6 +6,7 @@ import {
 	type Cleanup,
 	FLAG_CLEAN,
 	FLAG_DIRTY,
+	FLAG_RELINK,
 	flush,
 	link,
 	type MemoNode,
@@ -15,7 +16,7 @@ import {
 	TYPE_STORE,
 	untrack,
 } from '../graph'
-import { isFunction, isObjectOfType, isRecord } from '../util'
+import { isObjectOfType, isRecord } from '../util'
 import {
 	createList,
 	type DiffResult,
@@ -51,8 +52,8 @@ type BaseStore<T extends UnknownRecord> = {
 				? State<T[K] & {}>
 				: State<T[K] & {}> | undefined
 	get(): T
-	set(newValue: T): void
-	update(fn: (oldValue: T) => T): void
+	set(next: T): void
+	update(fn: (prev: T) => T): void
 	add<K extends keyof T & string>(key: K, value: T[K]): K
 	remove(key: string): void
 }
@@ -70,21 +71,18 @@ type Store<T extends UnknownRecord> = BaseStore<T> & {
 /* === Functions === */
 
 /** Diff two records and return granular changes */
-function diffRecords<T extends UnknownRecord>(
-	oldObj: T,
-	newObj: T,
-): DiffResult {
+function diffRecords<T extends UnknownRecord>(prev: T, next: T): DiffResult {
 	// Guard against non-objects that can't be diffed properly with Object.keys and 'in' operator
-	const oldValid = isRecord(oldObj) || Array.isArray(oldObj)
-	const newValid = isRecord(newObj) || Array.isArray(newObj)
-	if (!oldValid || !newValid) {
+	const prevValid = isRecord(prev) || Array.isArray(prev)
+	const nextValid = isRecord(next) || Array.isArray(next)
+	if (!prevValid || !nextValid) {
 		// For non-objects or non-plain objects, treat as complete change if different
-		const changed = !Object.is(oldObj, newObj)
+		const changed = !Object.is(prev, next)
 		return {
 			changed,
-			add: changed && newValid ? newObj : {},
+			add: changed && nextValid ? next : {},
 			change: {},
-			remove: changed && oldValid ? oldObj : {},
+			remove: changed && prevValid ? prev : {},
 		}
 	}
 
@@ -95,25 +93,25 @@ function diffRecords<T extends UnknownRecord>(
 	const remove = {} as UnknownRecord
 	let changed = false
 
-	const oldKeys = Object.keys(oldObj)
-	const newKeys = Object.keys(newObj)
+	const prevKeys = Object.keys(prev)
+	const nextKeys = Object.keys(next)
 
 	// Pass 1: iterate new keys — find additions and changes
-	for (const key of newKeys) {
-		if (key in oldObj) {
-			if (!isEqual(oldObj[key], newObj[key], visited)) {
-				change[key] = newObj[key]
+	for (const key of nextKeys) {
+		if (key in prev) {
+			if (!isEqual(prev[key], next[key], visited)) {
+				change[key] = next[key]
 				changed = true
 			}
 		} else {
-			add[key] = newObj[key]
+			add[key] = next[key]
 			changed = true
 		}
 	}
 
 	// Pass 2: iterate old keys — find removals
-	for (const key of oldKeys) {
-		if (!(key in newObj)) {
+	for (const key of prevKeys) {
+		if (!(key in next)) {
 			remove[key] = undefined
 			changed = true
 		}
@@ -128,7 +126,7 @@ function diffRecords<T extends UnknownRecord>(
  * Properties are accessible directly via proxy.
  *
  * @since 0.15.0
- * @param initialValue - Initial object value of the store
+ * @param value - Initial object value of the store
  * @param options - Optional configuration for watch lifecycle
  * @returns A Store with reactive properties
  *
@@ -140,10 +138,10 @@ function diffRecords<T extends UnknownRecord>(
  * ```
  */
 function createStore<T extends UnknownRecord>(
-	initialValue: T,
+	value: T,
 	options?: StoreOptions,
 ): Store<T> {
-	validateSignalValue(TYPE_STORE, initialValue, isRecord)
+	validateSignalValue(TYPE_STORE, value, isRecord)
 
 	const signals = new Map<
 		string,
@@ -152,11 +150,11 @@ function createStore<T extends UnknownRecord>(
 
 	// --- Internal helpers ---
 
-	const addSignal = (key: string, value: unknown): void => {
-		validateSignalValue(`${TYPE_STORE} for key "${key}"`, value)
-		if (Array.isArray(value)) signals.set(key, createList(value))
-		else if (isRecord(value)) signals.set(key, createStore(value))
-		else signals.set(key, createState(value as unknown & {}))
+	const addSignal = (key: string, val: unknown): void => {
+		validateSignalValue(`${TYPE_STORE} for key "${key}"`, val)
+		if (Array.isArray(val)) signals.set(key, createList(val))
+		else if (isRecord(val)) signals.set(key, createStore(val))
+		else signals.set(key, createState(val as unknown & {}))
 	}
 
 	// Build current value from child signals
@@ -171,10 +169,10 @@ 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: initialValue,
+		value,
 		flags: FLAG_DIRTY,
 		sources: null,
 		sourcesTail: null,
@@ -197,15 +195,15 @@ function createStore<T extends UnknownRecord>(
 		if (Object.keys(changes.change).length) {
 			batch(() => {
 				for (const key in changes.change) {
-					const value = changes.change[key]
-					validateSignalValue(`${TYPE_STORE} for key "${key}"`, value)
+					const val = changes.change[key]
+					validateSignalValue(`${TYPE_STORE} for key "${key}"`, val)
 					const signal = signals.get(key)
 					if (signal) {
 						// Type changed (e.g. primitive → object or vice versa): replace signal
-						if (isRecord(value) !== isStore(signal)) {
-							addSignal(key, value)
+						if (isRecord(val) !== isStore(signal)) {
+							addSignal(key, val)
 							structural = true
-						} else signal.set(value as never)
+						} else signal.set(val as never)
 					}
 				}
 			})
@@ -217,17 +215,25 @@ function createStore<T extends UnknownRecord>(
 			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 ---
-	for (const key of Object.keys(initialValue))
-		addSignal(key, initialValue[key])
+	for (const key of Object.keys(value)) addSignal(key, value[key])
 
 	// --- Store object ---
 	const store: BaseStore<T> = {
@@ -250,11 +256,7 @@ function createStore<T extends UnknownRecord>(
 		},
 
 		keys() {
-			if (activeSink) {
-				if (!node.sinks && options?.watched)
-					node.stop = options.watched()
-				link(node, activeSink)
-			}
+			subscribe()
 			return signals.keys()
 		},
 
@@ -270,18 +272,24 @@ function createStore<T extends UnknownRecord>(
 		},
 
 		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
 				// 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
@@ -291,16 +299,14 @@ function createStore<T extends UnknownRecord>(
 			return node.value
 		},
 
-		set(newValue: T) {
+		set(next: T) {
 			// Use cached value if clean, recompute if dirty
-			const currentValue =
-				node.flags & FLAG_DIRTY ? buildValue() : node.value
+			const prev = node.flags & FLAG_DIRTY ? buildValue() : node.value
 
-			const changes = diffRecords(currentValue, newValue)
+			const changes = diffRecords(prev, next)
 			if (applyChanges(changes)) {
-				// Call propagate BEFORE marking dirty to ensure it doesn't early-return
-				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()
 			}
 		},
@@ -313,10 +319,8 @@ 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
-			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
 		},
@@ -324,10 +328,8 @@ function createStore<T extends UnknownRecord>(
 		remove(key: string) {
 			const ok = signals.delete(key)
 			if (ok) {
-				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()
 			}
 		},
@@ -336,10 +338,7 @@ function createStore<T extends UnknownRecord>(
 	// --- Proxy ---
 	return new Proxy(store, {
 		get(target, prop) {
-			if (prop in target) {
-				const value = Reflect.get(target, prop)
-				return isFunction(value) ? value.bind(target) : value
-			}
+			if (prop in target) return Reflect.get(target, prop)
 			if (typeof prop !== 'symbol')
 				return target.byKey(prop as keyof T & string)
 		},

package/src/nodes/task.ts

@@ -5,10 +5,13 @@ import {
 } from '../errors'
 import {
 	activeSink,
+	batchDepth,
 	type ComputedOptions,
-	defaultEquals,
+	DEFAULT_EQUALITY,
 	FLAG_DIRTY,
+	flush,
 	link,
+	propagate,
 	refresh,
 	type SinkNode,
 	type TaskCallback,
@@ -62,6 +65,12 @@ type Task<T extends {}> = {
  * @template T - The type of value resolved by the task
  * @param fn - The async computation function that receives the previous value and an AbortSignal
  * @param options - Optional configuration for the task
+ * @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 task is first watched by an effect.
+ *   Receives an `invalidate` function to mark the task dirty and trigger re-execution.
+ *   Must return a cleanup function called when no effects are watching.
  * @returns A Task object with get(), isPending(), and abort() methods
  *
  * @example
@@ -108,15 +117,34 @@ function createTask<T extends {}>(
 		sinks: null,
 		sinksTail: null,
 		flags: FLAG_DIRTY,
-		equals: options?.equals ?? defaultEquals,
+		equals: options?.equals ?? DEFAULT_EQUALITY,
 		controller: undefined,
 		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_TASK,
 		get(): T {
-			if (activeSink) link(node, activeSink)
+			subscribe()
 			refresh(node as unknown as SinkNode)
 			if (node.error) throw node.error
 			validateReadValue(TYPE_TASK, node.value)

package/test/collection.test.ts

@@ -1,12 +1,12 @@
 import { describe, expect, test } from 'bun:test'
 import {
 	batch,
+	type CollectionChanges,
 	createCollection,
 	createEffect,
 	createList,
 	createScope,
 	createState,
-	type DiffResult,
 	isCollection,
 	isList,
 } from '../index.ts'
@@ -88,7 +88,7 @@ describe('Collection', () => {
 			let guardCalled = false
 			const col = createCollection(() => () => {}, {
 				value: [5, 10],
-				createItem: (_key, value) =>
+				createItem: value =>
 					createState(value, {
 						guard: (v): v is number => {
 							guardCalled = true
@@ -174,7 +174,9 @@ describe('Collection', () => {
 
 	describe('applyChanges', () => {
 		test('should add items', () => {
-			let apply: ((changes: DiffResult) => void) | undefined
+			let apply:
+				| ((changes: CollectionChanges<number>) => void)
+				| undefined
 			const col = createCollection<number>(applyChanges => {
 				apply = applyChanges
 				return () => {}
@@ -190,12 +192,7 @@ describe('Collection', () => {
 			expect(values).toEqual([[]])
 
 			// biome-ignore lint/style/noNonNullAssertion: test
-			apply!({
-				changed: true,
-				add: { a: 1, b: 2 },
-				change: {},
-				remove: {},
-			})
+			apply!({ add: [1, 2] })
 
 			expect(values.length).toBe(2)
 			expect(values[1]).toEqual([1, 2])
@@ -205,7 +202,11 @@ describe('Collection', () => {
 		})
 
 		test('should change item values', () => {
-			let apply: ((changes: DiffResult) => void) | undefined
+			let apply:
+				| ((
+						changes: CollectionChanges<{ id: string; val: number }>,
+				  ) => void)
+				| undefined
 			const col = createCollection(
 				applyChanges => {
 					apply = applyChanges
@@ -227,12 +228,7 @@ describe('Collection', () => {
 			expect(values[0]).toEqual([{ id: 'x', val: 1 }])
 
 			// biome-ignore lint/style/noNonNullAssertion: test
-			apply!({
-				changed: true,
-				add: {},
-				change: { x: { id: 'x', val: 42 } },
-				remove: {},
-			})
+			apply!({ change: [{ id: 'x', val: 42 }] })
 
 			expect(values.length).toBe(2)
 			expect(values[1]).toEqual([{ id: 'x', val: 42 }])
@@ -241,7 +237,11 @@ describe('Collection', () => {
 		})
 
 		test('should remove items', () => {
-			let apply: ((changes: DiffResult) => void) | undefined
+			let apply:
+				| ((
+						changes: CollectionChanges<{ id: string; v: number }>,
+				  ) => void)
+				| undefined
 			const col = createCollection(
 				applyChanges => {
 					apply = applyChanges
@@ -271,12 +271,7 @@ describe('Collection', () => {
 			])
 
 			// biome-ignore lint/style/noNonNullAssertion: test
-			apply!({
-				changed: true,
-				add: {},
-				change: {},
-				remove: { b: null },
-			})
+			apply!({ remove: [{ id: 'b', v: 2 }] })
 
 			expect(values.length).toBe(2)
 			expect(values[1]).toEqual([
@@ -289,7 +284,11 @@ describe('Collection', () => {
 		})
 
 		test('should handle mixed add/change/remove', () => {
-			let apply: ((changes: DiffResult) => void) | undefined
+			let apply:
+				| ((
+						changes: CollectionChanges<{ id: string; v: number }>,
+				  ) => void)
+				| undefined
 			const col = createCollection(
 				applyChanges => {
 					apply = applyChanges
@@ -313,10 +312,9 @@ describe('Collection', () => {
 
 			// biome-ignore lint/style/noNonNullAssertion: test
 			apply!({
-				changed: true,
-				add: { c: { id: 'c', v: 3 } },
-				change: { a: { id: 'a', v: 10 } },
-				remove: { b: null },
+				add: [{ id: 'c', v: 3 }],
+				change: [{ id: 'a', v: 10 }],
+				remove: [{ id: 'b', v: 2 }],
 			})
 
 			expect(values.length).toBe(2)
@@ -328,8 +326,10 @@ describe('Collection', () => {
 			dispose()
 		})
 
-		test('should skip when changed is false', () => {
-			let apply: ((changes: DiffResult) => void) | undefined
+		test('should skip when no changes provided', () => {
+			let apply:
+				| ((changes: CollectionChanges<number>) => void)
+				| undefined
 			const col = createCollection(
 				applyChanges => {
 					apply = applyChanges
@@ -349,7 +349,7 @@ describe('Collection', () => {
 			expect(callCount).toBe(1)
 
 			// biome-ignore lint/style/noNonNullAssertion: test
-			apply!({ changed: false, add: {}, change: {}, remove: {} })
+			apply!({})
 
 			expect(callCount).toBe(1)
 
@@ -357,7 +357,9 @@ describe('Collection', () => {
 		})
 
 		test('should trigger effects on structural changes', () => {
-			let apply: ((changes: DiffResult) => void) | undefined
+			let apply:
+				| ((changes: CollectionChanges<string>) => void)
+				| undefined
 			const col = createCollection<string>(applyChanges => {
 				apply = applyChanges
 				return () => {}
@@ -374,12 +376,7 @@ describe('Collection', () => {
 			expect(effectCount).toBe(1)
 
 			// biome-ignore lint/style/noNonNullAssertion: test
-			apply!({
-				changed: true,
-				add: { a: 'hello' },
-				change: {},
-				remove: {},
-			})
+			apply!({ add: ['hello'] })
 
 			expect(effectCount).toBe(2)
 			expect(col.length).toBe(1)
@@ -388,7 +385,9 @@ describe('Collection', () => {
 		})
 
 		test('should batch multiple calls', () => {
-			let apply: ((changes: DiffResult) => void) | undefined
+			let apply:
+				| ((changes: CollectionChanges<number>) => void)
+				| undefined
 			const col = createCollection<number>(applyChanges => {
 				apply = applyChanges
 				return () => {}
@@ -406,19 +405,9 @@ describe('Collection', () => {
 
 			batch(() => {
 				// biome-ignore lint/style/noNonNullAssertion: test
-				apply!({
-					changed: true,
-					add: { a: 1 },
-					change: {},
-					remove: {},
-				})
+				apply!({ add: [1] })
 				// biome-ignore lint/style/noNonNullAssertion: test
-				apply!({
-					changed: true,
-					add: { b: 2 },
-					change: {},
-					remove: {},
-				})
+				apply!({ add: [2] })
 			})
 
 			expect(effectCount).toBe(2)