mutts 1.0.5 → 1.0.6

package/src/reactive/interface.ts

@@ -4,7 +4,8 @@ import { withEffect } from './effect-context'
 import { effect, getActiveEffect, untracked } from './effects'
 import { isNonReactive, nonReactiveClass, nonReactiveObjects } from './non-reactive-state'
 import { unwrap } from './proxy-state'
-import { dependant, markWithRoot } from './tracking'
+import { dependant } from './tracking'
+import { markWithRoot } from './registry'
 import {
 	type DependencyAccess,
 	nonReactiveMark,
@@ -89,11 +90,11 @@ function watchObject(
 	const myParentEffect = getActiveEffect()
 	if (deep) return deepWatch(value, changed, { immediate })!
 	return effect(
-		markWithRoot(function watchObjectEffect() {
+		function watchObjectEffect() {
 			dependant(value)
 			if (immediate) withEffect(myParentEffect, () => changed(value))
 			immediate = true
-		}, changed)
+		}
 	)
 }
 
@@ -111,7 +112,7 @@ function watchCallBack<T>(
 			if (oldValue !== newValue)
 				withEffect(
 					myParentEffect,
-					markWithRoot(() => {
+					() => {
 						if (oldValue === unsetYet) {
 							if (immediate) changed(newValue)
 						} else changed(newValue, oldValue)
@@ -120,10 +121,10 @@ function watchCallBack<T>(
 							if (deepCleanup) deepCleanup()
 							deepCleanup = deepWatch(
 								newValue as object,
-								markWithRoot((value) => changed(value as T, value as T), changed)
+								(value) => changed(value as T, value as T)
 							)
 						}
-					}, changed)
+					}
 				)
 		}, value)
 	)
@@ -214,9 +215,9 @@ export function derived<T>(compute: (dep: DependencyAccess) => T): {
 		rv,
 		untracked(() =>
 			effect(
-				markWithRoot(function derivedEffect(access) {
+				function derivedEffect(access) {
 					rv.value = compute(access)
-				}, compute)
+				}
 			)
 		)
 	)

package/src/reactive/memoize.ts

@@ -1,8 +1,10 @@
 import { decorator } from '../decorator'
-import { renamed } from '../utils'
+import { deepCompare, renamed } from '../utils'
 import { touched1 } from './change'
-import { effect, root } from './effects'
-import { dependant, getRoot, markWithRoot } from './tracking'
+import { effect, root, untracked } from './effects'
+import { dependant } from './tracking'
+import { getRoot, markWithRoot } from './registry'
+import { options, rootFunction } from './types'
 
 export type Memoizable = object | any[] | symbol | ((...args: any[]) => any)
 
@@ -12,7 +14,8 @@ type MemoCacheTree<Result> = {
 	branches?: WeakMap<Memoizable, MemoCacheTree<Result>>
 }
 
