mutts 1.0.6 → 1.0.8

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]() {},
+		} as any	//TODO? (something easy)
 	}
 }

package/src/reactive/tracking.ts

@@ -1,34 +1,11 @@
 import { getActiveEffect } from './effect-context'
+import { unwrap } from './proxy-state'
 import {
 	effectToReactiveObjects,
-	getRoot,
-	globalTrackingDisabled,
-	setGlobalTrackingDisabled,
-	trackingDisabledEffects,
 	watchers,
 } from './registry'
-import { unwrap } from './proxy-state'
 import { allProps, type ScopedCallback } from './types'
 
-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) {
-		setGlobalTrackingDisabled(value)
-		return
-	}
-	const root = getRoot(active)
-	if (value) trackingDisabledEffects.add(root)
-	else trackingDisabledEffects.delete(root)
-}
-
-
-
 /**
  * Marks a property as a dependency of the current effect
  * @param obj - The object containing the property
@@ -41,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
@@ -179,6 +172,7 @@ export enum ReactiveErrorCode {
 	MaxReactionExceeded = 'MAX_REACTION_EXCEEDED',
 	WriteInComputed = 'WRITE_IN_COMPUTED',
 	TrackingError = 'TRACKING_ERROR',
+	BrokenEffects = 'BROKEN_EFFECTS',
 }
 
 export type CycleDebugInfo = {
@@ -199,6 +193,11 @@ export type MaxReactionDebugInfo = {
 	effect: string
 }
 
+export type BrokenEffectsDebugInfo = {
+	code: ReactiveErrorCode.BrokenEffects
+	cause: any
+}
+
 export type GenericDebugInfo = {
 	code: ReactiveErrorCode
 	causalChain?: string[]
@@ -210,6 +209,7 @@ export type ReactiveDebugInfo =
 	| CycleDebugInfo
 	| MaxDepthDebugInfo
 	| MaxReactionDebugInfo
+	| BrokenEffectsDebugInfo
 	| GenericDebugInfo
 
 /**
@@ -223,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
@@ -269,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
@@ -292,14 +300,14 @@ export const options = {
 	 * 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) => {
@@ -308,17 +316,31 @@ export const options = {
 	 * ```
 	 */
 	onMemoizationDiscrepancy: undefined as
-		| ((cached: any, fresh: any, fn: Function, args: any[], cause: "calculation" | "comparison") => void)
+		| ((
+				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)
-	 * - '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'
+	 * 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: 'throw' as 'throw' | 'warn' | 'break' | 'strict',
+	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
@@ -388,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/utils.ts

@@ -1,5 +1,3 @@
-import { prototypeForwarding } from './reactive/types'
-
 type ElementTypes<T extends readonly unknown[]> = {
 	[K in keyof T]: T[K] extends readonly (infer U)[] ? U : T[K]
 }
@@ -88,29 +86,29 @@ export function renamed<F extends Function>(fct: F, name: string): F {
 		},
 	})
 }
-
-export function ReflectGet(obj: any, prop: any, receiver: any) {
-	// Check if Node is available and obj is an instance of Node
-	if (typeof Node !== 'undefined' && obj instanceof Node) return (obj as any)[prop]
-	return Reflect.get(obj, prop, receiver)
-}
-
-export function ReflectSet(obj: any, prop: any, value: any, receiver: any) {
-	// Check if Node is available and obj is an instance of Node
-	if (typeof Node !== 'undefined' && obj instanceof Node) {
-		;(obj as any)[prop] = value
-		return true
-	}
-	if (!(obj instanceof Object) && !Reflect.has(obj, prop)) {
-		Object.defineProperty(obj, prop, {
-			value,
-			configurable: true,
-			writable: true,
-			enumerable: true,
-		})
-		return true
-	}
-	return Reflect.set(obj, prop, value, receiver)
+export const FoolProof = {
+	get(obj: any, prop: any, receiver: any) {
+		// Check if Node is available and obj is an instance of Node
+		if (typeof Node !== 'undefined' && obj instanceof Node) return (obj as any)[prop]
+		return Reflect.get(obj, prop, receiver)
+	},
+	set(obj: any, prop: any, value: any, receiver: any) {
+		// Check if Node is available and obj is an instance of Node
+		if (typeof Node !== 'undefined' && obj instanceof Node) {
+			;(obj as any)[prop] = value
+			return true
+		}
+		if (!(obj instanceof Object) && !Reflect.has(obj, prop)) {
+			Object.defineProperty(obj, prop, {
+				value,
+				configurable: true,
+				writable: true,
+				enumerable: true,
+			})
+			return true
+		}
+		return Reflect.set(obj, prop, value, receiver)
+	},
 }
 
 export function isOwnAccessor(obj: any, prop: any) {
@@ -128,14 +126,6 @@ export function isOwnAccessor(obj: any, prop: any) {
  * @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) {
@@ -146,7 +136,10 @@ export function deepCompare(a: any, b: any, cache = new Map<object, Set<object>>
 	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 })
+		console.warn(`[deepCompare] prototype mismatch:`, {
+			nameA: a?.constructor?.name,
+			nameB: b?.constructor?.name,
+		})
 		return false
 	}
 	// Circular reference protection
@@ -239,20 +232,70 @@ export function deepCompare(a: any, b: any, cache = new Map<object, Set<object>>
 	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 })
+		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)) {
+		if (!Object.hasOwn(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] })
+			console.warn(`[deepCompare] value mismatch for key ${String(key)}:`, {
+				valA: a[key],
+				valB: b[key],
+			})
 			return false
 		}
 	}
 
 	return true
 }
