mutts 1.0.4 → 1.0.6

package/src/reactive/project.ts

@@ -1,9 +1,29 @@
 import { ReflectGet, ReflectSet } from '../utils'
+import { setEffectName } from './debug'
+import { getActiveEffect } from './effect-context'
 import { effect, untracked } from './effects'
 import { cleanedBy, cleanup } from './interface'
 import { reactive } from './proxy'
 import { Register } from './register'
-import { type ScopedCallback } from './types'
+import { type ProjectionContext, projectionInfo, type ScopedCallback } from './types'
+
+/**
+ * Maps projection effects (item effects) to their projection context
+ */
+export const effectProjectionMetadata = new WeakMap<ScopedCallback, ProjectionContext>()
+
+/**
+ * Returns the projection context of the currently running effect, if any.
+ */
+export function getActiveProjection(): ProjectionContext | undefined {
+	const active = getActiveEffect()
+	return active ? effectProjectionMetadata.get(active) : undefined
+}
+
+/* TODO
+It seems to work and I feel like it's correct but I couldn't validate theoretically that `ascend`
+is the correct way to deal with nested effects.
+*/
 
 type ProjectOldValue<Target> = Target extends readonly (infer Item)[]
 	? Item
@@ -50,8 +70,17 @@ function defineAccessValue<Access extends { get(): unknown; set(value: unknown):
 function makeCleanup<Result extends object>(
 	target: Result,
 	effectMap: Map<unknown, ScopedCallback>,
-	onDispose: () => void
+	onDispose: () => void,
+	metadata?: any
 ): ProjectResult<Result> {
+	if (metadata) {
+		Object.defineProperty(target, projectionInfo, {
+			value: metadata,
+			writable: false,
+			enumerable: false,
+			configurable: true,
+		})
+	}
 	return cleanedBy(target, () => {
 		onDispose()
 		for (const stop of effectMap.values()) stop?.()
@@ -80,6 +109,9 @@ function projectArray<SourceValue, ResultValue>(
 		}
 	}
 
+	const parent = getActiveProjection()
+	const depth = parent ? parent.depth + 1 : 0
+
 	const cleanupLength = effect(function projectArrayLengthEffect({ ascend }) {
 		const length = observedSource.length
 		normalizeTargetLength(length)
@@ -102,13 +134,27 @@ function projectArray<SourceValue, ResultValue>(
 					const produced = apply(accessBase, target)
 					target[index] = produced
 				})
+				setEffectName(stop, `project[${depth}]:${index}`)
+				effectProjectionMetadata.set(stop, {
+					source: observedSource,
+					key: index,
+					target,
+					depth,
+					parent,
+				})
 				indexEffects.set(i, stop)
 			})
 		}
 		for (const index of existing) if (index >= length) disposeIndex(index)
 	})
 
-	return makeCleanup(target, indexEffects, () => cleanupLength())
+	return makeCleanup(target, indexEffects, () => cleanupLength(), {
+		source: observedSource,
+		target,
+		apply,
+		depth,
+		parent,
+	} as ProjectionContext)
 }
 
 function projectRegister<Key extends PropertyKey, SourceValue, ResultValue>(
@@ -135,6 +181,9 @@ function projectRegister<Key extends PropertyKey, SourceValue, ResultValue>(
 		}
 	}
 
+	const parent = getActiveProjection()
+	const depth = parent ? parent.depth + 1 : 0
+
 	const cleanupKeys = effect(function projectRegisterEffect({ ascend }) {
 		const keys = new Set<Key>()
 		for (const key of observedSource.mapKeys()) keys.add(key)
@@ -158,6 +207,14 @@ function projectRegister<Key extends PropertyKey, SourceValue, ResultValue>(
 					const produced = apply(accessBase, target)
 					target.set(key, produced)
 				})
+				setEffectName(stop, `project[${depth}]:${String(key)}`)
+				effectProjectionMetadata.set(stop, {
+					source: observedSource,
+					key,
+					target,
+					depth,
+					parent,
+				})
 				keyEffects.set(key, stop)
 			})
 		}
@@ -165,7 +222,13 @@ function projectRegister<Key extends PropertyKey, SourceValue, ResultValue>(
 		for (const key of Array.from(keyEffects.keys())) if (!keys.has(key)) disposeKey(key)
 	})
 
-	return makeCleanup(target, keyEffects, () => cleanupKeys())
+	return makeCleanup(target, keyEffects, () => cleanupKeys(), {
+		source: observedSource,
+		target,
+		apply,
+		depth,
+		parent,
+	} as ProjectionContext)
 }
 
 function projectRecord<Source extends Record<PropertyKey, any>, ResultValue>(
@@ -191,6 +254,9 @@ function projectRecord<Source extends Record<PropertyKey, any>, ResultValue>(
 		}
 	}
 
+	const parent = getActiveProjection()
+	const depth = parent ? parent.depth + 1 : 0
+
 	const cleanupKeys = effect(function projectRecordEffect({ ascend }) {
 		const keys = new Set<PropertyKey>()
 		for (const key in observedSource) keys.add(key)
@@ -222,6 +288,14 @@ function projectRecord<Source extends Record<PropertyKey, any>, ResultValue>(
 					const produced = apply(accessBase, target)
 					;(target as any)[sourceKey] = produced
 				})
+				setEffectName(stop, `project[${depth}]:${String(key)}`)
+				effectProjectionMetadata.set(stop, {
+					source: observedSource,
+					key,
+					target,
+					depth,
+					parent,
+				})
 				keyEffects.set(key, stop)
 			})
 		}
