mutts 1.0.4 → 1.0.6

package/src/reactive/change.ts

@@ -1,9 +1,9 @@
 import { recordTriggerLink } from './debug'
 import { bubbleUpChange, objectsWithDeepWatchers } from './deep-watch-state'
 import { getActiveEffect, isRunning } from './effect-context'
-import { batch, effectTrackers, opaqueEffects } from './effects'
+import { batch, effectTrackers, hasBatched, opaqueEffects, recordActivation } from './effects'
 import { unwrap } from './proxy-state'
-import { watchers } from './tracking'
+import { watchers } from './registry'
 import { allProps, type Evolution, options, type ScopedCallback, type State } from './types'
 
 const states = new WeakMap<object, State>()
@@ -49,7 +49,10 @@ export function collectEffects(
 						options.skipRunningEffect(effect, runningChain as any)
 						continue
 					}
-					effects.add(effect)
+					if (!effects.has(effect)) {
+						effects.add(effect)
+						if (!hasBatched(effect)) recordActivation(effect, obj, evolution, key)
+					}
 					const trackers = effectTrackers.get(effect)
 					recordTriggerLink(sourceEffect, effect, obj, key, evolution)
 					if (trackers) {
@@ -119,6 +122,7 @@ export function touchedOpaque(obj: any, evolution: Evolution, prop: any) {
 			continue
 		}
 		effects.add(effect)
+		recordActivation(effect, obj, evolution, prop)
 		const trackers = effectTrackers.get(effect)
 		recordTriggerLink(sourceEffect, effect, obj, prop, evolution)
 		if (trackers) {

package/src/reactive/debug.ts

@@ -5,7 +5,7 @@
  * - Provides graph data for tooling (DevTools panel, etc.)
  */
 
-import { effectParent, effectToReactiveObjects, getRoot } from './tracking'
+import { effectParent, effectToReactiveObjects, getRoot } from './registry'
 import { allProps, type Evolution, options, type ScopedCallback } from './types'
 
 const EXTERNAL_SOURCE = Symbol('external-source')

package/src/reactive/deep-touch.ts

@@ -3,7 +3,7 @@ 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 { effectParent, watchers } from './registry'
 import { allProps, type Evolution, options, type ScopedCallback } from './types'
 
 function isObject(value: any): value is object {

package/src/reactive/deep-watch.ts

@@ -6,7 +6,7 @@ import {
 import { effect } from './effects'
 import { isNonReactive } from './non-reactive-state'
 import { reactive, unwrap } from './proxy'
-import { markWithRoot } from './tracking'
+import { markWithRoot } from './registry'
 import { options, type ScopedCallback } from './types'
 
 function isObject(value: any): value is object {

package/src/reactive/effect-context.ts

@@ -1,4 +1,4 @@
-import { effectParent, getRoot } from './tracking'
+import { effectParent, getRoot } from './registry'
 import { ReactiveError, type ScopedCallback } from './types'
 
 /**
@@ -77,7 +77,7 @@ export function getActiveEffect() {
  * @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 {

package/src/reactive/effects.ts

@@ -8,16 +8,18 @@ import {
 	withEffect,
 	withEffectStack,
 } from './effect-context'
+import {
+	getTrackingDisabled,
+	setTrackingDisabled,
+} from './tracking'
 import {
 	effectChildren,
 	effectParent,
 	effectToReactiveObjects,
 	getRoot,
-	getTrackingDisabled,
 	markWithRoot,
-	setTrackingDisabled,
 	watchers,
-} from './tracking'
+} from './registry'
 import {
 	type DependencyAccess,
 	type EffectOptions,
@@ -27,6 +29,8 @@ import {
 	ReactiveErrorCode,
 	// type AsyncExecutionMode,
 	type ScopedCallback,
+	cleanup as cleanupSymbol,
+	stopped,
 } from './types'
 
 /**
@@ -60,6 +64,69 @@ import { ensureZoneHooked } from './zone'
 type EffectTracking = (obj: any, evolution: Evolution, prop: any) => void
 
 export { captureEffectStack, withEffectStack, getActiveEffect, effectStack }
+export interface ActivationRecord {
+	effect: ScopedCallback
+	obj: any
+	evolution: Evolution
+	prop: any
+	batchId: number
+}
+
+// Nested map structure for efficient counting and batch cleanup
+// batchId -> effect root -> obj -> prop -> count
+let activationRegistry: Map<Function, Map<any, Map<any, number>>> | undefined
+
+export const activationLog: Omit<ActivationRecord, 'batchId'>[] = new Array(100)
+
+export function getActivationLog() {
+	return activationLog
+}
+
+export function recordActivation(
+	effect: ScopedCallback,
+	obj: any,
+	evolution: Evolution,
+	prop: any
+) {
+	const root = getRoot(effect)
+
+	if (!activationRegistry) return
+	let effectData = activationRegistry.get(root)
+	if (!effectData) {
+		effectData = new Map()
+		activationRegistry.set(root, effectData)
+	}
+	let objData = effectData.get(obj)
+	if (!objData) {
+		objData = new Map()
+		effectData.set(obj, objData)
+	}
+	const count = (objData.get(prop) ?? 0) + 1
+	objData.set(prop, count)
+
+	// Keep a limited history for diagnostics
+	activationLog.unshift({
+		effect,
+		obj,
+		evolution,
+		prop,
+	})
+	activationLog.pop()
+
+	if (count >= options.maxTriggerPerBatch) {
+		const effectName = (root as any)?.name || 'anonymous'
+		const message = `Aggressive trigger detected: effect "${effectName}" triggered ${count} times in the batch by the same cause.`
+		if (options.maxEffectReaction === 'throw') {
+			throw new ReactiveError(message, {
+				code: ReactiveErrorCode.MaxReactionExceeded,
+				count,
+				effect: effectName,
+			})
+		}
+		options.warn(`[reactive] ${message}`)
+	}
+}
+
 /**
  * Registers a debug callback that is called when the current effect is triggered by a dependency change
  *
@@ -234,6 +301,7 @@ function addGraphEdge(callerRoot: Function, targetRoot: Function) {
  * @param end - Target node
  * @param exclude - Node to exclude from the path
  * @returns true if a path exists without going through the excluded node
+ * @todo Can be REALLY costly - optimise or make optional or ...
  */
 function hasPathExcluding(start: Function, end: Function, exclude: Function): boolean {
 	if (start === end) return true
@@ -380,6 +448,9 @@ interface BatchQueue {
 // Track currently executing effects to prevent re-execution
 // These are all the effects triggered under `activeEffect`
 let batchQueue: BatchQueue | undefined
+export function hasBatched(effect: ScopedCallback) {
+	return batchQueue?.all.has(getRoot(effect))
+}
 const batchCleanups = new Set<ScopedCallback>()
 
 /**
@@ -555,6 +626,11 @@ function wouldCreateCycle(callerRoot: Function, targetRoot: Function): boolean {
  * @param immediate - If true, don't create edges in the dependency graph
  */
 function addToBatch(effect: ScopedCallback, caller?: ScopedCallback, immediate?: boolean) {
+	const cleanupFn = (effect as any)[cleanupSymbol]
+	if (cleanupFn) cleanupFn()
+	// If the effect was stopped during cleanup (e.g. lazy memoization), don't add it to the batch
+	if ((effect as any)[stopped]) return
+
 	if (!batchQueue) return
 
 	const root = getRoot(effect)
@@ -851,6 +927,8 @@ export function batch(effect: ScopedCallback | ScopedCallback[], immediate?: 'im
 		// Otherwise, effects will be picked up in next executeNext() call
 	} else {
 		// New batch - initialize
+		if (!activationRegistry) activationRegistry = new Map()
+		else throw new Error('Batch already in progress')
 		options.beginChain(roots)
 		batchQueue = {
 			all: new Map(),
@@ -931,6 +1009,7 @@ export function batch(effect: ScopedCallback | ScopedCallback[], immediate?: 'im
 				for (const cleanup of cleanups) cleanup()
 				return firstReturn.value
 			} finally {
+				activationRegistry = undefined
 				batchQueue = undefined
 				options.endChain()
 			}
@@ -1003,11 +1082,11 @@ export function batch(effect: ScopedCallback | ScopedCallback[], immediate?: 'im
 				}
 				return firstReturn.value
 			} finally {
+				activationRegistry = undefined
 				batchQueue = undefined
 				options.endChain()
 			}
 		}
-
 	}
 }
 
@@ -1016,21 +1095,21 @@ export function batch(effect: ScopedCallback | ScopedCallback[], immediate?: 'im
  */
 export const atomic = decorator({
 	method(original) {
-		return function (...args: any[]) {
-			return batch(
-				markWithRoot(() => original.apply(this, args), original),
-				'immediate'
-			)
+		return function (this: any, ...args: any[]) {
+			const atomicEffect = () => original.apply(this, args)
+			// Debug: helpful to have a name
+			Object.defineProperty(atomicEffect, 'name', { value: `atomic(${original.name})` })
+			return batch(atomicEffect, 'immediate')
 		}
 	},
 	default<Args extends any[], Return>(
 		original: (...args: Args) => Return
 	): (...args: Args) => Return {
 		return function (this: any, ...args: Args) {
-			return batch(
-				markWithRoot(() => original.apply(this, args), original),
-				'immediate'
-			)
+			const atomicEffect = () => original.apply(this, args)
+			// Debug: helpful to have a name
+			Object.defineProperty(atomicEffect, 'name', { value: `atomic(${original.name})` })
+			return batch(atomicEffect, 'immediate')
 		}
 	},
 })
@@ -1069,7 +1148,7 @@ export function effect(
 	let cleanup: (() => void) | null = null
 	// capture the parent effect at creation time for ascend
 	const parentsForAscend = captureEffectStack()
-	const tracked = markWithRoot(<T>(cb: () => T) => withEffect(runEffect, cb), fn)
+	const tracked = <T>(cb: () => T) => withEffect(runEffect, cb)
 	const ascend = <T>(cb: () => T) => withEffectStack(parentsForAscend, cb)
 	let effectStopped = false
 	let hasReacted = false
@@ -1213,8 +1292,25 @@ export function effect(
 		cleanupEffectFromGraph(runEffect)
 		fr.unregister(stopEffect)
 	}
+	function augmentedRv(rv: ScopedCallback): ScopedCallback {
+		Object.defineProperty(rv, stopped, {
+			get() {
+				return effectStopped
+			},
+		})
+		Object.defineProperty(rv, cleanupSymbol, {
+			value: () => {
+				if (cleanup) {
+					const prevCleanup = cleanup
+					cleanup = null
+					withEffect(undefined, () => prevCleanup())
+				}
+			},
+		})
+		return rv
+	}
 	if (isRootEffect) {
-		const callIfCollected = () => stopEffect()
+		const callIfCollected = augmentedRv(() => stopEffect())
 		fr.register(
 			callIfCollected,
 			() => {
@@ -1231,15 +1327,16 @@ export function effect(
 		children = new Set()
 		effectChildren.set(parent, children)
 	}
-	const subEffectCleanup = (): void => {
+	const subEffectCleanup = augmentedRv(() => {
 		children.delete(subEffectCleanup)
 		if (children.size === 0) {
 			effectChildren.delete(parent)
 		}
 		// Execute this child effect cleanup (which triggers its own mainCleanup)
 		stopEffect()
-	}
+	})
 	children.add(subEffectCleanup)
+
 	return subEffectCleanup
 }
 

package/src/reactive/index.ts

@@ -17,6 +17,7 @@ export {
 	biDi,
 	defer,
 	effect,
+	getActivationLog,
 	getActiveEffect,
 	root,
 	trackEffect,
@@ -26,7 +27,7 @@ export { cleanedBy, cleanup, derived, unreactive, watch } from './interface'
 export { mapped, ReadOnlyError, reduced } from './mapped'
 export { type Memoizable, memoize } from './memoize'
 export { immutables, isNonReactive, registerNativeReactivity } from './non-reactive'
-export { project } from './project'
+export { getActiveProjection, project } from './project'
 export { isReactive, ReactiveBase, reactive, unwrap } from './proxy'
 export { organize, organized } from './record'
 export { Register, register } from './register'
@@ -51,7 +52,7 @@ import { ReactiveMap, ReactiveWeakMap } from './map'
 import { nonReactiveObjects, registerNativeReactivity } from './non-reactive-state'
 import { objectToProxy, proxyToObject } from './proxy'
 import { ReactiveSet, ReactiveWeakSet } from './set'
-import { effectToReactiveObjects, watchers } from './tracking'
+import { effectToReactiveObjects, watchers } from './registry'
 
 // Register native collection types to use specialized reactive wrappers
 registerNativeReactivity(WeakMap, ReactiveWeakMap)

package/src/reactive/interface.ts

@@ -1,10 +1,11 @@
-import { decorator, GenericClassDecorator } from '../decorator'
+import { decorator, type GenericClassDecorator } from '../decorator'
 import { deepWatch } from './deep-watch'
 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/map.ts

@@ -12,13 +12,13 @@ const native = Symbol('native')
  * Only tracks individual key operations, no size tracking (WeakMap limitation)
  */
 export class ReactiveWeakMap<K extends object, V> {
-	declare readonly [native]: WeakMap<K, V>
-	declare readonly content: symbol
+	readonly [native]!: WeakMap<K, V>
+	readonly content!: symbol
 	constructor(original: WeakMap<K, V>) {
 		Object.defineProperties(this, {
 			[native]: { value: original },
 			[prototypeForwarding]: { value: original },
-			content: { value: Symbol('content') },
+			content: { value: Symbol('WeakMapContent') },
 			[Symbol.toStringTag]: { value: 'ReactiveWeakMap' },
 		})
 	}
@@ -62,14 +62,14 @@ export class ReactiveWeakMap<K extends object, V> {
  * Tracks size changes, individual key operations, and collection-wide operations
  */
 export class ReactiveMap<K, V> {
-	declare readonly [native]: Map<K, V>
-	declare readonly content: symbol
+	readonly [native]!: Map<K, V>
+	readonly content!: symbol
 
 	constructor(original: Map<K, V>) {
 		Object.defineProperties(this, {
 			[native]: { value: original },
 			[prototypeForwarding]: { value: original },
-			content: { value: Symbol('content') },
+			content: { value: Symbol('MapContent') },
 			[Symbol.toStringTag]: { value: 'ReactiveMap' },
 		})
 	}

package/src/reactive/mapped.ts

@@ -5,10 +5,10 @@ import { effect, untracked } from './effects'
 import { cleanedBy } from './interface'
 import { reactive } from './proxy'
 import { dependant } from './tracking'
-import { prototypeForwarding, ScopedCallback } from './types'
+import { prototypeForwarding, type ScopedCallback } from './types'
 
 // TODO: Lazy reactivity ?
-export class ReadOnlyError extends Error {}
+export class ReadOnlyError extends Error { }
 /**
  * Reactive wrapper around JavaScript's Array class with full array method support
  * Tracks length changes, individual index operations, and collection-wide operations
@@ -29,7 +29,6 @@ class ReactiveReadOnlyArrayClass extends Indexable(ReactiveBaseArray, {
 		throw new ReadOnlyError(`Setting length to ${value} on a read-only array`)
 	},
 }) {
-	declare length: number
 	constructor(original: any[]) {
 		super()
 		Object.defineProperties(this, {

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)
 		}
 	},