+
+
+const contentRefs = new WeakMap<object, any>()
+export function contentRef(container: object) {
+	if (!contentRefs.has(container))
+		contentRefs.set(
+			container,
+			Object.seal(
+				Object.create(null, {
+					contentOf: { value: container, writable: false, configurable: false },
+				})
+			)
+		)
+	return contentRefs.get(container)
+}
+
+export function tag<T extends object>(name: string, obj: T): T {
+	Object.defineProperties(obj, {
+		[Symbol.toStringTag]: {
+			value: name,
+			writable: false,
+			configurable: false,
+		},
+		toString: {
+			value: () => name,
+			writable: false,
+			configurable: false,
+		},
+	})
+	return obj
+}
+
+export function named<T extends Function>(name: string, fn: T): T {
+	Object.defineProperty(fn, 'name', {
+		value: fn.name ? `${fn.name}::${name}` : name,
+		writable: false,
+		configurable: false,
+	})
+	return fn
+}

package/src/zone.ts

@@ -0,0 +1,138 @@
+import { asyncHooks } from "./async"
+import { named, tag } from "./utils"
+
+interface InternalZoneUse<T> {
+	enter(value?: T): unknown
+	leave(entered: unknown): void
+}
+function isu<T>(z: AZone<T> | InternalZoneUse<T>): InternalZoneUse<T> {
+	return z as InternalZoneUse<T>
+}
+export abstract class AZone<T> {
+	abstract active?: T
+	protected enter(value?: T): unknown {
+		const prev = this.active
+		this.active = value
+		return prev
+	}
+	protected leave(entered: unknown): void {
+		this.active = entered as T | undefined
+	}
+	with<R>(value: T, fn: () => R): R {
+		const entered = this.enter(value)
+        let res: R;
+		try {
+			res = fn()
+		} finally {
+			this.leave(entered)
+		}
+        // [HACK]: Sanitization
+        // See BROWSER_ASYNC_POLYFILL.md
+        return asyncHooks.sanitizePromise(res) as R
+	}
+	root<R>(fn: () => R): R {
+		let prev = this.enter()
+		try {
+			return fn()
+		} finally {
+			this.leave(prev)
+		}
+	}
+	get zoned(): FunctionWrapper {
+		const active = this.active
+		return named(`${this}@${active}`, (fn) => this.with(active, fn))
+	}
+}
+
+export type FunctionWrapper = <R>(fn?: () => R) => R
+
+export class Zone<T> extends AZone<T> {
+	active: T | undefined
+}
+type HistoryValue<T> = {present: T | undefined, history: Set<T>}
+export class ZoneHistory<T> extends AZone<HistoryValue<T>> {
+	private	history = new Set<T>()
+	public readonly present: AZone<T>
+	public has(value: T): boolean {
+		return this.history.has(value)
+	}
+	public some(predicate: (value: T) => boolean): boolean {
+		for(const value of this.history) if(predicate(value)) return true
+		return false
+	}
+	constructor(private controlled: AZone<T> = new Zone<T>()) {
+		super()
+		const self = this
+		this.present = Object.create(controlled,
+			Object.getOwnPropertyDescriptors({
+				get active() { return controlled.active },
+				set active(value: T | undefined) {
+					controlled.active = value
+				},
+				enter(value?: T) {
+					if(value && self.history.has(value)) throw new Error('ZoneHistory: re-entering historical zone')
+					if(value !== undefined) self.history.add(value)
+					return { added: value, entered: isu(controlled).enter(value) }
+				},
+				leave(entered: { added: T | undefined, entered: unknown }) {
+					if(entered.added !== undefined) self.history.delete(entered.added)
+					return isu(controlled).leave(entered.entered)
+				}
+			})
+		)
+	}
+	get active() {
+		return {present: this.controlled.active, history: new Set(this.history)}
+	}
+	set active(value: HistoryValue<T> | undefined) {
+		this.history = this.history && new Set(this.history)
+		this.controlled.active = value?.present
+	}
+}
+
+export class ZoneAggregator extends AZone<Map<AZone<unknown>, unknown>> {
+	#zones = new Set<AZone<unknown>>()
+	constructor(...zones: AZone<unknown>[]) {
+		super()
+		for (const z of zones) this.#zones.add(z)
+	}
+	get active(): Map<AZone<unknown>, unknown> | undefined {
+		const rv = new Map<AZone<unknown>, unknown>()
+		for (const z of this.#zones)
+			if (z.active !== undefined) rv.set(z, z.active)
+		return rv
+	}
+	set active(value: Map<AZone<unknown>, unknown> | undefined) {
+		for (const z of this.#zones) z.active = value?.get(z)
+	}
+	enter(value?: Map<AZone<unknown>, unknown> | undefined) {
+		const entered = new Map<AZone<unknown>, unknown>()
+		for (const z of this.#zones) {
+			const v = value?.get(z)
+			entered.set(z, isu(z).enter(v))
+		}
+		return entered
+	}
+	leave(entered: Map<AZone<unknown>, unknown>): void {
+		for (const z of this.#zones) isu(z).leave(entered.get(z))
+	}
+	add(z: AZone<unknown>) {
+		this.#zones.add(z)
+	}
+	delete(z: AZone<unknown>) {
+		this.#zones.delete(z)
+	}
+	clear() {
+		this.#zones.clear()
+	}
+}
+
+export const asyncZone = tag('async', new ZoneAggregator())
+asyncHooks.addHook(() => {
+	const zone = asyncZone.active
+	return () => {
+		const prev = asyncZone.active
+		asyncZone.active = zone
+		return () => asyncZone.active = prev
+	}
+})