@zeix/cause-effect 0.17.2 → 0.18.0

package/src/classes/ref.ts

@@ -1,96 +0,0 @@
-import { type Guard, InvalidHookError, validateSignalValue } from '../errors'
-import {
-	type Cleanup,
-	HOOK_WATCH,
-	type HookCallback,
-	notifyWatchers,
-	subscribeActiveWatcher,
-	type Watcher,
-	type WatchHook,
-} from '../system'
-import { isObjectOfType } from '../util'
-
-/* === Constants === */
-
-const TYPE_REF = 'Ref'
-
-/* === Class === */
-
-/**
- * Create a new ref signal.
- *
- * @since 0.17.1
- */
-class Ref<T extends {}> {
-	#watchers = new Set<Watcher>()
-	#value: T
-	#watchHookCallbacks: Set<HookCallback> | undefined
-
-	/**
-	 * Create a new ref signal.
-	 *
-	 * @param {T} value - Reference to external object
-	 * @param {Guard<T>} guard - Optional guard function to validate the value
-	 * @throws {NullishSignalValueError} - If the value is null or undefined
-	 * @throws {InvalidSignalValueError} - If the value is invalid
-	 */
-	constructor(value: T, guard?: Guard<T>) {
-		validateSignalValue(TYPE_REF, value, guard)
-
-		this.#value = value
-	}
-
-	get [Symbol.toStringTag](): string {
-		return TYPE_REF
-	}
-
-	/**
-	 * Get the value of the ref signal.
-	 *
-	 * @returns {T} - Object reference
-	 */
-	get(): T {
-		subscribeActiveWatcher(this.#watchers, this.#watchHookCallbacks)
-
-		return this.#value
-	}
-
-	/**
-	 * Notify watchers of relevant changes in the external reference.
-	 */
-	notify(): void {
-		notifyWatchers(this.#watchers)
-	}
-
-	/**
-	 * Register a callback to be called when HOOK_WATCH is triggered.
-	 *
-	 * @param {WatchHook} type - The type of hook to register the callback for; only HOOK_WATCH is supported
-	 * @param {HookCallback} callback - The callback to register
-	 * @returns {Cleanup} - A function to unregister the callback
-	 */
-	on(type: WatchHook, callback: HookCallback): Cleanup {
-		if (type === HOOK_WATCH) {
-			this.#watchHookCallbacks ||= new Set()
-			this.#watchHookCallbacks.add(callback)
-			return () => {
-				this.#watchHookCallbacks?.delete(callback)
-			}
-		}
-		throw new InvalidHookError(TYPE_REF, type)
-	}
-}
-
-/* === Functions === */
-
-/**
- * Check if the provided value is a Ref instance
- *
- * @since 0.17.1
- * @param {unknown} value - Value to check
- * @returns {boolean} - True if the value is a Ref instance, false otherwise
- */
-const isRef = /*#__PURE__*/ <T extends {}>(value: unknown): value is Ref<T> =>
-	isObjectOfType(value, TYPE_REF)
-
-export { TYPE_REF, Ref, isRef }

package/src/classes/state.ts

@@ -1,131 +0,0 @@
-import { isEqual } from '../diff'
-import {
-	InvalidHookError,
-	validateCallback,
-	validateSignalValue,
-} from '../errors'
-import {
-	type Cleanup,
-	HOOK_WATCH,
-	type HookCallback,
-	notifyWatchers,
-	subscribeActiveWatcher,
-	UNSET,
-	type Watcher,
-	type WatchHook,
-} from '../system'
-import { isObjectOfType } 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
-	#watchHookCallbacks: Set<HookCallback> | undefined
-
-	/**
-	 * 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(TYPE_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, this.#watchHookCallbacks)
-
-		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(TYPE_STATE, newValue)
-
-		if (isEqual(this.#value, newValue)) return
-		this.#value = newValue
-		if (this.#watchers.size) 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(`${TYPE_STATE} update`, updater)
-
-		this.set(updater(this.#value))
-	}
-
-	/**
-	 * Register a callback to be called when HOOK_WATCH is triggered.
-	 *
-	 * @param {WatchHook} type - The type of hook to register the callback for; only HOOK_WATCH is supported
-	 * @param {HookCallback} callback - The callback to register
-	 * @returns {Cleanup} - A function to unregister the callback
-	 */
-	on(type: WatchHook, callback: HookCallback): Cleanup {
-		if (type === HOOK_WATCH) {
-			this.#watchHookCallbacks ||= new Set()
-			this.#watchHookCallbacks.add(callback)
-			return () => {
-				this.#watchHookCallbacks?.delete(callback)
-			}
-		}
-		throw new InvalidHookError(this.constructor.name, type)
-	}
-}
-
-/* === 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

@@ -1,227 +0,0 @@
-import { diff, type UnknownRecord } from '../diff'
-import {
-	DuplicateKeyError,
-	InvalidHookError,
-	validateSignalValue,
-} from '../errors'
-import { createMutableSignal, type MutableSignal, type Signal } from '../signal'
-import {
-	type Cleanup,
-	HOOK_ADD,
-	HOOK_CHANGE,
-	HOOK_REMOVE,
-	HOOK_WATCH,
-	type Hook,
-	type HookCallback,
-	isHandledHook,
-	notifyWatchers,
-	subscribeActiveWatcher,
-	UNSET,
-	type Watcher,
-} from '../system'
-import { isFunction, isObjectOfType, isRecord, isSymbol } 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>()
-	#watchHookCallbacks: Set<HookCallback> | undefined
-
-	/**
-	 * 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(TYPE_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(`${TYPE_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] & {}>]
-	}
-
-	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
-	}
-
-	get(): T {
-		subscribeActiveWatcher(this.#watchers, this.#watchHookCallbacks)
-		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)
-	}
-
-	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(TYPE_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(type: Hook, callback: HookCallback): Cleanup {
-		if (type === HOOK_WATCH) {
-			this.#watchHookCallbacks ||= new Set<HookCallback>()
-			this.#watchHookCallbacks.add(callback)
-			return () => {
-				this.#watchHookCallbacks?.delete(callback)
-			}
-		} else if (isHandledHook(type, [HOOK_ADD, HOOK_CHANGE, HOOK_REMOVE])) {
-			return this.#composite.on(type, callback)
-		}
-		throw new InvalidHookError(TYPE_STORE, type)
-	}
-}
-
-/* === 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,138 +0,0 @@
-import { CircularDependencyError } from './errors'
-import { UNSET } from './system'
-import { isNonNullObject, isRecord, isRecordOrArray } from './util'
-
-/* === Types === */
-
-type UnknownRecord = Record<string, unknown>
-type UnknownArray = ReadonlyArray<unknown & {}>
-
-type DiffResult = {
-	changed: boolean
-	add: UnknownRecord
-	change: UnknownRecord
-	remove: UnknownRecord
-}
-
-/* === Functions === */
-
-/**
- * Checks if two values are equal with cycle detection
- *
- * @since 0.15.0
- * @param {T} a - First value to compare
- * @param {T} b - Second value to compare
- * @param {WeakSet<object>} visited - Set to track visited objects for cycle detection
- * @returns {boolean} Whether the two values are equal
- */
-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 (!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)
-	visited.add(b)
-
-	try {
-		if (Array.isArray(a) && Array.isArray(b)) {
-			if (a.length !== b.length) return false
-			for (let i = 0; i < a.length; i++) {
-				if (!isEqual(a[i], b[i], visited)) return false
-			}
-			return true
-		}
-
-		if (Array.isArray(a) !== Array.isArray(b)) return false
-
-		if (isRecord(a) && isRecord(b)) {
-			const aKeys = Object.keys(a)
-			const bKeys = Object.keys(b)
-
-			if (aKeys.length !== bKeys.length) return false
-			for (const key of aKeys) {
-				if (!(key in b)) return false
-				if (!isEqual(a[key], b[key], visited)) return false
-			}
-			return true
-		}
-
-		// For non-records/non-arrays, they are only equal if they are the same reference
-		// (which would have been caught by Object.is at the beginning)
-		return false
-	} finally {
-		visited.delete(a)
-		visited.delete(b)
-	}
-}
-
-/**
- * Compares two records and returns a result object containing the differences.
- *
- * @since 0.15.0
- * @param {T} oldObj - The old record to compare
- * @param {T} newObj - The new record to compare
- * @returns {DiffResult} The result of the comparison
- */
-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)
-	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
-
-	const oldKeys = Object.keys(oldObj)
-	const newKeys = Object.keys(newObj)
-	const allKeys = new Set([...oldKeys, ...newKeys])
-
-	for (const key of allKeys) {
-		const oldHas = key in oldObj
-		const newHas = key in newObj
-
-		if (!oldHas && newHas) {
-			add[key] = newObj[key]
-			continue
-		} else if (oldHas && !newHas) {
-			remove[key] = UNSET
-			continue
-		}
-
-		const oldValue = oldObj[key]
-		const newValue = newObj[key]
-
-		if (!isEqual(oldValue, newValue, visited)) change[key] = newValue
-	}
-
-	return {
-		add,
-		change,
-		remove,
-		changed: !!(
-			Object.keys(add).length ||
-			Object.keys(change).length ||
-			Object.keys(remove).length
-		),
-	}
-}
-
-/* === Exports === */
-
-export { type DiffResult, diff, isEqual, type UnknownRecord, type UnknownArray }