-const memoizedRegistry = new WeakMap<Function, Function>()
+const memoizedRegistry = new WeakMap<any, Function>()
+const wrapperRegistry = new WeakMap<Function, Function>()
 
 function getBranch<Result>(tree: MemoCacheTree<Result>, key: Memoizable): MemoCacheTree<Result> {
 	tree.branches ??= new WeakMap()
@@ -38,18 +41,33 @@ function memoizeFunction<Result, Args extends Memoizable[]>(
 			throw new Error('memoize expects non-null object arguments')
 
 		let node: MemoCacheTree<Result> = cacheRoot
+		// Note: decorators add `this` as first argument
 		for (const arg of localArgs) {
 			node = getBranch(node, arg)
 		}
 
 		dependant(node, 'memoize')
-		if ('result' in node) return node.result!
+		if ('result' in node) {
+			if (options.onMemoizationDiscrepancy) {
+				const wasVerification = options.isVerificationRun
+				options.isVerificationRun = true
+				try {
+					const fresh = untracked(() => fn(...localArgs))
+					if (!deepCompare(node.result, fresh)) {
+						options.onMemoizationDiscrepancy(node.result, fresh, fn, localArgs, 'calculation')
+					}
+				} finally {
+					options.isVerificationRun = wasVerification
+				}
+			}
+			return node.result!
+		}
 
 		// Create memoize internal effect to track dependencies and invalidate cache
 		// Use untracked to prevent the effect creation from being affected by parent effects
 		node.cleanup = root(() =>
 			effect(
-				markWithRoot(() => {
+				() => {
 					// Execute the function and track its dependencies
 					// The function execution will automatically track dependencies on reactive objects
 					node.result = fn(...localArgs)
@@ -57,11 +75,31 @@ function memoizeFunction<Result, Args extends Memoizable[]>(
 						// When dependencies change, clear the cache and notify consumers
 						delete node.result
 						touched1(node, { type: 'invalidate', prop: localArgs }, 'memoize')
+						// Lazy memoization: stop the effect so it doesn't re-run immediately.
+						// It will be re-created on next access.
+						if (node.cleanup) {
+							node.cleanup()
+							node.cleanup = undefined
+						}
 					}
-				}, fnRoot),
+				},
 				{ opaque: true }
 			)
 		)
+
+		if (options.onMemoizationDiscrepancy) {
+			const wasVerification = options.isVerificationRun
+			options.isVerificationRun = true
+			try {
+				const fresh = untracked(() => fn(...localArgs))
+				if (!deepCompare(node.result, fresh)) {
+					options.onMemoizationDiscrepancy(node.result, fresh, fn, localArgs, 'comparison')
+				}
+			} finally {
+				options.isVerificationRun = wasVerification
+			}
+		}
+
 		return node.result!
 	}, fn)
 