@@ -229,7 +303,13 @@ function projectRecord<Source extends Record<PropertyKey, any>, ResultValue>(
 		for (const key of Array.from(keyEffects.keys())) if (!keys.has(key)) disposeKey(key)
 	})
 
-	return makeCleanup(target, keyEffects, () => cleanupKeys())
+	return makeCleanup(target, keyEffects, () => cleanupKeys(), {
+		source: observedSource,
+		target,
+		apply,
+		depth,
+		parent,
+	} as ProjectionContext)
 }
 
 function projectMap<Key, Value, ResultValue>(
@@ -250,6 +330,9 @@ function projectMap<Key, Value, ResultValue>(
 		}
 	}
 
+	const parent = getActiveProjection()
+	const depth = parent ? parent.depth + 1 : 0
+
 	const cleanupKeys = effect(function projectMapEffect({ ascend }) {
 		const keys = new Set<Key>()
 		for (const key of observedSource.keys()) keys.add(key)
@@ -273,6 +356,14 @@ function projectMap<Key, Value, ResultValue>(
 					const produced = apply(accessBase, target)
 					target.set(key, produced)
 				})
+				setEffectName(stop, `project[${depth}]:${String(key)}`)
+				effectProjectionMetadata.set(stop, {
+					source: observedSource,
+					key,
+					target,
+					depth,
+					parent,
+				})
 				keyEffects.set(key, stop)
 			})
 		}
@@ -280,7 +371,13 @@ function projectMap<Key, Value, ResultValue>(
 		for (const key of Array.from(keyEffects.keys())) if (!keys.has(key)) disposeKey(key)
 	})
 
-	return makeCleanup(target, keyEffects, () => cleanupKeys())
+	return makeCleanup(target, keyEffects, () => cleanupKeys(), {
+		source: observedSource,
+		target,
+		apply,
+		depth,
+		parent,
+	} as ProjectionContext)
 }
 
 type ProjectOverload = {

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/set.ts

@@ -11,14 +11,14 @@ const native = Symbol('native')
  * Only tracks individual value operations, no size tracking (WeakSet limitation)
  */
 export class ReactiveWeakSet<T extends object> {
-	declare readonly [native]: WeakSet<T>
-	declare readonly content: symbol
+	readonly [native]!: WeakSet<T>
+	readonly content!: symbol
 
 	constructor(original: WeakSet<T>) {
 		Object.defineProperties(this, {
 			[native]: { value: original },
 			[prototypeForwarding]: { value: original },
-			content: { value: Symbol('content') },
+			content: { value: Symbol('WeakSetContent') },
 			[Symbol.toStringTag]: { value: 'ReactiveWeakSet' },
 		})
 	}
@@ -52,13 +52,13 @@ export class ReactiveWeakSet<T extends object> {
  * Tracks size changes, individual value operations, and collection-wide operations
  */
 export class ReactiveSet<T> {
-	declare readonly [native]: Set<T>
-	declare readonly content: symbol
+	readonly [native]!: Set<T>
+	readonly content!: symbol
 	constructor(original: Set<T>) {
 		Object.defineProperties(this, {
 			[native]: { value: original },
 			[prototypeForwarding]: { value: original },
-			content: { value: Symbol('content') },
+			content: { value: Symbol('SetContent') },
 			[Symbol.toStringTag]: { value: 'ReactiveSet' },
 		})
 	}

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

@@ -141,6 +141,32 @@ export const prototypeForwarding: unique symbol = Symbol('prototype-forwarding')
  */
 export const allProps = Symbol('all-props')
 
+/**
+ * Symbol for accessing projection information on reactive objects
+ */
+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
+ */
+export interface ProjectionContext {
+	source: any
+	key?: any
+	target: any
+	depth: number
+	parent?: ProjectionContext
+}
+
 // Symbol to mark functions with their root function
 const rootFunction = Symbol('root-function')
 
@@ -250,12 +276,40 @@ export const options = {
 	 * @default 100
 	 */
 	maxEffectChain: 100,
+	/**
+	 * Maximum number of times an effect can be triggered by the same cause in a single batch
+	 * Used to detect aggressive re-computation or infinite loops
+	 * @default 10
+	 */
+	maxTriggerPerBatch: 10,
 	/**
 	 * Debug purpose: maximum effect reaction (like call stack max depth)
 	 * Used to prevent infinite loops
 	 * @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)
@@ -265,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/reactive/zone.ts

@@ -15,7 +15,7 @@
  */
 
 import { captureEffectStack, withEffectStack } from './effect-context'
-import { options, ScopedCallback } from './types'
+import { options, type ScopedCallback } from './types'
 
 let zoneHooked = false
 

package/src/std-decorators.ts

@@ -1,4 +1,4 @@
-import { decorator, GenericClassDecorator } from './decorator'
+import { decorator, type GenericClassDecorator } from './decorator'
 
 // In order to avoid async re-entrance, we could use zone.js or something like that.
 const syncCalculating: { object: object; prop: PropertyKey }[] = []
@@ -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