mutts 1.0.7 → 1.0.9

package/src/reactive/register.ts

@@ -1,14 +1,39 @@
-import { FunctionWrapper } from '../zone'
+import { Eventful } from '../eventful'
 import { ArrayReadForward, forwardArray, getAt, Indexable, setAt } from '../indexable'
+import type { FunctionWrapper } from '../zone'
 import { effect } from './effects'
-import { unreactive } from './interface'
 import { reactive } from './proxy'
-import { type ScopedCallback } from './types'
-
-// TODO: use register in a real-world crud situation, have "events" for add, delete, update
+import type { EffectCleanup } from './types'
+import { unreactive } from './watch'
 
 type KeyFunction<T, K extends PropertyKey> = (item: T) => K
 
+/**
+ * Events emitted by the Register for CRUD operations
+ */
+export interface RegisterEvents<T, K extends PropertyKey> {
+	/**
+	 * Emitted when a new item is added to the register
+	 */
+	add: (item: T, key: K, index: number) => void
+	/**
+	 * Emitted when an item is removed from the register
+	 */
+	delete: (item: T, key: K, index: number) => void
+	/**
+	 * Emitted when an item's value is updated (same key, new value)
+	 */
+	update: (oldItem: T, newItem: T, key: K, index: number) => void
+	/**
+	 * Emitted when an item's key changes (rekey operation)
+	 */
+	rekey: (item: T, oldKey: K, newKey: K, index: number) => void
+	/**
+	 * Index signature for EventsBase compatibility
+	 */
+	[key: string]: (...args: any[]) => void
+}
+
 // Helper to work around TypeScript limitation: base class expressions cannot reference class type parameters
 function getRegisterBase<T>() {
 	class RegisterBase extends Indexable(ArrayReadForward, {
@@ -37,7 +62,6 @@ 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>()
@@ -50,9 +74,54 @@ class RegisterClass<T, K extends PropertyKey = PropertyKey>
 	readonly #keys: K[]
 	readonly #values: Map<K, T>
 	readonly #usage = new Map<K, number>()
-	readonly #valueInfo = new Map<T, { key: K; stop?: ScopedCallback }>()
-	readonly #keyEffects = new Set<ScopedCallback>()
+	readonly #valueInfo = new Map<T, { key: K; stop?: EffectCleanup }>()
+	readonly #keyEffects = new Set<EffectCleanup>()
 	readonly #ascend: FunctionWrapper
+	readonly #events = new Eventful<RegisterEvents<T, K>>()
+
+	/**
+	 * Register event listeners for CRUD operations
+	 */
+	on(events: Partial<RegisterEvents<T, K>>): void
+	on<EventType extends keyof RegisterEvents<T, K>>(
+		event: EventType,
+		cb: RegisterEvents<T, K>[EventType]
+	): () => void
+	on<EventType extends keyof RegisterEvents<T, K>>(
+		eventOrEvents: EventType | Partial<RegisterEvents<T, K>>,
+		cb?: RegisterEvents<T, K>[EventType]
+	): () => void {
+		// @ts-expect-error Delegate to Eventful
+		return this.#events.on(eventOrEvents, cb)
+	}
+
+	/**
+	 * Remove event listeners
+	 */
+	off(events: Partial<RegisterEvents<T, K>>): void
+	off<EventType extends keyof RegisterEvents<T, K>>(
+		event: EventType,
+		cb?: RegisterEvents<T, K>[EventType]
+	): void
+	off<EventType extends keyof RegisterEvents<T, K>>(
+		eventOrEvents: EventType | Partial<RegisterEvents<T, K>>,
+		cb?: RegisterEvents<T, K>[EventType]
+	): void {
+		// @ts-expect-error Delegate to Eventful
+		this.#events.off(eventOrEvents, cb)
+	}
+
+	/**
+	 * Register a global hook that receives all events
+	 */
+	hook(
+		cb: <EventType extends keyof RegisterEvents<T, K>>(
+			event: EventType,
+			...args: Parameters<RegisterEvents<T, K>[EventType]>
+		) => void
+	): () => void {
+		return this.#events.hook(cb)
+	}
 
 	constructor(keyFn: KeyFunction<T, K>, initial?: Iterable<T>) {
 		super()
@@ -84,7 +153,7 @@ class RegisterClass<T, K extends PropertyKey = PropertyKey>
 				info!.key = nextKey
 			})
 			info!.stop = stop
-			this.#keyEffects.add(stop)
+			this.#keyEffects.add(stop as EffectCleanup)
 		})
 		if (info.key === undefined) throw new Error('Register key function must return a property key')
 		return info.key
