mutts 1.0.9 → 1.0.11

package/src/reactive/deep-touch.ts

@@ -1,273 +0,0 @@
-import { addState, collectEffects, touched1, touchedOpaque } from './change'
-import { bubbleUpChange, objectsWithDeepWatchers } from './deep-watch-state'
-import { batch } from './effects'
-import { isNonReactive } from './non-reactive-state'
-import { unwrap } from './proxy-state'
-import { getEffectNode, watchers } from './registry'
-import { allProps, type EffectCleanup, type EffectTrigger, type Evolution, optionCall, options } from './types'
-
-function isObject(value: any): value is object {
-	return typeof value === 'object' && value !== null
-}
-
-function isObjectLike(value: unknown): value is object {
-	return isObject(value)
-}
-
-function getPrototypeToken(value: any): object | null | undefined {
-	if (!isObjectLike(value)) return undefined
-	if (Array.isArray(value)) return Array.prototype
-	try {
-		return value.constructor
-	} catch {
-		return undefined
-	}
-}
-
-export function shouldRecurseTouch(oldValue: any, newValue: any): boolean {
-	if (oldValue === newValue) return false
-	if (!isObjectLike(oldValue) || !isObjectLike(newValue)) return false
-	if (isNonReactive(oldValue) || isNonReactive(newValue)) return false
-	return getPrototypeToken(oldValue) === getPrototypeToken(newValue)
-}
-
-/**
- * Centralized function to handle property change notifications with optional recursive touch
- * @param targetObj - The object whose property changed
- * @param prop - The property that changed
- * @param oldValue - The old value (before change)
- * @param newValue - The new value (after change)
- * @param hadProperty - Whether the property existed before (for add vs set)
- */
-export function notifyPropertyChange(
-	targetObj: any,
-	prop: any,
-	oldValue: any,
-	newValue: any,
-	hadProperty: boolean
-) {
-	const evolution: Evolution = { type: hadProperty ? 'set' : 'add', prop }
-
-	if (
-		options.recursiveTouching &&
-		oldValue !== undefined &&
-		shouldRecurseTouch(oldValue, newValue)
-	) {
-		const unwrappedObj = unwrap(targetObj)
-		const origin = { obj: unwrappedObj, prop }
-		// Deep touch: only notify nested property changes with origin filtering
-		// Don't notify direct property change - the whole point is to avoid parent effects re-running
-		dispatchNotifications(recursiveTouch(oldValue, newValue, new WeakMap(), [], origin))
-
-		// Notify opaque listeners (like memoize) that always want to know about identity changes
-		touchedOpaque(targetObj, evolution, prop)
-	} else {
-		touched1(targetObj, evolution, prop)
-	}
-}
-
-type VisitedPairs = WeakMap<object, WeakSet<object>>
-type PendingNotification = {
-	target: any
-	evolution: Evolution
-	prop: any
-	origin?: { obj: object; prop: PropertyKey } // The property access that triggered this deep touch
-}
-
-function hasVisitedPair(visited: VisitedPairs, oldObj: object, newObj: object): boolean {
-	let mapped = visited.get(oldObj)
-	if (!mapped) {
-		mapped = new WeakSet<object>()
-		visited.set(oldObj, mapped)
-	}
-	if (mapped.has(newObj)) return true
-	mapped.add(newObj)
-	return false
-}
-
-function collectObjectKeys(obj: any): Set<PropertyKey> {
-	const keys = new Set<PropertyKey>(Reflect.ownKeys(obj))
-	let proto = Object.getPrototypeOf(obj)
-	// Continue walking while prototype exists and doesn't have its own constructor
-	// This stops at Object.prototype (has own constructor) and class prototypes (have own constructor)
-	// but continues for data prototypes (Object.create({}), Object.create(instance), etc.)
-	while (proto && !Object.hasOwn(proto, 'constructor')) {
-		for (const key of Reflect.ownKeys(proto)) keys.add(key)
-		proto = Object.getPrototypeOf(proto)
-	}
-	return keys
-}
-
-export function recursiveTouch(
-	oldValue: any,
-	newValue: any,
-	visited: VisitedPairs = new WeakMap(),
-	notifications: PendingNotification[] = [],
-	origin?: { obj: object; prop: PropertyKey }
-): PendingNotification[] {
-	if (!shouldRecurseTouch(oldValue, newValue)) return notifications
-	if (!isObjectLike(oldValue) || !isObjectLike(newValue)) return notifications
-	if (hasVisitedPair(visited, oldValue, newValue)) return notifications
-
-	if (Array.isArray(oldValue) && Array.isArray(newValue)) {
-		diffArrayElements(oldValue, newValue, visited, notifications, origin)
-		return notifications
-	}
-
-	diffObjectProperties(oldValue, newValue, visited, notifications, origin)
-	return notifications
-}
-
-function diffArrayElements(
-	oldArray: any[] | readonly any[],
-	newArray: any[] | readonly any[],
-	_visited: VisitedPairs,
-	notifications: PendingNotification[],
-	origin?: { obj: object; prop: PropertyKey }
-) {
-	const local: PendingNotification[] = []
-	const oldLength = oldArray.length
-	const newLength = newArray.length
-	const max = Math.max(oldLength, newLength)
-
-	for (let index = 0; index < max; index++) {
-		const hasOld = index < oldLength
-		const hasNew = index < newLength
-		if (hasOld && !hasNew) {
-			local.push({ target: oldArray, evolution: { type: 'del', prop: index }, prop: index, origin })
-			continue
-		}
-		if (!hasOld && hasNew) {
-			local.push({ target: oldArray, evolution: { type: 'add', prop: index }, prop: index, origin })
-			continue
-		}
-		if (!hasOld || !hasNew) continue
-		const oldEntry = unwrap(oldArray[index])
-		const newEntry = unwrap(newArray[index])
-		if (!Object.is(oldEntry, newEntry)) {
-			local.push({ target: oldArray, evolution: { type: 'set', prop: index }, prop: index, origin })
-		}
-	}
-
-	if (oldLength !== newLength)
-		local.push({
-			target: oldArray,
-			evolution: { type: 'set', prop: 'length' },
-			prop: 'length',
-			origin,
-		})
-
-	notifications.push(...local)
-}
-
-function diffObjectProperties(
-	oldObj: any,
-	newObj: any,
-	visited: VisitedPairs,
-	notifications: PendingNotification[],
-	origin?: { obj: object; prop: PropertyKey }
-) {
-	const oldKeys = collectObjectKeys(oldObj)
-	const newKeys = collectObjectKeys(newObj)
-	const local: PendingNotification[] = []
-
-	for (const key of oldKeys)
-		if (!newKeys.has(key))
-			local.push({ target: oldObj, evolution: { type: 'del', prop: key }, prop: key, origin })
-
-	for (const key of newKeys)
-		if (!oldKeys.has(key))
-			local.push({ target: oldObj, evolution: { type: 'add', prop: key }, prop: key, origin })
-
-	for (const key of newKeys) {
-		if (!oldKeys.has(key)) continue
-		const oldEntry = unwrap((oldObj as any)[key])
-		const newEntry = unwrap((newObj as any)[key])
-		if (shouldRecurseTouch(oldEntry, newEntry)) {
-			recursiveTouch(oldEntry, newEntry, visited, notifications, origin)
-		} else if (!Object.is(oldEntry, newEntry)) {
-			local.push({ target: oldObj, evolution: { type: 'set', prop: key }, prop: key, origin })
-		}
-	}
-
-	notifications.push(...local)
-}
-
-/**
- * Checks if an effect or any of its ancestors is in the allowed set
- */
-function hasAncestorInSet(
-	effect: EffectTrigger | EffectCleanup,
-	allowedSet: Set<EffectTrigger | EffectCleanup>
-): boolean {
-	let current: EffectTrigger | EffectCleanup | undefined = effect
-	const visited = new WeakSet<EffectTrigger | EffectCleanup>()
-	while (current && !visited.has(current)) {
-		visited.add(current)
-		if (allowedSet.has(current)) return true
-		const node = getEffectNode(current as EffectTrigger)
-		current = node.parent
-	}
-	return false
-}
-
-export function dispatchNotifications(notifications: PendingNotification[]) {
-	if (!notifications.length) return
-	const combinedEffects = new Set<EffectTrigger>()
-
-	// Extract origin from first notification (all should have the same origin from a single deep touch)
-	const origin = notifications[0]?.origin
-	let allowedEffects: Set<EffectTrigger> | undefined
-
-	// If origin exists, compute allowed effects (those that depend on origin.obj[origin.prop])
-	if (origin) {
-		allowedEffects = new Set<EffectTrigger>()
-		const originWatchers = watchers.get(origin.obj)
-		if (originWatchers) {
-			const originEffects = new Set<EffectTrigger>()
-			collectEffects(
-				origin.obj,
-				{ type: 'set', prop: origin.prop },
-				originEffects,
-				originWatchers,
-				[allProps],
-				[origin.prop]
-			)
-			for (const effect of originEffects) allowedEffects.add(effect)
-		}
-		// If no allowed effects, skip all notifications (no one should be notified)
-		if (allowedEffects.size === 0) return
-	}
-
-	for (const { target, evolution, prop } of notifications) {
-		if (!isObjectLike(target)) continue
-		const obj = unwrap(target)
-		addState(obj, evolution)
-		const objectWatchers = watchers.get(obj)
-		let currentEffects: Set<EffectTrigger> | undefined
-		const propsArray = [prop]
-		if (objectWatchers) {
-			// console.log(`[DEBUG] dispatchNotifications: processing ${obj.constructor.name} (has watchers)`)
-			currentEffects = new Set<EffectTrigger>()
-			collectEffects(obj, evolution, currentEffects, objectWatchers, [allProps], propsArray)
-
-			// Filter effects by ancestor chain if origin exists
-			// Include effects that either directly depend on origin or have an ancestor that does
-			if (origin && allowedEffects) {
-				const filteredEffects = new Set<EffectTrigger>()
-				for (const effect of currentEffects) {
-					// Check if effect itself is allowed OR has an ancestor that is allowed
-					if (allowedEffects.has(effect) || hasAncestorInSet(effect, allowedEffects)) {
-						filteredEffects.add(effect)
-					}
-				}
-				currentEffects = filteredEffects
-			}
-
-			for (const effect of currentEffects) combinedEffects.add(effect)
-		}
-		optionCall('touched', obj, evolution, propsArray, currentEffects)
-		if (objectsWithDeepWatchers.has(obj)) bubbleUpChange(obj, evolution)
-	}
-	if (combinedEffects.size) batch([...combinedEffects])
-}

