@zeix/cause-effect 0.17.3 → 0.18.0

package/src/nodes/sensor.ts

@@ -0,0 +1,139 @@
+import {
+	validateCallback,
+	validateReadValue,
+	validateSignalValue,
+} from '../errors'
+import {
+	activeSink,
+	type Cleanup,
+	type ComputedOptions,
+	defaultEquals,
+	link,
+	type StateNode,
+	setState,
+	TYPE_SENSOR,
+} from '../graph'
+import { isObjectOfType, isSyncFunction } from '../util'
+
+/* === Types === */
+
+/**
+ * A read-only signal that tracks external input and updates a state value as long as it is active.
+ *
+ * @template T - The type of value produced by the sensor
+ */
+type Sensor<T extends {}> = {
+	readonly [Symbol.toStringTag]: 'Sensor'
+
+	/**
+	 * 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.
+	 */
+	get(): T
+}
+
+/**
+ * A callback function for sensors when the sensor starts being watched.
+ *
+ * @template T - The type of value observed
+ * @param set - A function to set the observed value
+ * @returns A cleanup function when the sensor stops being watched
+ */
+type SensorCallback<T extends {}> = (set: (next: T) => void) => Cleanup
+
+/* === Exported Functions === */
+
+/**
+ * Creates a sensor that tracks external input and updates a state value as long as it is active.
+ * Sensors get activated when they are first accessed by an effect and deactivated when they are
+ * 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.
+ * @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`
+ *   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.
+ *
+ * @example Tracking external values
+ * ```ts
+ * const mousePos = createSensor<{ x: number; y: number }>((set) => {
+ *   const handler = (e: MouseEvent) => {
+ *     set({ x: e.clientX, y: e.clientY });
+ *   };
+ *   window.addEventListener('mousemove', handler);
+ *   return () => window.removeEventListener('mousemove', handler);
+ * });
+ * ```
+ *
+ * @example Observing a mutable object
+ * ```ts
+ * import { createSensor, SKIP_EQUALITY } from 'cause-effect';
+ *
+ * const el = createSensor<HTMLElement>((set) => {
+ *   const node = document.getElementById('box')!;
+ *   set(node);
+ *   const obs = new MutationObserver(() => set(node));
+ *   obs.observe(node, { attributes: true });
+ *   return () => obs.disconnect();
+ * }, { value: node, equals: SKIP_EQUALITY });
+ * ```
+ */
+function createSensor<T extends {}>(
+	start: SensorCallback<T>,
+	options?: ComputedOptions<T>,
+): Sensor<T> {
+	validateCallback(TYPE_SENSOR, start, isSyncFunction)
+	if (options?.value !== undefined)
+		validateSignalValue(TYPE_SENSOR, options.value, options?.guard)
+
+	const node: StateNode<T> = {
+		value: options?.value as T,
+		sinks: null,
+		sinksTail: null,
+		equals: options?.equals ?? defaultEquals,
+		guard: options?.guard,
+		stop: undefined,
+	}
+
+	return {
+		[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 => {
+						validateSignalValue(TYPE_SENSOR, next, node.guard)
+						setState(node, next)
+					})
+				link(node, activeSink)
+			}
+			validateReadValue(TYPE_SENSOR, node.value)
+			return node.value
+		},
+	}
+}
+
+/**
+ * Checks if a value is a Sensor signal.
+ *
+ * @since 0.18.0
+ * @param value - The value to check
+ * @returns True if the value is a Sensor
+ */
+function isSensor<T extends {} = unknown & {}>(
+	value: unknown,
+): value is Sensor<T> {
+	return isObjectOfType(value, TYPE_SENSOR)
+}
+
+export { createSensor, isSensor, type Sensor, type SensorCallback }

package/src/nodes/state.ts

