mutts 1.0.9 → 1.0.10

package/src/reactive/index.ts

@@ -1,72 +0,0 @@
-export { attend, lift, type ScanResult, scan } from './buffer'
-export { getState, touched, touched1 } from './change'
-export { deepWatch } from './deep-watch'
-export { cleanedBy, derived, effectAggregator, getActiveEffect } from './effect-context'
-export {
-	addBatchCleanup,
-	atomic,
-	biDi,
-	defer,
-	effect,
-	getActivationLog,
-	onEffectThrow,
-	onEffectTrigger,
-	reset,
-	root,
-	untracked,
-} from './effects'
-export { type Memoizable, memoize } from './memoize'
-export { immutables, isNonReactive, registerNativeReactivity } from './non-reactive'
-export { getActiveProjection, project } from './project'
-export { isReactive, ReactiveBase, reactive, unwrap } from './proxy'
-export { organize, organized } from './record'
-export { Register, register } from './register'
-export {
-	cleanup,
-	type EffectAccess as DependencyAccess,
-	type EffectCleanup,
-	type EffectOptions,
-	type EffectTrigger,
-	type Evolution,
-	options as reactiveOptions,
-	ReactiveError,
-	ReactiveErrorCode,
-	type ScopedCallback,
-} from './types'
-export { unreactive, watch } from './watch'
-export { describe } from './describe'
-
-import { ReactiveArray } from './array'
-import {
-	deepWatchers,
-	effectToDeepWatchedObjects,
-	objectParents,
-	objectsWithDeepWatchers,
-} from './deep-watch'
-import { ReactiveMap, ReactiveWeakMap } from './map'
-import { nonReactiveObjects } from './non-reactive-state'
-import { metaProtos, objectToProxy, proxyToObject } from './proxy'
-import { effectToReactiveObjects, watchers } from './registry'
-import { ReactiveSet, ReactiveWeakSet } from './set'
-
-// Register native collection types to use specialized reactive wrappers
-metaProtos.set(Array, ReactiveArray.prototype)
-metaProtos.set(Set, ReactiveSet.prototype)
-metaProtos.set(WeakSet, ReactiveWeakSet.prototype)
-metaProtos.set(Map, ReactiveMap.prototype)
-metaProtos.set(WeakMap, ReactiveWeakMap.prototype)
-
-/**
- * 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/map.ts

@@ -1,142 +0,0 @@
-import { contentRef } from '../utils'
-import { touched, touched1 } from './change'
-import { notifyPropertyChange } from './deep-touch'
-import { makeReactiveEntriesIterator, makeReactiveIterator } from './non-reactive'
-import { reactive } from './proxy'
-import { dependant } from './tracking'
-
-/**
- * Reactive wrapper around JavaScript's WeakMap class
- * Only tracks individual key operations, no size tracking (WeakMap limitation)
- */
-export abstract class ReactiveWeakMap<K extends object, V> extends WeakMap<K, V> {
-	// Implement WeakMap interface methods with reactivity
-	delete(key: K): boolean {
-		const hadKey = this.has(key)
-		const result = this.delete(key)
-
-		if (hadKey) touched1(contentRef(this), { type: 'del', prop: key }, key)
-
-		return result
-	}
-
-	get(key: K): V | undefined {
-		dependant(contentRef(this), key)
-		return reactive(this.get(key))
-	}
-
-	has(key: K): boolean {
-		dependant(contentRef(this), key)
-		return this.has(key)
-	}
-
-	set(key: K, value: V): this {
-		const hadKey = this.has(key)
-		const oldValue = this.get(key)
-		const reactiveValue = reactive(value)
-		this.set(key, reactiveValue)
-
-		if (!hadKey || oldValue !== reactiveValue) {
-			notifyPropertyChange(contentRef(this), key, oldValue, reactiveValue, hadKey)
-		}
-
-		return this
-	}
-}
-
-/**
- * Reactive wrapper around JavaScript's Map class
- * Tracks size changes, individual key operations, and collection-wide operations
- */
-export abstract class ReactiveMap<K, V> extends Map<K, V> {
-	// Implement Map interface methods with reactivity
-	get size(): number {
-		dependant(this, 'size') // The ReactiveMap instance still goes through proxy
-		return this.size
-	}
-
-	clear(): void {
-		const hadEntries = this.size > 0
-		this.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(contentRef(this), evolution)
-		}
-	}
-
-	entries(): Generator<[K, V]> {
-		dependant(contentRef(this))
-		return makeReactiveEntriesIterator(this.entries())
-	}
-
-	forEach(callbackfn: (value: V, key: K, map: Map<K, V>) => void, thisArg?: any): void {
-		dependant(contentRef(this))
-		this.forEach(callbackfn, thisArg)
-	}
-
-	keys(): MapIterator<K> {
-		dependant(contentRef(this))
-		return this.keys()
-	}
-
-	values(): Generator<V> {
-		dependant(contentRef(this))
-		return makeReactiveIterator(this.values())
-	}
-
-	[Symbol.iterator](): MapIterator<[K, V]> {
-		dependant(contentRef(this))
-		const it: MapIterator<[K, V]> = Map.prototype[Symbol.iterator].call(this)
-		const nativeNext = it.next.bind(it)
-		it.next = () => {
-			const result = nativeNext()
-			if (result.done) return result
-			const [key, value] = result.value
-			return { value: [reactive(key), reactive(value)], done: false }
-		}
-		return it
-	}
-
-	// Implement Map methods with reactivity
-	delete(key: K): boolean {
-		const hadKey = this.has(key)
-		const result = this.delete(key)
-
-		if (hadKey) {
-			const evolution = { type: 'del', prop: key } as const
-			touched1(contentRef(this), evolution, key)
-			touched1(this, evolution, 'size')
-		}
-
-		return result
-	}
-
-	get(key: K): V | undefined {
-		dependant(contentRef(this), key)
-		return reactive(this.get(key))
-	}
-
-	has(key: K): boolean {
-		dependant(contentRef(this), key)
-		return this.has(key)
-	}
-
-	set(key: K, value: V): this {
-		const hadKey = this.has(key)
-		const oldValue = this.get(key)
-		const reactiveValue = reactive(value)
-		this.set(key, reactiveValue)
-
-		if (!hadKey || oldValue !== reactiveValue) {
-			notifyPropertyChange(contentRef(this), 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/memoize.ts

@@ -1,186 +0,0 @@
-import { decorator } from '../decorator'
-import { deepCompare, renamed } from '../utils'
-import { touched1 } from './change'
-import { effect, root, untracked } from './effects'
-import { getRoot, markWithRoot } from './registry'
-import { dependant } from './tracking'
-import { optionCall, options, rootFunction } from './types'
-
-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<any, Function>()
-const wrapperRegistry = 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
-		// Note: decorators add `this` as first argument
-		for (const arg of localArgs) {
-			node = getBranch(node, arg)
-		}
-
-		dependant(node, 'memoize')
-		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)) {
-						optionCall('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(
-				() => {
-					// 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')
-						// 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
-						}
-					}
-				},
-				{ opaque: true }
-			)
-		)
-
-		if (options.onMemoizationDiscrepancy) {
-			const wasVerification = options.isVerificationRun
-			options.isVerificationRun = true
-			try {
-				const fresh = untracked(() => fn(...localArgs))
-				if (!deepCompare(node.result, fresh)) {
-					optionCall('onMemoizationDiscrepancy', node.result, fresh, fn, localArgs, 'comparison')
-				}
-			} finally {
-				options.isVerificationRun = wasVerification
-			}
-		}
-
-		return node.result!
-	}, fn)
-
-	memoizedRegistry.set(fnRoot, memoized)
-	memoizedRegistry.set(memoized, memoized)
-	return memoized as (...args: Args) => Result
-}
-
-/**
- * Decorator and function wrapper for memoizing computed values based on reactive dependencies.
- *
- * When used as a decorator on getters or methods, it caches the result and automatically
- * invalidates the cache when reactive dependencies change.
- *
- * When used as a function wrapper, it memoizes based on object arguments (WeakMap-based cache).
- *
- * @example
- * ```typescript
- * class User {
- *   @memoize
- *   get fullName() {
- *     return `${this.firstName} ${this.lastName}`
- *   }
- * }
- *
- * // Or as a function wrapper
- * const expensive = memoize((obj: SomeObject) => {
- *   return heavyComputation(obj)
- * })
- * ```
- */
-export const memoize = decorator({
-	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, 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)
-		}
-	},
-	default: memoizeFunction,
-})