package/src/reactive/deep-watch-state.ts

@@ -1,82 +0,0 @@
-import { batch } from './effects'
-import type { EffectTrigger, Evolution } from './types'
-
-// Track which objects contain which other objects (back-references)
-export const objectParents = new WeakMap<object, Set<{ parent: object; prop: PropertyKey }>>()
-
-// Track which objects have deep watchers
-export const objectsWithDeepWatchers = new WeakSet<object>()
-
-// Track deep watchers per object
-export const deepWatchers = new WeakMap<object, Set<EffectTrigger>>()
-
-// Track which effects are doing deep watching
-export const effectToDeepWatchedObjects = new WeakMap<EffectTrigger, Set<object>>()
-
-/**
- * Add a back-reference from child to parent
- */
-export function addBackReference(child: object, parent: object, prop: any) {
-	let parents = objectParents.get(child)
-	if (!parents) {
-		parents = new Set()
-		objectParents.set(child, parents)
-	}
-	parents.add({ parent, prop })
-}
-
-/**
- * Remove a back-reference from child to parent
- */
-export function removeBackReference(child: object, parent: object, prop: any) {
-	const parents = objectParents.get(child)
-	if (parents) {
-		for (const entry of parents) {
-			if (entry.parent === parent && entry.prop === prop) {
-				parents.delete(entry)
-				break
-			}
-		}
-		if (parents.size === 0) {
-			objectParents.delete(child)
-		}
-	}
-}
-
-/**
- * Check if an object needs back-references (has deep watchers or parents with deep watchers)
- */
-export function needsBackReferences(obj: object): boolean {
-	// Fast path: check if object itself has deep watchers
-	if (objectsWithDeepWatchers.has(obj)) return true
-	// Slow path: check if any parent has deep watchers (recursive)
-	return hasParentWithDeepWatchers(obj)
-}
-
-/**
- * Bubble up changes through the back-reference chain
- */
-export function bubbleUpChange(changedObject: object, evolution: Evolution) {
-	const parents = objectParents.get(changedObject)
-	if (!parents) return
-
-	for (const { parent } of parents) {
-		// Trigger deep watchers on parent
-		const parentDeepWatchers = deepWatchers.get(parent)
-		if (parentDeepWatchers) for (const watcher of parentDeepWatchers) batch(watcher)
-
-		// Continue bubbling up
-		bubbleUpChange(parent, evolution)
-	}
-}
-
-function hasParentWithDeepWatchers(obj: object): boolean {
-	const parents = objectParents.get(obj)
-	if (!parents) return false
-
-	for (const { parent } of parents) {
-		if (objectsWithDeepWatchers.has(parent)) return true
-		if (hasParentWithDeepWatchers(parent)) return true
-	}
-	return false
-}

