@zeix/cause-effect 0.17.3 → 0.18.1

package/src/nodes/store.ts

@@ -0,0 +1,378 @@
+import { DuplicateKeyError, validateSignalValue } from '../errors'
+import {
+	activeSink,
+	batch,
+	batchDepth,
+	type Cleanup,
+	FLAG_CLEAN,
+	FLAG_DIRTY,
+	flush,
+	link,
+	type MemoNode,
+	propagate,
+	refresh,
+	type SinkNode,
+	TYPE_STORE,
+	untrack,
+} from '../graph'
+import { isObjectOfType, isRecord } from '../util'
+import {
+	createList,
+	type DiffResult,
+	isEqual,
+	type List,
+	type UnknownRecord,
+} from './list'
+import { createState, type State } from './state'
+
+/* === Types === */
+
+type StoreOptions = {
+	watched?: () => Cleanup
+}
+
+type BaseStore<T extends UnknownRecord> = {
+	readonly [Symbol.toStringTag]: 'Store'
+	readonly [Symbol.isConcatSpreadable]: false
+	[Symbol.iterator](): IterableIterator<
+		[
+			string,
+			State<T[keyof T] & {}> | Store<UnknownRecord> | List<unknown & {}>,
+		]
+	>
+	keys(): IterableIterator<string>
+	byKey<K extends keyof T & string>(
+		key: K,
+	): T[K] extends readonly (infer U extends {})[]
+		? List<U>
+		: T[K] extends UnknownRecord
+			? Store<T[K]>
+			: T[K] extends unknown & {}
+				? State<T[K] & {}>
+				: State<T[K] & {}> | undefined
+	get(): T
+	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
+}
+
+type Store<T extends UnknownRecord> = BaseStore<T> & {
+	[K in keyof T]: T[K] extends readonly (infer U extends {})[]
+		? List<U>
+		: T[K] extends UnknownRecord
+			? Store<T[K]>
+			: T[K] extends unknown & {}
+				? State<T[K] & {}>
+				: State<T[K] & {}> | undefined
+}
+
+/* === Functions === */
+
+/** Diff two records and return granular changes */
+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 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(prev, next)
+		return {
+			changed,
+			add: changed && nextValid ? next : {},
+			change: {},
+			remove: changed && prevValid ? prev : {},
+		}
+	}
+
+	const visited = new WeakSet()
+
+	const add = {} as UnknownRecord
+	const change = {} as UnknownRecord
+	const remove = {} as UnknownRecord
+	let changed = false
+
+	const prevKeys = Object.keys(prev)
+	const nextKeys = Object.keys(next)
+
+	// Pass 1: iterate new keys — find additions and changes
+	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] = next[key]
+			changed = true
+		}
+	}
+
+	// Pass 2: iterate old keys — find removals
+	for (const key of prevKeys) {
+		if (!(key in next)) {
+			remove[key] = undefined
+			changed = true
+		}
+	}
+
+	return { add, change, remove, changed }
+}
+
+/**
+ * Creates a reactive store with deeply nested reactive properties.
+ * Each property becomes its own signal (State for primitives, nested Store for objects, List for arrays).
+ * Properties are accessible directly via proxy.
+ *
+ * @since 0.15.0
+ * @param value - Initial object value of the store
+ * @param options - Optional configuration for watch lifecycle
+ * @returns A Store with reactive properties
+ *
+ * @example
+ * ```ts
+ * const user = createStore({ name: 'Alice', age: 30 });
+ * user.name.set('Bob'); // Only name subscribers react
+ * console.log(user.get()); // { name: 'Bob', age: 30 }
+ * ```
+ */
+function createStore<T extends UnknownRecord>(
+	value: T,
+	options?: StoreOptions,
+): Store<T> {
+	validateSignalValue(TYPE_STORE, value, isRecord)
+
+	const signals = new Map<
+		string,
+		State<unknown & {}> | Store<UnknownRecord> | List<unknown & {}>
+	>()
+
+	// --- Internal helpers ---
+
+	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
+	const buildValue = (): T => {
+		const record = {} as UnknownRecord
+		signals.forEach((signal, key) => {
+			record[key] = signal.get()
+		})
+		return record as T
+	}
+
+	// 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.
+	const node: MemoNode<T> = {
+		fn: buildValue,
+		value,
+		flags: FLAG_DIRTY,
+		sources: null,
+		sourcesTail: null,
+		sinks: null,
+		sinksTail: null,
+		equals: isEqual,
+		error: undefined,
+	}
+
+	const applyChanges = (changes: DiffResult): boolean => {
+		let structural = false
+
+		// Additions
+		for (const key in changes.add) {
+			addSignal(key, changes.add[key])
+			structural = true
+		}
+
+		// Changes
+		if (Object.keys(changes.change).length) {
+			batch(() => {
+				for (const key in changes.change) {
+					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(val) !== isStore(signal)) {
+							addSignal(key, val)
+							structural = true
+						} else signal.set(val as never)
+					}
+				}
+			})
+		}
+
+		// Removals
+		for (const key in changes.remove) {
+			signals.delete(key)
+			structural = true
+		}
+
+		if (structural) {
+			node.sources = null
+			node.sourcesTail = null
+		}
+
+		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(value)) addSignal(key, value[key])
+
+	// --- Store object ---
+	const store: BaseStore<T> = {
+		[Symbol.toStringTag]: TYPE_STORE,
+		[Symbol.isConcatSpreadable]: false as const,
+
+		*[Symbol.iterator]() {
+			for (const key of Array.from(signals.keys())) {
+				const signal = signals.get(key)
+				if (signal)
+					yield [key, signal] as [
+						string,
+						(
+							| State<T[keyof T] & {}>
+							| Store<UnknownRecord>
+							| List<unknown & {}>
+						),
+					]
+			}
+		},
+
+		keys() {
+			subscribe()
+			return signals.keys()
+		},
+
+		byKey<K extends keyof T & string>(key: K) {
+			return signals.get(key) as T[K] extends readonly (infer U extends
+				{})[]
+				? List<U>
+				: T[K] extends UnknownRecord
+					? Store<T[K]>
+					: T[K] extends unknown & {}
+						? State<T[K] & {}>
+						: State<T[K] & {}> | undefined
+		},
+
+		get() {
+			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) {
+					node.value = untrack(buildValue)
+					node.flags = FLAG_CLEAN
+				}
+			} else {
+				// First access: use refresh() to establish child → store edges
+				refresh(node as unknown as SinkNode)
+				if (node.error) throw node.error
+			}
+			return node.value
+		},
+
+		set(next: T) {
+			// Use cached value if clean, recompute if dirty
+			const prev = node.flags & FLAG_DIRTY ? buildValue() : node.value
+
+			const changes = diffRecords(prev, next)
+			if (applyChanges(changes)) {
+				node.flags |= FLAG_DIRTY
+				for (let e = node.sinks; e; e = e.nextSink) propagate(e.sink)
+				if (batchDepth === 0) flush()
+			}
+		},
+
+		update(fn: (prev: T) => T) {
+			store.set(fn(store.get()))
+		},
+
+		add<K extends keyof T & string>(key: K, value: T[K]) {
+			if (signals.has(key))
+				throw new DuplicateKeyError(TYPE_STORE, key, value)
+			addSignal(key, value)
+			node.sources = null
+			node.sourcesTail = null
+			node.flags |= FLAG_DIRTY
+			for (let e = node.sinks; e; e = e.nextSink) propagate(e.sink)
+			if (batchDepth === 0) flush()
+			return key
+		},
+
+		remove(key: string) {
+			const ok = signals.delete(key)
+			if (ok) {
+				node.sources = null
+				node.sourcesTail = null
+				node.flags |= FLAG_DIRTY
+				for (let e = node.sinks; e; e = e.nextSink) propagate(e.sink)
+				if (batchDepth === 0) flush()
+			}
+		},
+	}
+
+	// --- Proxy ---
+	return new Proxy(store, {
+		get(target, prop) {
+			if (prop in target) return Reflect.get(target, prop)
+			if (typeof prop !== 'symbol')
+				return target.byKey(prop as keyof T & string)
+		},
+		has(target, prop) {
+			if (prop in target) return true
+			return target.byKey(String(prop) as keyof T & string) !== undefined
+		},
+		ownKeys(target) {
+			return Array.from(target.keys())
+		},
+		getOwnPropertyDescriptor(target, prop) {
+			if (prop in target)
+				return Reflect.getOwnPropertyDescriptor(target, prop)
+			if (typeof prop === 'symbol') return undefined
+			const signal = target.byKey(String(prop) as keyof T & string)
+			return signal
+				? {
+						enumerable: true,
+						configurable: true,
+						writable: true,
+						value: signal,
+					}
+				: undefined
+		},
+	}) as Store<T>
+}
+
+/**
+ * Checks if a value is a Store signal.
+ *
+ * @since 0.15.0
+ * @param value - The value to check
+ * @returns True if the value is a Store
+ */
+function isStore<T extends UnknownRecord>(value: unknown): value is Store<T> {
+	return isObjectOfType(value, TYPE_STORE)
+}
+
+/* === Exports === */
+
+export { createStore, isStore, type Store, type StoreOptions, TYPE_STORE }