package/src/reactive/non-reactive-state.ts

@@ -1,49 +0,0 @@
-import { nativeReactive, nonReactiveMark } from './types'
-
-export const nonReactiveObjects = new WeakSet<object>()
-export const immutables = new Set<(tested: any) => boolean>()
-export const absent = Symbol('absent')
-
-function markNonReactive<T extends object[]>(...obj: T): T[0] {
-	for (const o of obj) {
-		try {
-			Object.defineProperty(o, nonReactiveMark, {
-				value: true,
-				writable: false,
-				enumerable: false,
-				configurable: false,
-			})
-		} catch {}
-		if (!(nonReactiveMark in (o as object))) nonReactiveObjects.add(o as object)
-	}
-	return obj[0]
-}
-
-export function nonReactiveClass<T extends (new (...args: any[]) => any)[]>(...cls: T): T[0] {
-	for (const c of cls) if (c) (c.prototype as any)[nonReactiveMark] = true
-	return cls[0]
-}
-
-export function isNonReactive(obj: any): boolean {
-	if (obj === null || typeof obj !== 'object') return true
-	if (nonReactiveObjects.has(obj)) return true
-	if ((obj as any)[nonReactiveMark]) return true
-	for (const fn of immutables) if (fn(obj)) return true
-	return false
-}
-
-export function registerNativeReactivity(
-	originalClass: new (...args: any[]) => any,
-	reactiveClass: new (...args: any[]) => any
-) {
-	originalClass.prototype[nativeReactive] = reactiveClass
-	nonReactiveClass(reactiveClass)
-}
-
-nonReactiveClass(Date, RegExp, Error, Promise, Function)
-if (typeof window !== 'undefined') {
-	markNonReactive(window, document)
-	nonReactiveClass(Node, Element, HTMLElement, EventTarget)
-}
-
-export { markNonReactive as nonReactive }