package/src/reactive/deep-watch.ts

@@ -1,171 +0,0 @@
-import {
-	deepWatchers,
-	effectToDeepWatchedObjects,
-	objectsWithDeepWatchers,
-} from './deep-watch-state'
-import { effect } from './effects'
-import { isNonReactive } from './non-reactive-state'
-import { reactive, unwrap } from './proxy'
-import { markWithRoot } from './registry'
-import { type EffectCleanup, type EffectTrigger, options } from './types'
-
-function isObject(value: any): value is object {
-	return typeof value === 'object' && value !== null
-}
-
-export {
-	addBackReference,
-	bubbleUpChange,
-	deepWatchers,
-	effectToDeepWatchedObjects,
-	needsBackReferences,
-	objectParents,
-	objectsWithDeepWatchers,
-	removeBackReference,
-} from './deep-watch-state'
-
-/**
- * Deep watch an object and all its nested properties
- * @param target - The object to watch deeply
- * @param callback - The callback to call when any nested property changes
- * @param options - Options for the deep watch
- * @returns A cleanup function to stop watching
- */
-/**
- * Sets up deep watching for an object, tracking all nested property changes
- * @param target - The object to watch
- * @param callback - The callback to call when changes occur
- * @param options - Options for deep watching
- * @returns A cleanup function to stop deep watching
- */
-export function deepWatch<T extends object>(
-	target: T,
-	callback: (value: T) => void,
-	{ immediate = false } = {}
-): EffectCleanup | undefined {
-	if (target === null || target === undefined) return undefined
-	if (typeof target !== 'object') throw new Error('Target of deep watching must be an object')
-	// Create a wrapper callback that matches EffectTrigger signature
-	const wrappedCallback: EffectTrigger = markWithRoot(
-		(() => callback(target)) as EffectTrigger,
-		callback
-	)
-
-	// Use the existing effect system to register dependencies
-	return effect(() => {
-		// Mark the target object as having deep watchers
-		objectsWithDeepWatchers.add(target)
-
-		// Track which objects this effect is watching for cleanup
-		let effectObjects = effectToDeepWatchedObjects.get(wrappedCallback)
-		if (!effectObjects) {
-			effectObjects = new Set()
-			effectToDeepWatchedObjects.set(wrappedCallback, effectObjects)
-		}
-		effectObjects!.add(target)
-
-		// Traverse the object graph and register dependencies
-		// This will re-run every time the effect runs, ensuring we catch all changes
-		const visited = new WeakSet()
-		function traverseAndTrack(obj: any, depth = 0) {
-			// Prevent infinite recursion and excessive depth
-			if (!obj || visited.has(obj) || !isObject(obj) || depth > options.maxDeepWatchDepth) return
-			// Do not traverse into unreactive objects
-			if (isNonReactive(obj)) return
-			visited.add(obj)
-
-			// Mark this object as having deep watchers
-			objectsWithDeepWatchers.add(obj)
-			effectObjects!.add(obj)
-
-			// Traverse all properties to register dependencies
-			// unwrap to avoid kicking dependency
-			for (const key in unwrap(obj)) {
-				if (Object.hasOwn(obj, key)) {
-					// Access the property to register dependency
-					const value = (obj as any)[key]
-					// Make the value reactive if it's an object
-					const reactiveValue =
-						typeof value === 'object' && value !== null ? reactive(value) : value
-					traverseAndTrack(reactiveValue, depth + 1)
-				}
-			}
-
-			// Also handle array indices and length
-			// biome-ignore lint/suspicious/useIsArray: Check for both native arrays and reactive arrays
-			if (Array.isArray(obj) || obj instanceof Array) {
-				// Access array length to register dependency on length changes
-				const length = obj.length
-
-				// Access all current array elements to register dependencies
-				for (let i = 0; i < length; i++) {
-					// Access the array element to register dependency
-					const value = obj[i]
-					// Make the value reactive if it's an object
-					const reactiveValue =
-						typeof value === 'object' && value !== null ? reactive(value) : value
-					traverseAndTrack(reactiveValue, depth + 1)
-				}
-			}
-			// Handle Set values (deep watch values only, not keys since Sets don't have separate keys)
-			else if (obj instanceof Set) {
-				// Access all Set values to register dependencies
-				for (const value of obj) {
-					// Make the value reactive if it's an object
-					const reactiveValue =
-						typeof value === 'object' && value !== null ? reactive(value) : value
-					traverseAndTrack(reactiveValue, depth + 1)
-				}
-			}
-			// Handle Map values (deep watch values only, not keys)
-			else if (obj instanceof Map) {
-				// Access all Map values to register dependencies
-				for (const [_key, value] of obj) {
-					// Make the value reactive if it's an object
-					const reactiveValue =
-						typeof value === 'object' && value !== null ? reactive(value) : value
-					traverseAndTrack(reactiveValue, depth + 1)
-				}
-			}
-			// Note: WeakSet and WeakMap cannot be iterated, so we can't deep watch their contents
-			// They will only trigger when the collection itself is replaced
-		}
-
-		// Traverse the target object to register all dependencies
-		// This will register dependencies on all current properties and array elements
-		traverseAndTrack(target)
-
-		// Only call the callback if immediate is true or if it's not the first run
-		if (immediate) callback(target)
-		immediate = true
-
-		// Return a cleanup function that properly removes deep watcher tracking
-		return () => {
-			// Get the objects this effect was watching
-			const effectObjects = effectToDeepWatchedObjects.get(wrappedCallback)
-			if (effectObjects) {
-				// Remove deep watcher tracking from all objects this effect was watching
-				for (const obj of effectObjects) {
-					// Check if this object still has other deep watchers
-					const watchers = deepWatchers.get(obj)
-					if (watchers) {
-						// Remove this effect's callback from the watchers
-						watchers.delete(wrappedCallback)
-
-						// If no more watchers, remove the object from deep watchers tracking
-						if (watchers.size === 0) {
-							deepWatchers.delete(obj)
-							objectsWithDeepWatchers.delete(obj)
-						}
-					} else {
-						// No watchers found, remove from deep watchers tracking
-						objectsWithDeepWatchers.delete(obj)
-					}
-				}
-
-				// Clean up the tracking data
-				effectToDeepWatchedObjects.delete(wrappedCallback)
-			}
-		}
-	})
-}