package/src/nodes/task.ts

@@ -0,0 +1,174 @@
+import {
+	validateCallback,
+	validateReadValue,
+	validateSignalValue,
+} from '../errors'
+import {
+	activeSink,
+	batchDepth,
+	type ComputedOptions,
+	DEFAULT_EQUALITY,
+	FLAG_DIRTY,
+	flush,
+	link,
+	propagate,
+	refresh,
+	type SinkNode,
+	type TaskCallback,
+	type TaskNode,
+	TYPE_TASK,
+} from '../graph'
+import { isAsyncFunction, isObjectOfType } from '../util'
+
+/* === Types === */
+
+/**
+ * An asynchronous reactive computation (colorless async).
+ * Automatically tracks dependencies and re-executes when they change.
+ * Provides abort semantics and pending state tracking.
+ *
+ * @template T - The type of value resolved by the task
+ */
+type Task<T extends {}> = {
+	readonly [Symbol.toStringTag]: 'Task'
+
+	/**
+	 * Gets the current value of the task.
+	 * Returns the last resolved value, even while a new computation is pending.
+	 * When called inside another reactive context, creates a dependency.
+	 * @returns The current value
+	 * @throws UnsetSignalValueError If the task value is still unset when read.
+	 */
+	get(): T
+
+	/**
+	 * Checks if the task is currently executing.
+	 * @returns True if a computation is in progress
+	 */
+	isPending(): boolean
+
+	/**
+	 * Aborts the current computation if one is running.
+	 * The task's AbortSignal will be triggered.
+	 */
+	abort(): void
+}
+
+/* === Exported Functions === */
+
+/**
+ * Creates an asynchronous reactive computation (colorless async).
+ * The computation automatically tracks dependencies and re-executes when they change.
+ * Provides abort semantics - in-flight computations are aborted when dependencies change.
+ *
+ * @since 0.18.0
+ * @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
+ * ```ts
+ * const userId = createState(1);
+ * const user = createTask(async (prev, signal) => {
+ *   const response = await fetch(`/api/users/${userId.get()}`, { signal });
+ *   return response.json();
+ * });
+ *
+ * // When userId changes, the previous fetch is aborted
+ * userId.set(2);
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Check pending state
+ * if (user.isPending()) {
+ *   console.log('Loading...');
+ * }
+ * ```
+ */
+function createTask<T extends {}>(
+	fn: (prev: T, signal: AbortSignal) => Promise<T>,
+	options: ComputedOptions<T> & { value: T },
+): Task<T>
+function createTask<T extends {}>(
+	fn: TaskCallback<T>,
+	options?: ComputedOptions<T>,
+): Task<T>
+function createTask<T extends {}>(
+	fn: TaskCallback<T>,
+	options?: ComputedOptions<T>,
+): Task<T> {
+	validateCallback(TYPE_TASK, fn, isAsyncFunction)
+	if (options?.value !== undefined)
+		validateSignalValue(TYPE_TASK, options.value, options?.guard)
+
+	const node: TaskNode<T> = {
+		fn,
+		value: options?.value as T,
+		sources: null,
+		sourcesTail: null,
+		sinks: null,
+		sinksTail: null,
+		flags: FLAG_DIRTY,
+		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 {
+			subscribe()
+			refresh(node as unknown as SinkNode)
+			if (node.error) throw node.error
+			validateReadValue(TYPE_TASK, node.value)
+			return node.value
+		},
+		isPending(): boolean {
+			return !!node.controller
+		},
+		abort(): void {
+			node.controller?.abort()
+			node.controller = undefined
+		},
+	}
+}
+
+/**
+ * Checks if a value is a Task signal.
+ *
+ * @since 0.18.0
+ * @param value - The value to check
+ * @returns True if the value is a Task
+ */
+function isTask<T extends {} = unknown & {}>(value: unknown): value is Task<T> {
+	return isObjectOfType(value, TYPE_TASK)
+}
+
+export { createTask, isTask, type Task }