mutts 1.0.5 → 1.0.7

package/src/reactive/register.ts

@@ -1,8 +1,9 @@
+import { FunctionWrapper } from '../zone'
 import { ArrayReadForward, forwardArray, getAt, Indexable, setAt } from '../indexable'
 import { effect } from './effects'
 import { unreactive } from './interface'
 import { reactive } from './proxy'
-import { type DependencyFunction, prototypeForwarding, type ScopedCallback } from './types'
+import { type ScopedCallback } from './types'
 
 // TODO: use register in a real-world crud situation, have "events" for add, delete, update
 
@@ -36,7 +37,7 @@ function getRegisterBase<T>() {
 interface RegisterInstance<T> extends ArrayReadForward<T> {
 	[index: number]: T
 }
-
+// TODO: What to do with prototype forwarding ?
 @unreactive
 class RegisterClass<T, K extends PropertyKey = PropertyKey>
 	extends getRegisterBase<any>()
@@ -51,12 +52,12 @@ class RegisterClass<T, K extends PropertyKey = PropertyKey>
 	readonly #usage = new Map<K, number>()
 	readonly #valueInfo = new Map<T, { key: K; stop?: ScopedCallback }>()
 	readonly #keyEffects = new Set<ScopedCallback>()
-	readonly #ascend: DependencyFunction
+	readonly #ascend: FunctionWrapper
 
 	constructor(keyFn: KeyFunction<T, K>, initial?: Iterable<T>) {
 		super()
 		/* Moved below initialization */
-		let ascendGet: DependencyFunction | undefined
+		let ascendGet: FunctionWrapper | undefined
 		effect(({ ascend }) => {
 			ascendGet = ascend
 		})
@@ -65,9 +66,6 @@ class RegisterClass<T, K extends PropertyKey = PropertyKey>
 		this.#keyFn = keyFn
 		this.#keys = reactive([] as K[])
 		this.#values = reactive(new Map<K, T>())
-		Object.defineProperties(this, {
-			[prototypeForwarding]: { value: this.#keys },
-		})
 		if (initial) this.push(...initial)
 	}
 

package/src/reactive/registry.ts

@@ -0,0 +1,59 @@
+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
+}

package/src/reactive/set.ts

@@ -1,49 +1,38 @@
+import { contentRef } from '../utils'
 import { touched, touched1 } from './change'
 import { makeReactiveEntriesIterator, makeReactiveIterator } from './non-reactive'
 import { reactive } from './proxy'
 import { dependant } from './tracking'
-import { prototypeForwarding } from './types'
-
-const native = Symbol('native')
 
 /**
  * Reactive wrapper around JavaScript's WeakSet class
  * Only tracks individual value operations, no size tracking (WeakSet limitation)
  */
-export class ReactiveWeakSet<T extends object> {
-	readonly [native]!: WeakSet<T>
-	readonly content!: symbol
-
-	constructor(original: WeakSet<T>) {
-		Object.defineProperties(this, {
-			[native]: { value: original },
-			[prototypeForwarding]: { value: original },
-			content: { value: Symbol('WeakSetContent') },
-			[Symbol.toStringTag]: { value: 'ReactiveWeakSet' },
-		})
+export abstract class ReactiveWeakSet<T extends object> extends WeakSet<T> {
+	get [Symbol.toStringTag]() {
+		return 'ReactiveWeakSet'
 	}
-
 	add(value: T): this {
-		const had = this[native].has(value)
-		this[native].add(value)
+		const had = this.has(value)
+		this.add(value)
 		if (!had) {
 			// touch the specific value and the collection view
-			touched1(this.content, { type: 'add', prop: value }, value)
+			touched1(contentRef(this), { type: 'add', prop: value }, value)
 			// no size/allProps for WeakSet
 		}
 		return this
 	}
 
 	delete(value: T): boolean {
-		const had = this[native].has(value)
-		const res = this[native].delete(value)
-		if (had) touched1(this.content, { type: 'del', prop: value }, value)
+		const had = this.has(value)
+		const res = this.delete(value)
+		if (had) touched1(contentRef(this), { type: 'del', prop: value }, value)
 		return res
 	}
 
 	has(value: T): boolean {
-		dependant(this.content, value)
-		return this[native].has(value)
+		dependant(contentRef(this), value)
+		return this.has(value)
 	}
 }
 
@@ -51,86 +40,79 @@ export class ReactiveWeakSet<T extends object> {
  * Reactive wrapper around JavaScript's Set class
  * Tracks size changes, individual value operations, and collection-wide operations
  */
-export class ReactiveSet<T> {
-	readonly [native]!: Set<T>
-	readonly content!: symbol
-	constructor(original: Set<T>) {
-		Object.defineProperties(this, {
-			[native]: { value: original },
-			[prototypeForwarding]: { value: original },
-			content: { value: Symbol('SetContent') },
-			[Symbol.toStringTag]: { value: 'ReactiveSet' },
-		})
+export abstract class ReactiveSet<T> extends Set<T> {
+	get [Symbol.toStringTag]() {
+		return 'ReactiveSet'
 	}
 
 	get size(): number {
 		// size depends on the wrapper instance, like Map counterpart
 		dependant(this, 'size')
-		return this[native].size
+		return this.size
 	}
 
 	add(value: T): this {
-		const had = this[native].has(value)
+		const had = this.has(value)
 		const reactiveValue = reactive(value)
-		this[native].add(reactiveValue)
+		this.add(reactiveValue)
 		if (!had) {
 			const evolution = { type: 'add', prop: reactiveValue } as const
 			// touch for value-specific and aggregate dependencies
-			touched1(this.content, evolution, reactiveValue)
+			touched1(contentRef(this), evolution, reactiveValue)
 			touched1(this, evolution, 'size')
 		}
 		return this
 	}
 
 	clear(): void {
-		const hadEntries = this[native].size > 0
-		this[native].clear()
+		const hadEntries = this.size > 0
+		this.clear()
 		if (hadEntries) {
 			const evolution = { type: 'bunch', method: 'clear' } as const
 			touched1(this, evolution, 'size')
-			touched(this.content, evolution)
+			touched(contentRef(this), evolution)
 		}
 	}
 
 	delete(value: T): boolean {
-		const had = this[native].has(value)
-		const res = this[native].delete(value)
+		const had = this.has(value)
+		const res = this.delete(value)
 		if (had) {
 			const evolution = { type: 'del', prop: value } as const
-			touched1(this.content, evolution, value)
+			touched1(contentRef(this), evolution, value)
 			touched1(this, evolution, 'size')
 		}
 		return res
 	}
 
 	has(value: T): boolean {
-		dependant(this.content, value)
-		return this[native].has(value)
+		dependant(contentRef(this), value)
+		return this.has(value)
 	}
 
 	entries(): Generator<[T, T]> {
-		dependant(this.content)
-		return makeReactiveEntriesIterator(this[native].entries())
+		dependant(contentRef(this))
+		return makeReactiveEntriesIterator(this.entries())
 	}
 
 	forEach(callbackfn: (value: T, value2: T, set: Set<T>) => void, thisArg?: any): void {
-		dependant(this.content)
-		this[native].forEach(callbackfn, thisArg)
+		dependant(contentRef(this))
+		this.forEach(callbackfn, thisArg)
 	}
 
 	keys(): Generator<T> {
-		dependant(this.content)
-		return makeReactiveIterator(this[native].keys())
+		dependant(contentRef(this))
+		return makeReactiveIterator(this.keys())
 	}
 
 	values(): Generator<T> {
-		dependant(this.content)
-		return makeReactiveIterator(this[native].values())
+		dependant(contentRef(this))
+		return makeReactiveIterator(this.values())
 	}
 
-	[Symbol.iterator](): Iterator<T> {
-		dependant(this.content)
-		const nativeIterator = this[native][Symbol.iterator]()
+	[Symbol.iterator](): SetIterator<T> {
+		dependant(contentRef(this))
+		const nativeIterator = this[Symbol.iterator]()
 		return {
 			next() {
 				const result = nativeIterator.next()
@@ -139,6 +121,10 @@ export class ReactiveSet<T> {
 				}
 				return { value: reactive(result.value), done: false }
 			},
+			[Symbol.iterator]() {
+				return this
+			},
+			[Symbol.dispose]() {},
 		}
 	}
 }

package/src/reactive/tracking.ts

@@ -1,62 +1,10 @@
 import { getActiveEffect } from './effect-context'
 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
-
-export function getTrackingDisabled(): boolean {
-	const active = getActiveEffect()
-	if (!active) return globalTrackingDisabled
-	return trackingDisabledEffects.has(getRoot(active))
-}
-
-export function setTrackingDisabled(value: boolean): void {
-	const active = getActiveEffect()
-	if (!active) {
-		globalTrackingDisabled = value
-		return
-	}
-	const root = getRoot(active)
-	if (value) trackingDisabledEffects.add(root)
-	else trackingDisabledEffects.delete(root)
-}
+import {
+	effectToReactiveObjects,
+	watchers,
+} from './registry'
+import { allProps, type ScopedCallback } from './types'
 
 /**
  * Marks a property as a dependency of the current effect
@@ -70,15 +18,10 @@ export function dependant(obj: any, prop: any = allProps) {
 	// Early return if no active effect, tracking disabled, or invalid prop
 	if (
 		!currentActiveEffect ||
-		getTrackingDisabled() ||
 		(typeof prop === 'symbol' && prop !== allProps)
 	)
 		return
 
-	registerDependency(obj, prop, currentActiveEffect)
-}
-
-function registerDependency(obj: any, prop: any, currentActiveEffect: ScopedCallback) {
 	let objectWatchers = watchers.get(obj)
 	if (!objectWatchers) {
 		objectWatchers = new Map<PropertyKey, Set<ScopedCallback>>()

package/src/reactive/types.ts

@@ -1,11 +1,8 @@
 // biome-ignore-all lint/suspicious/noConfusingVoidType: Type 'void' is not assignable to type 'ScopedCallback | undefined'.
 // Argument of type '() => void' is not assignable to parameter of type '(dep: DependencyFunction) => ScopedCallback | undefined'.
 
-/**
- * Function type for dependency tracking in effects
- * Restores the active effect context for dependency tracking
- */
-export type DependencyFunction = <T>(cb: () => T) => T
+import { FunctionWrapper } from "../zone"
+
 /**
  * Dependency access passed to user callbacks within effects/watch
  * Provides functions to track dependencies and information about the effect execution
@@ -25,7 +22,7 @@ export interface DependencyAccess {
 	 * })
 	 * ```
 	 */
-	tracked: DependencyFunction
+	tracked: FunctionWrapper
 	/**
 	 * Tracks dependencies in the parent effect context
 	 * Use this when child effects should track dependencies in the parent,
@@ -43,7 +40,7 @@ export interface DependencyAccess {
 	 * })
 	 * ```
 	 */
-	ascend: DependencyFunction
+	ascend: FunctionWrapper
 	/**
 	 * Indicates whether the effect is running as a reaction (i.e. not the first call)
 	 * - `false`: First execution when the effect is created
@@ -131,10 +128,6 @@ export const nonReactiveMark = Symbol('non-reactive')
  * Symbol to mark class properties as non-reactive
  */
 export const unreactiveProperties = Symbol('unreactive-properties')
-/**
- * Symbol for prototype forwarding in reactive objects
- */
-export const prototypeForwarding: unique symbol = Symbol('prototype-forwarding')
 
 /**
  * Symbol representing all properties in reactive tracking
@@ -146,6 +139,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
  */
@@ -169,6 +172,7 @@ export enum ReactiveErrorCode {
 	MaxReactionExceeded = 'MAX_REACTION_EXCEEDED',
 	WriteInComputed = 'WRITE_IN_COMPUTED',
 	TrackingError = 'TRACKING_ERROR',
+	BrokenEffects = 'BROKEN_EFFECTS',
 }
 
 export type CycleDebugInfo = {
@@ -189,6 +193,11 @@ export type MaxReactionDebugInfo = {
 	effect: string
 }
 
+export type BrokenEffectsDebugInfo = {
+	code: ReactiveErrorCode.BrokenEffects
+	cause: any
+}
+
 export type GenericDebugInfo = {
 	code: ReactiveErrorCode
 	causalChain?: string[]
@@ -200,6 +209,7 @@ export type ReactiveDebugInfo =
 	| CycleDebugInfo
 	| MaxDepthDebugInfo
 	| MaxReactionDebugInfo
+	| BrokenEffectsDebugInfo
 	| GenericDebugInfo
 
 /**
@@ -213,6 +223,14 @@ export class ReactiveError extends Error {
 		super(message)
 		this.name = 'ReactiveError'
 	}
+
+	get code(): ReactiveErrorCode | undefined {
+		return this.debugInfo?.code
+	}
+
+	get cause(): any {
+		return (this.debugInfo as any)?.cause
+	}
 }
 
 // biome-ignore-start lint/correctness/noUnusedFunctionParameters: Interface declaration with empty defaults
@@ -259,7 +277,7 @@ export const options = {
 	 * @param effect - The effect that is already running
 	 * @param runningChain - The array of effects from the detected one to the currently running one
 	 */
-	skipRunningEffect: (_effect: ScopedCallback, _runningChain: ScopedCallback[]) => {},
+	skipRunningEffect: (_effect: ScopedCallback) => {},
 	/**
 	 * Debug purpose: maximum effect chain (like call stack max depth)
 	 * Used to prevent infinite loops
@@ -279,14 +297,55 @@ export const options = {
 	 */
 	maxEffectReaction: 'throw' as 'throw' | 'debug' | 'warn',
 	/**
-	 * How to handle cycles detected in effect batches
-	 * - 'throw': Throw an error with cycle information (default, recommended for development)
-	 * - 'warn': Log a warning and break the cycle by executing one effect
-	 * - 'break': Silently break the cycle by executing one effect (recommended for production)
-	 * - 'strict': Prevent cycle creation by checking graph before execution (throws error)
-	 * @default 'throw'
+	 * 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.
+	 *
+	 * - `'none'` (Default): High-performance mode. Disables dependency graph maintenance and
+	 *   Topological Sorting in favor of a simple FIFO queue. Use this for trustworthy, acyclic UI code.
+	 *   Cycle detection is heuristic (uses execution counts).
+	 *
+	 * - `'throw'`: Traditional Topological Sorting. Guarantees dependency order and catches
+	 *   circular dependencies mathematically before execution.
+	 *
+	 * - `'warn'`: Topological sorting, but logs a warning instead of throwing on cycles.
+	 * - `'break'`: Topological sorting, but silently breaks cycles.
+	 * - `'strict'`: Prevents cycle creation by checking the graph *during* dependency discovery.
+	 *
+	 * @default 'none'
+	 */
+	cycleHandling: 'none' as 'none' | '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
 	 */
-	cycleHandling: 'throw' as 'throw' | 'warn' | 'break' | 'strict',
+	isVerificationRun: false,
 	/**
 	 * Maximum depth for deep watching traversal
 	 * Used to prevent infinite recursion in circular references
@@ -351,6 +410,7 @@ export const options = {
 	 * Configuration for zone hooks - control which async APIs are hooked
 	 * Each option controls whether the corresponding async API is wrapped to preserve effect context
 	 * Only applies when asyncMode is enabled (truthy)
+	 * @deprecated Should take all when we made sure PIXI.create, Game.create, ... are -> .root()
 	 */
 	zones: {
 		/**

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