package/src/reactive/describe.ts

@@ -1,39 +0,0 @@
-import { attend } from './buffer'
-import { touched1 } from './change'
-import { cleanedBy } from './effect-context'
-import { reactive } from './proxy'
-
-/**
- * Reactively defines properties on a target object based on a descriptors record.
- * 
- * It tracks the keys of the descriptors record and defines/updates/removes 
- * properties on the target object as they change.
- *
- * @param descriptors - A reactive record of property descriptors.
- * @param target - The object to define properties on (defaults to a new object).
- * @returns The target object with reactive property definitions.
- */
-export function describe<T extends object>(
-	descriptors: Record<PropertyKey, PropertyDescriptor>,
-	target: T = Object.create(null) as T
-): T {
-	descriptors = reactive(descriptors)
-
-	const stop = attend(
-		() => Reflect.ownKeys(descriptors),
-		(key) => {
-			const desc = (descriptors as any)[key]
-			if (desc) {
-				Object.defineProperty(target, key, {
-					enumerable: true,
-					...desc,
-					configurable: true,
-				})
-				touched1(target, { type: 'set', prop: key }, key)
-			}
-			return () => Reflect.deleteProperty(target, key)
-		}
-	)
-
-	return cleanedBy(target, stop)
-}

package/src/reactive/effect-context.ts

