@zeix/cause-effect 0.17.3 → 0.18.1

package/src/nodes/collection.ts

@@ -0,0 +1,512 @@
+import {
+	UnsetSignalValueError,
+	validateCallback,
+	validateSignalValue,
+} from '../errors'
+import {
+	activeSink,
+	batch,
+	type Cleanup,
+	FLAG_CLEAN,
+	FLAG_DIRTY,
+	link,
+	type MemoNode,
+	propagate,
+	refresh,
+	type Signal,
+	type SinkNode,
+	SKIP_EQUALITY,
+	TYPE_COLLECTION,
+	untrack,
+} from '../graph'
+import { isAsyncFunction, isObjectOfType, isSyncFunction } from '../util'
+import {
+	getKeyGenerator,
+	isList,
+	type KeyConfig,
+	keysEqual,
+	type List,
+} from './list'
+import { createMemo, type Memo } from './memo'
+import { createState, isState } from './state'
+import { createTask } from './task'
+
+/* === Types === */
+
+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 {}> = {
+	readonly [Symbol.toStringTag]: 'Collection'
+	readonly [Symbol.isConcatSpreadable]: true
+	[Symbol.iterator](): IterableIterator<Signal<T>>
+	keys(): IterableIterator<string>
+	get(): T[]
+	at(index: number): Signal<T> | undefined
+	byKey(key: string): Signal<T> | undefined
+	keyAt(index: number): string | undefined
+	indexOfKey(key: string): number
+	deriveCollection<R extends {}>(
+		callback: (sourceValue: T) => R,
+	): Collection<R>
+	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?: (value: T) => Signal<T>
+}
+
+type CollectionCallback<T extends {}> = (
+	apply: (changes: CollectionChanges<T>) => void,
+) => Cleanup
+
+/* === Functions === */
+
+/**
+ * Creates a derived Collection from a List or another Collection with item-level memoization.
+ * Sync callbacks use createMemo, async callbacks use createTask.
+ * Structural changes are tracked reactively via the source's keys.
+ *
+ * @since 0.18.0
+ * @param source - The source List or Collection to derive from
+ * @param callback - Transformation function applied to each item
+ * @returns A Collection signal
+ */
+function deriveCollection<T extends {}, U extends {}>(
+	source: CollectionSource<U>,
+	callback: (sourceValue: U) => T,
+): Collection<T>
+function deriveCollection<T extends {}, U extends {}>(
+	source: CollectionSource<U>,
+	callback: (sourceValue: U, abort: AbortSignal) => Promise<T>,
+): Collection<T>
+function deriveCollection<T extends {}, U extends {}>(
+	source: CollectionSource<U>,
+	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>>()
+	let keys: string[] = []
+
+	const addSignal = (key: string): void => {
+		const signal = isAsync
+			? createTask(async (prev: T | undefined, abort: AbortSignal) => {
+					const sourceValue = source.byKey(key)?.get() as U
+					if (sourceValue == null) return prev as T
+					return (
+						callback as (
+							sourceValue: U,
+							abort: AbortSignal,
+						) => Promise<T>
+					)(sourceValue, abort)
+				})
+			: createMemo(() => {
+					const sourceValue = source.byKey(key)?.get() as U
+					if (sourceValue == null) return undefined as unknown as T
+					return (callback as (sourceValue: U) => T)(sourceValue)
+				})
+
+		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.
+	// 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())
+
+		if (!keysEqual(keys, nextKeys)) {
+			const a = new Set(keys)
+			const b = new Set(nextKeys)
+
+			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
+		}
+	}
+
+	// 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.
+	function buildValue(): T[] {
+		syncKeys()
+		const result: T[] = []
+		for (const key of keys) {
+			try {
+				const v = signals.get(key)?.get()
+				if (v != null) result.push(v)
+			} catch (e) {
+				// Skip pending async items; rethrow real errors
+				if (!(e instanceof UnsetSignalValueError)) throw e
+			}
+		}
+		return result
+	}
+
+	// Shallow reference equality for value arrays — prevents unnecessary
+	// downstream propagation when re-evaluation produces the same item references
+	const valuesEqual = (a: T[], b: T[]): 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
+	}
+
+	// Structural tracking node — mirrors the List/Store/createCollection pattern.
+	// fn (buildValue) syncs keys then reads child signals to produce T[].
+	// Keys are tracked separately in a local variable.
+	const node: MemoNode<T[]> = {
+		fn: buildValue,
+		value: [],
+		flags: FLAG_DIRTY,
+		sources: null,
+		sourcesTail: null,
+		sinks: null,
+		sinksTail: null,
+		equals: valuesEqual,
+		error: undefined,
+	}
+
+	function ensureFresh(): void {
+		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) {
+					node.flags = FLAG_DIRTY
+					refresh(node as unknown as SinkNode)
+					if (node.error) throw node.error
+				}
+			}
+		} else {
+			refresh(node as unknown as SinkNode)
+			if (node.error) throw node.error
+		}
+	}
+
+	// Initialize signals for current source keys
+	const initialKeys = Array.from(source.keys())
+	for (const key of initialKeys) addSignal(key)
+	keys = initialKeys
+	// Keep FLAG_DIRTY so the first refresh() establishes edges
+
+	const collection: Collection<T> = {
+		[Symbol.toStringTag]: TYPE_COLLECTION,
+		[Symbol.isConcatSpreadable]: true as const,
+
+		*[Symbol.iterator]() {
+			for (const key of keys) {
+				const signal = signals.get(key)
+				if (signal) yield signal
+			}
+		},
+
+		get length() {
+			if (activeSink) link(node, activeSink)
+			ensureFresh()
+			return keys.length
+		},
+
+		keys() {
+			if (activeSink) link(node, activeSink)
+			ensureFresh()
+			return keys.values()
+		},
+
+		get() {
+			if (activeSink) link(node, activeSink)
+			ensureFresh()
+			return node.value
+		},
+
+		at(index: number) {
+			return signals.get(keys[index])
+		},
+
+		byKey(key: string) {
+			return signals.get(key)
+		},
+
+		keyAt(index: number) {
+			return keys[index]
+		},
+
+		indexOfKey(key: string) {
+			return keys.indexOf(key)
+		},
+
+		deriveCollection<R extends {}>(
+			cb: DeriveCollectionCallback<R, T>,
+		): Collection<R> {
+			return (
+				deriveCollection as <T2 extends {}, U2 extends {}>(
+					source: CollectionSource<U2>,
+					callback: DeriveCollectionCallback<T2, U2>,
+				) => Collection<T2>
+			)(collection, cb)
+		},
+	}
+
+	return collection
+}
+
+/**
+ * Creates an externally-driven Collection with a watched lifecycle.
+ * 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 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
+ */
+function createCollection<T extends {}>(
+	watched: CollectionCallback<T>,
+	options?: CollectionOptions<T>,
+): Collection<T> {
+	const value = options?.value ?? []
+	if (value.length) validateSignalValue(TYPE_COLLECTION, value, Array.isArray)
+	validateCallback(TYPE_COLLECTION, watched, isSyncFunction)
+
+	const signals = new Map<string, Signal<T>>()
+	const keys: string[] = []
+	const itemToKey = new Map<T, string>()
+
+	const [generateKey, contentBased] = getKeyGenerator(options?.keyConfig)
+
+	const resolveKey = (item: T): string | undefined =>
+		itemToKey.get(item) ?? (contentBased ? generateKey(item) : undefined)
+
+	const itemFactory = options?.createItem ?? createState
+
+	// Build current value from child signals
+	function buildValue(): T[] {
+		const result: T[] = []
+		for (const key of keys) {
+			try {
+				const v = signals.get(key)?.get()
+				if (v != null) result.push(v)
+			} catch (e) {
+				// Skip pending async items; rethrow real errors
+				if (!(e instanceof UnsetSignalValueError)) throw e
+			}
+		}
+		return result
+	}
+
+	const node: MemoNode<T[]> = {
+		fn: buildValue,
+		value,
+		flags: FLAG_DIRTY,
+		sources: null,
+		sourcesTail: null,
+		sinks: null,
+		sinksTail: null,
+		equals: SKIP_EQUALITY, // Always rebuild — structural changes are managed externally
+		error: undefined,
+	}
+
+	// Initialize signals for initial value
+	for (const item of value) {
+		const key = generateKey(item)
+		signals.set(key, itemFactory(item))
+		itemToKey.set(item, key)
+		keys.push(key)
+	}
+	node.value = value
+	node.flags = FLAG_DIRTY // First refresh() will establish child edges
+
+	function subscribe(): void {
+		if (activeSink) {
+			if (!node.sinks)
+				node.stop = watched((changes: CollectionChanges<T>): void => {
+					const { add, change, remove } = changes
+					if (!add?.length && !change?.length && !remove?.length)
+						return
+					let structural = false
+
+					batch(() => {
+						// Additions
+						if (add) {
+							for (const item of add) {
+								const key = generateKey(item)
+								signals.set(key, itemFactory(item))
+								itemToKey.set(item, key)
+								if (!keys.includes(key)) keys.push(key)
+								structural = true
+							}
+						}
+
+						// Changes — only for State signals
+						if (change) {
+							for (const item of change) {
+								const key = resolveKey(item)
+								if (!key) continue
+								const signal = signals.get(key)
+								if (signal && isState(signal)) {
+									// Update reverse map: remove old reference, add new
+									itemToKey.delete(signal.get())
+									signal.set(item)
+									itemToKey.set(item, key)
+								}
+							}
+						}
+
+						// Removals
+						if (remove) {
+							for (const item of remove) {
+								const key = resolveKey(item)
+								if (!key) continue
+								itemToKey.delete(item)
+								signals.delete(key)
+								const index = keys.indexOf(key)
+								if (index !== -1) keys.splice(index, 1)
+								structural = true
+							}
+						}
+
+						if (structural) {
+							node.sources = null
+							node.sourcesTail = null
+						}
+						// Mark DIRTY so next get() rebuilds; propagate to sinks
+						node.flags = FLAG_DIRTY
+						for (let e = node.sinks; e; e = e.nextSink)
+							propagate(e.sink)
+					})
+				})
+			link(node, activeSink)
+		}
+	}
+
+	const collection: Collection<T> = {
+		[Symbol.toStringTag]: TYPE_COLLECTION,
+		[Symbol.isConcatSpreadable]: true as const,
+
+		*[Symbol.iterator]() {
+			for (const key of keys) {
+				const signal = signals.get(key)
+				if (signal) yield signal
+			}
+		},
+
+		get length() {
+			subscribe()
+			return keys.length
+		},
+
+		keys() {
+			subscribe()
+			return keys.values()
+		},
+
+		get() {
+			subscribe()
+			if (node.sources) {
+				if (node.flags) {
+					node.value = untrack(buildValue)
+					node.flags = FLAG_CLEAN
+				}
+			} else {
+				refresh(node as unknown as SinkNode)
+				if (node.error) throw node.error
+			}
+			return node.value
+		},
+
+		at(index: number) {
+			return signals.get(keys[index])
+		},
+
+		byKey(key: string) {
+			return signals.get(key)
+		},
+
+		keyAt(index: number) {
+			return keys[index]
+		},
+
+		indexOfKey(key: string) {
+			return keys.indexOf(key)
+		},
+
+		deriveCollection<R extends {}>(
+			cb: DeriveCollectionCallback<R, T>,
+		): Collection<R> {
+			return (
+				deriveCollection as <T2 extends {}, U2 extends {}>(
+					source: CollectionSource<U2>,
+					callback: DeriveCollectionCallback<T2, U2>,
+				) => Collection<T2>
+			)(collection, cb)
+		},
+	}
+
+	return collection
+}
+
+/**
+ * Checks if a value is a Collection signal.
+ *
+ * @since 0.17.2
+ * @param value - The value to check
+ * @returns True if the value is a Collection
+ */
+function isCollection<T extends {}>(value: unknown): value is Collection<T> {
+	return isObjectOfType(value, TYPE_COLLECTION)
+}
+
+/**
+ * Checks if a value is a valid Collection source (List or Collection).
+ *
+ * @since 0.17.2
+ * @param value - The value to check
+ * @returns True if the value is a List or Collection
+ */
+function isCollectionSource<T extends {}>(
+	value: unknown,
+): value is CollectionSource<T> {
+	return isList(value) || isCollection(value)
+}
+
+/* === Exports === */
+
+export {
+	createCollection,
+	deriveCollection,
+	isCollection,
+	isCollectionSource,
+	type Collection,
+	type CollectionCallback,
+	type CollectionChanges,
+	type CollectionOptions,
+	type CollectionSource,
+	type DeriveCollectionCallback,
+}

