@zeix/cause-effect 0.17.3 → 0.18.0

package/src/classes/store.ts

@@ -1,262 +0,0 @@
-import { type DiffResult, diff, type UnknownRecord } from '../diff'
-import {
-	DuplicateKeyError,
-	guardMutableSignal,
-	validateSignalValue,
-} from '../errors'
-import { createMutableSignal, type MutableSignal } from '../signal'
-import {
-	batch,
-	notifyOf,
-	registerWatchCallbacks,
-	type SignalOptions,
-	subscribeTo,
-	UNSET,
-	unsubscribeAllFrom,
-} from '../system'
-import { isFunction, isObjectOfType, isRecord, isSymbol } from '../util'
-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 === */
-
-/**
- * Create a new store with the given initial value.
- *
- * @since 0.17.0
- * @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
- */
-class BaseStore<T extends UnknownRecord> {
-	#signals = new Map<keyof T & string, MutableSignal<T[keyof T] & {}>>()
-
-	constructor(initialValue: T, options?: SignalOptions<T>) {
-		validateSignalValue(
-			TYPE_STORE,
-			initialValue,
-			options?.guard ?? isRecord,
-		)
-
-		this.#change({
-			add: initialValue,
-			change: {},
-			remove: {},
-			changed: true,
-		})
-		if (options?.watched)
-			registerWatchCallbacks(this, options.watched, options.unwatched)
-	}
-
-	get #value(): T {
-		const record = {} as UnknownRecord
-		for (const [key, signal] of this.#signals.entries())
-			record[key] = signal.get()
-		return record as T
-	}
-
-	#validate<K extends keyof T & string>(
-		key: K,
-		value: unknown,
-	): value is T[K] & {} {
-		validateSignalValue(`${TYPE_STORE} for key "${key}"`, value)
-		return true
-	}
-
-	#add<K extends keyof T & string>(key: K, value: T[K]): boolean {
-		if (!this.#validate(key, value)) return false
-
-		this.#signals.set(
-			key,
-			createMutableSignal(value) as unknown as MutableSignal<
-				T[keyof T] & {}
-			>,
-		)
-		return true
-	}
-
-	#change(changes: DiffResult): boolean {
-		// Additions
-		if (Object.keys(changes.add).length) {
-			for (const key in changes.add)
-				this.#add(
-					key,
-					changes.add[key] as T[Extract<keyof T, string>] & {},
-				)
-		}
-
-		// Changes
-		if (Object.keys(changes.change).length) {
-			batch(() => {
-				for (const key in changes.change) {
-					const value = changes.change[key]
-					if (!this.#validate(key, value)) continue
-
-					const signal = this.#signals.get(key)
-					if (guardMutableSignal(`list item "${key}"`, value, signal))
-						signal.set(value)
-				}
-			})
-		}
-
-		// Removals
-		if (Object.keys(changes.remove).length) {
-			for (const key in changes.remove) this.remove(key)
-		}
-
-		return changes.changed
-	}
-
-	// 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.#signals.entries()) yield [key, signal]
-	}
-
-	keys(): IterableIterator<string> {
-		subscribeTo(this)
-		return this.#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.#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 {
-		subscribeTo(this)
-		return this.#value
-	}
-
-	set(newValue: T): void {
-		if (UNSET === newValue) {
-			this.#signals.clear()
-			notifyOf(this)
-			unsubscribeAllFrom(this)
-			return
-		}
-
-		const changed = this.#change(diff(this.#value, newValue))
-		if (changed) notifyOf(this)
-	}
-
-	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.#signals.has(key))
-			throw new DuplicateKeyError(TYPE_STORE, key, value)
-
-		const ok = this.#add(key, value)
-		if (ok) notifyOf(this)
-		return key
-	}
-
-	remove(key: string): void {
-		const ok = this.#signals.delete(key)
-		if (ok) notifyOf(this)
-	}
-}
-
-/* === 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
- * @param {SignalOptions<T>} options - Options for the store
- * @returns {Store<T>} - New store with reactive properties that preserves the original type T
- */
-const createStore = <T extends UnknownRecord>(
-	initialValue: T,
-	options?: SignalOptions<T>,
-): Store<T> => {
-	const instance = new BaseStore(initialValue, options)
-
-	// 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,93 +0,0 @@
-import { CircularDependencyError, InvalidCallbackError } from './errors'
-import { type Cleanup, createWatcher, type MaybeCleanup } 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(
-		() => {
-			watcher.run()
-		},
-		() => {
-			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.onCleanup(cleanup)
-						})
-						.catch(error => {
-							if (!isAbortError(error))
-								console.error(
-									'Error in async effect callback:',
-									error,
-								)
-						})
-				} else {
-					cleanup = callback()
-					if (isFunction(cleanup)) watcher.onCleanup(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 }

package/src/match.ts

@@ -1,45 +0,0 @@
-import { createError } from './errors'
-import type { ResolveResult } from './resolve'
-import type { SignalValues, UnknownSignalRecord } from './signal'
-
-/* === Types === */
-
-type MatchHandlers<S extends UnknownSignalRecord> = {
-	ok: (values: SignalValues<S>) => void
-	err?: (errors: readonly Error[]) => void
-	nil?: () => void
-}
-
-/* === Functions === */
-
-/**
- * Match on resolve result and call appropriate handler for side effects
- *
- * This is a utility function for those who prefer the handler pattern.
- * All handlers are for side effects only and return void. If you need
- * cleanup logic, use a hoisted let variable in your effect.
- *
- * @since 0.15.0
- * @param {ResolveResult<S>} result - Result from resolve()
- * @param {MatchHandlers<S>} handlers - Handlers for different states (side effects only)
- * @returns {void} - Always returns void
- */
-function match<S extends UnknownSignalRecord>(
-	result: ResolveResult<S>,
-	handlers: MatchHandlers<S>,
-): void {
-	try {
-		if (result.pending) handlers.nil?.()
-		else if (result.errors) handlers.err?.(result.errors)
-		else if (result.ok) handlers.ok(result.values)
-	} 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
-	}
-}
-
-/* === Exports === */
-
-export { match, type MatchHandlers }