@@ -96,10 +165,17 @@ class RegisterClass<T, K extends PropertyKey = PropertyKey>
 			throw new Error('Register key function must return a property key')
 	}
 
-	private setKeyValue(key: K, value: T) {
+	private setKeyValue(key: K, value: T, index?: number) {
 		const existing = this.#values.get(key)
-		if (existing !== undefined && existing !== value) this.cleanupValue(existing)
-		this.#values.set(key, value)
+		if (existing !== undefined && existing !== value) {
+			this.cleanupValue(existing)
+			this.#values.set(key, value)
+			if (index !== undefined) {
+				this.#events.emit('update', existing, value, key, index)
+			}
+		} else {
+			this.#values.set(key, value)
+		}
 	}
 
 	private cleanupValue(value: T) {
@@ -128,13 +204,20 @@ class RegisterClass<T, K extends PropertyKey = PropertyKey>
 		if (!count) return
 		const existingCount = this.#usage.get(newKey) ?? 0
 		this.setKeyValue(newKey, value)
+		let index = -1
 		for (let i = 0; i < this.#keys.length; i++)
-			if (Object.is(this.#keys[i], oldKey)) this.#keys[i] = newKey
+			if (Object.is(this.#keys[i], oldKey)) {
+				this.#keys[i] = newKey
+				if (index === -1) index = i
+			}
 		this.#usage.set(newKey, existingCount + count)
 		this.#usage.delete(oldKey)
 		this.#values.delete(oldKey)
 		const updatedInfo = this.#valueInfo.get(value)
 		if (updatedInfo) updatedInfo.key = newKey
+		if (index !== -1) {
+			this.#events.emit('rekey', value, oldKey, newKey, index)
+		}
 	}
 
 	private incrementUsage(key: K) {
@@ -142,14 +225,18 @@ class RegisterClass<T, K extends PropertyKey = PropertyKey>
 		this.#usage.set(key, count + 1)
 	}
 
-	private decrementUsage(key: K) {
+	private decrementUsage(key: K, index?: number) {
 		const count = this.#usage.get(key)
 		if (!count) return
 		if (count <= 1) {
 			const value = this.#values.get(key)
 			this.#usage.delete(key)
 			this.#values.delete(key)
-			if (value !== undefined) this.cleanupValue(value)
+			if (value !== undefined) {
+				this.cleanupValue(value)
+				const idx = index ?? this.#keys.indexOf(key)
+				this.#events.emit('delete', value, key, idx)
+			}
 		} else {
 			this.#usage.set(key, count - 1)
 		}
@@ -170,19 +257,25 @@ class RegisterClass<T, K extends PropertyKey = PropertyKey>
 	private assignAt(index: number, key: K, value: T) {
 		const oldKey = this.#keys[index]
 		if (oldKey !== undefined && Object.is(oldKey, key)) {
+			const oldValue = this.#values.get(key)
 			this.setKeyValue(key, value)
+			if (oldValue !== undefined && oldValue !== value) {
+				this.#events.emit('update', oldValue, value, key, index)
+			}
 			return
 		}
 		if (oldKey !== undefined) this.decrementUsage(oldKey as K)
 		this.#keys[index] = key
 		this.incrementUsage(key)
 		this.setKeyValue(key, value)
+		this.#events.emit('add', value, key, index)
 	}
 
 	private insertKeyValue(index: number, key: K, value: T) {
 		this.#keys.splice(index, 0, key)
 		this.incrementUsage(key)
 		this.setKeyValue(key, value)
+		this.#events.emit('add', value, key, index)
 	}
 
 	private rebuildFrom(values: T[]) {
@@ -255,10 +348,11 @@ class RegisterClass<T, K extends PropertyKey = PropertyKey>
 		for (const item of items) keysToInsert.push(this.ensureKey(item))
 		const removedKeys = this.#keys.splice(normalizedStart, actualDelete, ...keysToInsert)
 		const removedValues: T[] = []
-		for (const key of removedKeys) {
+		for (let i = 0; i < removedKeys.length; i++) {
+			const key = removedKeys[i]
 			if (key === undefined) continue
 			const value = this.#values.get(key as K)
-			this.decrementUsage(key as K)
+			this.decrementUsage(key as K, normalizedStart + i)
 			removedValues.push(value as T)
 		}
 		for (let i = 0; i < keysToInsert.length; i++) {
@@ -296,7 +390,7 @@ class RegisterClass<T, K extends PropertyKey = PropertyKey>
 		const [key] = this.#keys.splice(index, 1)
 		if (key === undefined) return undefined
 		const value = this.#values.get(key as K)
-		this.decrementUsage(key as K)
+		this.decrementUsage(key as K, index)
 		return value
 	}
 
@@ -336,7 +430,10 @@ class RegisterClass<T, K extends PropertyKey = PropertyKey>
 	update(...values: T[]): void {
 		for (const value of values) {
 			const key = this.ensureKey(value)
-			if (this.#values.has(key)) this.setKeyValue(key, value)
+			if (this.#values.has(key)) {
+				const index = this.#keys.indexOf(key)
+				this.setKeyValue(key, value, index)
+			}
 		}
 	}
 
@@ -411,6 +508,28 @@ export const Register = RegisterClass as new <T, K extends PropertyKey = Propert
 	initial?: Iterable<T>
 ) => Register<T, K>
 
+/**
+ * Creates a reactive Register - an ordered, array-like collection with stable key-based identity.
+ *
+ * Register combines array semantics (indexable access, ordering, iteration) with Map-like
+ * key-based lookups. Items with the same key share the same value instance, making it ideal
+ * for UI lists keyed by IDs or when you need to preserve identity across reorders.
+ *
+ * @param keyFn - Function that extracts the key from each item
+ * @param initial - Optional initial items to populate the register
+ * @returns A reactive Register instance
+ *
+ * @example
+ * ```typescript
+ * const users = register(
+ *   (user: User) => user.id,
+ *   [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }]
+ * )
+ *
+ * users.push({ id: 3, name: 'Charlie' })
+ * const bob = users.get(2) // Get by key
+ * ```
+ */
 export function register<T, K extends PropertyKey = PropertyKey>(
 	keyFn: KeyFunction<T, K>,
 	initial?: Iterable<T>

package/src/reactive/registry.ts

@@ -1,19 +1,32 @@
-import { rootFunction, type ScopedCallback } from './types'
+import { type EffectCleanup, type EffectNode, type EffectTrigger, rootFunction } from './types'
 
 // Track which effects are watching which reactive objects for cleanup
-export const effectToReactiveObjects = new WeakMap<ScopedCallback, Set<object>>()
+export let effectToReactiveObjects = new WeakMap<EffectTrigger, Set<object>>()
 
 // Track effects per reactive object and property
-export const watchers = new WeakMap<object, Map<any, Set<ScopedCallback>>>()
+export let watchers = new WeakMap<object, Map<any, Set<EffectTrigger>>>()
 
-// runEffect -> set<stop>
-export const effectChildren = new WeakMap<ScopedCallback, Set<ScopedCallback>>()
+// Track effect metadata and relationships
+export let effectNodes = new WeakMap<EffectTrigger, EffectNode>()
 
-// Track parent effect relationships for hierarchy traversal (used in deep touch filtering)
-export const effectParent = new WeakMap<ScopedCallback, ScopedCallback | undefined>()
+export function getEffectNode(effect: EffectTrigger): EffectNode {
+    let node = effectNodes.get(effect)
+    if (!node) {
+        node = {}
+        effectNodes.set(effect, node)
+    }
+    return node
+}
 
 // Track reverse mapping to ensure unicity: One Root -> One Function
-const reverseRoots = new WeakMap<any, WeakRef<Function>>()
+let reverseRoots = new WeakMap<any, WeakRef<Function>>()
+
+export function resetRegistry() {
+	effectToReactiveObjects = new WeakMap()
+	watchers = new WeakMap()
+	effectNodes = new WeakMap()
+	reverseRoots = new WeakMap()
+}
 
 /**
  * Marks a function with its root function for effect tracking
@@ -56,4 +69,4 @@ export function markWithRoot<T extends Function>(fn: T, root: any): T {
 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

@@ -9,9 +9,6 @@ import { dependant } from './tracking'
  * Only tracks individual value operations, no size tracking (WeakSet limitation)
  */
 export abstract class ReactiveWeakSet<T extends object> extends WeakSet<T> {
-	get [Symbol.toStringTag]() {
-		return 'ReactiveWeakSet'
-	}
 	add(value: T): this {
 		const had = this.has(value)
 		this.add(value)
@@ -41,10 +38,6 @@ export abstract class ReactiveWeakSet<T extends object> extends WeakSet<T> {
  * Tracks size changes, individual value operations, and collection-wide operations
  */
 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')
@@ -112,19 +105,13 @@ export abstract class ReactiveSet<T> extends Set<T> {
 
 	[Symbol.iterator](): SetIterator<T> {
 		dependant(contentRef(this))
-		const nativeIterator = this[Symbol.iterator]()
-		return {
-			next() {
-				const result = nativeIterator.next()
-				if (result.done) {
-					return result
-				}
-				return { value: reactive(result.value), done: false }
-			},
-			[Symbol.iterator]() {
-				return this
-			},
-			[Symbol.dispose]() {},
+		const it: SetIterator<T> = Set.prototype[Symbol.iterator].call(this)
+		const nativeNext = it.next.bind(it)
+		it.next = () => {
+			const result = nativeNext()
+			if (result.done) return result
+			return { value: reactive(result.value), done: false }
 		}
+		return it
 	}
 }

package/src/reactive/tracking.ts

@@ -1,10 +1,7 @@
 import { getActiveEffect } from './effect-context'
 import { unwrap } from './proxy-state'
-import {
-	effectToReactiveObjects,
-	watchers,
-} from './registry'
-import { allProps, type ScopedCallback } from './types'
+import { effectToReactiveObjects, watchers } from './registry'
+import { allProps, type EffectTrigger } from './types'
 
 /**
  * Marks a property as a dependency of the current effect
@@ -16,20 +13,20 @@ export function dependant(obj: any, prop: any = allProps) {
 	const currentActiveEffect = getActiveEffect()
 
 	// Early return if no active effect, tracking disabled, or invalid prop
-	if (
-		!currentActiveEffect ||
-		(typeof prop === 'symbol' && prop !== allProps)
-	)
-		return
+	if (!currentActiveEffect || (typeof prop === 'symbol' && prop !== allProps)) return
 
+	if ('dependencyHook' in currentActiveEffect) {
+		// @ts-expect-error We declared it nowhere - it's okay as it's really internal and for edge-case debug purpose only
+		currentActiveEffect.dependencyHook(obj, prop)
+	}
 	let objectWatchers = watchers.get(obj)
 	if (!objectWatchers) {
-		objectWatchers = new Map<PropertyKey, Set<ScopedCallback>>()
+		objectWatchers = new Map<PropertyKey, Set<EffectTrigger>>()
 		watchers.set(obj, objectWatchers)
 	}
 	let deps = objectWatchers.get(prop)
 	if (!deps) {
-		deps = new Set<ScopedCallback>()
+		deps = new Set<EffectTrigger>()
 		objectWatchers.set(prop, deps)
 	}
 	deps.add(currentActiveEffect)

package/src/reactive/types.ts

@@ -1,15 +1,17 @@
 // 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'.
 
-import { FunctionWrapper } from "../zone"
+import type { FunctionWrapper } from '../zone'
+
+export type EffectAccessEvents = {
+	triggered(event: string, ...args: any[]): void
+}
 
 /**
- * Dependency access passed to user callbacks within effects/watch
+ * Effect access passed to user callbacks within effects/watch
  * Provides functions to track dependencies and information about the effect execution
  */
-export interface DependencyAccess {
-	// TODO: remove tracked (async is managed)
-	// TODO: remove ascend (make a global like `untracked` who  withEffect(parentEffect, () => {}))
+export interface EffectAccess {
 	/**
 	 * Tracks dependencies in the current effect context
 	 * Use this for normal dependency tracking within the effect
@@ -64,10 +66,60 @@ export interface DependencyAccess {
 // It automatically preserves effect context across Promise boundaries (.then, .catch, .finally)
 
 /**
- * Type for effect cleanup functions
+ * Base type for effect callbacks - simple function without additional properties
  */
 export type ScopedCallback = () => void
 
+/**
+ * Type for effect cleanup functions with stopped state tracking
+ */
+export type EffectCleanup = ScopedCallback & {
+	[stopped]: boolean
+}
+
+// Debug type for stack frames
+export type StackFrame = {
+    functionName: string
+    fileName: string
+    lineNumber: number
+    columnNumber: number
+    raw: string
+}
+
+export type EffectTracking = (obj: any, evolution: Evolution, prop: any, effect: EffectTrigger) => void
+
+/**
+ * Centralized node for all effect metadata and relationships
+ */
+export interface EffectNode {
+    // Graph relationships
+    parent?: EffectTrigger
+    children?: Set<EffectCleanup>
+
+    // Lifecycle
+    cleanup?: ScopedCallback
+    stopped?: boolean
+    
+    // Error handling
+    forwardThrow?: CatchFunction
+    catchers?: CatchFunction[]
+
+    // Debug / Metadata
+    creationStack?: StackFrame[]
+    dependencyHook?: (obj: any, prop: any) => void
+    
+    // Tracking
+    trackers?: EffectTracking[]
+    
+    // Configuration
+    isOpaque?: boolean
+}
+
+/**
+ * Type for the `runEffect` function of an effect - argument-less function to call to trigger the effect
+ */
+export type EffectTrigger = ScopedCallback
+
 /**
  * Async execution mode for effects
  * - `cancel`: Cancel previous async execution when dependencies change (default)
@@ -91,6 +143,14 @@ export interface EffectOptions {
 	 * Use this for effects that depend on object identity (like memoize).
 	 */
 	opaque?: boolean
+	/**
+	 * Used for debugging purpose. Provides a callback to be called every time a dependency is created.
+	 */
+	dependencyHook?: (obj: any, prop: any) => void
+	/**
+	 * Used for debugging purpose. Provides a name for the effect.
+	 */
+	name?: string
 }
 
 /**
@@ -149,6 +209,12 @@ export const stopped = Symbol('stopped')
  */
 export const cleanup = Symbol('cleanup')
 
+export const forwardThrow = Symbol('throw')
+
+export type EffectCloser = (error?: any) => void
+//biome-ignore lint/suspicious/noConfusingVoidType: We have to
+export type CatchFunction = (error: any) => EffectCloser | undefined | void
+
 /**
  * Context for a running projection item effect
  */
@@ -193,15 +259,11 @@ export type MaxReactionDebugInfo = {
 	effect: string
 }
 
-export type BrokenEffectsDebugInfo = {
-	code: ReactiveErrorCode.BrokenEffects
-	cause: any
-}
-
 export type GenericDebugInfo = {
 	code: ReactiveErrorCode
 	causalChain?: string[]
-	creationStack?: string
+	creationStack?: string | any[]
+	lineage?: any[]
 	[key: string]: any
 }
 
@@ -209,7 +271,6 @@ export type ReactiveDebugInfo =
 	| CycleDebugInfo
 	| MaxDepthDebugInfo
 	| MaxReactionDebugInfo
-	| BrokenEffectsDebugInfo
 	| GenericDebugInfo
 
 /**
@@ -271,13 +332,13 @@ export const options = {
 	 * @param props - The properties that changed
 	 * @param deps - The dependencies that changed
 	 */
-	touched: (_obj: any, _evolution: Evolution, _props?: any[], _deps?: Set<ScopedCallback>) => {},
+	touched: (_obj: any, _evolution: Evolution, _props?: any[], _deps?: Set<EffectTrigger>) => {},
 	/**
 	 * Debug purpose: called when an effect is skipped because it's already running
 	 * @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) => {},
+	skipRunningEffect: (_effect: EffectTrigger) => {},
 	/**
 	 * Debug purpose: maximum effect chain (like call stack max depth)
 	 * Used to prevent infinite loops
@@ -327,20 +388,20 @@ export const options = {
 	/**
 	 * How to handle cycles detected in effect batches.
 	 *
-	 * - `'none'` (Default): High-performance mode. Disables dependency graph maintenance and
+	 * - `'production'` (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).
+	 *   Cycle detection is heuristic (uses maxEffectChain execution counts).
 	 *
-	 * - `'throw'`: Traditional Topological Sorting. Guarantees dependency order and catches
-	 *   circular dependencies mathematically before execution.
+	 * - `'development'`: Maintains direct dependency graph for early cycle detection during edge creation.
+	 *   Catches cycles before effects execute via DFS check when adding edges. Throws immediately with
+	 *   basic path information. Good balance of debugging help with moderate overhead.
 	 *
-	 * - `'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.
+	 * - `'debug'`: Full diagnostic mode with transitive closures and topological sorting.
+	 *   Provides detailed cycle path reporting. Highest overhead but most informative for bug hunting.
 	 *
-	 * @default 'none'
+	 * @default 'production'
 	 */
-	cycleHandling: 'none' as 'none' | 'throw' | 'warn' | 'break' | 'strict',
+	cycleHandling: 'development' as 'production' | 'development' | 'debug',
 	/**
 	 * 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
@@ -437,4 +498,23 @@ export const options = {
 }
 // biome-ignore-end lint/correctness/noUnusedFunctionParameters: Interface declaration with empty defaults
 
+type CallableOption = {
+	[K in keyof typeof options]: (typeof options)[K] extends ((...args: any[]) => any) | undefined
+		? K
+		: never
+}[keyof typeof options]
+
+export function optionCall<K extends CallableOption>(
+	name: K,
+	...args: NonNullable<(typeof options)[K]> extends (...a: infer A) => unknown ? A : never
+): void {
+	const fn = options[name]
+	if (typeof fn !== 'function') return
+	try {
+		;(fn as Function)(...args)
+	} catch (error) {
+		options.warn(`options.${name} threw`, error)
+	}
+}
+
 export { type State, nativeReactive, rootFunction }