@zeix/cause-effect 0.17.3 → 0.18.1

package/src/nodes/memo.ts

@@ -0,0 +1,148 @@
+import {
+	validateCallback,
+	validateReadValue,
+	validateSignalValue,
+} from '../errors'
+import {
+	activeSink,
+	batchDepth,
+	type ComputedOptions,
+	DEFAULT_EQUALITY,
+	FLAG_DIRTY,
+	flush,
+	link,
+	type MemoCallback,
+	type MemoNode,
+	propagate,
+	refresh,
+	type SinkNode,
+	TYPE_MEMO,
+} from '../graph'
+import { isObjectOfType, isSyncFunction } from '../util'
+
+/* === Types === */
+
+/**
+ * A derived reactive computation that caches its result.
+ * Automatically tracks dependencies and recomputes when they change.
+ *
+ * @template T - The type of value computed by the memo
+ */
+type Memo<T extends {}> = {
+	readonly [Symbol.toStringTag]: 'Memo'
+
+	/**
+	 * Gets the current value of the memo.
+	 * Recomputes if dependencies have changed since last access.
+	 * When called inside another reactive context, creates a dependency.
+	 * @returns The computed value
+	 * @throws UnsetSignalValueError If the memo value is still unset when read.
+	 */
+	get(): T
+}
+
+/* === Exported Functions === */
+
+/**
+ * Creates a derived reactive computation that caches its result.
+ * The computation automatically tracks dependencies and recomputes when they change.
+ * Uses lazy evaluation - only computes when the value is accessed.
+ *
+ * @since 0.18.0
+ * @template T - The type of value computed by the memo
+ * @param fn - The computation function that receives the previous value
+ * @param options - Optional configuration for the memo
+ * @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 memo is first watched by an effect.
+ *   Receives an `invalidate` function to mark the memo dirty and trigger recomputation.
+ *   Must return a cleanup function called when no effects are watching.
+ * @returns A Memo object with a get() method
+ *
+ * @example
+ * ```ts
+ * const count = createState(0);
+ * const doubled = createMemo(() => count.get() * 2);
+ * console.log(doubled.get()); // 0
+ * count.set(5);
+ * console.log(doubled.get()); // 10
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Using previous value
+ * const sum = createMemo((prev) => prev + count.get(), { value: 0, equals: Object.is });
+ * ```
+ */
+function createMemo<T extends {}>(
+	fn: (prev: T) => T,
+	options: ComputedOptions<T> & { value: T },
+): Memo<T>
+function createMemo<T extends {}>(
+	fn: MemoCallback<T>,
+	options?: ComputedOptions<T>,
+): Memo<T>
+function createMemo<T extends {}>(
+	fn: MemoCallback<T>,
+	options?: ComputedOptions<T>,
+): Memo<T> {
+	validateCallback(TYPE_MEMO, fn, isSyncFunction)
+	if (options?.value !== undefined)
+		validateSignalValue(TYPE_MEMO, options.value, options?.guard)
+
+	const node: MemoNode<T> = {
+		fn,
+		value: options?.value as T,
+		flags: FLAG_DIRTY,
+		sources: null,
+		sourcesTail: null,
+		sinks: null,
+		sinksTail: null,
+		equals: options?.equals ?? DEFAULT_EQUALITY,
+		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_MEMO,
+		get() {
+			subscribe()
+			refresh(node as unknown as SinkNode)
+			if (node.error) throw node.error
+			validateReadValue(TYPE_MEMO, node.value)
+			return node.value
+		},
+	}
+}
+
+/**
+ * Checks if a value is a Memo signal.
+ *
+ * @since 0.18.0
+ * @param value - The value to check
+ * @returns True if the value is a Memo
+ */
+function isMemo<T extends {} = unknown & {}>(value: unknown): value is Memo<T> {
+	return isObjectOfType(value, TYPE_MEMO)
+}
+
+export { createMemo, isMemo, type Memo }

package/src/nodes/sensor.ts

@@ -0,0 +1,149 @@
+import {
+	validateCallback,
+	validateReadValue,
+	validateSignalValue,
+} from '../errors'
+import {
+	activeSink,
+	type Cleanup,
+	DEFAULT_EQUALITY,
+	link,
+	type SignalOptions,
+	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.
+	 * 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 SensorOptions<T extends {}> = SignalOptions<T> & {
+	/**
+	 * Optional initial value. Avoids `UnsetSignalValueError` on first read
+	 * before the watched callback fires.
+	 */
+	value?: T
+}
+
+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 produced by the sensor
+ * @param watched - The callback invoked when the sensor starts being watched, receives a `set` function and returns a cleanup function.
+ * @param options - Optional configuration for the sensor.
+ * @param options.value - Optional initial value. Avoids `UnsetSignalValueError` on first read
+ *   before the watched callback fires. Essential for the mutable-object observation pattern.
+ * @param options.equals - Optional equality function. Defaults to strict equality (`===`). 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 {}>(
+	watched: SensorCallback<T>,
+	options?: SensorOptions<T>,
+): Sensor<T> {
+	validateCallback(TYPE_SENSOR, watched, 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 ?? DEFAULT_EQUALITY,
+		guard: options?.guard,
+		stop: undefined,
+	}
+
+	return {
+		[Symbol.toStringTag]: TYPE_SENSOR,
+		get(): T {
+			if (activeSink) {
+				if (!node.sinks)
+					node.stop = watched((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,
+	type SensorOptions,
+}

package/src/nodes/state.ts

@@ -0,0 +1,135 @@
+import { validateCallback, validateSignalValue } from '../errors'
+import {
+	activeSink,
+	DEFAULT_EQUALITY,
+	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 ?? DEFAULT_EQUALITY,
+		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 }