mutts 1.0.9 → 1.0.10

package/docs/reactive/describe.md

@@ -1,85 +0,0 @@
-# Reactive Property Description (`describe`)
-
-The `describe` utility provides a reactive way to define or update properties on an object using a record of property descriptors.
-
-## Overview
-
-Unlike `Object.defineProperties`, the reactive `describe` utility is alive:
-- It tracks the **keys** of the descriptors record.
-- When a new key is added to the descriptors record, the property is defined on the target object.
-- When a key is removed, the property is removed from the target object.
-- When a descriptor itself changes (e.g. its `value` or `get` function), the property definition is updated.
-
-This is particularly useful when projecting props or dynamically extending objects in a reactive way.
-
-Internally, `describe` is built on [`attend`](./attend.md), which provides the reactive key lifecycle.
-
-## API
-
-```typescript
-function describe<T extends object>(
-    descriptors: Record<PropertyKey, PropertyDescriptor>,
-    target: T = {} as T
-): T
-```
-
-### Parameters
-
-- `descriptors`: A reactive record where each value is a standard `PropertyDescriptor`.
-- `target` (optional): The object to define properties on. If omitted, a new plain object is created and returned.
-
-### Returns
-
-The `target` object with reactive property definitions.
-
-## Basic Usage
-
-```typescript
-import { reactive, describe, effect } from 'mutts/reactive'
-
-const target = {}
-const descriptors = reactive({
-    foo: { value: 1, enumerable: true }
-})
-
-describe(descriptors, target)
-
-console.log(target.foo) // 1
-
-// Adding a property reactively
-descriptors.bar = { get: () => 42, enumerable: true }
-console.log(target.bar) // 42
-
-// Removing a property reactively
-delete descriptors.foo
-console.log('foo' in target) // false
-```
-
-## Integration with `project`
-
-`describe` is often used in conjunction with `project` to create dynamic projections of property descriptors:
-
-```typescript
-import { project, describe, memoize } from 'mutts/reactive'
-
-function propsInto(props, into) {
-    const descriptors = project(props, ({ key, value }) => ({
-        get: memoize(() => (typeof value === 'function' ? value() : value)),
-        enumerable: true,
-        configurable: true
-    }))
-    
-    return describe(descriptors, into)
-}
-```
-
-## Renaming Conflict
-
-Previously, `mutts` had a decorator named `describe`. To avoid confusion with this utility, the decorator has been renamed to `@descriptor`.
-
-```typescript
-@descriptor({ enumerable: false })
-class MyClass {
-    internal = 'secret'
-}
-```

package/docs/reactive/project.md