package/src/nodes/effect.ts

@@ -0,0 +1,149 @@
+import {
+	RequiredOwnerError,
+	UnsetSignalValueError,
+	validateCallback,
+} from '../errors'
+import {
+	activeOwner,
+	type Cleanup,
+	type EffectCallback,
+	type EffectNode,
+	FLAG_CLEAN,
+	FLAG_DIRTY,
+	type MaybeCleanup,
+	registerCleanup,
+	runCleanup,
+	runEffect,
+	type Signal,
+	trimSources,
+} from '../graph'
+
+/* === Types === */
+
+type MaybePromise<T> = T | Promise<T>
+
+type MatchHandlers<T extends Signal<unknown & {}>[]> = {
+	ok: (values: {
+		[K in keyof T]: T[K] extends Signal<infer V> ? V : never
+	}) => MaybePromise<MaybeCleanup>
+	err?: (errors: readonly Error[]) => MaybePromise<MaybeCleanup>
+	nil?: () => MaybePromise<MaybeCleanup>
+}
+
+/* === Exported Functions === */
+
+/**
+ * Creates a reactive effect that automatically runs when its dependencies change.
+ * Effects run immediately upon creation and re-run when any tracked signal changes.
+ * Effects are executed during the flush phase, after all updates have been batched.
+ *
+ * @since 0.1.0
+ * @param fn - The effect function that can track dependencies and register cleanup callbacks
+ * @returns A cleanup function that can be called to dispose of the effect
+ *
+ * @example
+ * ```ts
+ * const count = createState(0);
+ * const dispose = createEffect(() => {
+ *   console.log('Count is:', count.get());
+ * });
+ *
+ * count.set(1); // Logs: "Count is: 1"
+ * dispose(); // Stop the effect
+ * ```
+ *
+ * @example
+ * ```ts
+ * // With cleanup
+ * createEffect(() => {
+ *   const timer = setInterval(() => console.log(count.get()), 1000);
+ *   return () => clearInterval(timer);
+ * });
+ * ```
+ */
+function createEffect(fn: EffectCallback): Cleanup {
+	validateCallback('Effect', fn)
+
+	const node: EffectNode = {
+		fn,
+		flags: FLAG_DIRTY,
+		sources: null,
+		sourcesTail: null,
+		cleanup: null,
+	}
+
+	const dispose = () => {
+		runCleanup(node)
+		node.fn = undefined as unknown as EffectCallback
+		node.flags = FLAG_CLEAN
+		node.sourcesTail = null
+		trimSources(node)
+	}
+
+	if (activeOwner) registerCleanup(activeOwner, dispose)
+
+	runEffect(node)
+
+	return dispose
+}
+
+/**
+ * Runs handlers based on the current values of signals.
+ * Must be called within an active owner (effect or scope) so async cleanup can be registered.
+ *
+ * @since 0.15.0
+ * @throws RequiredOwnerError If called without an active owner.
+ */
+function match<T extends Signal<unknown & {}>[]>(
+	signals: T,
+	handlers: MatchHandlers<T>,
+): MaybeCleanup {
+	if (!activeOwner) throw new RequiredOwnerError('match')
+	const { ok, err = console.error, nil } = handlers
+	let errors: Error[] | undefined
+	let pending = false
+	const values = new Array(signals.length)
+
+	for (let i = 0; i < signals.length; i++) {
+		try {
+			values[i] = signals[i].get()
+		} catch (e) {
+			if (e instanceof UnsetSignalValueError) {
+				pending = true
+				continue
+			}
+			if (!errors) errors = []
+			errors.push(e instanceof Error ? e : new Error(String(e)))
+		}
+	}
+
+	let out: MaybePromise<MaybeCleanup>
+	try {
+		if (pending) out = nil?.()
+		else if (errors) out = err(errors)
+		else
+			out = ok(
+				values as {
+					[K in keyof T]: T[K] extends Signal<infer V> ? V : never
+				},
+			)
+	} catch (e) {
+		err([e instanceof Error ? e : new Error(String(e))])
+	}
+
+	if (typeof out === 'function') return out
+
+	if (out instanceof Promise) {
+		const owner = activeOwner
+		const controller = new AbortController()
+		registerCleanup(owner, () => controller.abort())
+		out.then(cleanup => {
+			if (!controller.signal.aborted && typeof cleanup === 'function')
+				registerCleanup(owner, cleanup)
+		}).catch(e => {
+			err([e instanceof Error ? e : new Error(String(e))])
+		})
+	}
+}
+
+export { type MaybePromise, type MatchHandlers, createEffect, match }