mutts 1.0.2 → 1.0.3

package/src/reactive/types.ts

@@ -0,0 +1,358 @@
+// 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
+/**
+ * Dependency 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, () => {}))
+	/**
+	 * Tracks dependencies in the current effect context
+	 * Use this for normal dependency tracking within the effect
+	 * @example
+	 * ```typescript
+	 * effect(({ tracked }) => {
+	 *   // In async context, use tracked to restore dependency tracking
+	 *   await someAsyncOperation()
+	 *   const value = tracked(() => state.count) // Tracks state.count in this effect
+	 * })
+	 * ```
+	 */
+	tracked: DependencyFunction
+	/**
+	 * Tracks dependencies in the parent effect context
+	 * Use this when child effects should track dependencies in the parent,
+	 * allowing parent cleanup to manage child effects while dependencies trigger the parent
+	 * @example
+	 * ```typescript
+	 * effect(({ ascend }) => {
+	 *   const length = inputs.length
+	 *   if (length > 0) {
+	 *     ascend(() => {
+	 *       // Dependencies here are tracked in the parent effect
+	 *       inputs.forEach(item => console.log(item))
+	 *     })
+	 *   }
+	 * })
+	 * ```
+	 */
+	ascend: DependencyFunction
+	/**
+	 * Indicates whether the effect is running as a reaction (i.e. not the first call)
+	 * - `false`: First execution when the effect is created
+	 * - `true`: Subsequent executions triggered by dependency changes
+	 * @example
+	 * ```typescript
+	 * effect(({ reaction }) => {
+	 *   if (!reaction) {
+	 *     console.log('Effect initialized')
+	 *     // Setup code that should only run once
+	 *   } else {
+	 *     console.log('Effect re-ran due to dependency change')
+	 *     // Code that runs on every update
+	 *   }
+	 * })
+	 * ```
+	 */
+	reaction: boolean
+}
+// Zone-based async context preservation is implemented in zone.ts
+// It automatically preserves effect context across Promise boundaries (.then, .catch, .finally)
+
+/**
+ * Type for effect cleanup functions
+ */
+export type ScopedCallback = () => void
+
+/**
+ * Async execution mode for effects
+ * - `cancel`: Cancel previous async execution when dependencies change (default)
+ * - `queue`: Queue next execution to run after current completes
+ * - `ignore`: Ignore new executions while async work is running
+ */
+export type AsyncExecutionMode = 'cancel' | 'queue' | 'ignore'
+
+/**
+ * Options for effect creation
+ */
+export interface EffectOptions {
+	/**
+	 * How to handle async effect executions when dependencies change
+	 * @default 'cancel'
+	 */
+	asyncMode?: AsyncExecutionMode
+	/**
+	 * If true, this effect is "opaque" to deep optimizations: it sees the object reference itself
+	 * and must be notified when it changes, regardless of deep content similarity.
+	 * Use this for effects that depend on object identity (like memoize).
+	 */
+	opaque?: boolean
+}
+
+/**
+ * Type for property evolution events
+ */
+export type PropEvolution = {
+	type: 'set' | 'del' | 'add' | 'invalidate'
+	prop: any
+}
+
+/**
+ * Type for collection operation evolution events
+ */
+export type BunchEvolution = {
+	type: 'bunch'
+	method: string
+}
+export type Evolution = PropEvolution | BunchEvolution
+
+type State =
+	| {
+			evolution: Evolution
+			next: State
+	  }
+	| {}
+
+// Track native reactivity
+const nativeReactive = Symbol('native-reactive')
+
+/**
+ * Symbol to mark individual objects as non-reactive
+ */
+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
+ */
+export const allProps = Symbol('all-props')
+
+// Symbol to mark functions with their root function
+const rootFunction = Symbol('root-function')
+
+/**
+ * Structured error codes for machine-readable diagnosis
+ */
+export enum ReactiveErrorCode {
+	CycleDetected = 'CYCLE_DETECTED',
+	MaxDepthExceeded = 'MAX_DEPTH_EXCEEDED',
+	MaxReactionExceeded = 'MAX_REACTION_EXCEEDED',
+	WriteInComputed = 'WRITE_IN_COMPUTED',
+	TrackingError = 'TRACKING_ERROR',
+}
+
+export type CycleDebugInfo = {
+	code: ReactiveErrorCode.CycleDetected
+	cycle: string[]
+	details?: string
+}
+
+export type MaxDepthDebugInfo = {
+	code: ReactiveErrorCode.MaxDepthExceeded
+	depth: number
+	chain: string[]
+}
+
+export type MaxReactionDebugInfo = {
+	code: ReactiveErrorCode.MaxReactionExceeded
+	count: number
+	effect: string
+}
+
+export type GenericDebugInfo = {
+	code: ReactiveErrorCode
+	causalChain?: string[]
+	creationStack?: string
+	[key: string]: any
+}
+
+export type ReactiveDebugInfo =
+	| CycleDebugInfo
+	| MaxDepthDebugInfo
+	| MaxReactionDebugInfo
+	| GenericDebugInfo
+
+/**
+ * Error class for reactive system errors
+ */
+export class ReactiveError extends Error {
+	constructor(
+		message: string,
+		public debugInfo?: ReactiveDebugInfo
+	) {
+		super(message)
+		this.name = 'ReactiveError'
+	}
+}
+
+// biome-ignore-start lint/correctness/noUnusedFunctionParameters: Interface declaration with empty defaults
+/**
+ * Global options for the reactive system
+ */
+export const options = {
+	/**
+	 * Debug purpose: called when an effect is entered
+	 * @param effect - The effect that is entered
+	 */
+	enter: (_effect: Function) => {},
+	/**
+	 * Debug purpose: called when an effect is left
+	 * @param effect - The effect that is left
+	 */
+	leave: (_effect: Function) => {},
+	/**
+	 * Debug purpose: called when an effect is chained
+	 * @param target - The effect that is being triggered
+	 * @param caller - The effect that is calling the target
+	 */
+	chain: (_targets: Function[], _caller?: Function) => {},
+	/**
+	 * Debug purpose: called when an effect chain is started
+	 * @param target - The effect that is being triggered
+	 */
+	beginChain: (_targets: Function[]) => {},
+	/**
+	 * Debug purpose: called when an effect chain is ended
+	 */
+	endChain: () => {},
+	garbageCollected: (_fn: Function) => {},
+	/**
+	 * Debug purpose: called when an object is touched
+	 * @param obj - The object that is touched
+	 * @param evolution - The type of change
+	 * @param props - The properties that changed
+	 * @param deps - The dependencies that changed
+	 */
+	touched: (_obj: any, _evolution: Evolution, _props?: any[], _deps?: Set<ScopedCallback>) => {},
+	/**
+	 * 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, _runningChain: ScopedCallback[]) => {},
+	/**
+	 * Debug purpose: maximum effect chain (like call stack max depth)
+	 * Used to prevent infinite loops
+	 * @default 100
+	 */
+	maxEffectChain: 100,
+	/**
+	 * Debug purpose: maximum effect reaction (like call stack max depth)
+	 * Used to prevent infinite loops
+	 * @default 'throw'
+	 */
+	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'
+	 */
+	cycleHandling: 'throw' as 'throw' | 'warn' | 'break' | 'strict',
+	/**
+	 * Maximum depth for deep watching traversal
+	 * Used to prevent infinite recursion in circular references
+	 * @default 100
+	 */
+	maxDeepWatchDepth: 100,
+	/**
+	 * Only react on instance members modification (not inherited properties)
+	 * For instance, do not track class methods
+	 * @default true
+	 */
+	instanceMembers: true,
+	/**
+	 * Ignore accessors (getters and setters) and only track direct properties
+	 * @default true
+	 */
+	ignoreAccessors: true,
+	/**
+	 * Enable recursive touching when objects with the same prototype are replaced
+	 * When enabled, replacing an object with another of the same prototype triggers
+	 * recursive diffing instead of notifying parent effects
+	 * @default true
+	 */
+	recursiveTouching: true,
+	/**
+	 * Default async execution mode for effects that return Promises
+	 * - 'cancel': Cancel previous async execution when dependencies change (default, enables async zone)
+	 * - 'queue': Queue next execution to run after current completes (enables async zone)
+	 * - 'ignore': Ignore new executions while async work is running (enables async zone)
+	 * - false: Disable async zone and async mode handling (effects run concurrently)
+	 *
+	 * **When truthy:** Enables async zone (Promise.prototype wrapping) for automatic context
+	 * preservation in Promise callbacks. Warning: This modifies Promise.prototype globally.
+	 * Only enable if no other library modifies Promise.prototype.
+	 *
+	 * **When false:** Async zone is disabled. Use `tracked()` manually in Promise callbacks.
+	 *
+	 * Can be overridden per-effect via EffectOptions
+	 * @default 'cancel'
+	 */
+	asyncMode: 'cancel' as AsyncExecutionMode | false,
+	// biome-ignore lint/suspicious/noConsole: This is the whole point here
+	warn: (...args: any[]) => console.warn(...args),
+
+	/**
+	 * Configuration for the introspection system
+	 */
+	introspection: {
+		/**
+		 * Whether to keep a history of mutations for debugging
+		 * @default false
+		 */
+		enableHistory: false,
+		/**
+		 * Number of mutations to keep in history
+		 * @default 50
+		 */
+		historySize: 50,
+	},
+
+	/**
+	 * 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)
+	 */
+	zones: {
+		/**
+		 * Hook setTimeout to preserve effect context
+		 * @default true
+		 */
+		setTimeout: true,
+		/**
+		 * Hook setInterval to preserve effect context
+		 * @default true
+		 */
+		setInterval: true,
+		/**
+		 * Hook requestAnimationFrame (runs in untracked context when hooked)
+		 * @default true
+		 */
+		requestAnimationFrame: true,
+		/**
+		 * Hook queueMicrotask to preserve effect context
+		 * @default true
+		 */
+		queueMicrotask: true,
+	},
+}
+// biome-ignore-end lint/correctness/noUnusedFunctionParameters: Interface declaration with empty defaults
+
+export { type State, nativeReactive, rootFunction }