@@ -1,93 +0,0 @@
-# Reactive Register Memoization Notes
-
-## Background
-
-- Register entries are stored in a reactive `Map`. Updating an entry via `Map.set` marks the entire value as changed.
-- Memoized computations that read through `map.get(key)` re-execute fully when the entry changes, even if only a nested property is touched.
-- The goal for rendering lists in a JSX/HTML engine is to avoid rebuilding DOM nodes; only the affected properties should update.
-
-## Evolution: From `organized` to `project`
-
-### Initial State
-
-- `memoize` caches results but invalidates on `Map.set`, so large effects still re-run.
-- `organized` (designed for `Record` sources) creates per-key effects so downstream work reruns only for the touched key; this matches the desired behaviour.
-- **Gap:** `organized` operates on plain objects: key enumeration relies on property iteration and `FoolProof.get/set`. Registers and other keyed collections (`Map`, `Register`, custom stores) need the same per-entry orchestration without converting to records.
-
-### Completed Evolution: `project` Implementation
-
-We implemented `project` as a generalized transformation helper that works across arrays, records, and maps:
-
-**Key Design Decisions:**
-- **Unified API:** Single `project` function with runtime dispatch to `project.array`, `project.record`, or `project.map` based on source type.
-- **Access Pattern:** Callback receives a `ProjectAccess` object with `get()`, `set()`, `key`, `source`, and `value` (computed property) - similar to `organized` but returning a value instead of an effect.
-- **Automatic Target Creation:** The function always creates its own reactive target container (array, record, or map) - no `baseTarget` parameter needed.
-- **Per-Key Effects:** Each source key/index gets its own reactive effect that recomputes only when that specific entry changes, enabling granular updates for rendering pipelines.
-
-**Current API:**
-```typescript
-project.array(source: readonly T[], apply: (access, target) => U): ProjectResult<U[]>
-project.record(source: Record<K, T>, apply: (access, target) => U): ProjectResult<Record<K, U>>
-project.map(source: Map<K, T>, apply: (access, target) => U): ProjectResult<Map<K, U>>
-```
-
-**Current Behavior:**
-- Eager computation: all entries are computed immediately when keys are present.
-- One-way transformation: callback only handles "get" (read) operations; no write-back support.
-- Mutable results: returned arrays/records/maps are fully mutable.
-- `ProjectAccess.old` exposes the previously computed result for each entry, enabling incremental updates and state preservation.
-
-## Future Evolutions
-
-### Bidirectional Transformation (Set Callback)
-
-**Goal:** Support writing back to the source through the projected object.
-
-**Implementation:**
-- Add optional second callback parameter: `set: (access, newValue, target) => void | boolean`
-- When `set` is provided, mutations to the projected object trigger the set callback.
-- The callback receives the same `ProjectAccess` object plus the new value, allowing it to update the source.
-- If `set` returns `false` or throws, the mutation is rejected.
-
-**API Impact:**
-```typescript
-project.array(
-  source: readonly T[],
-  apply: (access, target) => U,
-  set?: (access, newValue: U, target) => void | boolean
-): ProjectResult<U[]>
-```
-
-### Readonly Results When No Set Callback
-
-**Goal:** Make projected objects readonly when no write-back is supported.
-
-**Implementation:**
-- When `set` callback is not provided, wrap the result in a readonly proxy or use read-only array/record types.
-- Prevents accidental mutations that would have no effect on the source.
-- Type system should reflect readonly nature in return types.
-
-**API Impact:**
-- Return type becomes `ProjectResult<readonly U[]>` or similar when `set` is omitted.
-- Arrays use `ReactiveReadOnlyArray` (already exists in `mapped.ts`).
-- Records and maps need readonly wrappers or proxy-based protection.
-
-## Implementation Notes for AI Agents
-
-**Current State:**
-- `project` is fully functional for arrays, records, maps, and registers with eager, one-way transformation.
-- Tests cover per-key reactivity, key addition/removal, automatic helper selection, and `access.old` value propagation.
-- The implementation follows the same per-key effect pattern as `organized` but returns computed values.
-
-**Future Work:**
-- Lazy computing requires careful effect lifecycle management to avoid memory leaks.
-- Bidirectional support needs to handle edge cases (concurrent reads/writes, validation).
-- Readonly enforcement should align with existing `ReactiveReadOnlyArray` patterns where possible.
-- Consider whether these features should be opt-in via options object or separate function variants.
-
-**Related Files:**
-- `src/reactive/project.ts` - Main implementation
-- `src/reactive/array.ts` - Reference for `ReactiveReadOnlyArray` pattern
-- `src/reactive/record.ts` - Reference for `organized` pattern (different use case)
-- `tests/reactive/project.test.ts` - Test coverage
-

package/src/async/browser.ts