package/src/effect.ts

@@ -1,96 +0,0 @@
-import { CircularDependencyError, InvalidCallbackError } from './errors'
-import {
-	type Cleanup,
-	createWatcher,
-	HOOK_CLEANUP,
-	type MaybeCleanup,
-	trackSignalReads,
-} from './system'
-import { isAbortError, isAsyncFunction, isFunction } from './util'
-
-/* === Types === */
-
-type EffectCallback =
-	| (() => MaybeCleanup)
-	| ((abort: AbortSignal) => Promise<MaybeCleanup>)
-
-/* === Functions === */
-
-/**
- * Define what happens when a reactive state changes
- *
- * The callback can be synchronous or asynchronous. Async callbacks receive
- * an AbortSignal parameter, which is automatically aborted when the effect
- * re-runs or is cleaned up, preventing stale async operations.
- *
- * @since 0.1.0
- * @param {EffectCallback} callback - Synchronous or asynchronous effect callback
- * @returns {Cleanup} - Cleanup function for the effect
- */
-const createEffect = (callback: EffectCallback): Cleanup => {
-	if (!isFunction(callback) || callback.length > 1)
-		throw new InvalidCallbackError('effect', callback)
-
-	const isAsync = isAsyncFunction(callback)
-	let running = false
-	let controller: AbortController | undefined
-
-	const watcher = createWatcher(() =>
-		trackSignalReads(watcher, () => {
-			if (running) throw new CircularDependencyError('effect')
-			running = true
-
-			// Abort any previous async operations
-			controller?.abort()
-			controller = undefined
-
-			let cleanup: MaybeCleanup | Promise<MaybeCleanup>
-
-			try {
-				if (isAsync) {
-					// Create AbortController for async callback
-					controller = new AbortController()
-					const currentController = controller
-					callback(controller.signal)
-						.then(cleanup => {
-							// Only register cleanup if this is still the current controller
-							if (
-								isFunction(cleanup) &&
-								controller === currentController
-							)
-								watcher.on(HOOK_CLEANUP, cleanup)
-						})
-						.catch(error => {
-							if (!isAbortError(error))
-								console.error(
-									'Error in async effect callback:',
-									error,
-								)
-						})
-				} else {
-					cleanup = callback()
-					if (isFunction(cleanup)) watcher.on(HOOK_CLEANUP, cleanup)
-				}
-			} catch (error) {
-				if (!isAbortError(error))
-					console.error('Error in effect callback:', error)
-			}
-
-			running = false
-		}),
-	)
-
-	watcher()
-	return () => {
-		controller?.abort()
-		try {
-			watcher.stop()
-		} catch (error) {
-			console.error('Error in effect cleanup:', error)
-		}
-	}
-}
-
-/* === Exports === */
-
-export { type MaybeCleanup, type EffectCallback, createEffect }