mutts 1.0.1 → 1.0.3

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

@@ -0,0 +1,49 @@
+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

@@ -0,0 +1,43 @@
+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.project.md

@@ -0,0 +1,93 @@
+# 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 `ReflectGet/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/reactive/project.ts

@@ -0,0 +1,335 @@
+import { ReflectGet, ReflectSet } from '../utils'
+import { effect, untracked } from './effects'
+import { cleanedBy, cleanup } from './interface'
+import { reactive } from './proxy'
+import { Register } from './register'
+import { type ScopedCallback } from './types'
+
+type ProjectOldValue<Target> = Target extends readonly (infer Item)[]
+	? Item
+	: Target extends Map<any, infer Item>
+		? Item
+		: Target extends Record<PropertyKey, infer Item>
+			? Item
+			: unknown
+
+export type ProjectAccess<SourceValue, Key, SourceType, Target> = {
+	readonly key: Key
+	get(): SourceValue
+	set(value: SourceValue): boolean
+	readonly source: SourceType
+	readonly old?: ProjectOldValue<Target>
+	value: SourceValue
+}
+
+type BivariantProjectCallback<Args extends any[], Return> = {
+	bivarianceHack(...args: Args): Return
+}['bivarianceHack']
+
+export type ProjectCallback<
+	SourceValue,
+	Key,
+	Target extends object,
+	SourceType,
+	Result,
+> = BivariantProjectCallback<[ProjectAccess<SourceValue, Key, SourceType, Target>, Target], Result>
+
+export type ProjectResult<Target extends object> = Target & { [cleanup]: ScopedCallback }
+
+function defineAccessValue<Access extends { get(): unknown; set(value: unknown): boolean }>(
+	access: Access
+) {
+	Object.defineProperty(access, 'value', {
+		get: access.get,
+		set: access.set,
+		configurable: true,
+		enumerable: true,
+	})
+}
+
+function makeCleanup<Result extends object>(
+	target: Result,
+	effectMap: Map<unknown, ScopedCallback>,
+	onDispose: () => void
+): ProjectResult<Result> {
+	return cleanedBy(target, () => {
+		onDispose()
+		for (const stop of effectMap.values()) stop?.()
+		effectMap.clear()
+	}) as ProjectResult<Result>
+}
+
+function projectArray<SourceValue, ResultValue>(
+	source: readonly SourceValue[],
+	apply: ProjectCallback<SourceValue, number, ResultValue[], readonly SourceValue[], ResultValue>
+): ProjectResult<ResultValue[]> {
+	const observedSource = reactive(source) as readonly SourceValue[]
+	const target = reactive([] as ResultValue[])
+	const indexEffects = new Map<number, ScopedCallback>()
+
+	function normalizeTargetLength(length: number) {
+		ReflectSet(target as unknown as object, 'length', length, target)
+	}
+
+	function disposeIndex(index: number) {
+		const stopEffect = indexEffects.get(index)
+		if (stopEffect) {
+			indexEffects.delete(index)
+			stopEffect()
+			Reflect.deleteProperty(target as unknown as object, index)
+		}
+	}
+
+	const cleanupLength = effect(function projectArrayLengthEffect({ ascend }) {
+		const length = observedSource.length
+		normalizeTargetLength(length)
+		const existing = Array.from(indexEffects.keys())
+		for (let i = 0; i < length; i++) {
+			if (indexEffects.has(i)) continue
+			ascend(() => {
+				const index = i
+				const stop = effect(function projectArrayIndexEffect() {
+					const previous = untracked(() => target[index])
+					const accessBase = {
+						key: index,
+						source: observedSource,
+						get: () => ReflectGet(observedSource as any, index, observedSource),
+						set: (value: SourceValue) =>
+							ReflectSet(observedSource as any, index, value, observedSource),
+						old: previous,
+					} as ProjectAccess<SourceValue, number, readonly SourceValue[], ResultValue[]>
+					defineAccessValue(accessBase)
+					const produced = apply(accessBase, target)
+					target[index] = produced
+				})
+				indexEffects.set(i, stop)
+			})
+		}
+		for (const index of existing) if (index >= length) disposeIndex(index)
+	})
+
+	return makeCleanup(target, indexEffects, () => cleanupLength())
+}
+
+function projectRegister<Key extends PropertyKey, SourceValue, ResultValue>(
+	source: Register<SourceValue, Key>,
+	apply: ProjectCallback<
+		SourceValue,
+		Key,
+		Map<Key, ResultValue>,
+		Register<SourceValue, Key>,
+		ResultValue
+	>
+): ProjectResult<Map<Key, ResultValue>> {
+	const observedSource = reactive(source) as Register<SourceValue, Key>
+	const rawTarget = new Map<Key, ResultValue>()
+	const target = reactive(rawTarget) as Map<Key, ResultValue>
+	const keyEffects = new Map<Key, ScopedCallback>()
+
+	function disposeKey(key: Key) {
+		const stopEffect = keyEffects.get(key)
+		if (stopEffect) {
+			stopEffect()
+			keyEffects.delete(key)
+			target.delete(key)
+		}
+	}
+
+	const cleanupKeys = effect(function projectRegisterEffect({ ascend }) {
+		const keys = new Set<Key>()
+		for (const key of observedSource.mapKeys()) keys.add(key)
+
+		for (const key of keys) {
+			if (keyEffects.has(key)) continue
+			ascend(() => {
+				const stop = effect(function projectRegisterKeyEffect() {
+					const previous = untracked(() => target.get(key))
+					const accessBase = {
+						key,
+						source: observedSource,
+						get: () => observedSource.get(key) as SourceValue,
+						set: (value: SourceValue) => {
+							observedSource.set(key, value)
+							return true
+						},
+						old: previous,
+					} as ProjectAccess<SourceValue, Key, Register<SourceValue, Key>, Map<Key, ResultValue>>
+					defineAccessValue(accessBase)
+					const produced = apply(accessBase, target)
+					target.set(key, produced)
+				})
+				keyEffects.set(key, stop)
+			})
+		}
+
+		for (const key of Array.from(keyEffects.keys())) if (!keys.has(key)) disposeKey(key)
+	})
+
+	return makeCleanup(target, keyEffects, () => cleanupKeys())
+}
+
+function projectRecord<Source extends Record<PropertyKey, any>, ResultValue>(
+	source: Source,
+	apply: ProjectCallback<
+		Source[keyof Source],
+		keyof Source,
+		Record<keyof Source, ResultValue>,
+		Source,
+		ResultValue
+	>
+): ProjectResult<Record<keyof Source, ResultValue>> {
+	const observedSource = reactive(source) as Source
+	const target = reactive({} as Record<keyof Source, ResultValue>)
+	const keyEffects = new Map<PropertyKey, ScopedCallback>()
+
+	function disposeKey(key: PropertyKey) {
+		const stopEffect = keyEffects.get(key)
+		if (stopEffect) {
+			stopEffect()
+			keyEffects.delete(key)
+			Reflect.deleteProperty(target as Record<PropertyKey, unknown>, key)
+		}
+	}
+
+	const cleanupKeys = effect(function projectRecordEffect({ ascend }) {
+		const keys = new Set<PropertyKey>()
+		for (const key in observedSource) keys.add(key)
+		const observed = Reflect.ownKeys(observedSource)
+		for (const key of observed) keys.add(key)
+
+		for (const key of keys) {
+			if (keyEffects.has(key)) continue
+			ascend(() => {
+				const stop = effect(function projectRecordKeyEffect() {
+					const sourceKey = key as keyof Source
+					const previous = untracked(
+						() => (target as Record<PropertyKey, ResultValue | undefined>)[key]
+					)
+					const accessBase = {
+						key: sourceKey,
+						source: observedSource,
+						get: () => ReflectGet(observedSource, sourceKey, observedSource),
+						set: (value: Source[typeof sourceKey]) =>
+							ReflectSet(observedSource, sourceKey, value, observedSource),
+						old: previous,
+					} as ProjectAccess<
+						Source[typeof sourceKey],
+						keyof Source,
+						Source,
+						Record<keyof Source, ResultValue>
+					>
+					defineAccessValue(accessBase)
+					const produced = apply(accessBase, target)
+					;(target as any)[sourceKey] = produced
+				})
+				keyEffects.set(key, stop)
+			})
+		}
+
+		for (const key of Array.from(keyEffects.keys())) if (!keys.has(key)) disposeKey(key)
+	})
+
+	return makeCleanup(target, keyEffects, () => cleanupKeys())
+}
+
+function projectMap<Key, Value, ResultValue>(
+	source: Map<Key, Value>,
+	apply: ProjectCallback<Value, Key, Map<Key, ResultValue>, Map<Key, Value>, ResultValue>
+): ProjectResult<Map<Key, ResultValue>> {
+	const observedSource = reactive(source) as Map<Key, Value>
+	const rawTarget = new Map<Key, ResultValue>()
+	const target = reactive(rawTarget) as Map<Key, ResultValue>
+	const keyEffects = new Map<Key, ScopedCallback>()
+
+	function disposeKey(key: Key) {
+		const stopEffect = keyEffects.get(key)
+		if (stopEffect) {
+			stopEffect()
+			keyEffects.delete(key)
+			target.delete(key)
+		}
+	}
+
+	const cleanupKeys = effect(function projectMapEffect({ ascend }) {
+		const keys = new Set<Key>()
+		for (const key of observedSource.keys()) keys.add(key)
+
+		for (const key of keys) {
+			if (keyEffects.has(key)) continue
+			ascend(() => {
+				const stop = effect(function projectMapKeyEffect() {
+					const previous = untracked(() => target.get(key))
+					const accessBase = {
+						key,
+						source: observedSource,
+						get: () => observedSource.get(key) as Value,
+						set: (value: Value) => {
+							observedSource.set(key, value)
+							return true
+						},
+						old: previous,
+					} as ProjectAccess<Value, Key, Map<Key, Value>, Map<Key, ResultValue>>
+					defineAccessValue(accessBase)
+					const produced = apply(accessBase, target)
+					target.set(key, produced)
+				})
+				keyEffects.set(key, stop)
+			})
+		}
+
+		for (const key of Array.from(keyEffects.keys())) if (!keys.has(key)) disposeKey(key)
+	})
+
+	return makeCleanup(target, keyEffects, () => cleanupKeys())
+}
+
+type ProjectOverload = {
+	<SourceValue, ResultValue>(
+		source: readonly SourceValue[],
+		apply: ProjectCallback<SourceValue, number, ResultValue[], readonly SourceValue[], ResultValue>
+	): ProjectResult<ResultValue[]>
+	<Key extends PropertyKey, SourceValue, ResultValue>(
+		source: Register<SourceValue, Key>,
+		apply: ProjectCallback<
+			SourceValue,
+			Key,
+			Map<Key, ResultValue>,
+			Register<SourceValue, Key>,
+			ResultValue
+		>
+	): ProjectResult<Map<Key, ResultValue>>
+	<Source extends Record<PropertyKey, any>, ResultValue>(
+		source: Source,
+		apply: ProjectCallback<
+			Source[keyof Source],
+			keyof Source,
+			Record<keyof Source, ResultValue>,
+			Source,
+			ResultValue
+		>
+	): ProjectResult<Record<keyof Source, ResultValue>>
+	<Key, Value, ResultValue>(
+		source: Map<Key, Value>,
+		apply: ProjectCallback<Value, Key, Map<Key, ResultValue>, Map<Key, Value>, ResultValue>
+	): ProjectResult<Map<Key, ResultValue>>
+	array: typeof projectArray
+	register: typeof projectRegister
+	record: typeof projectRecord
+	map: typeof projectMap
+}
+
+function projectCore(source: any, apply: any): ProjectResult<any> {
+	if (Array.isArray(source)) return projectArray(source, apply)
+	if (source instanceof Map) return projectMap(source, apply)
+	if (source instanceof Register) return projectRegister(source, apply)
+	if (source && (source.constructor === Object || source.constructor === undefined))
+		return projectRecord(source, apply)
+	throw new Error('Unsupported source type')
+}
+
+export const project: ProjectOverload = Object.assign(projectCore, {
+	array: projectArray,
+	register: projectRegister,
+	record: projectRecord,
+	map: projectMap,
+})

package/src/reactive/proxy-state.ts

@@ -0,0 +1,27 @@
+export const objectToProxy = new WeakMap<object, object>()
+export const proxyToObject = new WeakMap<object, object>()
+
+export function storeProxyRelationship(target: object, proxy: object) {
+	objectToProxy.set(target, proxy)
+	proxyToObject.set(proxy, target)
+}
+
+export function getExistingProxy<T extends object>(target: T): T | undefined {
+	return objectToProxy.get(target) as T | undefined
+}
+
+export function trackProxyObject(proxy: object, target: object) {
+	proxyToObject.set(proxy, target)
+}
+
+export function unwrap<T>(obj: T): T {
+	let current = obj
+	while (current && typeof current === 'object' && current !== null && proxyToObject.has(current)) {
+		current = proxyToObject.get(current) as T
+	}
+	return current
+}
+
+export function isReactive(obj: any): boolean {
+	return proxyToObject.has(obj)
+}