mutts 1.0.2 → 1.0.4

package/src/reactive/proxy.ts

@@ -0,0 +1,289 @@
+import { decorator } from '../decorator'
+import { mixin } from '../mixins'
+import { isOwnAccessor, ReflectGet, ReflectSet } from '../utils'
+import { touched1 } from './change'
+import { notifyPropertyChange } from './deep-touch'
+import {
+	addBackReference,
+	bubbleUpChange,
+	needsBackReferences,
+	objectsWithDeepWatchers,
+	removeBackReference,
+} from './deep-watch-state'
+import { withEffect } from './effect-context'
+import { absent, isNonReactive } from './non-reactive-state'
+import {
+	getExistingProxy,
+	proxyToObject,
+	storeProxyRelationship,
+	trackProxyObject,
+	unwrap,
+} from './proxy-state'
+import { dependant } from './tracking'
+import {
+	allProps,
+	nativeReactive,
+	nonReactiveMark,
+	options,
+	prototypeForwarding,
+	ReactiveError,
+	ReactiveErrorCode,
+	unreactiveProperties,
+} from './types'
+
+const hasReentry: any[] = []
+const reactiveHandlers = {
+	[Symbol.toStringTag]: 'MutTs Reactive',
+	get(obj: any, prop: PropertyKey, receiver: any) {
+		if (prop === nonReactiveMark) return false
+		const unwrappedObj = unwrap(obj)
+		// Check if this property is marked as unreactive
+		if (unwrappedObj[unreactiveProperties]?.has(prop) || typeof prop === 'symbol')
+			return ReflectGet(obj, prop, receiver)
+
+		// Special-case: array wrappers use prototype forwarding + numeric accessors.
+		// With options.instanceMembers=true, inherited reads are normally not tracked, which breaks
+		// reactivity for array indices/length (they appear inherited on the proxy).
+		const isArrayCase =
+			prototypeForwarding in obj &&
+			// biome-ignore lint/suspicious/useIsArray: This is the whole point here
+			obj[prototypeForwarding] instanceof Array &&
+			typeof prop === 'string' &&
+			(prop === 'length' || !Number.isNaN(Number(prop)))
+		if (isArrayCase) {
+			dependant(obj, prop === 'length' ? 'length' : Number(prop))
+		}
+		// Check if property exists and if it's an own property (cached for later use)
+		const hasProp = Reflect.has(receiver, prop)
+		const isOwnProp = hasProp && Object.hasOwn(receiver, prop)
+		const isInheritedAccess = hasProp && !isOwnProp
+
+		// For accessor properties, check the unwrapped object to see if it's an accessor
+		// This ensures ignoreAccessors works correctly even after operations like Object.setPrototypeOf
+		const shouldIgnoreAccessor =
+			options.ignoreAccessors &&
+			isOwnProp &&
+			(isOwnAccessor(receiver, prop) || isOwnAccessor(unwrappedObj, prop))
+
+		// Depend if...
+		if (
+			!hasProp ||
+			(!(options.instanceMembers && isInheritedAccess && obj instanceof Object) &&
+				!shouldIgnoreAccessor)
+		)
+			dependant(obj, prop)
+
+		// Watch the whole prototype chain when requested or for null-proto objects
+		if (isInheritedAccess && (!options.instanceMembers || !(obj instanceof Object))) {
+			let current = reactiveObject(Object.getPrototypeOf(obj))
+			while (current && current !== Object.prototype) {
+				dependant(current, prop)
+				if (Object.hasOwn(current, prop)) break
+				let next = reactiveObject(Object.getPrototypeOf(current))
+				if (next === current) {
+					next = reactiveObject(Object.getPrototypeOf(unwrap(current)))
+				}
+				current = next
+			}
+		}
+		const value = ReflectGet(obj, prop, receiver)
+		if (typeof value === 'object' && value !== null) {
+			const reactiveValue = reactiveObject(value)
+
+			// Only create back-references if this object needs them
+			if (needsBackReferences(obj)) {
+				addBackReference(reactiveValue, obj, prop)
+			}
+
+			return reactiveValue
+		}
+		return value
+	},
+	set(obj: any, prop: PropertyKey, value: any, receiver: any): boolean {
+		// Read old value directly from unwrapped object to avoid triggering dependency tracking
+		const unwrappedObj = unwrap(obj)
+		const unwrappedReceiver = unwrap(receiver)
+
+		// Check if this property is marked as unreactive
+		if (unwrappedObj[unreactiveProperties]?.has(prop) || unwrappedObj !== unwrappedReceiver)
+			return ReflectSet(obj, prop, value, receiver)
+		// Really specific case for when Array is forwarder, in order to let it manage the reactivity
+		const isArrayCase =
+			prototypeForwarding in obj &&
+			// biome-ignore lint/suspicious/useIsArray: This is the whole point here
+			obj[prototypeForwarding] instanceof Array &&
+			(!Number.isNaN(Number(prop)) || prop === 'length')
+		const newValue = unwrap(value)
+
+		if (isArrayCase) {
+			;(obj as any)[prop] = newValue
+			return true
+		}
+		// Read old value, using withEffect(undefined, ...) for getter-only accessors to avoid
+		// breaking memoization dependency tracking during SET operations
+		let oldVal = absent
+		if (Reflect.has(unwrappedReceiver, prop)) {
+			// Check descriptor on both receiver and target to handle proxy cases
+			const receiverDesc = Object.getOwnPropertyDescriptor(unwrappedReceiver, prop)
+			const targetDesc = Object.getOwnPropertyDescriptor(unwrappedObj, prop)
+			const desc = receiverDesc || targetDesc
+			// If it's a getter-only accessor (has getter but no setter), read without tracking
+			// to avoid breaking memoization invalidation when the getter calls memoized functions
+			if (desc?.get && !desc?.set) {
+				oldVal = withEffect(undefined, () => Reflect.get(unwrappedObj, prop, unwrappedReceiver))
+			} else {
+				oldVal = Reflect.get(unwrappedObj, prop, unwrappedReceiver)
+			}
+		}
+		if (objectsWithDeepWatchers.has(obj)) {
+			if (typeof oldVal === 'object' && oldVal !== null) {
+				removeBackReference(oldVal, obj, prop)
+			}
+			if (typeof newValue === 'object' && newValue !== null) {
+				const reactiveValue = reactiveObject(newValue)
+				addBackReference(reactiveValue, obj, prop)
+			}
+		}
+
+		if (oldVal !== newValue) {
+			// For getter-only accessors, Reflect.set() may fail, but we still return true
+			// to avoid throwing errors. Only proceed with change notifications if set succeeded.
+			if (ReflectSet(obj, prop, newValue, receiver)) {
+				notifyPropertyChange(obj, prop, oldVal, newValue, oldVal !== absent)
+			}
+		}
+		return true
+	},
+	has(obj: any, prop: PropertyKey): boolean {
+		if (hasReentry.includes(obj))
+			throw new ReactiveError(
+				`[reactive] Circular dependency detected in 'has' check for property '${String(prop)}'`,
+				{
+					code: ReactiveErrorCode.CycleDetected,
+					cycle: [], // We don't have the full cycle here, but we know it involves obj
+				}
+			)
+		hasReentry.push(obj)
+		dependant(obj, prop)
+		const rv = Reflect.has(obj, prop)
+		hasReentry.pop()
+		return rv
+	},
+	deleteProperty(obj: any, prop: PropertyKey): boolean {
+		if (!Object.hasOwn(obj, prop)) return false
+
+		const oldVal = (obj as any)[prop]
+
+		// Remove back-references if this object has deep watchers
+		if (objectsWithDeepWatchers.has(obj) && typeof oldVal === 'object' && oldVal !== null) {
+			removeBackReference(oldVal, obj, prop)
+		}
+
+		delete (obj as any)[prop]
+		touched1(obj, { type: 'del', prop }, prop)
+
+		// Bubble up changes if this object has deep watchers
+		if (objectsWithDeepWatchers.has(obj)) {
+			bubbleUpChange(obj, { type: 'del', prop })
+		}
+
+		return true
+	},
+	getPrototypeOf(obj: any): object | null {
+		if (prototypeForwarding in obj) return obj[prototypeForwarding]
+		return Object.getPrototypeOf(obj)
+	},
+	setPrototypeOf(obj: any, proto: object | null): boolean {
+		if (prototypeForwarding in obj) return false
+		Object.setPrototypeOf(obj, proto)
+		return true
+	},
+	ownKeys(obj: any): (string | symbol)[] {
+		dependant(obj, allProps)
+		return Reflect.ownKeys(obj)
+	},
+} as const
+
+const reactiveClasses = new WeakSet<Function>()
+
+// Create the ReactiveBase mixin
+/**
+ * Base mixin for reactive classes that provides proper constructor reactivity
+ * Solves constructor reactivity issues in complex inheritance trees
+ */
+export const ReactiveBase = mixin((base) => {
+	class ReactiveMixin extends base {
+		constructor(...args: any[]) {
+			super(...args)
+			// Only apply reactive transformation if the class is marked with @reactive
+			// This allows the mixin to work properly with method inheritance
+			// biome-ignore lint/correctness/noConstructorReturn: This is the whole point here
+			return reactiveClasses.has(new.target) ? reactive(this) : this
+		}
+	}
+	return ReactiveMixin
+})
+function reactiveObject<T>(anyTarget: T): T {
+	if (!anyTarget || typeof anyTarget !== 'object') return anyTarget
+	const target = anyTarget as any
+	// If target is already a proxy, return it
+	if (isNonReactive(target)) return target as T
+	const isProxy = proxyToObject.has(target)
+	if (isProxy) return target as T
+
+	// If we already have a proxy for this object, return it (optimized: get returns undefined if not found)
+	const existing = getExistingProxy(target)
+	if (existing !== undefined) return existing as T
+
+	const proxied =
+		nativeReactive in target && !(target instanceof target[nativeReactive])
+			? new target[nativeReactive](target)
+			: target
+	if (proxied !== target) trackProxyObject(proxied, target)
+	const proxy = new Proxy(proxied, reactiveHandlers)
+
+	// Store the relationships
+	storeProxyRelationship(target, proxy)
+	return proxy as T
+}
+
+/**
+ * Main decorator for making classes reactive
+ * Automatically makes class instances reactive when created
+ */
+export const reactive = decorator({
+	class(original) {
+		if (original.prototype instanceof ReactiveBase) {
+			reactiveClasses.add(original)
+			return original
+		}
+
+		class Reactive extends original {
+			constructor(...args: any[]) {
+				super(...args)
+				if (new.target !== Reactive && !reactiveClasses.has(new.target))
+					options.warn(
+						`${(original as any).name} has been inherited by ${this.constructor.name} that is not reactive.
+@reactive decorator must be applied to the leaf class OR classes have to extend ReactiveBase.`
+					)
+				// biome-ignore lint/correctness/noConstructorReturn: This is the whole point here
+				return reactive(this)
+			}
+		}
+		Object.defineProperty(Reactive, 'name', {
+			value: `Reactive<${original.name}>`,
+		})
+		return Reactive as any
+	},
+	get(original: any) {
+		return reactiveObject(original)
+	},
+	default: reactiveObject,
+})
+
+/**
+ * Gets the original, non-reactive object from a reactive proxy
+ * @param proxy - The reactive proxy
+ * @returns The original object
+ */
+export { isReactive, objectToProxy, proxyToObject, unwrap } from './proxy-state'

