mutts 1.0.2 → 1.0.3

package/src/reactive/index.ts

@@ -0,0 +1,75 @@
+export { getState, touched, touched1 } from './change'
+export type { ReactivityGraph } from './debug'
+export {
+	buildReactivityGraph,
+	enableDevTools,
+	isDevtoolsEnabled,
+	registerEffectForDebug,
+	registerObjectForDebug,
+	setEffectName,
+	setObjectName,
+} from './debug'
+export { deepWatch } from './deep-watch'
+export {
+	addBatchCleanup,
+	atomic,
+	biDi,
+	defer,
+	effect,
+	getActiveEffect,
+	root,
+	trackEffect,
+	untracked,
+} from './effects'
+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 { isReactive, ReactiveBase, reactive, unwrap } from './proxy'
+export { organize, organized } from './record'
+export { Register, register } from './register'
+export {
+	type DependencyAccess,
+	type DependencyFunction,
+	type Evolution,
+	options as reactiveOptions,
+	ReactiveError,
+	type ScopedCallback,
+} from './types'
+export { isZoneEnabled, setZoneEnabled } from './zone'
+
+import { ReactiveArray } from './array'
+import {
+	deepWatchers,
+	effectToDeepWatchedObjects,
+	objectParents,
+	objectsWithDeepWatchers,
+} from './deep-watch'
+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'
+
+// Register native collection types to use specialized reactive wrappers
+registerNativeReactivity(WeakMap, ReactiveWeakMap)
+registerNativeReactivity(Map, ReactiveMap)
+registerNativeReactivity(WeakSet, ReactiveWeakSet)
+registerNativeReactivity(Set, ReactiveSet)
+registerNativeReactivity(Array, ReactiveArray)
+
+/**
+ * Object containing internal reactive system state for debugging and profiling
+ */
+export const profileInfo: any = {
+	objectToProxy,
+	proxyToObject,
+	effectToReactiveObjects,
+	watchers,
+	objectParents,
+	objectsWithDeepWatchers,
+	deepWatchers,
+	effectToDeepWatchedObjects,
+	nonReactiveObjects,
+}

package/src/reactive/interface.ts