package/src/reactive/non-reactive.ts

@@ -1,43 +0,0 @@
-import {
-	absent,
-	immutables,
-	isNonReactive,
-	nonReactive,
-	nonReactiveClass,
-	nonReactiveObjects,
-	registerNativeReactivity,
-} from './non-reactive-state'
-import { reactive } from './proxy'
-
-/**
- * Converts an iterator to a generator that yields reactive values
- */
-export function* makeReactiveIterator<T>(iterator: Iterator<T>): Generator<T> {
-	let result = iterator.next()
-	while (!result.done) {
-		yield reactive(result.value)
-		result = iterator.next()
-	}
-}
-
-/**
- * Converts an iterator of key-value pairs to a generator that yields reactive key-value pairs
- */
-export function* makeReactiveEntriesIterator<K, V>(iterator: Iterator<[K, V]>): Generator<[K, V]> {
-	let result = iterator.next()
-	while (!result.done) {
-		const [key, value] = result.value
-		yield [reactive(key), reactive(value)]
-		result = iterator.next()
-	}
-}
-
-export {
-	absent,
-	immutables,
-	isNonReactive,
-	nonReactive,
-	nonReactiveClass,
-	nonReactiveObjects,
-	registerNativeReactivity,
-}

package/src/reactive/project.md

@@ -1,107 +0,0 @@
-# project
-
-This document explains how `project(...)` composes reactive effects, and why it uses `ascend(...)` when creating per-item/per-key effects.
-
-## What `project` builds
-
-`project` is a reactive “mapping” primitive.
-
-- A **source** collection (`Array`, `Map`, `Register`, plain record)
-- A **target** collection of the same shape
-- A set of effects that keep target in sync with source:
-  - **structure effect** (length/keys watcher)
-  - **item effect** per key/index (computes the projected value)
-
-The important property is **stability**: changing one source entry should only re-run the effect that owns that entry.
-
-## Effects involved
-
-For `project.array(source, apply)` the implementation creates:
-
-- **Length effect**: watches the set of valid indexes by reading `source.length`.
-- **Index effects**: created lazily (when an index appears), one effect per index.
-
-The other variants (`project.map`, `project.record`, `project.register`) follow the same pattern:
-
-- a *keys effect* (watches which keys exist)
-- a *key effect* per key
-
-## Cleanup and “garbage collection”
-
-`effect(...)` has two cleanup pathways:
-
-- **explicit**: you keep the returned stop function and call it.
-- **GC-driven** (Node with `--expose-gc`): for **root effects only**, a `FinalizationRegistry` calls `stopEffect()` when the stop function itself becomes unreachable.
-
-Parenting matters because only root effects are eligible for automatic GC cleanup.
-
-### Parent-child relationship
-
-When an effect is created while another effect is active, it becomes a **child**:
-
-- the parent keeps a reference to a child-cleanup function
-- when the parent is cleaned up, it calls child-cleanups
-
-This guarantees that **unstored** children do not leak and do not rely on GC.
-
-## Why `project` uses `ascend(...)`
-
-In `project.ts`, per-item effects are created inside the structure effect.
-
-If we created item effects “normally” inside the structure effect body, they would be parented to the structure effect.
-
-That is *not* what we want:
-
-- The structure effect re-runs whenever the set of keys/indexes changes.
-- On each re-run, `effect(...)` executes the previous cleanup first.
-- If item effects were children of the structure effect, that cleanup would stop all item effects on every structural update.
-
-That would break stability:
-
-- pushing a new element would unnecessarily dispose and recreate existing item effects
-- nested projections would be especially unstable
-
-### What `ascend` does here
-
-`ascend` is a wrapper around `effectHistory.zoned`.
-
-It executes a function in the **parent effect context** (the effect that was active when the structure effect itself was created).
-
-So the parent chain becomes:
-
-- owning effect (the effect that called `project(...)`)
-  - structure effect (length/keys)
-  - item effects (per index/key)
-
-All of them share the same owner.
-
-This gives the intended semantics:
-
-- structure effect may re-run many times without killing item effects
-- when the owning effect stops (explicitly or by GC), it will stop:
-  - the structure effect
-  - all item effects
-  - all nested projections under those item effects
-
-## Projection context
-
-During an item effect’s first run, `project` calls:
-
-- `setActiveProjection({ source, key, target, depth, parent })`
-
-This attaches a `ProjectionContext` to the currently running effect via `effectProjectionMetadata`.
-
-`getActiveProjection()` is how nested projections discover their parent projection.
-
-The goal is to allow:
-
-- a nested projection to compute its own `depth`
-- a nested projection to know its parent projection (for debugging/introspection)
-
-## Testing expectations
-
-The behavior that matters (and that tests should lock down) is:
-
-- item effects are not disposed on structural updates of the same projection
-- disposing an outer item stops all nested projection effects under that item
-- disposing the owning effect (or letting it be GC’ed) stops all projection effects created under it