package/src/reactive/record.ts

@@ -0,0 +1,196 @@
+import { ReflectGet, ReflectSet } from '../utils'
+import { touched1 } from './change'
+import { effect } from './effects'
+import { cleanedBy, cleanup } from './interface'
+import { reactive } from './proxy'
+import { type ScopedCallback } from './types'
+
+/**
+ * Provides type-safe access to a source object's property within the organized callback.
+ * @template Source - The type of the source object
+ * @template Key - The type of the property key in the source object
+ */
+export type OrganizedAccess<Source extends Record<PropertyKey, any>, Key extends keyof Source> = {
+	/** The property key being accessed */
+	readonly key: Key
+
+	/**
+	 * Gets the current value of the property from the source object
+	 * @returns The current value of the property
+	 */
+	get(): Source[Key]
+
+	/**
+	 * Updates the property value in the source object
+	 * @param value - The new value to set
+	 * @returns {boolean} True if the update was successful
+	 */
+	set(value: Source[Key]): boolean
+
+	/**
+	 * The current value of the property (equivalent to using get()/set() directly)
+	 */
+	value: Source[Key]
+}
+
+/**
+ * Callback function type for the organized function that processes each source property.
+ * @template Source - The type of the source object
+ * @template Target - The type of the target object
+ */
+export type OrganizedCallback<Source extends Record<PropertyKey, any>, Target extends object> = <
+	Key extends keyof Source,
+>(
+	/**
+	 * Accessor object for the current source property
+	 */
+	access: OrganizedAccess<Source, Key>,
+
+	/**
+	 * The target object where organized data will be stored
+	 */
+	target: Target
+) => ScopedCallback | undefined
+
+/**
+ * The result type of the organized function, combining the target object with cleanup capability.
+ * @template Target - The type of the target object
+ */
+export type OrganizedResult<Target extends object> = Target & {
+	/**
+	 * Cleanup function to dispose of all reactive bindings created by organized().
+	 * This is automatically called when the effect that created the organized binding is disposed.
+	 */
+	[cleanup]: ScopedCallback
+}
+
+/**
+ * Organizes a source object's properties into a target object using a callback function.
+ * This creates a reactive mapping between source properties and a target object,
+ * automatically handling property additions, updates, and removals.
+ *
+ * @template Source - The type of the source object
+ * @template Target - The type of the target object (defaults to Record<PropertyKey, any>)
+ *
+ * @param {Source} source - The source object to organize
+ * @param {OrganizedCallback<Source, Target>} apply - Callback function that defines how each source property is mapped to the target
+ * @param {Target} [baseTarget={}] - Optional base target object to use (will be made reactive if not already)
+ *
+ * @returns {OrganizedResult<Target>} The target object with cleanup capability
+ *
+ * @example
+ * // Organize user permissions into role-based access
+ * const user = reactive({ isAdmin: true, canEdit: false });
+ * const permissions = organized(
+ *   user,
+ *   (access, target) => {
+ *     if (access.key === 'isAdmin') {
+ *       target.hasFullAccess = access.value;
+ *     }
+ *     target[`can${access.key.charAt(0).toUpperCase() + access.key.slice(1)}`] = access.value;
+ *   }
+ * );
+ *
+ * @example
+ * // Transform object structure with cleanup
+ * const source = reactive({ firstName: 'John', lastName: 'Doe' });
+ * const formatted = organized(
+ *   source,
+ *   (access, target) => {
+ *     if (access.key === 'firstName' || access.key === 'lastName') {
+ *       target.fullName = `${source.firstName} ${source.lastName}`.trim();
+ *     }
+ *   }
+ * );
+ *
+ * @example
+ * // Using with cleanup in a component
+ * effect(() => {
+ *   const data = fetchData();
+ *   const organizedData = organized(data, (access, target) => {
+ *     // Transform data
+ *   });
+ *
+ *   // The cleanup will be called automatically when the effect is disposed
+ *   return () => organizedData[cleanup]();
+ * });
+ */
+export function organized<
+	Source extends Record<PropertyKey, any>,
+	Target extends object = Record<PropertyKey, any>,
+>(
+	source: Source,
+	apply: OrganizedCallback<Source, Target>,
+	baseTarget: Target = {} as Target
+): OrganizedResult<Target> {
+	const observedSource = reactive(source) as Source
+	const target = reactive(baseTarget) as Target
+	const keyEffects = new Map<PropertyKey, ScopedCallback>()
+
+	function disposeKey(key: PropertyKey) {
+		const stopEffect = keyEffects.get(key)
+		if (stopEffect) {
+			keyEffects.delete(key)
+			stopEffect()
+		}
+	}
+
+	const cleanupKeys = effect(function organizedKeysEffect({ ascend }) {
+		//const keys = Reflect.ownKeys(observedSource) as PropertyKey[]
+		const keys = new Set<PropertyKey>()
+		for (const key in observedSource) keys.add(key)
+
+		for (const key of keys) {
+			if (keyEffects.has(key)) continue
+			ascend(() => {
+				const stop = effect(function organizedKeyEffect() {
+					const sourceKey = key as keyof Source
+					const accessBase = {
+						key: sourceKey,
+						get: () => ReflectGet(observedSource, sourceKey, observedSource),
+						set: (value: Source[typeof sourceKey]) =>
+							ReflectSet(observedSource, sourceKey, value, observedSource),
+					}
+					Object.defineProperty(accessBase, 'value', {
+						get: accessBase.get,
+						set: accessBase.set,
+						configurable: true,
+						enumerable: true,
+					})
+					return apply(accessBase as OrganizedAccess<Source, typeof sourceKey>, target)
+				})
+				keyEffects.set(key, stop)
+			})
+		}
+
+		for (const key of Array.from(keyEffects.keys())) if (!keys.has(key)) disposeKey(key)
+	})
+
+	return cleanedBy(target, () => {
+		cleanupKeys()
+		for (const key of Array.from(keyEffects.keys())) disposeKey(key)
+	}) as OrganizedResult<Target>
+}
+
+/**
+ * Organizes a property on a target object
+ * Shortcut for defineProperty/delete with touched signal
+ * @param target - The target object
+ * @param property - The property to organize
+ * @param access - The access object
+ * @returns The property descriptor
+ */
+export function organize<T>(
+	target: object,
+	property: PropertyKey,
+	access: { get?(): T; set?(value: T): boolean }
+) {
+	Object.defineProperty(target, property, {
+		get: access.get,
+		set: access.set,
+		configurable: true,
+		enumerable: true,
+	})
+	touched1(target, { type: 'set', prop: property }, property)
+	return () => delete (target as any)[property]
+}