mutts 1.0.2 → 1.0.4

package/src/reactive/deep-touch.ts

@@ -0,0 +1,268 @@
+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 { effectParent, watchers } from './tracking'
+import { allProps, type Evolution, options, type ScopedCallback } 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: ScopedCallback, allowedSet: Set<ScopedCallback>): boolean {
+	let current: ScopedCallback | undefined = effect
+	const visited = new WeakSet<ScopedCallback>()
+	while (current && !visited.has(current)) {
+		visited.add(current)
+		if (allowedSet.has(current)) return true
+		current = effectParent.get(current)
+	}
+	return false
+}
+
+export function dispatchNotifications(notifications: PendingNotification[]) {
+	if (!notifications.length) return
+	const combinedEffects = new Set<ScopedCallback>()
+
+	// Extract origin from first notification (all should have the same origin from a single deep touch)
+	const origin = notifications[0]?.origin
+	let allowedEffects: Set<ScopedCallback> | undefined
+
+	// If origin exists, compute allowed effects (those that depend on origin.obj[origin.prop])
+	if (origin) {
+		allowedEffects = new Set<ScopedCallback>()
+		const originWatchers = watchers.get(origin.obj)
+		if (originWatchers) {
+			const originEffects = new Set<ScopedCallback>()
+			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<ScopedCallback> | undefined
+		const propsArray = [prop]
+		if (objectWatchers) {
+			currentEffects = new Set<ScopedCallback>()
+			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<ScopedCallback>()
+				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)
+		}
+		options.touched(obj, evolution, propsArray, currentEffects)
+		if (objectsWithDeepWatchers.has(obj)) bubbleUpChange(obj, evolution)
+	}
+	if (combinedEffects.size) batch([...combinedEffects])
+}

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

@@ -0,0 +1,82 @@
+import { batch } from './effects'
+import type { Evolution, ScopedCallback } 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<ScopedCallback>>()
+
+// Track which effects are doing deep watching
+export const effectToDeepWatchedObjects = new WeakMap<ScopedCallback, 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

@@ -0,0 +1,168 @@
+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 './tracking'
+import { options, type ScopedCallback } 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 } = {}
+): (() => void) | 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 ScopedCallback signature
+	const wrappedCallback: ScopedCallback = markWithRoot(() => callback(target), 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/effect-context.ts

@@ -0,0 +1,94 @@
+import { effectParent, getRoot } from './tracking'
+import { ReactiveError, type ScopedCallback } from './types'
+
+/**
+ * Effect context stack for nested tracking (front = active, next = parent)
+ */
+const stack: (ScopedCallback | undefined)[] = []
+export const effectStack = stack
+
+export function captureEffectStack() {
+	return stack.slice()
+}
+export function isRunning(effect: ScopedCallback): (ScopedCallback | undefined)[] | false {
+	const rootEffect = getRoot(effect)
+
+	// Check if the effect is directly in the stack
+	const rootIndex = stack.indexOf(rootEffect)
+	if (rootIndex !== -1) {
+		return stack.slice(0, rootIndex + 1).reverse()
+	}
+
+	// Check if any effect in the stack is a descendant of this effect
+	// (i.e., walk up the parent chain from each stack effect to see if we reach this effect)
+	for (let i = 0; i < stack.length; i++) {
+		const stackEffect = stack[i]
+		let current: ScopedCallback | undefined = stackEffect
+		const visited = new WeakSet<ScopedCallback>()
+		const ancestorChain: ScopedCallback[] = []
+		// TODO: That's perhaps a lot of computations for an `assert`
+		// Walk up the parent chain to find if this effect is an ancestor
+		while (current && !visited.has(current)) {
+			visited.add(current)
+			const currentRoot = getRoot(current)
+			ancestorChain.push(currentRoot)
+			if (currentRoot === rootEffect) {
+				// Found a descendant - build the full chain from ancestor to active
+				// The ancestorChain contains [descendant, parent, ..., ancestor] (walking up)
+				// We need [ancestor (effect), ..., parent, descendant, ...stack from descendant to active]
+				const chainFromAncestor = ancestorChain.reverse() // [ancestor, ..., descendant]
+				// Prepend the actual effect we're checking (in case current is a wrapper)
+				if (chainFromAncestor[0] !== rootEffect) {
+					chainFromAncestor.unshift(rootEffect)
+				}
+				// Append the rest of the stack from the descendant to the active effect
+				const stackFromDescendant = stack.slice(0, i + 1).reverse() // [descendant, ..., active]
+				// Remove duplicate descendant (it's both at end of chainFromAncestor and start of stackFromDescendant)
+				if (chainFromAncestor.length > 0 && stackFromDescendant.length > 0) {
+					stackFromDescendant.shift() // Remove duplicate descendant
+				}
+				return [...chainFromAncestor, ...stackFromDescendant]
+			}
+			current = effectParent.get(current)
+		}
+	}
+
+	return false
+}
+export function withEffectStack<T>(snapshot: (ScopedCallback | undefined)[], fn: () => T): T {
+	const previousStack = stack.slice()
+	assignStack(snapshot)
+	try {
+		return fn()
+	} finally {
+		assignStack(previousStack)
+	}
+}
+
+export function getActiveEffect() {
+	return stack[0]
+}
+
+/**
+ * Executes a function with a specific effect context
+ * @param effect - The effect to use as context
+ * @param fn - The function to execute
+ * @param keepParent - Whether to keep the parent effect context
+ * @returns The result of the function
+ */
+export function withEffect<T>(effect: ScopedCallback | undefined, fn: () => T): T {
+	// console.log('[Mutts] withEffect', effect ? 'Active' : 'NULL');
+	if (getRoot(effect) === getRoot(getActiveEffect())) return fn()
+	stack.unshift(effect)
+	try {
+		return fn()
+	} finally {
+		const recoveredEffect = stack.shift()
+		if (recoveredEffect !== effect) throw new ReactiveError('[reactive] Effect stack mismatch')
+	}
+}
+
+function assignStack(values: (ScopedCallback | undefined)[]) {
+	stack.length = 0
+	stack.push(...values)
+}