@@ -0,0 +1,135 @@
+import { validateCallback, validateSignalValue } from '../errors'
+import {
+	activeSink,
+	defaultEquals,
+	link,
+	type SignalOptions,
+	type StateNode,
+	setState,
+	TYPE_STATE,
+} from '../graph'
+import { isObjectOfType } from '../util'
+
+/* === Types === */
+
+/**
+ * A callback function for states that updates a value based on the previous value.
+ *
+ * @template T - The type of value
+ * @param prev - The previous state value
+ * @returns The new state value
+ */
+type UpdateCallback<T extends {}> = (prev: T) => T
+
+/**
+ * A mutable reactive state container.
+ * Changes to the state will automatically propagate to dependent computations and effects.
+ *
+ * @template T - The type of value stored in the state
+ */
+type State<T extends {}> = {
+	readonly [Symbol.toStringTag]: 'State'
+
+	/**
+	 * Gets the current value of the state.
+	 * When called inside a memo, task, or effect, creates a dependency.
+	 * @returns The current value
+	 */
+	get(): T
+
+	/**
+	 * Sets a new value for the state.
+	 * If the new value is different (according to the equality function), all dependents will be notified.
+	 * @param next - The new value to set
+	 */
+	set(next: T): void
+
+	/**
+	 * Updates the state with a new value computed by a callback function.
+	 * The callback receives the current value as an argument.
+	 * @param fn - The callback function to compute the new value
+	 */
+	update(fn: UpdateCallback<T>): void
+}
+
+/* === Exported Functions === */
+
+/**
+ * Creates a mutable reactive state container.
+ *
+ * @since 0.9.0
+ * @template T - The type of value stored in the state
+ * @param value - The initial value
+ * @param options - Optional configuration for the state
+ * @returns A State object with get() and set() methods
+ *
+ * @example
+ * ```ts
+ * const count = createState(0);
+ * count.set(1);
+ * console.log(count.get()); // 1
+ * ```
+ *
+ * @example
+ * ```ts
+ * // With type guard
+ * const count = createState(0, {
+ *   guard: (v): v is number => typeof v === 'number'
+ * });
+ * ```
+ */
+function createState<T extends {}>(
+	value: T,
+	options?: SignalOptions<T>,
+): State<T> {
+	validateSignalValue(TYPE_STATE, value, options?.guard)
+
+	const node: StateNode<T> = {
+		value,
+		sinks: null,
+		sinksTail: null,
+		equals: options?.equals ?? defaultEquals,
+		guard: options?.guard,
+	}
+
+	return {
+		[Symbol.toStringTag]: TYPE_STATE,
+		get(): T {
+			if (activeSink) link(node, activeSink)
+			return node.value
+		},
+		set(next: T): void {
+			validateSignalValue(TYPE_STATE, next, node.guard)
+			setState(node, next)
+		},
+		update(fn: UpdateCallback<T>): void {
+			validateCallback(TYPE_STATE, fn)
+			const next = fn(node.value)
+			validateSignalValue(TYPE_STATE, next, node.guard)
+			setState(node, next)
+		},
+	}
+}
+
+/**
+ * Checks if a value is a State signal.
+ *
+ * @since 0.9.0
+ * @param value - The value to check
+ * @returns True if the value is a State
+ *
+ * @example
+ * ```ts
+ * const state = createState(0);
+ * if (isState(state)) {
+ *   state.set(1); // TypeScript knows state has set()
+ * }
+ * ```
+ */
+function isState<T extends {} = unknown & {}>(
+	value: unknown,
+): value is State<T> {
+	return isObjectOfType(value, TYPE_STATE)
+}
+
+export { createState, isState, type State, type UpdateCallback }

package/src/nodes/store.ts

@@ -0,0 +1,383 @@
+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 { isFunction, 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(newValue: T): void
+	update(fn: (oldValue: 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>(
+	oldObj: T,
+	newObj: 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) {
+		// For non-objects or non-plain objects, treat as complete change if different
+		const changed = !Object.is(oldObj, newObj)
+		return {
+			changed,
+			add: changed && newValid ? newObj : {},
+			change: {},
+			remove: changed && oldValid ? oldObj : {},
+		}
+	}
+
+	const visited = new WeakSet()
+
+	const add = {} as UnknownRecord
+	const change = {} as UnknownRecord
+	const remove = {} as UnknownRecord
+	let changed = false
+
+	const oldKeys = Object.keys(oldObj)
+	const newKeys = Object.keys(newObj)
+
+	// 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]
+				changed = true
+			}
+		} else {
+			add[key] = newObj[key]
+			changed = true
+		}
+	}
+
+	// Pass 2: iterate old keys — find removals
+	for (const key of oldKeys) {
+		if (!(key in newObj)) {
+			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 initialValue - 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>(
+	initialValue: T,
+	options?: StoreOptions,
+): Store<T> {
+	validateSignalValue(TYPE_STORE, initialValue, isRecord)
+
+	const signals = new Map<
+		string,
+		State<unknown & {}> | Store<UnknownRecord> | List<unknown & {}>
+	>()
+
+	// --- 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 & {}))
+	}
+
+	// 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: initialValue,
+		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 value = changes.change[key]
+					validateSignalValue(`${TYPE_STORE} for key "${key}"`, value)
+					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)
+							structural = true
+						} else signal.set(value 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
+	}
+
+	// --- Initialize ---
+	for (const key of Object.keys(initialValue))
+		addSignal(key, initialValue[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() {
+			if (activeSink) {
+				if (!node.sinks && options?.watched)
+					node.stop = options.watched()
+				link(node, activeSink)
+			}
+			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() {
+			if (activeSink) {
+				if (!node.sinks && options?.watched)
+					node.stop = options.watched()
+				link(node, activeSink)
+			}
+			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(newValue: T) {
+			// Use cached value if clean, recompute if dirty
+			const currentValue =
+				node.flags & FLAG_DIRTY ? buildValue() : node.value
+
+			const changes = diffRecords(currentValue, newValue)
+			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
+				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
+			propagate(node as unknown as SinkNode)
+			node.flags |= FLAG_DIRTY
+			if (batchDepth === 0) flush()
+			return key
+		},
+
+		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
+				if (batchDepth === 0) flush()
+			}
+		},
+	}
+
+	// --- 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 (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 }