mutts 1.0.8 → 1.0.10

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/mapped.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,319 +0,0 @@
-import { Hook, Restorer, asyncHooks } from '.'
-
-const hooks = new Set<Hook>()
-const promiseContexts = new WeakMap<Promise<any>, Set<Restorer>>()
-
-asyncHooks.addHook = function (hook: Hook) {
-	hooks.add(hook)
-	return () => {
-		hooks.delete(hook)
-	}
-}
-
-// [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 = function<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 = function<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 = function<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 = function<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 = function<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 = function<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,23 +0,0 @@
-export type Restorer = () => () => void
-export type Hook = () => Restorer
-
-export const asyncHooks = {
-	addHook(_hook: Hook): () => void {
-		throw 'One must import the library from the server or the client side'
-	},
-    /** 
-     * [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,104 +0,0 @@
-import { createHook } from 'node:async_hooks'
-import { Hook, Restorer, asyncHooks } from '.'
-
-// 1. Generic async_hooks implementation for Hooks
-// This maintains support for 'asyncHooks.addHook' for generic use cases.
-
-const hooks = new Set<Hook>()
-asyncHooks.addHook = function (hook: Hook) {
-	hooks.add(hook)
-	return () => {
-		hooks.delete(hook)
-	}
-}
-
-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
-
-