@@ -1,83 +0,0 @@
-import { tag } from '../utils'
-import { asyncZone, ZoneAggregator, ZoneHistory } from '../zone'
-import { effect, untracked } from './effects'
-import { getRoot } from './registry'
-import {
-	cleanup,
-	type EffectAccess,
-	type EffectTrigger,
-	type ScopedCallback,
-	stopped,
-} from './types'
-
-export const effectHistory = tag('effectHistory', new ZoneHistory<EffectTrigger>())
-tag('effectHistory.present', effectHistory.present)
-asyncZone.add(effectHistory)
-
-/**
- * Aggregator for zones that need to be tracked along effects.
- * ie. in each effect, the active zone of the given zoning will be the one active at effect's definition
- */
-export const effectAggregator = tag('effectAggregator', new ZoneAggregator(effectHistory.present))
-
-export function isRunning(effect: EffectTrigger): boolean {
-	const root = getRoot(effect)
-	return effectHistory.some((e) => getRoot(e) === root)
-}
-
-export function getActiveEffect() {
-	return effectHistory.present.active
-}
-
-/**
- * ADD a cleanup function to an object using the cleanup symbol.
- * The cleanup function will be called when the object needs to be disposed.
- *
- * Note: most of the time, you don't need to use this function directly.
- * The main use if for the cleanup function to be stored with the object, as GC calls the cleanup function when the *function* is garbage collected.
- *
- * @param obj - The object to attach the cleanup function to
- * @param cleanupFn - The cleanup function to attach
- * @returns The object with the cleanup function attached
- */
-export function cleanedBy<T extends object>(obj: T, cleanupFn: ScopedCallback) {
-	const oldCleanup = obj[cleanup]
-	return Object.defineProperty(obj, cleanup, {
-		value: oldCleanup
-			? Object.defineProperties(
-					() => {
-						oldCleanup()
-						cleanupFn()
-					},
-					{
-						[stopped]: { get: () => oldCleanup[stopped] || cleanupFn[stopped] },
-					}
-				)
-			: cleanupFn,
-		writable: false,
-		enumerable: false,
-		configurable: true,
-	}) as T & { [cleanup]: ScopedCallback }
-}
-
-//#region greedy caching
-
-/**
- * Creates a derived value that automatically recomputes when dependencies change
- * @param compute - Function that computes the derived value
- * @returns Object with value and cleanup function
- */
-export function derived<T>(compute: (dep: EffectAccess) => T): {
-	value: T
-	[cleanup]: ScopedCallback
-} {
-	const rv = { value: undefined as unknown as T }
-	return cleanedBy(
-		rv,
-		untracked(() =>
-			effect(function derivedEffect(access) {
-				rv.value = compute(access)
-			})
-		)
-	)
-}