package/src/reactive/zone.ts

@@ -0,0 +1,208 @@
+/**
+ * Zone-like async context preservation for reactive effects
+ *
+ * Automatically preserves effect context across async boundaries:
+ * - Promise methods: .then(), .catch(), .finally()
+ * - Timers: setTimeout(), setInterval()
+ * - Animation: requestAnimationFrame() (if available) - runs in untracked context
+ * - Microtasks: queueMicrotask() (if available)
+ *
+ * **IMPORTANT:** This module is opt-in via `reactiveOptions.asyncMode` (truthy = enabled, false = disabled).
+ * By default, async zone is ENABLED with 'cancel' mode.
+ *
+ * When disabled (asyncMode = false), use `tracked()` manually in async callbacks.
+ * When enabled (asyncMode = 'cancel' | 'queue' | 'ignore'), async entry points are wrapped ONCE.
+ */
+
+import { captureEffectStack, withEffectStack } from './effect-context'
+import { options, ScopedCallback } from './types'
+
+let zoneHooked = false
+
+// Store original Promise methods at module load time (before any wrapping)
+// This ensures we always have the true originals, even if wrapping happens multiple times
+const originalPromiseThen =
+	Object.getOwnPropertyDescriptor(Promise.prototype, 'then')?.value || Promise.prototype.then
+const originalPromiseCatch =
+	Object.getOwnPropertyDescriptor(Promise.prototype, 'catch')?.value || Promise.prototype.catch
+const originalPromiseFinally =
+	Object.getOwnPropertyDescriptor(Promise.prototype, 'finally')?.value || Promise.prototype.finally
+
+// Store original timer functions at module load time
+const originalSetTimeout = globalThis.setTimeout
+const originalSetInterval = globalThis.setInterval
+const originalRequestAnimationFrame =
+	typeof globalThis.requestAnimationFrame !== 'undefined'
+		? globalThis.requestAnimationFrame
+		: undefined
+const originalQueueMicrotask =
+	typeof globalThis.queueMicrotask !== 'undefined' ? globalThis.queueMicrotask : undefined
+
+// Store batch function to avoid circular dependency
+let batchFn: ((cb: () => any, type: 'immediate') => any) | undefined
+
+/**
+ * Check the asyncMode option and hook Promise.prototype once if enabled
+ * Called lazily on first effect creation
+ * asyncMode being truthy enables async zone, false disables it
+ *
+ * @param batch - Optional batch function injection from effects.ts to avoid circular dependency
+ */
+export function ensureZoneHooked(batch?: (cb: () => any, type: 'immediate') => any) {
+	if (batch) batchFn = batch
+	if (zoneHooked || !options.asyncMode) return
+	hookZone()
+	zoneHooked = true
+}
+
+/**
+ * Hook Promise.prototype methods to preserve effect context
+ */
+function hookZone() {
+	// biome-ignore lint/suspicious/noThenProperty: Intentional wrapping for zone functionality
+	Promise.prototype.then = function <T, R1, R2>(
+		this: Promise<T>,
+		onFulfilled?: ((value: T) => R1 | PromiseLike<R1>) | null,
+		onRejected?: ((reason: any) => R2 | PromiseLike<R2>) | null
+	): Promise<R1 | R2> {
+		const capturedStack = captureEffectStack()
+		return originalPromiseThen.call(
+			this,
+			wrapCallback(onFulfilled, capturedStack),
+			wrapCallback(onRejected, capturedStack)
+		)
+	}
+
+	Promise.prototype.catch = function <T>(
+		this: Promise<T>,
+		onRejected?: ((reason: any) => T | PromiseLike<T>) | null
+	): Promise<T> {
+		const capturedStack = captureEffectStack()
+		return originalPromiseCatch.call(this, wrapCallback(onRejected, capturedStack))
+	}
+
+	Promise.prototype.finally = function <T>(
+		this: Promise<T>,
+		onFinally?: (() => void) | null
+	): Promise<T> {
+		const capturedStack = captureEffectStack()
+		return originalPromiseFinally.call(this, wrapCallback(onFinally, capturedStack))
+	}
+
+	// Hook setTimeout - preserve original function properties for Node.js compatibility
+	const wrappedSetTimeout = (<TArgs extends any[]>(
+		callback: (...args: TArgs) => void,
+		delay?: number,
+		...args: TArgs
+	): ReturnType<typeof originalSetTimeout> => {
+		const capturedStack = options.zones.setTimeout ? captureEffectStack() : undefined
+		return originalSetTimeout.apply(globalThis, [
+			wrapCallback(callback, capturedStack) as (...args: any[]) => void,
+			delay,
+			...args,
+		] as any)
+	}) as typeof originalSetTimeout
+	Object.assign(wrappedSetTimeout, originalSetTimeout)
+	globalThis.setTimeout = wrappedSetTimeout
+
+	// Hook setInterval - preserve original function properties for Node.js compatibility
+	const wrappedSetInterval = (<TArgs extends any[]>(
+		callback: (...args: TArgs) => void,
+		delay?: number,
+		...args: TArgs
+	): ReturnType<typeof originalSetInterval> => {
+		const capturedStack = options.zones.setInterval ? captureEffectStack() : undefined
+		return originalSetInterval.apply(globalThis, [
+			wrapCallback(callback, capturedStack) as (...args: any[]) => void,
+			delay,
+			...args,
+		] as any)
+	}) as typeof originalSetInterval
+	Object.assign(wrappedSetInterval, originalSetInterval)
+	globalThis.setInterval = wrappedSetInterval
+
+	// Hook requestAnimationFrame if available
+	if (originalRequestAnimationFrame) {
+		globalThis.requestAnimationFrame = ((
+			callback: FrameRequestCallback
+		): ReturnType<typeof originalRequestAnimationFrame> => {
+			const capturedStack = options.zones.requestAnimationFrame ? captureEffectStack() : undefined
+			return originalRequestAnimationFrame.call(
+				globalThis,
+				wrapCallback(callback as any, capturedStack) as FrameRequestCallback
+			)
+		}) as typeof originalRequestAnimationFrame
+	}
+
+	// Hook queueMicrotask if available
+	if (originalQueueMicrotask) {
+		globalThis.queueMicrotask = ((callback: () => void): void => {
+			const capturedStack = options.zones.queueMicrotask ? captureEffectStack() : undefined
+			originalQueueMicrotask.call(globalThis, wrapCallback(callback, capturedStack) as () => void)
+		}) as typeof originalQueueMicrotask
+	}
+}
+
+/**
+ * Wraps a callback to restore effect context and ensure batching
+ */
+function wrapCallback<T extends (...args: any[]) => any>(
+	callback: T | null | undefined,
+	capturedStack: (ScopedCallback | undefined)[] | undefined
+): T | undefined {
+	if (!callback) return undefined
+
+	// If no stack to restore and no batch function, direct call (optimization)
+	if ((!capturedStack || !capturedStack.length) && !batchFn) {
+		return callback
+	}
+
+	return ((...args: any[]) => {
+		const execute = () => {
+			if (capturedStack?.length) {
+				return withEffectStack(capturedStack, () => callback(...args))
+			}
+			return callback(...args)
+		}
+
+		if (batchFn) {
+			return batchFn(execute, 'immediate')
+		}
+		return execute()
+	}) as T
+}
+
+/**
+ * Manually enable/disable the zone (for testing)
+ */
+export function setZoneEnabled(enabled: boolean) {
+	if (enabled && !zoneHooked) {
+		hookZone()
+		zoneHooked = true
+	} else if (!enabled && zoneHooked) {
+		// Restore original Promise methods
+		// biome-ignore lint/suspicious/noThenProperty: Restoring original methods
+		Promise.prototype.then = originalPromiseThen
+		Promise.prototype.catch = originalPromiseCatch
+		Promise.prototype.finally = originalPromiseFinally
+
+		// Restore original timer functions
+		globalThis.setTimeout = originalSetTimeout
+		globalThis.setInterval = originalSetInterval
+		if (originalRequestAnimationFrame) {
+			globalThis.requestAnimationFrame = originalRequestAnimationFrame
+		}
+		if (originalQueueMicrotask) {
+			globalThis.queueMicrotask = originalQueueMicrotask
+		}
+
+		zoneHooked = false
+	}
+}
+
+/**
+ * Check if zone is currently hooked
+ */
+export function isZoneEnabled(): boolean {
+	return zoneHooked
+}