@@ -1,323 +0,0 @@
-import { asyncHooks, hooks, type Restorer } from '.'
-
-const promiseContexts = new WeakMap<Promise<any>, Set<Restorer>>()
-
-// [HACK]: Sanitization
-// If a Promise is created inside the zone, it carries the "Sticky" zone context.
-// If returned to the outer scope, that context leaks. We wrap it in a new Promise
-// created here (in the outer scope) to break the chain and sanitize the return value.
-// See BROWSER_ASYNC_POLYFILL.md for full details.
-asyncHooks.sanitizePromise = (res: any) => {
-	if (res && typeof (res as any).then === 'function') {
-		return new Promise((resolve, reject) => {
-			setTimeout(() => {
-				;(res as any).then(resolve, reject)
-			}, 0)
-		})
-	}
-	return res
-}
-
-function captureRestorers() {
-	const restorers = new Set<Restorer>()
-	for (const hook of hooks) {
-		const restorer = hook()
-		if (restorer) restorers.add(restorer)
-	}
-	return restorers
-}
-
-function wrap<Args extends any[], R>(
-	fn: ((...args: Args) => R) | null | undefined,
-	capturedRestorers?: Set<Restorer>
-) {
-	if (typeof fn !== 'function') return fn
-	const restorers = capturedRestorers || captureRestorers()
-	return function (this: any, ...args: Args) {
-		const undoers: (() => void)[] = []
-		for (const restore of restorers) undoers.push(restore())
-		try {
-			return fn.apply(this, args)
-		} finally {
-			if (originals.queueMicrotask) {
-				// Double microtask ensures we run after the first await resumption microtask
-				originals.queueMicrotask.call(globalThis, () => {
-					originals.queueMicrotask.call(globalThis, () => {
-						originals.queueMicrotask.call(globalThis, () => {
-							for (let i = undoers.length - 1; i >= 0; i--) undoers[i]()
-						})
-					})
-				})
-			} else {
-				for (let i = undoers.length - 1; i >= 0; i--) undoers[i]()
-			}
-		}
-	}
-}
-
-const targetWrappers = new WeakMap<any, Map<string, WeakMap<Function, Function>>>()
-
-function patchEventTarget(proto: any) {
-	if (!proto || !proto.addEventListener || !proto.removeEventListener) return
-	const nativeAdd = proto.addEventListener
-	const nativeRemove = proto.removeEventListener
-
-	proto.addEventListener = function (this: any, type: string, listener: any, options: any) {
-		if (typeof listener !== 'function') {
-			return nativeAdd.call(this, type, listener, options)
-		}
-
-		let types = targetWrappers.get(this)
-		if (!types) {
-			types = new Map()
-			targetWrappers.set(this, types)
-		}
-		let listeners = types.get(type)
-		if (!listeners) {
-			listeners = new WeakMap()
-			types.set(type, listeners)
-		}
-
-		let wrapped = listeners.get(listener)
-		if (!wrapped) {
-			wrapped = wrap(listener)
-			listeners.set(listener, wrapped)
-		}
-
-		return nativeAdd.call(this, type, wrapped, options)
-	}
-
-	proto.removeEventListener = function (this: any, type: string, listener: any, options: any) {
-		if (typeof listener !== 'function') {
-			return nativeRemove.call(this, type, listener, options)
-		}
-
-		const types = targetWrappers.get(this)
-		if (types) {
-			const listeners = types.get(type)
-			if (listeners) {
-				const wrapped = listeners.get(listener)
-				if (wrapped) {
-					return nativeRemove.call(this, type, wrapped, options)
-				}
-			}
-		}
-
-		return nativeRemove.call(this, type, listener, options)
-	}
-}
-
-function patchOnProperties(proto: any) {
-	if (!proto) return
-	for (const prop of Object.getOwnPropertyNames(proto)) {
-		if (prop.startsWith('on')) {
-			const desc = Object.getOwnPropertyDescriptor(proto, prop)
-			if (desc && desc.set && desc.configurable) {
-				const nativeSet = desc.set
-				Object.defineProperty(proto, prop, {
-					...desc,
-					set: function (this: any, fn: any) {
-						nativeSet.call(this, wrap(fn))
-					},
-				})
-			}
-		}
-	}
-}
-
-if (typeof EventTarget !== 'undefined') {
-	patchEventTarget(EventTarget.prototype)
-}
-
-const prototypesToPatch = [
-	typeof EventTarget !== 'undefined' && EventTarget.prototype,
-	typeof HTMLElement !== 'undefined' && HTMLElement.prototype,
-	typeof Window !== 'undefined' && Window.prototype,
-	typeof Document !== 'undefined' && Document.prototype,
-	typeof MessagePort !== 'undefined' && MessagePort.prototype,
-	typeof XMLHttpRequest !== 'undefined' && XMLHttpRequest.prototype,
-	typeof IDBRequest !== 'undefined' && IDBRequest.prototype,
-	typeof IDBTransaction !== 'undefined' && IDBTransaction.prototype,
-	typeof IDBDatabase !== 'undefined' && IDBDatabase.prototype,
-	typeof FileReader !== 'undefined' && FileReader.prototype,
-	typeof AbortSignal !== 'undefined' && AbortSignal.prototype,
-]
-
-for (const proto of prototypesToPatch) {
-	if (proto) {
-		patchOnProperties(proto)
-	}
-}
-
-const GLOBAL_ORIGINALS = Symbol.for('mutts.originals')
-const GLOBAL_PROMISE = Symbol.for('mutts.OriginalPromise')
-
-let originals: any
-let OriginalPromise: any
-
-if ((globalThis as any)[GLOBAL_ORIGINALS]) {
-	originals = (globalThis as any)[GLOBAL_ORIGINALS]
-	OriginalPromise = (globalThis as any)[GLOBAL_PROMISE]
-} else {
-	OriginalPromise = globalThis.Promise
-	originals = {
-		then: OriginalPromise.prototype.then,
-		catch: OriginalPromise.prototype.catch,
-		finally: OriginalPromise.prototype.finally,
-		resolve: OriginalPromise.resolve,
-		reject: OriginalPromise.reject,
-		all: OriginalPromise.all,
-		allSettled: (OriginalPromise as any).allSettled,
-		race: OriginalPromise.race,
-		any: (OriginalPromise as any).any,
-		setTimeout: globalThis.setTimeout,
-		setInterval: globalThis.setInterval,
-		setImmediate: (globalThis as any).setImmediate,
-		requestAnimationFrame: (globalThis as any).requestAnimationFrame,
-		queueMicrotask: globalThis.queueMicrotask,
-	}
-	;(globalThis as any)[GLOBAL_ORIGINALS] = originals
-	;(globalThis as any)[GLOBAL_PROMISE] = OriginalPromise
-}
-
-// Ensure modern statics are captured even if originals was cached from an older version
-if (!originals.allSettled) originals.allSettled = (OriginalPromise as any).allSettled
-if (!originals.any) originals.any = (OriginalPromise as any).any
-if (!originals.race) originals.race = OriginalPromise.race
-
-function patchedThen(this: any, onFulfilled: any, onRejected: any) {
-	const context = promiseContexts.get(this) || captureRestorers()
-	const nextPromise = originals.then.call(
-		this,
-		wrap(onFulfilled, context),
-		wrap(onRejected, context)
-	)
-	if (context.size > 0) promiseContexts.set(nextPromise, context)
-	return nextPromise
-}
-
-function patchedCatch(this: any, onRejected: any) {
-	const context = promiseContexts.get(this) || captureRestorers()
-	const nextPromise = originals.catch.call(this, wrap(onRejected, context))
-	if (context.size > 0) promiseContexts.set(nextPromise, context)
-	return nextPromise
-}
-
-function patchedFinally(this: any, onFinally: any) {
-	const context = promiseContexts.get(this) || captureRestorers()
-	const nextPromise = originals.finally.call(this, wrap(onFinally, context))
-	if (context.size > 0) promiseContexts.set(nextPromise, context)
-	return nextPromise
-}
-
-function PatchedPromise<T>(
-	this: any,
-	executor: (resolve: (value: T | PromiseLike<T>) => void, reject: (reason?: any) => void) => void
-) {
-	if (typeof executor === 'function') {
-		const p = new OriginalPromise((resolve, reject) => {
-			const wrappedResolve = wrap(resolve)
-			const wrappedReject = wrap(reject)
-			executor(wrappedResolve, wrappedReject)
-		})
-		const context = captureRestorers()
-		promiseContexts.set(p, context) // Always set, even if empty (Sticky Root)
-		return p
-	}
-	return new OriginalPromise(executor)
-}
-
-// Copy statics
-Object.assign(PatchedPromise, OriginalPromise as any)
-
-// Inherit prototype for instanceof checks
-PatchedPromise.prototype = OriginalPromise.prototype
-
-PatchedPromise.resolve = (<T>(value?: T | PromiseLike<T>): Promise<T> => {
-	const p = originals.resolve.call(OriginalPromise, value) as Promise<T>
-	const context = captureRestorers()
-	// Ensure we don't overwrite if it already has context (e.g. from constructor)
-	if (context.size > 0 && !promiseContexts.has(p)) promiseContexts.set(p, context)
-	return p
-}) as any
-
-PatchedPromise.reject = (<T = never>(reason?: any): Promise<T> => {
-	const p = originals.reject.call(OriginalPromise, reason) as Promise<T>
-	const context = captureRestorers()
-	if (context.size > 0) promiseContexts.set(p, context)
-	return p
-}) as any
-
-PatchedPromise.all = (<T>(values: Iterable<T | PromiseLike<T>>): Promise<Awaited<T>[]> => {
-	const p = originals.all.call(OriginalPromise, values) as Promise<Awaited<T>[]>
-	const context = captureRestorers()
-	if (context.size > 0) promiseContexts.set(p, context)
-	return p
-}) as any
-
-PatchedPromise.allSettled = (<T>(
-	values: Iterable<T | PromiseLike<T>>
-): Promise<PromiseSettledResult<Awaited<T>>[]> => {
-	const p = (originals.allSettled as any).call(OriginalPromise, values)
-	const context = captureRestorers()
-	if (context.size > 0) promiseContexts.set(p, context)
-	return p
-}) as any
-
-PatchedPromise.race = (<T>(values: Iterable<T | PromiseLike<T>>): Promise<Awaited<T>> => {
-	const p = originals.race.call(OriginalPromise, values) as Promise<Awaited<T>>
-	const context = captureRestorers()
-	if (context.size > 0) promiseContexts.set(p, context)
-	return p
-}) as any
-
-PatchedPromise.any = (<T>(values: Iterable<T | PromiseLike<T>>): Promise<Awaited<T>> => {
-	const p = (originals.any as any).call(OriginalPromise, values)
-	const context = captureRestorers()
-	if (context.size > 0) promiseContexts.set(p, context)
-	return p
-}) as any
-
-// Only apply patches if not already applied (or re-apply safely)
-// Note: OriginalPromise.prototype might be shared if we used the global one.
-// We must ensure we don't patch it twice if it's the SAME object.
-if (OriginalPromise.prototype.then !== patchedThen) {
-	OriginalPromise.prototype.then = patchedThen as any
-	OriginalPromise.prototype.catch = patchedCatch as any
-	OriginalPromise.prototype.finally = patchedFinally as any
-}
-
-try {
-	Object.defineProperty(OriginalPromise, Symbol.species, {
-		get: () => PatchedPromise,
-		configurable: true,
-	})
-} catch (e) {}
-
-;(globalThis as any).Promise = PatchedPromise
-
-globalThis.setTimeout = ((callback: Function, ...args: any[]) => {
-	return originals.setTimeout.call(globalThis, wrap(callback as any), ...args)
-}) as any
-
-globalThis.setInterval = ((callback: Function, ...args: any[]) => {
-	return originals.setInterval.call(globalThis, wrap(callback as any), ...args)
-}) as any
-
-if (originals.setImmediate) {
-	;(globalThis as any).setImmediate = ((callback: Function, ...args: any[]) => {
-		return originals.setImmediate.call(globalThis, wrap(callback as any), ...args)
-	}) as any
-}
-
-if (originals.requestAnimationFrame) {
-	globalThis.requestAnimationFrame = (callback: FrameRequestCallback) => {
-		return originals.requestAnimationFrame.call(globalThis, wrap(callback))
-	}
-}
-
-if (originals.queueMicrotask) {
-	globalThis.queueMicrotask = (callback: VoidFunction): void => {
-		originals.queueMicrotask.call(globalThis, wrap(callback))
-	}
-}