@@ -71,35 +109,43 @@ function memoizeFunction<Result, Args extends Memoizable[]>(
 }
 
 export const memoize = decorator({
-	getter(original, propertyKey) {
-		const memoized = memoizeFunction(
-			markWithRoot(
-				renamed(
-					(that: object) => {
-						return original.call(that)
-					},
-					`${String(this.constructor.name)}.${String(propertyKey)}`
-				),
-				original
-			)
-		)
+	getter(original, target, propertyKey) {
 		return function (this: any) {
+			let wrapper = wrapperRegistry.get(original)
+			if (!wrapper) {
+				wrapper = markWithRoot(
+					renamed((that: object) => {
+						return original.call(that)
+					}, `${String(target?.constructor?.name ?? target?.name ?? 'Object')}.${String(propertyKey)}`),
+					{
+						method: original,
+						propertyKey,
+						...((original as any)[rootFunction] ? { [rootFunction]: (original as any)[rootFunction] } : {}),
+					}
+				)
+				wrapperRegistry.set(original, wrapper)
+			}
+			const memoized = memoizeFunction(wrapper as any)
 			return memoized(this)
 		}
 	},
-	method(original, name) {
-		const memoized = memoizeFunction(
-			markWithRoot(
-				renamed(
-					(that: object, ...args: object[]) => {
-						return original.call(that, ...args)
-					},
-					`${String(this.constructor.name)}.${String(name)}`
-				),
-				original
-			)
-		) as (...args: object[]) => unknown
+	method(original, target, name) {
 		return function (this: any, ...args: object[]) {
+			let wrapper = wrapperRegistry.get(original)
+			if (!wrapper) {
+				wrapper = markWithRoot(
+					renamed((that: object, ...args: object[]) => {
+						return original.call(that, ...args)
+					}, `${String(target?.constructor?.name ?? target?.name ?? 'Object')}.${String(name)}`),
+					{
+						method: original,
+						propertyKey: name,
+						...((original as any)[rootFunction] ? { [rootFunction]: (original as any)[rootFunction] } : {}),
+					}
+				)
+				wrapperRegistry.set(original, wrapper)
+			}
+			const memoized = memoizeFunction(wrapper as any) as (...args: object[]) => unknown
 			return memoized(this, ...args)
 		}
 	},

package/src/reactive/proxy.ts

@@ -127,12 +127,12 @@ const reactiveHandlers = {
 			const receiverDesc = Object.getOwnPropertyDescriptor(unwrappedReceiver, prop)
 			const targetDesc = Object.getOwnPropertyDescriptor(unwrappedObj, prop)
 			const desc = receiverDesc || targetDesc
-			// If it's a getter-only accessor (has getter but no setter), read without tracking
-			// to avoid breaking memoization invalidation when the getter calls memoized functions
+			// We *need* to use `receiver` and not `unwrappedObj` here, otherwise we break
+			// the dependency tracking for memoized getters
 			if (desc?.get && !desc?.set) {
-				oldVal = withEffect(undefined, () => Reflect.get(unwrappedObj, prop, unwrappedReceiver))
+				oldVal = withEffect(undefined, () => Reflect.get(unwrappedObj, prop, receiver))
 			} else {
-				oldVal = Reflect.get(unwrappedObj, prop, unwrappedReceiver)
+				oldVal = withEffect(undefined, () => Reflect.get(unwrappedObj, prop, receiver))
 			}
 		}
 		if (objectsWithDeepWatchers.has(obj)) {

package/src/reactive/registry.ts

@@ -0,0 +1,67 @@
+import { rootFunction, type ScopedCallback } from './types'
+
+// Track which effects are watching which reactive objects for cleanup
+export const effectToReactiveObjects = new WeakMap<ScopedCallback, Set<object>>()
+
+// Track effects per reactive object and property
+export const watchers = new WeakMap<object, Map<any, Set<ScopedCallback>>>()
+
+// runEffect -> set<stop>
+export const effectChildren = new WeakMap<ScopedCallback, Set<ScopedCallback>>()
+
+// Track parent effect relationships for hierarchy traversal (used in deep touch filtering)
+export const effectParent = new WeakMap<ScopedCallback, ScopedCallback | undefined>()
+
+// Track reverse mapping to ensure unicity: One Root -> One Function
+const reverseRoots = new WeakMap<any, WeakRef<Function>>()
+
+/**
+ * Marks a function with its root function for effect tracking
+ * Enforces strict unicity: A root function can only identify ONE function.
+ * @param fn - The function to mark
+ * @param root - The root function
+ * @returns The marked function
+ */
+export function markWithRoot<T extends Function>(fn: T, root: any): T {	
+	// Check for collision
+	const existingRef = reverseRoots.get(root)
+	const existing = existingRef?.deref()
+		
+	if (existing && existing !== fn) {
+		const rootName = root.name || 'anonymous'
+		const existingName = existing.name || 'anonymous'
+		const fnName = fn.name || 'anonymous'
+		throw new Error(
+			`[reactive] Abusive Shared Root detected: Root '${rootName}' is already identifying function '${existingName}'. ` +
+			`Cannot reuse it for '${fnName}'. Shared roots cause lost updates and broken identity logic.`
+		)
+	}
+	
+	// Always update the map so subsequent checks find this one
+	// (Last writer wins for the check)
+	reverseRoots.set(root, new WeakRef(fn))
+
+	// Mark fn with the new root
+	return Object.defineProperty(fn, rootFunction, {
+		value: getRoot(root),
+			writable: false,
+		})
+	}
+
+/**
+ * Gets the root function of a function for effect tracking
+ * @param fn - The function to get the root of
+ * @returns The root function
+ */
+export function getRoot<T extends Function | undefined>(fn: T): T {
+	while(fn && rootFunction in fn) fn = fn[rootFunction] as T
+	return fn
+}
+
+// Flag to disable dependency tracking for the current active effect (not globally)
+export const trackingDisabledEffects = new WeakSet<ScopedCallback>()
+export let globalTrackingDisabled = false
+
+export function setGlobalTrackingDisabled(value: boolean): void {
+	globalTrackingDisabled = value
+}

package/src/reactive/tracking.ts

@@ -1,45 +1,14 @@
 import { getActiveEffect } from './effect-context'
+import {
+	effectToReactiveObjects,
+	getRoot,
+	globalTrackingDisabled,
+	setGlobalTrackingDisabled,
+	trackingDisabledEffects,
+	watchers,
+} from './registry'
 import { unwrap } from './proxy-state'
-import { allProps, rootFunction, type ScopedCallback } from './types'
-
-// Track which effects are watching which reactive objects for cleanup
-export const effectToReactiveObjects = new WeakMap<ScopedCallback, Set<object>>()
-
-// Track effects per reactive object and property
-export const watchers = new WeakMap<object, Map<any, Set<ScopedCallback>>>()
-
-// runEffect -> set<stop>
-export const effectChildren = new WeakMap<ScopedCallback, Set<ScopedCallback>>()
-
-// Track parent effect relationships for hierarchy traversal (used in deep touch filtering)
-export const effectParent = new WeakMap<ScopedCallback, ScopedCallback | undefined>()
-
-/**
- * Marks a function with its root function for effect tracking
- * @param fn - The function to mark
- * @param root - The root function
- * @returns The marked function
- */
-export function markWithRoot<T extends Function>(fn: T, root: Function): T {
-	// Mark fn with the new root
-	return Object.defineProperty(fn, rootFunction, {
-		value: getRoot(root),
-		writable: false,
-	})
-}
-
-/**
- * Gets the root function of a function for effect tracking
- * @param fn - The function to get the root of
- * @returns The root function
- */
-export function getRoot<T extends Function | undefined>(fn: T): T {
-	return (fn as any)?.[rootFunction] || fn
-}
-
-// Flag to disable dependency tracking for the current active effect (not globally)
-const trackingDisabledEffects = new WeakSet<ScopedCallback>()
-let globalTrackingDisabled = false
+import { allProps, type ScopedCallback } from './types'
 
 export function getTrackingDisabled(): boolean {
 	const active = getActiveEffect()
@@ -50,7 +19,7 @@ export function getTrackingDisabled(): boolean {
 export function setTrackingDisabled(value: boolean): void {
 	const active = getActiveEffect()
 	if (!active) {
-		globalTrackingDisabled = value
+		setGlobalTrackingDisabled(value)
 		return
 	}
 	const root = getRoot(active)
@@ -58,6 +27,8 @@ export function setTrackingDisabled(value: boolean): void {
 	else trackingDisabledEffects.delete(root)
 }
 
+
+
 /**
  * Marks a property as a dependency of the current effect
  * @param obj - The object containing the property

package/src/reactive/types.ts

@@ -146,6 +146,16 @@ export const allProps = Symbol('all-props')
  */
 export const projectionInfo = Symbol('projection-info')
 
+/**
+ * Symbol to check if an effect is stopped
+ */
+export const stopped = Symbol('stopped')
+
+/**
+ * Symbol to access effect cleanup function
+ */
+export const cleanup = Symbol('cleanup')
+
 /**
  * Context for a running projection item effect
  */
@@ -278,6 +288,28 @@ export const options = {
 	 * @default 'throw'
 	 */
 	maxEffectReaction: 'throw' as 'throw' | 'debug' | 'warn',
+	/**
+	 * Callback called when a memoization discrepancy is detected (debug only)
+	 * When defined, memoized functions will run a second time (untracked) to verify consistency.
+	 * If the untracked run returns a different value than the cached one, this callback is triggered.
+	 * 
+	 * This is the primary tool for detecting missing reactive dependencies in computed values.
+	 * 
+	 * @param cached - The value currently in the memoization cache
+	 * @param fresh - The value obtained by re-running the function untracked
+	 * @param fn - The memoized function itself
+	 * @param args - Arguments passed to the function
+	 * 
+	 * @example
+	 * ```typescript
+	 * reactiveOptions.onMemoizationDiscrepancy = (cached, fresh, fn, args) => {
+	 *   throw new Error(`Memoization discrepancy in ${fn.name}!`);
+	 * };
+	 * ```
+	 */
+	onMemoizationDiscrepancy: undefined as
+		| ((cached: any, fresh: any, fn: Function, args: any[], cause: "calculation" | "comparison") => void)
+		| undefined,
 	/**
 	 * How to handle cycles detected in effect batches
 	 * - 'throw': Throw an error with cycle information (default, recommended for development)
@@ -287,6 +319,11 @@ export const options = {
 	 * @default 'throw'
 	 */
 	cycleHandling: 'throw' as 'throw' | 'warn' | 'break' | 'strict',
+	/**
+	 * Internal flag used by memoization discrepancy detector to avoid counting calls in tests
+	 * @warning Do not modify this flag manually, this flag is given by the engine
+	 */
+	isVerificationRun: false,
 	/**
 	 * Maximum depth for deep watching traversal
 	 * Used to prevent infinite recursion in circular references

package/src/std-decorators.ts

@@ -7,7 +7,7 @@ const syncCalculating: { object: object; prop: PropertyKey }[] = []
  * Prevents circular dependencies and provides automatic cache invalidation
  */
 export const cached = decorator({
-	getter(original, propertyKey) {
+	getter(original, _target, propertyKey) {
 		return function (this: any) {
 			const alreadyCalculating = syncCalculating.findIndex(
 				(c) => c.object === this && c.prop === propertyKey
@@ -83,19 +83,19 @@ export function describe(descriptor: {
  */
 export const deprecated = Object.assign(
 	decorator({
-		method(original, propertyKey) {
+		method(original, _target, propertyKey) {
 			return function (this: any, ...args: any[]) {
 				deprecated.warn(this, propertyKey)
 				return original.apply(this, args)
 			}
 		},
-		getter(original, propertyKey) {
+		getter(original, _target, propertyKey) {
 			return function (this: any) {
 				deprecated.warn(this, propertyKey)
 				return original.call(this)
 			}
 		},
-		setter(original, propertyKey) {
+		setter(original, _target, propertyKey) {
 			return function (this: any, value: any) {
 				deprecated.warn(this, propertyKey)
 				return original.call(this, value)
@@ -111,19 +111,19 @@ export const deprecated = Object.assign(
 		},
 		default(message: string) {
 			return decorator({
-				method(original, propertyKey) {
+				method(original, _target, propertyKey) {
 					return function (this: any, ...args: any[]) {
 						deprecated.warn(this, propertyKey, message)
 						return original.apply(this, args)
 					}
 				},
-				getter(original, propertyKey) {
+				getter(original, _target, propertyKey) {
 					return function (this: any) {
 						deprecated.warn(this, propertyKey, message)
 						return original.call(this)
 					}
 				},
-				setter(original, propertyKey) {
+				setter(original, _target, propertyKey) {
 					return function (this: any, value: any) {
 						deprecated.warn(this, propertyKey, message)
 						return original.call(this, value)
@@ -157,7 +157,7 @@ export const deprecated = Object.assign(
  */
 export function debounce(delay: number) {
 	return decorator({
-		method(original, _propertyKey) {
+		method(original, _target, _propertyKey) {
 			let timeoutId: ReturnType<typeof setTimeout> | null = null
 
 			return function (this: any, ...args: any[]) {
@@ -183,7 +183,7 @@ export function debounce(delay: number) {
  */
 export function throttle(delay: number) {
 	return decorator({
-		method(original, _propertyKey) {
+		method(original, _target, _propertyKey) {
 			let lastCallTime = 0
 			let timeoutId: ReturnType<typeof setTimeout> | null = null
 

package/src/utils.ts

@@ -1,3 +1,5 @@
+import { prototypeForwarding } from './reactive/types'
+
 type ElementTypes<T extends readonly unknown[]> = {
 	[K in keyof T]: T[K] extends readonly (infer U)[] ? U : T[K]
 }
@@ -115,3 +117,142 @@ export function isOwnAccessor(obj: any, prop: any) {
 	const opd = Object.getOwnPropertyDescriptor(obj, prop)
 	return !!(opd?.get || opd?.set)
 }
+
+/**
+ * Deeply compares two values.
+ * For objects, compares prototypes with === and then own properties recursively.
+ * Uses a cache to handle circular references.
+ * @param a - First value
+ * @param b - Second value
+ * @param cache - Map for circular reference protection (internal use)
+ * @returns True if values are deeply equal
+ */
+export function deepCompare(a: any, b: any, cache = new Map<object, Set<object>>()): boolean {
+	// Unwrap mutts proxies if present
+	while (a && typeof a === 'object' && prototypeForwarding in a) {
+		a = (a as any)[prototypeForwarding]
+	}
+	while (b && typeof b === 'object' && prototypeForwarding in b) {
+		b = (b as any)[prototypeForwarding]
+	}
+
+	if (a === b) return true
+
+	if (typeof a !== 'object' || a === null || typeof b !== 'object' || b === null) {
+		return a === b
+	}
+
+	// Prototype check
+	const protoA = Object.getPrototypeOf(a)
+	const protoB = Object.getPrototypeOf(b)
+	if (protoA !== protoB) {
+		console.warn(`[deepCompare] prototype mismatch:`, { nameA: a?.constructor?.name, nameB: b?.constructor?.name })
+		return false
+	}
+	// Circular reference protection
+	let compared = cache.get(a)
+	if (compared?.has(b)) return true
+	if (!compared) {
+		compared = new Set()
+		cache.set(a, compared)
+	}
+	compared.add(b)
+
+	// Handle specific object types
+	if (Array.isArray(a)) {
+		if (!Array.isArray(b)) {
+			console.warn(`[deepCompare] B is not an array`)
+			return false
+		}
+		if (a.length !== b.length) {
+			console.warn(`[deepCompare] array length mismatch:`, { lenA: a.length, lenB: b.length })
+			return false
+		}
+		for (let i = 0; i < a.length; i++) {
+			if (!deepCompare(a[i], b[i], cache)) {
+				console.warn(`[deepCompare] array element mismatch at index ${i}`)
+				return false
+			}
+		}
+		return true
+	}
+
+	if (a instanceof Date) {
+		const match = b instanceof Date && a.getTime() === b.getTime()
+		if (!match) console.warn(`[deepCompare] Date mismatch`)
+		return match
+	}
+	if (a instanceof RegExp) {
+		const match = b instanceof RegExp && a.toString() === b.toString()
+		if (!match) console.warn(`[deepCompare] RegExp mismatch`)
+		return match
+	}
+	if (a instanceof Set) {
+		if (!(b instanceof Set) || a.size !== b.size) {
+			console.warn(`[deepCompare] Set size mismatch`)
+			return false
+		}
+		for (const val of a) {
+			let found = false
+			for (const bVal of b) {
+				if (deepCompare(val, bVal, cache)) {
+					found = true
+					break
+				}
+			}
+			if (!found) {
+				console.warn(`[deepCompare] missing Set element`)
+				return false
+			}
+		}
+		return true
+	}
+	if (a instanceof Map) {
+		if (!(b instanceof Map) || a.size !== b.size) {
+			console.warn(`[deepCompare] Map size mismatch`)
+			return false
+		}
+		for (const [key, val] of a) {
+			if (!b.has(key)) {
+				let foundMatch = false
+				for (const [bKey, bVal] of b) {
+					if (deepCompare(key, bKey, cache) && deepCompare(val, bVal, cache)) {
+						foundMatch = true
+						break
+					}
+				}
+				if (!foundMatch) {
+					console.warn(`[deepCompare] missing Map key`)
+					return false
+				}
+			} else {
+				if (!deepCompare(val, b.get(key), cache)) {
+					console.warn(`[deepCompare] Map value mismatch for key`)
+					return false
+				}
+			}
+		}
+		return true
+	}
+
+	// Compare own properties
+	const keysA = Object.keys(a)
+	const keysB = Object.keys(b)
+	if (keysA.length !== keysB.length) {
+		console.warn(`[deepCompare] keys length mismatch:`, { lenA: keysA.length, lenB: keysB.length, keysA, keysB, a, b })
+		return false
+	}
+
+	for (const key of keysA) {
+		if (!Object.prototype.hasOwnProperty.call(b, key)) {
+			console.warn(`[deepCompare] missing key ${String(key)} in B`)
+			return false
+		}
+		if (!deepCompare(a[key], b[key], cache)) {
+			console.warn(`[deepCompare] value mismatch for key ${String(key)}:`, { valA: a[key], valB: b[key] })
+			return false
+		}
+	}
+
+	return true
+}

package/dist/chunks/_tslib-Mzh1rNsX.esm.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"_tslib-Mzh1rNsX.esm.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}