@@ -0,0 +1,223 @@
+import { decorator, 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 {
+	type DependencyAccess,
+	nonReactiveMark,
+	type ScopedCallback,
+	unreactiveProperties,
+} from './types'
+
+/**
+ * Symbol for accessing the cleanup function on cleaned objects
+ */
+export const cleanup = Symbol('cleanup')
+
+//#region watch
+
+const unsetYet = Symbol('unset-yet')
+/**
+ * Options for the watch function
+ */
+export interface WatchOptions {
+	/** Whether to call the callback immediately */
+	immediate?: boolean
+	/** Whether to watch nested properties */
+	deep?: boolean
+}
+
+/**
+ * Watches a reactive value and calls a callback when it changes
+ * @param value - Function that returns the value to watch
+ * @param changed - Callback to call when the value changes
+ * @param options - Watch options
+ * @returns Cleanup function to stop watching
+ */
+export function watch<T>(
+	value: (dep: DependencyAccess) => T,
+	changed: (value: T, oldValue?: T) => void,
+	options?: Omit<WatchOptions, 'deep'> & { deep?: false }
+): ScopedCallback
+/**
+ * Watches a reactive value with deep watching enabled
+ * @param value - Function that returns the value to watch
+ * @param changed - Callback to call when the value changes
+ * @param options - Watch options with deep watching enabled
+ * @returns Cleanup function to stop watching
+ */
+export function watch<T extends object | any[]>(
+	value: (dep: DependencyAccess) => T,
+	changed: (value: T, oldValue?: T) => void,
+	options?: Omit<WatchOptions, 'deep'> & { deep: true }
+): ScopedCallback
+/**
+ * Watches a reactive object directly
+ * @param value - The reactive object to watch
+ * @param changed - Callback to call when the object changes
+ * @param options - Watch options
+ * @returns Cleanup function to stop watching
+ */
+export function watch<T extends object | any[]>(
+	value: T,
+	changed: (value: T) => void,
+	options?: WatchOptions
+): ScopedCallback
+
+export function watch(
+	value: any, //object | ((dep: DependencyAccess) => object),
+	changed: (value?: object, oldValue?: object) => void,
+	options: any = {}
+) {
+	return typeof value === 'function'
+		? watchCallBack(value, changed, options)
+		: typeof value === 'object' && value !== null
+			? watchObject(value, changed, options)
+			: (() => {
+					throw new Error('watch: value must be a function or an object')
+				})()
+}
+
+function watchObject(
+	value: object,
+	changed: (value: object) => void,
+	{ immediate = false, deep = false } = {}
+): ScopedCallback {
+	const myParentEffect = getActiveEffect()
+	if (deep) return deepWatch(value, changed, { immediate })!
+	return effect(
+		markWithRoot(function watchObjectEffect() {
+			dependant(value)
+			if (immediate) withEffect(myParentEffect, () => changed(value))
+			immediate = true
+		}, changed)
+	)
+}
+
+function watchCallBack<T>(
+	value: (dep: DependencyAccess) => T,
+	changed: (value: T, oldValue?: T) => void,
+	{ immediate = false, deep = false } = {}
+): ScopedCallback {
+	const myParentEffect = getActiveEffect()
+	let oldValue: T | typeof unsetYet = unsetYet
+	let deepCleanup: ScopedCallback | undefined
+	const cbCleanup = effect(
+		markWithRoot(function watchCallBackEffect(access) {
+			const newValue = value(access)
+			if (oldValue !== newValue)
+				withEffect(
+					myParentEffect,
+					markWithRoot(() => {
+						if (oldValue === unsetYet) {
+							if (immediate) changed(newValue)
+						} else changed(newValue, oldValue)
+						oldValue = newValue
+						if (deep) {
+							if (deepCleanup) deepCleanup()
+							deepCleanup = deepWatch(
+								newValue as object,
+								markWithRoot((value) => changed(value as T, value as T), changed)
+							)
+						}
+					}, changed)
+				)
+		}, value)
+	)
+	return () => {
+		cbCleanup()
+		if (deepCleanup) deepCleanup()
+	}
+}
+
+//#endregion
+
+//#region nonReactive
+
+/**
+ * Mark an object as non-reactive. This object and all its properties will never be made reactive.
+ * @param obj - The object to mark as non-reactive
+ */
+function deepNonReactive<T>(obj: T): T {
+	obj = unwrap(obj)
+	if (isNonReactive(obj)) return obj
+	try {
+		Object.defineProperty(obj as object, nonReactiveMark, {
+			value: true,
+			writable: false,
+			enumerable: false,
+			configurable: true,
+		})
+	} catch {}
+	if (!(nonReactiveMark in (obj as object))) nonReactiveObjects.add(obj as object)
+	//for (const key in obj) deepNonReactive(obj[key])
+	return obj
+}
+function unreactiveApplication<T extends object>(...args: (keyof T)[]): GenericClassDecorator<T>
+function unreactiveApplication<T extends object>(obj: T): T
+function unreactiveApplication<T extends object>(
+	arg1: T | keyof T,
+	...args: (keyof T)[]
+): GenericClassDecorator<T> | T {
+	return typeof arg1 === 'object'
+		? deepNonReactive(arg1)
+		: (((original) => {
+				// Copy the parent's unreactive properties if they exist
+				original.prototype[unreactiveProperties] = new Set<PropertyKey>(
+					original.prototype[unreactiveProperties] || []
+				)
+				// Add all arguments (including the first one)
+				original.prototype[unreactiveProperties].add(arg1)
+				for (const arg of args) original.prototype[unreactiveProperties].add(arg)
+				return original // Return the class
+			}) as GenericClassDecorator<T>)
+}
+/**
+ * Decorator that marks classes or properties as non-reactive
+ * Prevents objects from being made reactive
+ */
+export const unreactive = decorator({
+	class(original) {
+		// Called without arguments, mark entire class as non-reactive
+		nonReactiveClass(original)
+	},
+	default: unreactiveApplication,
+})
+
+//#endregion
+
+export function cleanedBy<T extends object>(obj: T, cleanupFn: ScopedCallback) {
+	return Object.defineProperty(obj, cleanup, {
+		value: cleanupFn,
+		writable: false,
+		enumerable: false,
+		configurable: true,
+	}) as T & { [cleanup]: ScopedCallback }
+}
+
+//#region greedy caching
+
+/**
+ * Creates a derived value that automatically recomputes when dependencies change
+ * @param compute - Function that computes the derived value
+ * @returns Object with value and cleanup function
+ */
+export function derived<T>(compute: (dep: DependencyAccess) => T): {
+	value: T
+	[cleanup]: ScopedCallback
+} {
+	const rv = { value: undefined as unknown as T }
+	return cleanedBy(
+		rv,
+		untracked(() =>
+			effect(
+				markWithRoot(function derivedEffect(access) {
+					rv.value = compute(access)
+				}, compute)
+			)
+		)
+	)
+}

package/src/reactive/map.ts

@@ -0,0 +1,171 @@
+import { touched, touched1 } from './change'
+import { notifyPropertyChange } from './deep-touch'
+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 WeakMap class
+ * 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
+	constructor(original: WeakMap<K, V>) {
+		Object.defineProperties(this, {
+			[native]: { value: original },
+			[prototypeForwarding]: { value: original },
+			content: { value: Symbol('content') },
+			[Symbol.toStringTag]: { value: 'ReactiveWeakMap' },
+		})
+	}
+
+	// Implement WeakMap interface methods with reactivity
+	delete(key: K): boolean {
+		const hadKey = this[native].has(key)
+		const result = this[native].delete(key)
+
+		if (hadKey) touched1(this.content, { type: 'del', prop: key }, key)
+
+		return result
+	}
+
+	get(key: K): V | undefined {
+		dependant(this.content, key)
+		return reactive(this[native].get(key))
+	}
+
+	has(key: K): boolean {
+		dependant(this.content, key)
+		return this[native].has(key)
+	}
+
+	set(key: K, value: V): this {
+		const hadKey = this[native].has(key)
+		const oldValue = this[native].get(key)
+		const reactiveValue = reactive(value)
+		this[native].set(key, reactiveValue)
+
+		if (!hadKey || oldValue !== reactiveValue) {
+			notifyPropertyChange(this.content, key, oldValue, reactiveValue, hadKey)
+		}
+
+		return this
+	}
+}
+
+/**
+ * Reactive wrapper around JavaScript's Map class
+ * 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
+
+	constructor(original: Map<K, V>) {
+		Object.defineProperties(this, {
+			[native]: { value: original },
+			[prototypeForwarding]: { value: original },
+			content: { value: Symbol('content') },
+			[Symbol.toStringTag]: { value: 'ReactiveMap' },
+		})
+	}
+
+	// Implement Map interface methods with reactivity
+	get size(): number {
+		dependant(this, 'size') // The ReactiveMap instance still goes through proxy
+		return this[native].size
+	}
+
+	clear(): void {
+		const hadEntries = this[native].size > 0
+		this[native].clear()
+
+		if (hadEntries) {
+			const evolution = { type: 'bunch', method: 'clear' } as const
+			// Clear triggers all effects since all keys are affected
+			touched1(this, evolution, 'size')
+			touched(this.content, evolution)
+		}
+	}
+
+	entries(): Generator<[K, V]> {
+		dependant(this.content)
+		return makeReactiveEntriesIterator(this[native].entries())
+	}
+
+	forEach(callbackfn: (value: V, key: K, map: Map<K, V>) => void, thisArg?: any): void {
+		dependant(this.content)
+		this[native].forEach(callbackfn, thisArg)
+	}
+
+	keys(): MapIterator<K> {
+		dependant(this.content)
+		return this[native].keys()
+	}
+
+	values(): Generator<V> {
+		dependant(this.content)
+		return makeReactiveIterator(this[native].values())
+	}
+
+	[Symbol.iterator](): Iterator<[K, V]> {
+		dependant(this.content)
+		const nativeIterator = this[native][Symbol.iterator]()
+		return {
+			next() {
+				const result = nativeIterator.next()
+				if (result.done) {
+					return result
+				}
+				return {
+					value: [result.value[0], reactive(result.value[1])],
+					done: false,
+				}
+			},
+		}
+	}
+
+	// Implement Map methods with reactivity
+	delete(key: K): boolean {
+		const hadKey = this[native].has(key)
+		const result = this[native].delete(key)
+
+		if (hadKey) {
+			const evolution = { type: 'del', prop: key } as const
+			touched1(this.content, evolution, key)
+			touched1(this, evolution, 'size')
+		}
+
+		return result
+	}
+
+	get(key: K): V | undefined {
+		dependant(this.content, key)
+		return reactive(this[native].get(key))
+	}
+
+	has(key: K): boolean {
+		dependant(this.content, key)
+		return this[native].has(key)
+	}
+
+	set(key: K, value: V): this {
+		const hadKey = this[native].has(key)
+		const oldValue = this[native].get(key)
+		const reactiveValue = reactive(value)
+		this[native].set(key, reactiveValue)
+
+		if (!hadKey || oldValue !== reactiveValue) {
+			notifyPropertyChange(this.content, key, oldValue, reactiveValue, hadKey)
+			// Also notify size change for Map (WeakMap doesn't track size)
+			const evolution = { type: hadKey ? 'set' : 'add', prop: key } as const
+			touched1(this, evolution, 'size')
+		}
+
+		return this
+	}
+}

package/src/reactive/mapped.ts

@@ -0,0 +1,130 @@
+import { Indexable } from '../indexable'
+import { native, ReactiveBaseArray } from './array'
+import { touched, touched1 } from './change'
+import { effect, untracked } from './effects'
+import { cleanedBy } from './interface'
+import { reactive } from './proxy'
+import { dependant } from './tracking'
+import { prototypeForwarding, ScopedCallback } from './types'
+
+// TODO: Lazy reactivity ?
+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
+ */
+class ReactiveReadOnlyArrayClass extends Indexable(ReactiveBaseArray, {
+	get(i: number): any {
+		dependant(this, i)
+		return reactive(this[native][i])
+	},
+	set(i: number, _value: any) {
+		throw new ReadOnlyError(`Setting index ${i} on a read-only array`)
+	},
+	getLength() {
+		dependant(this, 'length')
+		return this[native].length
+	},
+	setLength(value: number) {
+		throw new ReadOnlyError(`Setting length to ${value} on a read-only array`)
+	},
+}) {
+	declare length: number
+	constructor(original: any[]) {
+		super()
+		Object.defineProperties(this, {
+			// We have to make it double, as [native] must be `unique symbol` - impossible through import
+			[native]: { value: original },
+			[prototypeForwarding]: { value: original },
+		})
+	}
+
+	push(..._items: any[]) {
+		throw new ReadOnlyError(`Pushing items to a read-only array`)
+	}
+
+	pop() {
+		throw new ReadOnlyError(`Popping from a read-only array`)
+	}
+
+	shift() {
+		throw new ReadOnlyError(`Shifting from a read-only array`)
+	}
+
+	unshift(..._items: any[]) {
+		throw new ReadOnlyError(`Unshifting items to a read-only array`)
+	}
+
+	splice(_start: number, _deleteCount?: number, ..._items: any[]) {
+		throw new ReadOnlyError(`Splice from a read-only array`)
+	}
+
+	reverse() {
+		throw new ReadOnlyError(`Reversing a read-only array`)
+	}
+
+	sort(_compareFn?: (a: any, b: any) => number) {
+		throw new ReadOnlyError(`Sorting a read-only array`)
+	}
+
+	fill(_value: any, _start?: number, _end?: number) {
+		throw new ReadOnlyError(`Filling a read-only array`)
+	}
+
+	copyWithin(_target: number, _start: number, _end?: number) {
+		throw new ReadOnlyError(`Copying within a read-only array`)
+	}
+}
+
+export const ReactiveReadOnlyArray = reactive(ReactiveReadOnlyArrayClass)
+export type ReactiveReadOnlyArray<T> = readonly T[]
+export function mapped<T, U>(
+	inputs: readonly T[],
+	compute: (input: T, index: number, output: U[]) => U,
+	resize?: (newLength: number, oldLength: number) => void
+): readonly U[] {
+	const result: U[] = []
+	const resultReactive = new ReactiveReadOnlyArray(result)
+	const cleanups: ScopedCallback[] = []
+	function input(index: number) {
+		return effect(function computedIndexedMapInputEffect() {
+			result[index] = compute(inputs[index], index, resultReactive)
+			touched1(resultReactive, { type: 'set', prop: index }, index)
+		})
+	}
+	const cleanupLength = effect(function computedMapLengthEffect({ ascend }) {
+		const length = inputs.length
+		const resultLength = untracked(() => result.length)
+		resize?.(length, resultLength)
+		touched1(resultReactive, { type: 'set', prop: 'length' }, 'length')
+		if (length < resultLength) {
+			const toCleanup = cleanups.splice(length)
+			for (const cleanup of toCleanup) cleanup()
+			result.length = length
+		} else if (length > resultLength)
+			// the input effects will be registered as the call's children, so they will remain not cleaned with this effect on length
+			ascend(function computedMapNewElements() {
+				for (let i = resultLength; i < length; i++) cleanups.push(input(i))
+			})
+	})
+	return cleanedBy(resultReactive, () => {
+		for (const cleanup of cleanups) cleanup()
+		cleanups.length = 0
+		cleanupLength()
+	})
+}
+
+export function reduced<T, U, R extends object = any>(
+	inputs: readonly T[],
+	compute: (input: T, factor: R) => readonly U[]
+): readonly U[] {
+	const result: U[] = []
+	const resultReactive = new ReactiveReadOnlyArray(result)
+	const cleanupFactor = effect(function computedReducedFactorEffect() {
+		const factor: R = {} as R
+		result.length = 0
+		for (const input of inputs) result.push(...compute(input, factor))
+		touched(resultReactive, { type: 'invalidate', prop: 'reduced' })
+	})
+	return cleanedBy(resultReactive, cleanupFactor)
+}