package/src/async/index.ts

@@ -1,27 +0,0 @@
-export type Restorer = () => () => void
-export type Hook = () => Restorer
-
-// Queue for hooks registered before the environment is ready (circular dependency fix)
-export const hooks = new Set<Hook>()
-
-export const asyncHooks = {
-	addHook(hook: Hook): () => void {
-		hooks.add(hook)
-		return () => hooks.delete(hook)
-	},
-	/**
-	 * [Hack] Sanitize a promise (or value) to prevent context leaks.
-	 * Default: Identity function.
-	 * Browser: Uses Macrotask wrapping to break microtask chains.
-	 */
-	sanitizePromise(p: any): any {
-		return p
-	},
-}
-
-/**
- * Register a hook that will be called whenever an asynchronous operation is initiated.
- * The hook should return a restorer function which will be called just before the async callback runs.
- * That restorer should in turn return an undoer function which will be called just after the async callback finishes.
- */
-export const asyncHook = (hook: Hook) => asyncHooks.addHook(hook)

package/src/async/node.ts

@@ -1,92 +0,0 @@
-import { createHook } from 'node:async_hooks'
-import { hooks, type Restorer } from '.'
-
-// 1. Generic async_hooks implementation for Hooks
-// This maintains support for 'asyncHooks.addHook' for generic use cases.
-
-const contexts = new Map<number, Restorer[]>()
-const activeUndoers = new Map<number, (() => void)[]>()
-
-// Helper to capture current hooks state
-function captureRestorers() {
-	if (hooks.size === 0) return []
-	const restorers: Restorer[] = []
-	for (const h of hooks) {
-		const r = h()
-		if (r) restorers.push(r)
-	}
-	return restorers
-}
-
-// Manual Wrap function to handle Promise callbacks
-function wrap<Args extends any[], R>(fn: ((...args: Args) => R) | null | undefined) {
-	if (typeof fn !== 'function') return fn
-	const restorers = captureRestorers()
-	if (restorers.length === 0) return fn
-
-	return function (this: any, ...args: Args) {
-		const undoers: (() => void)[] = []
-		for (const restore of restorers) {
-			const u = restore()
-			if (u) undoers.push(u)
-		}
-		try {
-			return fn.apply(this, args)
-		} finally {
-			for (let i = undoers.length - 1; i >= 0; i--) undoers[i]()
-		}
-	}
-}
-
-const hook = createHook({
-	init(asyncId, _type, _triggerId, _resource) {
-		// Used for native resources like Timers
-		const restorers = captureRestorers()
-		if (restorers.length > 0) contexts.set(asyncId, restorers)
-	},
-	before(asyncId) {
-		const restorers = contexts.get(asyncId)
-		if (!restorers) return
-		const undoers: (() => void)[] = []
-		for (const restore of restorers) {
-			const u = restore()
-			if (u) undoers.push(u)
-		}
-		if (undoers.length > 0) activeUndoers.set(asyncId, undoers)
-	},
-	after(asyncId) {
-		const undoers = activeUndoers.get(asyncId)
-		if (!undoers) return
-		for (let i = undoers.length - 1; i >= 0; i--) undoers[i]()
-		activeUndoers.delete(asyncId)
-	},
-	destroy(asyncId) {
-		contexts.delete(asyncId)
-		activeUndoers.delete(asyncId)
-	},
-})
-hook.enable()
-
-// 2. Shadow Promise Implementation
-// Ensures V8 await resumptions are visible as .then callbacks, wrapping them to restore context.
-
-const OriginalPromise = globalThis.Promise
-const originalMethods = {
-	then: OriginalPromise.prototype.then,
-	catch: OriginalPromise.prototype.catch,
-	finally: OriginalPromise.prototype.finally,
-	resolve: OriginalPromise.resolve,
-	reject: OriginalPromise.reject,
-	all: OriginalPromise.all,
-}
-
-// Patch prototype
-OriginalPromise.prototype.then = function (onFulfilled, onRejected) {
-	return originalMethods.then.call(this, wrap(onFulfilled), wrap(onRejected))
-} as any
-OriginalPromise.prototype.catch = function (onRejected) {
-	return originalMethods.catch.call(this, wrap(onRejected))
-} as any
-OriginalPromise.prototype.finally = function (onFinally) {
-	return originalMethods.finally.call(this, wrap(onFinally))
-} as any