@zeix/cause-effect 0.16.1 → 0.17.1

package/src/classes/state.ts

@@ -0,0 +1,98 @@
+import { isEqual } from '../diff'
+import { validateCallback, validateSignalValue } from '../errors'
+import { notifyWatchers, subscribeActiveWatcher, type Watcher } from '../system'
+import { isObjectOfType, UNSET } from '../util'
+
+/* === Constants === */
+
+const TYPE_STATE = 'State' as const
+
+/* === Class === */
+
+/**
+ * Create a new state signal.
+ *
+ * @since 0.17.0
+ */
+class State<T extends {}> {
+	#watchers = new Set<Watcher>()
+	#value: T
+
+	/**
+	 * Create a new state signal.
+	 *
+	 * @param {T} initialValue - Initial value of the state
+	 * @throws {NullishSignalValueError} - If the initial value is null or undefined
+	 * @throws {InvalidSignalValueError} - If the initial value is invalid
+	 */
+	constructor(initialValue: T) {
+		validateSignalValue('state', initialValue)
+
+		this.#value = initialValue
+	}
+
+	get [Symbol.toStringTag](): string {
+		return TYPE_STATE
+	}
+
+	/**
+	 * Get the current value of the state signal.
+	 *
+	 * @returns {T} - Current value of the state
+	 */
+	get(): T {
+		subscribeActiveWatcher(this.#watchers)
+		return this.#value
+	}
+
+	/**
+	 * Set the value of the state signal.
+	 *
+	 * @param {T} newValue - New value of the state
+	 * @returns {void}
+	 * @throws {NullishSignalValueError} - If the initial value is null or undefined
+	 * @throws {InvalidSignalValueError} - If the initial value is invalid
+	 */
+	set(newValue: T): void {
+		validateSignalValue('state', newValue)
+
+		if (isEqual(this.#value, newValue)) return
+		this.#value = newValue
+		notifyWatchers(this.#watchers)
+
+		// Setting to UNSET clears the watchers so the signal can be garbage collected
+		if (UNSET === this.#value) this.#watchers.clear()
+	}
+
+	/**
+	 * Update the value of the state signal.
+	 *
+	 * @param {Function} updater - Function that takes the current value and returns the new value
+	 * @returns {void}
+	 * @throws {InvalidCallbackError} - If the updater function is not a function
+	 * @throws {NullishSignalValueError} - If the initial value is null or undefined
+	 * @throws {InvalidSignalValueError} - If the initial value is invalid
+	 */
+	update(updater: (oldValue: T) => T): void {
+		validateCallback('state update', updater)
+
+		this.set(updater(this.#value))
+	}
+}
+
+/* === Functions === */
+
+/**
+ * Check if the provided value is a State instance
+ *
+ * @since 0.9.0
+ * @param {unknown} value - Value to check
+ * @returns {boolean} - True if the value is a State instance, false otherwise
+ */
+const isState = /*#__PURE__*/ <T extends {}>(
+	value: unknown,
+): value is State<T> => isObjectOfType(value, TYPE_STATE)
+
+/* === Exports === */
+
+export { TYPE_STATE, isState, State }

package/src/classes/store.ts

@@ -0,0 +1,210 @@
+import { diff, type UnknownRecord } from '../diff'
+import { DuplicateKeyError, validateSignalValue } from '../errors'
+import { createMutableSignal, type MutableSignal, type Signal } from '../signal'
+import {
+	type Cleanup,
+	type Listener,
+	type Listeners,
+	notifyWatchers,
+	subscribeActiveWatcher,
+	type Watcher,
+} from '../system'
+import { isFunction, isObjectOfType, isRecord, isSymbol, UNSET } from '../util'
+import { Composite } from './composite'
+import type { List } from './list'
+import type { State } from './state'
+
+/* === Types === */
+
+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]>
+			: State<T[K] & {}>
+}
+
+/* === Constants === */
+
+const TYPE_STORE = 'Store' as const
+
+/* === Store Implementation === */
+
+class BaseStore<T extends UnknownRecord> {
+	#composite: Composite<T, Signal<T[keyof T] & {}>>
+	#watchers = new Set<Watcher>()
+
+	/**
+	 * Create a new store with the given initial value.
+	 *
+	 * @param {T} initialValue - The initial value of the store
+	 * @throws {NullishSignalValueError} - If the initial value is null or undefined
+	 * @throws {InvalidSignalValueError} - If the initial value is not an object
+	 */
+	constructor(initialValue: T) {
+		validateSignalValue('store', initialValue, isRecord)
+
+		this.#composite = new Composite<T, Signal<T[keyof T] & {}>>(
+			initialValue,
+			<K extends keyof T & string>(
+				key: K,
+				value: unknown,
+			): value is T[K] & {} => {
+				validateSignalValue(`store for key "${key}"`, value)
+				return true
+			},
+			value => createMutableSignal(value),
+		)
+	}
+
+	get #value(): T {
+		const record = {} as UnknownRecord
+		for (const [key, signal] of this.#composite.signals.entries())
+			record[key] = signal.get()
+		return record as T
+	}
+
+	// Public methods
+	get [Symbol.toStringTag](): 'Store' {
+		return TYPE_STORE
+	}
+
+	get [Symbol.isConcatSpreadable](): boolean {
+		return false
+	}
+
+	*[Symbol.iterator](): IterableIterator<
+		[string, MutableSignal<T[keyof T] & {}>]
+	> {
+		for (const [key, signal] of this.#composite.signals.entries())
+			yield [key, signal as MutableSignal<T[keyof T] & {}>]
+	}
+
+	get(): T {
+		subscribeActiveWatcher(this.#watchers)
+		return this.#value
+	}
+
+	set(newValue: T): void {
+		if (UNSET === newValue) {
+			this.#composite.clear()
+			notifyWatchers(this.#watchers)
+			this.#watchers.clear()
+			return
+		}
+
+		const oldValue = this.#value
+		const changed = this.#composite.change(diff(oldValue, newValue))
+		if (changed) notifyWatchers(this.#watchers)
+	}
+
+	keys(): IterableIterator<string> {
+		return this.#composite.signals.keys()
+	}
+
+	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 {
+		return this.#composite.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
+	}
+
+	update(fn: (oldValue: T) => T): void {
+		this.set(fn(this.get()))
+	}
+
+	add<K extends keyof T & string>(key: K, value: T[K]): K {
+		if (this.#composite.signals.has(key))
+			throw new DuplicateKeyError('store', key, value)
+
+		const ok = this.#composite.add(key, value)
+		if (ok) notifyWatchers(this.#watchers)
+		return key
+	}
+
+	remove(key: string): void {
+		const ok = this.#composite.remove(key)
+		if (ok) notifyWatchers(this.#watchers)
+	}
+
+	on<K extends keyof Omit<Listeners, 'sort'>>(
+		type: K,
+		listener: Listener<K>,
+	): Cleanup {
+		return this.#composite.on(type, listener)
+	}
+}
+
+/* === Functions === */
+
+/**
+ * Create a new store with deeply nested reactive properties
+ *
+ * @since 0.15.0
+ * @param {T} initialValue - Initial object or array value of the store
+ * @returns {Store<T>} - New store with reactive properties that preserves the original type T
+ */
+const createStore = <T extends UnknownRecord>(initialValue: T): Store<T> => {
+	const instance = new BaseStore(initialValue)
+
+	// Return proxy for property access
+	return new Proxy(instance, {
+		get(target, prop) {
+			if (prop in target) {
+				const value = Reflect.get(target, prop)
+				return isFunction(value) ? value.bind(target) : value
+			}
+			if (!isSymbol(prop)) return target.byKey(prop)
+		},
+		has(target, prop) {
+			if (prop in target) return true
+			return target.byKey(String(prop)) !== undefined
+		},
+		ownKeys(target) {
+			return Array.from(target.keys())
+		},
+		getOwnPropertyDescriptor(target, prop) {
+			if (prop in target)
+				return Reflect.getOwnPropertyDescriptor(target, prop)
+			if (isSymbol(prop)) return undefined
+
+			const signal = target.byKey(String(prop))
+			return signal
+				? {
+						enumerable: true,
+						configurable: true,
+						writable: true,
+						value: signal,
+					}
+				: undefined
+		},
+	}) as Store<T>
+}
+
+/**
+ * Check if the provided value is a Store instance
+ *
+ * @since 0.15.0
+ * @param {unknown} value - Value to check
+ * @returns {boolean} - True if the value is a Store instance, false otherwise
+ */
+const isStore = <T extends UnknownRecord>(
+	value: unknown,
+): value is BaseStore<T> => isObjectOfType(value, TYPE_STORE)
+
+/* === Exports === */
+
+export { createStore, isStore, BaseStore, TYPE_STORE, type Store }

package/src/diff.ts

@@ -1,24 +1,16 @@
 import { CircularDependencyError } from './errors'
-import { isRecord, isRecordOrArray, UNSET } from './util'
+import { isNonNullObject, isRecord, isRecordOrArray, UNSET } from './util'
 
 /* === Types === */
 
-type UnknownRecord = Record<string, unknown & {}>
+type UnknownRecord = Record<string, unknown>
 type UnknownArray = ReadonlyArray<unknown & {}>
 
-type ArrayToRecord<T extends UnknownArray> = {
-	[key: string]: T extends Array<infer U extends {}> ? U : never
-}
-
-type PartialRecord<T> = T extends UnknownArray
-	? Partial<ArrayToRecord<T>>
-	: Partial<T>
-
-type DiffResult<T extends UnknownRecord | UnknownArray = UnknownRecord> = {
+type DiffResult = {
 	changed: boolean
-	add: PartialRecord<T>
-	change: PartialRecord<T>
-	remove: PartialRecord<T>
+	add: UnknownRecord
+	change: UnknownRecord
+	remove: UnknownRecord
 }
 
 /* === Functions === */
@@ -36,14 +28,14 @@ const isEqual = <T>(a: T, b: T, visited?: WeakSet<object>): boolean => {
 	// Fast paths
 	if (Object.is(a, b)) return true
 	if (typeof a !== typeof b) return false
-	if (typeof a !== 'object' || a === null || b === null) return false
+	if (!isNonNullObject(a) || !isNonNullObject(b)) return false
 
 	// Cycle detection
 	if (!visited) visited = new WeakSet()
 	if (visited.has(a as object) || visited.has(b as object))
 		throw new CircularDependencyError('isEqual')
-	visited.add(a as object)
-	visited.add(b as object)
+	visited.add(a)
+	visited.add(b)
 
 	try {
 		if (Array.isArray(a) && Array.isArray(b)) {
@@ -63,14 +55,7 @@ const isEqual = <T>(a: T, b: T, visited?: WeakSet<object>): boolean => {
 			if (aKeys.length !== bKeys.length) return false
 			for (const key of aKeys) {
 				if (!(key in b)) return false
-				if (
-					!isEqual(
-						(a as Record<string, unknown>)[key],
-						(b as Record<string, unknown>)[key],
-						visited,
-					)
-				)
-					return false
+				if (!isEqual(a[key], b[key], visited)) return false
 			}
 			return true
 		}
@@ -79,8 +64,8 @@ const isEqual = <T>(a: T, b: T, visited?: WeakSet<object>): boolean => {
 		// (which would have been caught by Object.is at the beginning)
 		return false
 	} finally {
-		visited.delete(a as object)
-		visited.delete(b as object)
+		visited.delete(a)
+		visited.delete(b)
 	}
 }
 
@@ -90,12 +75,9 @@ const isEqual = <T>(a: T, b: T, visited?: WeakSet<object>): boolean => {
  * @since 0.15.0
  * @param {T} oldObj - The old record to compare
  * @param {T} newObj - The new record to compare
- * @returns {DiffResult<T>} The result of the comparison
+ * @returns {DiffResult} The result of the comparison
  */
-const diff = <T extends UnknownRecord | UnknownArray>(
-	oldObj: T extends UnknownArray ? ArrayToRecord<T> : T,
-	newObj: T extends UnknownArray ? ArrayToRecord<T> : T,
-): DiffResult<T> => {
+const diff = <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 = isRecordOrArray(oldObj)
 	const newValid = isRecordOrArray(newObj)
@@ -104,17 +86,17 @@ const diff = <T extends UnknownRecord | UnknownArray>(
 		const changed = !Object.is(oldObj, newObj)
 		return {
 			changed,
-			add: changed && newValid ? newObj : ({} as PartialRecord<T>),
-			change: {} as PartialRecord<T>,
-			remove: changed && oldValid ? oldObj : ({} as PartialRecord<T>),
+			add: changed && newValid ? newObj : {},
+			change: {},
+			remove: changed && oldValid ? oldObj : {},
 		}
 	}
 
 	const visited = new WeakSet()
 
-	const add = {} as PartialRecord<T>
-	const change = {} as PartialRecord<T>
-	const remove = {} as PartialRecord<T>
+	const add = {} as UnknownRecord
+	const change = {} as UnknownRecord
+	const remove = {} as UnknownRecord
 
 	const oldKeys = Object.keys(oldObj)
 	const newKeys = Object.keys(newObj)
@@ -138,27 +120,18 @@ const diff = <T extends UnknownRecord | UnknownArray>(
 		if (!isEqual(oldValue, newValue, visited)) change[key] = newValue
 	}
 
-	const changed =
-		Object.keys(add).length > 0 ||
-		Object.keys(change).length > 0 ||
-		Object.keys(remove).length > 0
-
 	return {
-		changed,
 		add,
 		change,
 		remove,
+		changed: !!(
+			Object.keys(add).length ||
+			Object.keys(change).length ||
+			Object.keys(remove).length
+		),
 	}
 }
 
 /* === Exports === */
 
-export {
-	type ArrayToRecord,
-	type DiffResult,
-	diff,
-	isEqual,
-	type UnknownRecord,
-	type UnknownArray,
-	type PartialRecord,
-}
+export { type DiffResult, diff, isEqual, type UnknownRecord, type UnknownArray }

package/src/effect.ts

@@ -1,6 +1,6 @@
 import { CircularDependencyError, InvalidCallbackError } from './errors'
-import { type Cleanup, createWatcher, observe } from './system'
-import { isAbortError, isAsyncFunction, isFunction, valueString } from './util'
+import { type Cleanup, createWatcher, trackSignalReads } from './system'
+import { isAbortError, isAsyncFunction, isFunction } from './util'
 
 /* === Types === */
 
@@ -26,14 +26,14 @@ type EffectCallback =
  */
 const createEffect = (callback: EffectCallback): Cleanup => {
 	if (!isFunction(callback) || callback.length > 1)
-		throw new InvalidCallbackError('effect', valueString(callback))
+		throw new InvalidCallbackError('effect', callback)
 
 	const isAsync = isAsyncFunction(callback)
 	let running = false
 	let controller: AbortController | undefined
 
 	const watcher = createWatcher(() =>
-		observe(() => {
+		trackSignalReads(watcher, () => {
 			if (running) throw new CircularDependencyError('effect')
 			running = true
 
@@ -55,15 +55,15 @@ const createEffect = (callback: EffectCallback): Cleanup => {
 								isFunction(cleanup) &&
 								controller === currentController
 							)
-								watcher.unwatch(cleanup)
+								watcher.onCleanup(cleanup)
 						})
 						.catch(error => {
 							if (!isAbortError(error))
 								console.error('Async effect error:', error)
 						})
 				} else {
-					cleanup = (callback as () => MaybeCleanup)()
-					if (isFunction(cleanup)) watcher.unwatch(cleanup)
+					cleanup = callback()
+					if (isFunction(cleanup)) watcher.onCleanup(cleanup)
 				}
 			} catch (error) {
 				if (!isAbortError(error))
@@ -71,13 +71,13 @@ const createEffect = (callback: EffectCallback): Cleanup => {
 			}
 
 			running = false
-		}, watcher),
+		}),
 	)
 
 	watcher()
 	return () => {
 		controller?.abort()
-		watcher.cleanup()
+		watcher.stop()
 	}
 }
 

package/src/errors.ts

@@ -1,3 +1,12 @@
+import { isMutableSignal, type MutableSignal } from './signal'
+import { isFunction, isSymbol, UNSET, valueString } from './util'
+
+/* === Types === */
+
+type Guard<T> = (value: unknown) => value is T
+
+/* === Classes === */
+
 class CircularDependencyError extends Error {
 	constructor(where: string) {
 		super(`Circular dependency detected in ${where}`)
@@ -5,16 +14,34 @@ class CircularDependencyError extends Error {
 	}
 }
 
+class DuplicateKeyError extends Error {
+	constructor(where: string, key: string, value?: unknown) {
+		super(
+			`Could not add ${where} key "${key}"${
+				value ? ` with value ${valueString(value)}` : ''
+			} because it already exists`,
+		)
+		this.name = 'DuplicateKeyError'
+	}
+}
+
 class InvalidCallbackError extends TypeError {
-	constructor(where: string, value: string) {
-		super(`Invalid ${where} callback ${value}`)
+	constructor(where: string, value: unknown) {
+		super(`Invalid ${where} callback ${valueString(value)}`)
 		this.name = 'InvalidCallbackError'
 	}
 }
 
+class InvalidCollectionSourceError extends TypeError {
+	constructor(where: string, value: unknown) {
+		super(`Invalid ${where} source ${valueString(value)}`)
+		this.name = 'InvalidCollectionSourceError'
+	}
+}
+
 class InvalidSignalValueError extends TypeError {
-	constructor(where: string, value: string) {
-		super(`Invalid signal value ${value} in ${where}`)
+	constructor(where: string, value: unknown) {
+		super(`Invalid signal value ${valueString(value)} in ${where}`)
 		this.name = 'InvalidSignalValueError'
 	}
 }
@@ -26,39 +53,58 @@ class NullishSignalValueError extends TypeError {
 	}
 }
 
-class StoreKeyExistsError extends Error {
-	constructor(key: string, value: string) {
+class ReadonlySignalError extends Error {
+	constructor(what: string, value: unknown) {
 		super(
-			`Could not add store key "${key}" with value ${value} because it already exists`,
+			`Could not set ${what} to ${valueString(value)} because signal is read-only`,
 		)
-		this.name = 'StoreKeyExistsError'
+		this.name = 'ReadonlySignalError'
 	}
 }
 
-class StoreKeyRangeError extends RangeError {
-	constructor(index: number) {
-		super(
-			`Could not remove store index ${String(index)} because it is out of range`,
-		)
-		this.name = 'StoreKeyRangeError'
-	}
+/* === Functions === */
+
+const createError = /*#__PURE__*/ (reason: unknown): Error =>
+	reason instanceof Error ? reason : Error(String(reason))
+
+const validateCallback = (
+	where: string,
+	value: unknown,
+	guard: (value: unknown) => boolean = isFunction,
+): void => {
+	if (!guard(value)) throw new InvalidCallbackError(where, value)
 }
 
-class StoreKeyReadonlyError extends Error {
-	constructor(key: string, value: string) {
-		super(
-			`Could not set store key "${key}" to ${value} because it is readonly`,
-		)
-		this.name = 'StoreKeyReadonlyError'
-	}
+const validateSignalValue = (
+	where: string,
+	value: unknown,
+	guard: (value: unknown) => boolean = () =>
+		!(isSymbol(value) && value !== UNSET) || isFunction(value),
+): void => {
+	if (value == null) throw new NullishSignalValueError(where)
+	if (!guard(value)) throw new InvalidSignalValueError(where, value)
+}
+
+const guardMutableSignal = <T extends {}>(
+	what: string,
+	value: unknown,
+	signal: unknown,
+): signal is MutableSignal<T> => {
+	if (!isMutableSignal(signal)) throw new ReadonlySignalError(what, value)
+	return true
 }
 
 export {
+	type Guard,
 	CircularDependencyError,
+	DuplicateKeyError,
 	InvalidCallbackError,
+	InvalidCollectionSourceError,
 	InvalidSignalValueError,
 	NullishSignalValueError,
-	StoreKeyExistsError,
-	StoreKeyRangeError,
-	StoreKeyReadonlyError,
+	ReadonlySignalError,
+	createError,
+	validateCallback,
+	validateSignalValue,
+	guardMutableSignal,
 }

package/src/match.ts

@@ -1,6 +1,6 @@
+import { createError } from './errors'
 import type { ResolveResult } from './resolve'
 import type { SignalValues, UnknownSignalRecord } from './signal'
-import { toError } from './util'
 
 /* === Types === */
 
@@ -32,17 +32,10 @@ function match<S extends UnknownSignalRecord>(
 		if (result.pending) handlers.nil?.()
 		else if (result.errors) handlers.err?.(result.errors)
 		else if (result.ok) handlers.ok(result.values)
-	} catch (error) {
-		// If handler throws, try error handler, otherwise rethrow
-		if (
-			handlers.err &&
-			(!result.errors || !result.errors.includes(toError(error)))
-		)
-			handlers.err(
-				result.errors
-					? [...result.errors, toError(error)]
-					: [toError(error)],
-			)
+	} catch (e) {
+		const error = createError(e)
+		if (handlers.err && (!result.errors || !result.errors.includes(error)))
+			handlers.err(result.errors ? [...result.errors, error] : [error])
 		else throw error
 	}
 }

package/src/resolve.ts

@@ -1,6 +1,7 @@
 import type { UnknownRecord } from './diff'
+import { createError } from './errors'
 import type { SignalValues, UnknownSignalRecord } from './signal'
-import { toError, UNSET } from './util'
+import { UNSET } from './util'
 
 /* === Types === */
 
@@ -33,7 +34,7 @@ function resolve<S extends UnknownSignalRecord>(signals: S): ResolveResult<S> {
 			if (value === UNSET) pending = true
 			else values[key] = value
 		} catch (e) {
-			errors.push(toError(e))
+			errors.push(createError(e))
 		}
 	}