package/src/reactive/memoize.ts

@@ -0,0 +1,107 @@
+import { decorator } from '../decorator'
+import { renamed } from '../utils'
+import { touched1 } from './change'
+import { effect, root } from './effects'
+import { dependant, getRoot, markWithRoot } from './tracking'
+
+export type Memoizable = object | any[] | symbol | ((...args: any[]) => any)
+
+type MemoCacheTree<Result> = {
+	result?: Result
+	cleanup?: () => void
+	branches?: WeakMap<Memoizable, MemoCacheTree<Result>>
+}
+
+const memoizedRegistry = new WeakMap<Function, Function>()
+
+function getBranch<Result>(tree: MemoCacheTree<Result>, key: Memoizable): MemoCacheTree<Result> {
+	tree.branches ??= new WeakMap()
+	let branch = tree.branches.get(key)
+	if (!branch) {
+		branch = {}
+		tree.branches.set(key, branch)
+	}
+	return branch
+}
+
+function memoizeFunction<Result, Args extends Memoizable[]>(
+	fn: (...args: Args) => Result
+): (...args: Args) => Result {
+	const fnRoot = getRoot(fn)
+	const existing = memoizedRegistry.get(fnRoot)
+	if (existing) return existing as (...args: Args) => Result
+
+	const cacheRoot: MemoCacheTree<Result> = {}
+	const memoized = markWithRoot((...args: Args): Result => {
+		const localArgs = args //: Args = maxArgs !== undefined ? (args.slice(0, maxArgs) as Args) : args
+		if (localArgs.some((arg) => !(arg && ['object', 'symbol', 'function'].includes(typeof arg))))
+			throw new Error('memoize expects non-null object arguments')
+
+		let node: MemoCacheTree<Result> = cacheRoot
+		for (const arg of localArgs) {
+			node = getBranch(node, arg)
+		}
+
+		dependant(node, 'memoize')
+		if ('result' in node) 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)
+					return () => {
+						// When dependencies change, clear the cache and notify consumers
+						delete node.result
+						touched1(node, { type: 'invalidate', prop: localArgs }, 'memoize')
+					}
+				}, fnRoot),
+				{ opaque: true }
+			)
+		)
+		return node.result!
+	}, fn)
+
+	memoizedRegistry.set(fnRoot, memoized)
+	memoizedRegistry.set(memoized, memoized)
+	return memoized as (...args: Args) => Result
+}
+
+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
+			)
+		)
+		return function (this: 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
+		return function (this: any, ...args: object[]) {
+			return memoized(this, ...args)
+		}
+	},
+	default: memoizeFunction,
+})