package/src/resolve.ts

@@ -1,49 +0,0 @@
-import type { UnknownRecord } from './diff'
-import { createError } from './errors'
-import type { SignalValues, UnknownSignalRecord } from './signal'
-import { UNSET } from './system'
-
-/* === Types === */
-
-type ResolveResult<S extends UnknownSignalRecord> =
-	| { ok: true; values: SignalValues<S>; errors?: never; pending?: never }
-	| { ok: false; errors: readonly Error[]; values?: never; pending?: never }
-	| { ok: false; pending: true; values?: never; errors?: never }
-
-/* === Functions === */
-
-/**
- * Resolve signal values with perfect type inference
- *
- * Always returns a discriminated union result, regardless of whether
- * handlers are provided or not. This ensures a predictable API.
- *
- * @since 0.15.0
- * @param {S} signals - Signals to resolve
- * @returns {ResolveResult<S>} - Discriminated union result
- */
-function resolve<S extends UnknownSignalRecord>(signals: S): ResolveResult<S> {
-	const errors: Error[] = []
-	let pending = false
-	const values: UnknownRecord = {}
-
-	// Collect values and errors
-	for (const [key, signal] of Object.entries(signals)) {
-		try {
-			const value = signal.get()
-			if (value === UNSET) pending = true
-			else values[key] = value
-		} catch (e) {
-			errors.push(createError(e))
-		}
-	}
-
-	// Return discriminated union
-	if (pending) return { ok: false, pending: true }
-	if (errors.length > 0) return { ok: false, errors }
-	return { ok: true, values: values as SignalValues<S> }
-}
-
-/* === Exports === */
-
-export { resolve, type ResolveResult }