aberdeen 1.0.13 → 1.2.0

package/src/aberdeen.ts

@@ -166,7 +166,7 @@ abstract class Scope implements QueueRunner {
 
 	[ptr: ReverseSortedSetPointer]: this;
 
-	abstract onChange(index: any, newData: any, oldData: any): void;
+	abstract onChange(index: any): void;
 	abstract queueRun(): void;
 
 	abstract getLastNode(): Node | undefined;
@@ -245,7 +245,7 @@ abstract class ContentScope extends Scope {
 		return this.getLastNode() || this.getPrecedingNode();
 	}
 
-	onChange(index: any, newData: any, oldData: any) {
+	onChange() {
 		queue(this);
 	}
 
@@ -451,43 +451,6 @@ class SetArgScope extends ChainedScope {
 	}
 }
 
-let immediateQueue: ReverseSortedSet<Scope, "prio"> = new ReverseSortedSet(
-	"prio",
-);
-
-class ImmediateScope extends RegularScope {
-	onChange(index: any, newData: any, oldData: any) {
-		immediateQueue.add(this);
-	}
-}
-
-let immediateQueueRunning = false;
-function runImmediateQueue() {
-	for (
-		let count = 0;
-		!immediateQueue.isEmpty() && !immediateQueueRunning;
-		count++
-	) {
-		if (count > 42) {
-			immediateQueue.clear();
-			throw new Error("Too many immediate-mode recursive updates");
-		}
-		immediateQueueRunning = true;
-		const copy = immediateQueue;
-		immediateQueue = new ReverseSortedSet("prio");
-		try {
-			for (const scope of copy) {
-				// On exception, the exception will be bubbled up to the call site, discarding any
-				// remaining immediate scopes from the queue. This behavior is perhaps debatable,
-				// but getting a synchronous exception at the call site can be very helpful.
-				scope.queueRun();
-			}
-		} finally {
-			immediateQueueRunning = false;
-		}
-	}
-}
-
 /** @internal */
 class OnEachScope extends Scope {
 	// biome-ignore lint/correctness/noInvalidUseBeforeDeclaration: circular, as currentScope is initialized with a Scope
@@ -528,15 +491,11 @@ class OnEachScope extends Scope {
 		// Do _addChild() calls for initial items
 		if (target instanceof Array) {
 			for (let i = 0; i < target.length; i++) {
-				if (target[i] !== undefined) {
-					new OnEachItemScope(this, i, false);
-				}
+				new OnEachItemScope(this, i, false);
 			}
 		} else {
-			for (const [key, value] of getEntries(target)) {
-				if (value !== undefined) {
-					new OnEachItemScope(this, key, false);
-				}
+			for (const key of (target instanceof Map ? target.keys() : Object.keys(target))) {
+				new OnEachItemScope(this, key, false);
 			}
 		}
 	}
@@ -545,7 +504,7 @@ class OnEachScope extends Scope {
 		return findLastNodeInPrevSiblings(this.prevSibling);
 	}
 
-	onChange(index: any, newData: any, oldData: any) {
+	onChange(index: any) {
 		if (!(this.target instanceof Array) || typeof index === "number")
 			this.changedIndexes.add(index);
 		queue(this);
@@ -558,17 +517,12 @@ class OnEachScope extends Scope {
 			const oldScope = this.byIndex.get(index);
 			if (oldScope) oldScope.remove();
 
-			let hasValue;
-			if (this.target instanceof Map) {
-				hasValue = this.target.has(index);
+			if (this.target instanceof Map ? this.target.has(index) : index in this.target) {
+				// Item still exists
+				new OnEachItemScope(this, index, true);
 			} else {
-				hasValue = (this.target as any)[index] !== undefined;
-			}
-
-			if (!hasValue) {
+				// Item has disappeared
 				this.byIndex.delete(index);
-			} else {
-				new OnEachItemScope(this, index, true);
 			}
 		}
 		topRedrawScope = undefined;
@@ -774,6 +728,23 @@ function addNode(node: Node) {
 const ROOT_SCOPE = new RootScope();
 let currentScope: ContentScope = ROOT_SCOPE;
 
+/**
+ * Execute a function in a never-cleaned root scope. Even {@link unmountAll} will not
+ * clean up observers/nodes created by the function.
+ * @param func The function to execute.
+ * @returns The return value of the function.
+ * @internal
+ */
+export function leakScope<T>(func: () => T): T {
+	const savedScope = currentScope;
+	currentScope = new RootScope();
+	try {
+		return func();
+	} finally {
+		currentScope = savedScope;
+	}
+}
+
 /**
  * A special Node observer index to subscribe to any value in the map changing.
  */
@@ -925,10 +896,12 @@ export function onEach(
 }
 
 function isObjEmpty(obj: object): boolean {
-	for (const k in obj) return false;
+	for (const k of Object.keys(obj)) return false;
 	return true;
 }
 
+const EMPTY = Symbol("empty");
+
 /**
  * Reactively checks if an observable array or object is empty.
  *
@@ -938,7 +911,7 @@ function isObjEmpty(obj: object): boolean {
  * is deleted from an object), the scope that called `isEmpty` will be automatically
  * scheduled for re-evaluation.
  *
- * @param proxied The observable array or object (obtained via `observe()`) to check.
+ * @param proxied The observable array or object to check.
  * @returns `true` if the array has length 0 or the object has no own enumerable properties, `false` otherwise.
  *
  * @example
@@ -981,7 +954,7 @@ export function isEmpty(proxied: TargetType): boolean {
 	
 	const result = isObjEmpty(target);
 	subscribe(target, ANY_SYMBOL, (index: any, newData: any, oldData: any) => {
-		if (result ? oldData === undefined : newData === undefined) queue(scope);
+		if (result ? oldData === EMPTY : newData === EMPTY) queue(scope);
 	});
 	return result;
 }
@@ -1006,8 +979,8 @@ export interface ValueRef<T> {
  * $('div', {text: cnt});
  * // <div>2</div>
 
- * // Or we can use it in an {@link observe} function:
- * observe(() => console.log("The count is now", cnt.value));
+ * // Or we can use it in an {@link derive} function:
+ * $(() => console.log("The count is now", cnt.value));
  * // The count is now 2
  * 
  * // Adding/removing items will update the count
@@ -1023,7 +996,7 @@ export function count(proxied: TargetType): ValueRef<number> {
 
 	const target = (proxied as any)[TARGET_SYMBOL] || proxied;
 	let cnt = 0;
-	for (const k in target) if (target[k] !== undefined) cnt++;
+	for (const k of Object.keys(target)) if (target[k] !== undefined) cnt++;
 
 	const result = proxy(cnt);
 	subscribe(
@@ -1031,8 +1004,8 @@ export function count(proxied: TargetType): ValueRef<number> {
 		ANY_SYMBOL,
 		(index: any, newData: any, oldData: any) => {
 			if (oldData === newData) {
-			} else if (oldData === undefined) result.value = ++cnt;
-			else if (newData === undefined) result.value = --cnt;
+			} else if (oldData === EMPTY) result.value = ++cnt;
+			else if (newData === EMPTY) result.value = --cnt;
 		},
 	);
 
@@ -1058,7 +1031,7 @@ export function defaultEmitHandler(
 		if (byIndex) {
 			for (const observer of byIndex) {
 				if (typeof observer === "function") observer(index, newData, oldData);
-				else observer.onChange(index, newData, oldData);
+				else observer.onChange(index);
 			}
 		}
 	}
@@ -1075,25 +1048,22 @@ const objectHandler: ProxyHandler<any> = {
 		// Make sure newData is unproxied
 		if (typeof newData === "object" && newData)
 			newData = (newData as any)[TARGET_SYMBOL] || newData;
-		const oldData = target[prop];
+		const oldData = target.hasOwnProperty(prop) ? target[prop] : EMPTY;
 		if (newData !== oldData) {
 			target[prop] = newData;
 			emit(target, prop, newData, oldData);
-			runImmediateQueue();
 		}
 		return true;
 	},
 	deleteProperty(target: any, prop: any) {
-		const old = target[prop];
+		const old = target.hasOwnProperty(prop) ? target[prop] : EMPTY;
 		delete target[prop];
-		emit(target, prop, undefined, old);
-		runImmediateQueue();
+		emit(target, prop, EMPTY, old);
 		return true;
 	},
 	has(target: any, prop: any) {
-		const result = prop in target;
 		subscribe(target, prop);
-		return result;
+		return target.hasOwnProperty(prop);
 	},
 	ownKeys(target: any) {
 		subscribe(target, ANY_SYMBOL);
@@ -1103,9 +1073,11 @@ const objectHandler: ProxyHandler<any> = {
 
 function arraySet(target: any, prop: any, newData: any) {
 	// Make sure newData is unproxied
-	if (typeof newData === "object" && newData)
+	if (typeof newData === "object" && newData) {
 		newData = (newData as any)[TARGET_SYMBOL] || newData;
-	const oldData = target[prop];
+	}
+	let oldData = target[prop];
+	if (oldData === undefined && !target.hasOwnProperty(prop)) oldData = EMPTY;
 	if (newData !== oldData) {
 		const oldLength = target.length;
 
@@ -1114,11 +1086,13 @@ function arraySet(target: any, prop: any, newData: any) {
 
 			// We only need to emit for shrinking, as growing just adds undefineds
 			for (let i = newData; i < oldLength; i++) {
-				emit(target, i, undefined, target[i]);
+				emit(target, i, EMPTY, target[i]);
 			}
 		} else {
-			const intProp = Number.parseInt(prop);
-			if (intProp.toString() === prop) prop = intProp;
+			if (typeof prop === 'string') { // Convert to int when possible
+				const n = 0|prop as any;
+				if (String(n) === prop && n >= 0) prop = n;
+			}
 
 			target[prop] = newData;
 			emit(target, prop, newData, oldData);
@@ -1126,7 +1100,6 @@ function arraySet(target: any, prop: any, newData: any) {
 		if (target.length !== oldLength) {
 			emit(target, "length", target.length, oldLength);
 		}
-		runImmediateQueue();
 	}
 	return true;
 }
@@ -1134,17 +1107,24 @@ function arraySet(target: any, prop: any, newData: any) {
 const arrayHandler: ProxyHandler<any[]> = {
 	get(target: any, prop: any) {
 		if (prop === TARGET_SYMBOL) return target;
-		let subProp = prop;
-		if (typeof prop !== "symbol") {
-			const intProp = Number.parseInt(prop);
-			if (intProp.toString() === prop) subProp = intProp;
+		if (typeof prop === 'string') { // Convert to int when possible
+			const n = 0|prop as any;
+			if (String(n) === prop && n >= 0) prop = n;
 		}
-		subscribe(target, subProp);
+		subscribe(target, prop);
 		return optProxy(target[prop]);
 	},
 	set: arraySet,
-	deleteProperty(target: any, prop: string | symbol) {
-		return arraySet(target, prop, undefined);
+	deleteProperty(target: any, prop: any) {
+		if (typeof prop === 'string') { // Convert to int when possible
+			const n = 0|prop as any;
+			if (String(n) === prop && n >= 0) prop = n;
+		}
+		let oldData = target[prop];
+		if (oldData === undefined && !target.hasOwnProperty(prop)) oldData = EMPTY;
+		delete target[prop];
+		emit(target, prop, EMPTY, oldData);
+		return true;
 	},
 };
 
@@ -1190,31 +1170,34 @@ const mapMethodHandlers = {
 	set(this: any, key: any, newData: any): any {
 		const target: Map<any, any> = this[TARGET_SYMBOL];
 		// Make sure key and newData are unproxied
-		if (typeof key === "object" && key)
+		if (typeof key === "object" && key) {
 			key = (key as any)[TARGET_SYMBOL] || key;
-		if (typeof newData === "object" && newData)
+		}
+		if (typeof newData === "object" && newData) {
 			newData = (newData as any)[TARGET_SYMBOL] || newData;
-		const oldData = target.get(key);
+		}
+		let oldData = target.get(key);
+		if (oldData === undefined && !target.has(key)) oldData = EMPTY;
 		if (newData !== oldData) {
 			const oldSize = target.size;
 			target.set(key, newData);
 			emit(target, key, newData, oldData);
 			emit(target, MAP_SIZE_SYMBOL, target.size, oldSize);
-			runImmediateQueue();
 		}
 		return this;
 	},
 	delete(this: any, key: any): boolean {
 		const target: Map<any, any> = this[TARGET_SYMBOL];
 		// Make sure key is unproxied
-		if (typeof key === "object" && key)
+		if (typeof key === "object" && key) {
 			key = (key as any)[TARGET_SYMBOL] || key;
-		const oldData = target.get(key);
+		}
+		let oldData = target.get(key);
+		if (oldData === undefined && !target.has(key)) oldData = EMPTY;
 		const result: boolean = target.delete(key);
 		if (result) {
-			emit(target, key, undefined, oldData);
+			emit(target, key, EMPTY, oldData);
 			emit(target, MAP_SIZE_SYMBOL, target.size, target.size + 1);
-			runImmediateQueue();
 		}
 		return result;
 	},
@@ -1222,18 +1205,17 @@ const mapMethodHandlers = {
 		const target: Map<any, any> = this[TARGET_SYMBOL];
 		const oldSize = target.size;
 		for (const key of target.keys()) {
-			const oldData = target.get(key);
-			emit(target, key, undefined, oldData);
+			emit(target, key, undefined, target.get(key));
 		}
 		target.clear();
 		emit(target, MAP_SIZE_SYMBOL, 0, oldSize);
-		runImmediateQueue();
 	},
 	has(this: any, key: any): boolean {
 		const target: Map<any, any> = this[TARGET_SYMBOL];
 		// Make sure key is unproxied
-		if (typeof key === "object" && key)
+		if (typeof key === "object" && key) {
 			key = (key as any)[TARGET_SYMBOL] || key;
+		}
 		subscribe(target, key);
 		return target.has(key);
 	},
@@ -1264,7 +1246,7 @@ const mapHandler: ProxyHandler<Map<any, any>> = {
 		if (prop === TARGET_SYMBOL) return target;
 		
 		// Handle Map methods using lookup object
-		if (prop in mapMethodHandlers) {
+		if (mapMethodHandlers.hasOwnProperty(prop)) {
 			return (mapMethodHandlers as any)[prop];
 		}
 		
@@ -1275,8 +1257,7 @@ const mapHandler: ProxyHandler<Map<any, any>> = {
 		}
 		
 		// Handle other properties normally
-		subscribe(target, prop);
-		return optProxy((target as any)[prop]);
+		return (target as any)[prop];
 	},
 };
 
@@ -1308,41 +1289,32 @@ function optProxy(value: any): any {
 	return proxied;
 }
 
-export function proxy<T extends any>(
-	target: Array<T>,
-): Array<
-	T extends number
-		? number
-		: T extends string
-			? string
-			: T extends boolean
-				? boolean
-				: T
->;
+interface PromiseProxy<T> {
+	busy: boolean;
+	error?: any;
+	value?: T;
+}
+
+export function proxy<T extends any>(target: Promise<T>): PromiseProxy<T>;
+export function proxy<T extends any>(target: Array<T>): Array<T extends number ? number : T extends string ? string : T extends boolean ? boolean : T >;
 export function proxy<T extends object>(target: T): T;
-export function proxy<T extends any>(
-	target: T,
-): ValueRef<
-	T extends number
-		? number
-		: T extends string
-			? string
-			: T extends boolean
-				? boolean
-				: T
->;
+export function proxy<T extends any>(target: T): ValueRef<T extends number ? number : T extends string ? string : T extends boolean ? boolean : T>;
 
 /**
  * Creates a reactive proxy around the given data.
  *
  * Reading properties from the returned proxy within a reactive scope (like one created by
- * {@link $} or {@link observe}) establishes a subscription. Modifying properties *through*
+ * {@link $} or {@link derive}) establishes a subscription. Modifying properties *through*
  * the proxy will notify subscribed scopes, causing them to re-execute.
  *
  * - Plain objects and arrays are wrapped in a standard JavaScript `Proxy` that intercepts
  *   property access and mutations, but otherwise works like the underlying data.
  * - Primitives (string, number, boolean, null, undefined) are wrapped in an object
  *   `{ value: T }` which is then proxied. Access the primitive via the `.value` property.
+ * - Promises are represented by proxied objects `{ busy: boolean, value?: T, error?: any }`.
+ *   Initially, `busy` is `true`. When the promise resolves, `value` is set and `busy`
+ *   is set to `false`. If the promise is rejected, `error` is set and `busy` is also
+ *   set to `false`.
  *
  * Use {@link unproxy} to get the original underlying data back.
  *
@@ -1353,23 +1325,23 @@ export function proxy<T extends any>(
  * @example Object
  * ```javascript
  * const state = proxy({ count: 0, message: 'Hello' });
- * observe(() => console.log(state.message)); // Subscribes to message
- * setTimeout(() => state.message = 'World', 1000); // Triggers the observe function
+ * $(() => console.log(state.message)); // Subscribes to message
+ * setTimeout(() => state.message = 'World', 1000); // Triggers the observing function
  * setTimeout(() => state.count++, 2000); // Triggers nothing
  * ```
  *
  * @example Array
  * ```javascript
  * const items = proxy(['a', 'b']);
- * observe(() => console.log(items.length)); // Subscribes to length
- * setTimeout(() => items.push('c'), 2000); // Triggers the observe function
+ * $(() => console.log(items.length)); // Subscribes to length
+ * setTimeout(() => items.push('c'), 2000); // Triggers the observing function
  * ```
  *
  * @example Primitive
  * ```javascript
  * const name = proxy('Aberdeen');
- * observe(() => console.log(name.value)); // Subscribes to value
- * setTimeout(() => name.value = 'UI', 2000); // Triggers the observe function
+ * $(() => console.log(name.value)); // Subscribes to value
+ * setTimeout(() => name.value = 'UI', 2000); // Triggers the observing function
  * ```
  *
  * @example Class instance
@@ -1380,12 +1352,27 @@ export function proxy<T extends any>(
  *   toString() { return `${this.name}Widget (${this.width}x${this.height})`; }
  * }
  * let graph: Widget = proxy(new Widget('Graph', 200, 100));
- * observe(() => console.log(''+graph));
+ * $(() => console.log(''+graph));
  * setTimeout(() => graph.grow(), 2000);
  * setTimeout(() => graph.grow(), 4000);
  * ```
  */
 export function proxy(target: TargetType): TargetType {
+	if (target instanceof Promise) {
+		const result: PromiseProxy<any> = optProxy({
+			busy: true,
+		});
+		target
+			.then((value) => {
+				result.value = value;
+				result.busy = false;
+			})
+			.catch((err) => {
+				result.error = err;
+				result.busy = false;
+			});
+		return result;
+	}
 	return optProxy(
 		typeof target === "object" && target !== null ? target : { value: target },
 	);
@@ -1453,12 +1440,9 @@ function destroyWithClass(element: Element, cls: string) {
  *
  * @param dst - The destination object/array/Map (proxied or unproxied).
  * @param src - The source object/array/Map (proxied or unproxied). It won't be modified.
- * @param flags - Bitmask controlling copy behavior:
- *   - {@link MERGE}: Performs a partial update. Properties in `dst` not present in `src` are kept.
- *     `null`/`undefined` in `src` delete properties in `dst`. Handles partial array updates via object keys.
- *   - {@link SHALLOW}: Performs a shallow copy; when an array/object of the right type doesn't exist in `dst` yet, a reference to the array/object in `src` will be made, instead of creating a copy. If the array/object already exists, it won't be replaced (by a reference), but all items will be individually checked and copied like normal, keeping changes (and therefore UI updates) to a minimum.
- * @template T - The type of the destination object.
- * @throws Error if attempting to copy an array into a non-array or vice versa (unless {@link MERGE} is set, allowing for sparse array updates).
+ * @template T - The type of the objects being copied.
+ * @returns `true` if any changes were made to `dst`, or `false` if not.
+ * @throws Error if attempting to copy an array into a non-array or vice versa.
  *
  * @example Basic Copy
  * ```typescript
@@ -1466,204 +1450,231 @@ function destroyWithClass(element: Element, cls: string) {
  * const dest = proxy({ b: { d: 3 } });
  * copy(dest, source);
  * console.log(dest); // proxy({ a: 1, b: { c: 2 } })
+ * copy(dest, 'b', { e: 4 });
+ * console.log(dest); // proxy({ a: 1, b: { e: 4 } })
  * ```
- *
- * @example Map to Object
- * ```typescript
- * const source = new Map([['x', 3], ['y', 4]]);
- * const dest = proxy({});
- * copy(dest, source);
- * console.log(dest); // proxy({ x: 3, y: 4 })
- * ```
- *
- * @example Object to Map
- * ```typescript
- * const source = { x: 3, y: 4 };
- * const dest = proxy(new Map());
- * copy(dest, source);
- * console.log(dest); // proxy(Map([['x', 3], ['y', 4]]))
- * ```
- *
- * @example MERGE
+ */
+
+export function copy<T extends object>(dst: T, src: T): boolean;
+/**
+ * Like above, but copies `src` into `dst[dstKey]`. This is useful if you're unsure if dst[dstKey]
+ * already exists (as the right type of object) or if you don't want to subscribe to dst[dstKey].
+ * 
+ * @param dstKey - Optional key in `dst` to copy into. 
+ */
+export function copy<T extends object>(dst: T, dstKey: keyof T, src: T[typeof dstKey]): boolean;
+export function copy(a: any, b: any, c?: any): boolean {
+	if (arguments.length > 2) return copySet(a, b, c, 0);
+	return copyImpl(a, b, 0);
+}
+
+function copySet(dst: any, dstKey: any, src: any, flags: number): boolean {
+	let dstVal = peek(dst, dstKey);
+	if (src === dstVal) return false;
+	if (typeof dstVal === "object" && dstVal && typeof src === "object" && src && dstVal.constructor === src.constructor) {
+		return copyImpl(dstVal, src, flags);
+	}
+	src = clone(src); 
+	if (dst instanceof Map) dst.set(dstKey, src);
+	else dst[dstKey] = clone(src);
+	return true;
+}
+
+/**
+ * Like {@link copy}, but uses merge semantics. Properties in `dst` not present in `src` are kept.
+ * `null`/`undefined` in `src` delete properties in `dst`.
+ * 
+ * When the destination is an object and the source is an array, its keys are used as (sparse) array indices.
+ * 
+ * @example Basic merge
  * ```typescript
  * const source = { b: { c: 99 }, d: undefined }; // d: undefined will delete
  * const dest = proxy({ a: 1, b: { x: 5 }, d: 4 });
- * copy(dest, source, MERGE);
- * console.log(dest); // proxy({ a: 1, b: { c: 99, x: 5 } })
+ * merge(dest, source);
+ * merge(dest, 'b', { y: 6 }); // merge into dest.b
+ * merge(dest, 'c', { z: 7 }); // merge.c doesn't exist yet, so it will just be assigned
+ * console.log(dest); // proxy({ a: 1, b: { c: 99, x: 5, y: 6 }, c: { z: 7 } })
  * ```
  *
- * @example Partial Array Update with MERGE
+ * @example Partial Array Merge
  * ```typescript
  * const messages = proxy(['msg1', 'msg2', 'msg3']);
  * const update = { 1: 'updated msg2' }; // Update using object key as index
- * copy(messages, update, MERGE);
+ * merge(messages, update);
  * console.log(messages); // proxy(['msg1', 'updated msg2', 'msg3'])
  * ```
  *
- * @example SHALLOW
- * ```typescript
- * const source = { nested: [1, 2] };
- * const dest = {};
- * copy(dest, source, SHALLOW);
- * dest.nested.push(3);
- * console.log(source.nested); // [1, 2, 3] (source was modified)
- * ```
  */
-
-// Overload for Map destination with object source
-export function copy<K, V>(dst: Map<K, V>, src: Record<K extends string | number | symbol ? K : never, V> | Partial<Record<K extends string | number | symbol ? K : never, V>>, flags?: number): void;
-// Overload for Map destination with Map source
-export function copy<K, V>(dst: Map<K, V>, src: Map<K, V> | Partial<Map<K, V>>, flags?: number): void;
-// Overload for object destination with Map source
-export function copy<T extends Record<string | number | symbol, any>>(dst: T, src: Map<keyof T, T[keyof T]>, flags?: number): void;
-// Overload for same-type copying
-export function copy<T extends object>(dst: T, src: Partial<T>, flags?: number): void;
-// Implementation
-export function copy(dst: any, src: any, flags = 0) {
-	copyRecurse(dst, src, flags);
-	runImmediateQueue();
+export function merge<T extends object>(dst: T, value: Partial<T>): boolean;
+export function merge<T extends object>(dst: T, dstKey: keyof T, value: Partial<T[typeof dstKey]>): boolean;
+export function merge(a: any, b: any, c?: any) {
+	if (arguments.length > 2) return copySet(a, b, c, MERGE);
+	return copyImpl(a, b, MERGE);
 }
-/** Flag to {@link copy} causing it to use merge semantics. See {@link copy} for details. */
-export const MERGE = 1;
-/** Flag to {@link copy} and {@link clone} causing them to create a shallow copy (instead of the deep copy done by default).*/
-export const SHALLOW = 2;
-const COPY_SUBSCRIBE = 32;
-const COPY_EMIT = 64;
 
-/**
- * Clone an (optionally proxied) object or array.
- *
- * @param src The object or array to clone. If it is proxied, `clone` will subscribe to any changes to the (nested) data structure.
- * @param flags
- *   - {@link SHALLOW}: Performs a shallow clone, meaning that only the top-level array or object will be copied, while object/array values will just be references to the original data in `src`.
- * @template T - The type of the objects being copied.
- * @returns A new unproxied array or object (of the same type as `src`), containing a deep (by default) copy of `src`.
- */
-export function clone<T extends object>(src: T, flags = 0): T {
-	let dst: T;
-	if (src instanceof Map) {
-		dst = new Map() as T;
-	} else {
-		dst = Object.create(Object.getPrototypeOf(src)) as T;
-	}
-	copyRecurse(dst, src, flags);
-	return dst;
-}
-
-function getEntries(subject: any) {
-	return (subject instanceof Map) ? subject.entries() : Object.entries(subject);
-}
-
-function getKeys(subject: any) {
-	return (subject instanceof Map) ? subject.keys() : Object.keys(subject);
-}
-
-function copyRecurse(dst: any, src: any, flags: number) {
+function copyImpl(dst: any, src: any, flags: number): boolean {
 	// We never want to subscribe to reads we do to the target (to find changes). So we'll
 	// take the unproxied version and `emit` updates ourselve.
-	let unproxied = dst[TARGET_SYMBOL];
+	let unproxied = (dst as any)[TARGET_SYMBOL];
 	if (unproxied) {
 		dst = unproxied;
 		flags |= COPY_EMIT;
 	}
 	// For performance, we'll work on the unproxied `src` and manually subscribe to changes.
-	unproxied = src[TARGET_SYMBOL];
+	unproxied = (src as any)[TARGET_SYMBOL];
 	if (unproxied) {
 		src = unproxied;
 		// If we're not in peek mode, we'll manually subscribe to all source reads.
 		if (currentScope !== ROOT_SCOPE && !peeking) flags |= COPY_SUBSCRIBE;
 	}
 
+	return copyRecursive(dst, src, flags);
+}
+
+// The dst and src parameters must be objects. Will throw a friendly message if they're not both the same type.
+function copyRecursive<T extends object>(dst: T, src: T, flags: number): boolean {
+
 	if (flags & COPY_SUBSCRIBE) subscribe(src, ANY_SYMBOL);
-	if (src instanceof Array) {
-		if (!(dst instanceof Array))
-			throw new Error("Cannot copy array into object");
+	let changed = false;
+
+	// The following loops are somewhat repetitive, but it keeps performance high by avoiding
+	// function calls and extra checks within the loops.
+
+	if (src instanceof Array && dst instanceof Array) {
 		const dstLen = dst.length;
 		const srcLen = src.length;
-		for (let i = 0; i < srcLen; i++) {
-			copyValue(dst, i, src[i], flags);
+		for (let index = 0; index < srcLen; index++) {
+			// changed = copyValue(dst, i, src[i], flags) || changed;
+
+			let dstValue = dst[index];
+			if (dstValue === undefined && !dst.hasOwnProperty(index)) dstValue = EMPTY;
+			let srcValue = src[index];
+			if (srcValue === undefined && !src.hasOwnProperty(index)) {
+				delete dst[index];
+				if (flags & COPY_EMIT) emit(dst, index, EMPTY, dstValue);
+				changed = true;
+			}
+			else if (dstValue !== srcValue) {
+				if (srcValue && typeof srcValue === "object") {
+					if (typeof dstValue === "object" && dstValue && srcValue.constructor === dstValue.constructor) {
+						changed = copyRecursive(dstValue, srcValue, flags) || changed;
+						continue;
+					}
+					srcValue = clone(srcValue);
+				}
+				dst[index] = srcValue;
+
+				if (flags & COPY_EMIT) emit(dst, index, srcValue, dstValue);
+				changed = true;
+			}
 		}
+
 		// Leaving additional values in the old array doesn't make sense, so we'll do this even when MERGE is set:
 		if (srcLen !== dstLen) {
 			if (flags & COPY_EMIT) {
 				for (let i = srcLen; i < dstLen; i++) {
 					const old = dst[i];
-					dst[i] = undefined;
-					emit(dst, i, undefined, old);
+					delete dst[i];
+					emit(dst, i, EMPTY, old);
 				}
 				dst.length = srcLen;
 				emit(dst, "length", srcLen, dstLen);
 			} else {
 				dst.length = srcLen;
 			}
+			changed = true;
 		}
-	} else {
-		// Copy all entries from src to dst (both of which can be Map or object)
-		for (const [key, value] of getEntries(src)) {
-			copyValue(dst, key, value, flags);
+	} else if (src instanceof Map && dst instanceof Map) {
+		for (const key of src.keys()) {
+			// changed = copyValue(dst, k, src.get(k), flags) || changed;
+			let srcValue = src.get(key);
+			let dstValue = dst.get(key);
+			if (dstValue === undefined && !dst.has(key)) dstValue = EMPTY;
+			if (dstValue !== srcValue) {
+				if (srcValue && typeof srcValue === "object") {
+					if (typeof dstValue === "object" && dstValue && srcValue.constructor === dstValue.constructor) {
+						changed = copyRecursive(dstValue, srcValue, flags) || changed;
+						continue;
+					}
+					srcValue = clone(srcValue);
+				}
+
+				dst.set(key, srcValue);
+
+				if (flags & COPY_EMIT) emit(dst, key, srcValue, dstValue);
+				changed = true;
+			}
 		}
-		
-		// Remove entries from dst that don't exist in src (unless MERGE flag is set)
+
 		if (!(flags & MERGE)) {
-			if (src instanceof Map) {
-				for (const key of getKeys(dst)) {
-					if (!src.has(key)) {
-						deleteKey(dst, key, flags);
+			for (const k of dst.keys()) {
+				if (!src.has(k)) {
+					const old = dst.get(k);
+					dst.delete(k);
+					if (flags & COPY_EMIT) {
+						emit(dst, k, undefined, old);
 					}
+					changed = true;
 				}
-			} else {
-				for (const key of getKeys(dst)) {
-					if (!(key in src)) {
-						deleteKey(dst, key, flags);
+			}
+		}
+	} else if (src.constructor === dst.constructor) {
+		for (const key of Object.keys(src) as (keyof typeof src)[]) {
+			// changed = copyValue(dst, k, src[k as keyof typeof src], flags) || changed;
+			let srcValue = src[key];
+			const dstValue = dst.hasOwnProperty(key) ? dst[key] : EMPTY;
+			if (dstValue !== srcValue) {
+				if (srcValue && typeof srcValue === "object") {
+					if (typeof dstValue === "object" && dstValue && srcValue.constructor === dstValue.constructor) {
+						changed = copyRecursive(dstValue as typeof srcValue, srcValue, flags) || changed;
+						continue;
 					}
+					srcValue = clone(srcValue);
 				}
+
+				dst[key] = srcValue;
+
+				if (flags & COPY_EMIT) emit(dst, key, srcValue, dstValue);
+				changed = true;
 			}
 		}
-	}
-}
 
-function deleteKey(dst: any, key: any, flags: number) {
-	let old;
-	if (dst instanceof Map) {
-		old = dst.get(key);
-		dst.delete(key);
+		if (!(flags & MERGE)) {
+			for (const k of Object.keys(dst) as (keyof typeof dst)[]) {
+				if (!src.hasOwnProperty(k)) {
+					const old = dst[k];
+					delete dst[k];
+					if (flags & COPY_EMIT && old !== undefined) {
+						emit(dst, k, undefined, old);
+					}
+					changed = true;
+				}
+			}
+		}
 	} else {
-		old = dst[key];
-		delete dst[key];
-	}
-	if (flags & COPY_EMIT && old !== undefined) {
-		emit(dst, key, undefined, old);
+		throw new Error(`Incompatible or non-object types: ${src?.constructor?.name || typeof src} vs ${dst?.constructor?.name || typeof dst}`);
 	}
+	return changed;
 }
 
-function copyValue(dst: any, index: any, srcValue: any, flags: number) {
-	const dstValue = dst instanceof Map ? dst.get(index) : dst[index];
-	if (srcValue !== dstValue) {
-		if (
-			srcValue && dstValue && typeof srcValue === "object" && typeof dstValue === "object" &&
-			(srcValue.constructor === dstValue.constructor || (flags & MERGE && dstValue instanceof Array))
-		) {
-			copyRecurse(dstValue, srcValue, flags);
-			return;
-		}
+const MERGE = 1;
+const COPY_SUBSCRIBE = 32;
+const COPY_EMIT = 64;
 
-		if (!(flags & SHALLOW) && srcValue && typeof srcValue === "object") {
-			// Create an empty object of the same type
-			const copy = Object.create(Object.getPrototypeOf(srcValue));
-			// Copy all properties to it. This doesn't need to emit anything
-			// and MERGE does not apply as this is a new branch.
-			copyRecurse(copy, srcValue, 0);
-			srcValue = copy;
-		}
-		if (dst instanceof Map) {
-			if (flags & MERGE && srcValue == null) dst.delete(index);
-			else dst.set(index, srcValue);
-		} else {
-			if (flags & MERGE && srcValue == null) delete dst[index];
-			else dst[index] = srcValue;
-		}
-		if (flags & COPY_EMIT) emit(dst, index, srcValue, dstValue);
-	}
+/**
+ * Clone an (optionally proxied) object or array.
+ *
+ * @param src The object or array to clone. If it is proxied, `clone` will subscribe to any changes to the (nested) data structure.
+ * @template T - The type of the objects being copied.
+ * @returns A new unproxied array or object (of the same type as `src`), containing a deep copy of `src`.
+ */
+export function clone<T extends object>(src: T): T {
+	// Create an empty object of the same type
+	const copied = Array.isArray(src) ? [] : src instanceof Map ? new Map() : Object.create(Object.getPrototypeOf(src));
+	// Copy all properties to it. This doesn't need to emit anything, and because
+	// the destination is an empty object, we can just MERGE, which is a bit faster.
+	copyImpl(copied, src, MERGE);
+	return copied;
 }
 
 interface RefTarget {
@@ -1771,7 +1782,7 @@ function applyBind(el: HTMLInputElement, target: any) {
 				throw new Error(`SELECT has no '${target.value}' OPTION (yet)`);
 		};
 	}
-	observe(onProxyChange);
+	derive(onProxyChange);
 	el.addEventListener("input", onInputChange);
 	clean(() => {
 		el.removeEventListener("input", onInputChange);
@@ -1808,11 +1819,6 @@ const SPECIAL_PROPS: { [key: string]: (value: any) => void } = {
 	text: (value: any) => {
 		addNode(document.createTextNode(value));
 	},
-	element: (value: any) => {
-		console.log("Aberdeen: $({element: myElement}) is deprecated, use $(myElement) instead");
-		addNode(value);
-		SPECIAL_PROPS.element = addNode; // Avoid the console.log next time
-	},
 };
 
 /**
@@ -1823,12 +1829,14 @@ const SPECIAL_PROPS: { [key: string]: (value: any) => void } = {
  * @param {...(string | function | object | false | undefined | null)} args - Any number of arguments can be given. How they're interpreted depends on their types:
  *
  * - `string`: Strings can be used to create and insert new elements, set classnames for the *current* element, and add text to the current element.
- *   The format of a string is: **tag**? (`.` **class**)* (':' **text**)?
- *   meaning it consists of...
- *   - An optional HTML **tag**, something like `h1`. If present, a DOM element of that tag is created, and that element will be the *current* element for the rest of this `$` function execution.
- *   - Any number of CSS classes prefixed by `.` characters. These classes will be added to the *current* element.
- *   - Optional content **text** prefixed by a `:` character, ranging til the end of the string. This will be added as a TextNode to the *current* element.
- * - `function`: When a function (without argument nor a return value) is passed in, it will be reactively executed in its own observe scope, preserving the *current element*. So any `$()` invocations within this function will create DOM elements with our *current* element as parent. If the function reads observable data, and that data is changed later on, the function we re-execute (after side effects, such as DOM modifications through `$`, have been cleaned - see also {@link clean}).
+ *   The format of a string is: (**tag** | `.` **class** | **key**=**val** | **key**="**long val**")* (':' **text** | **key**=)?
+ *   So there can be:
+ *   - Any number of **tag** element, like `h1` or `div`. These elements are created, added to the *current* element, and become the new *current* element for the rest of this `$` function execution.
+ *   - Any number of CSS classes prefixed by `.` characters. These classes will be added to the *current* element. Optionally, CSS classes can be appended to a **tag** without a space. So both `div.myclass` and `div .myclass` are valid and do the same thing.
+ *   - Any number of key/value pairs with string values, like `placeholder="Your name"` or `data-id=123`. These will be handled according to the rules specified for `object`, below, but with the caveat that values can only be strings. The quotes around string values are optional, unless the value contains spaces. It's not possible to escape quotes within the value. If you want to do that, or if you have user-provided values, use the `object` syntax (see below) or end your string with `key=` followed by the data as a separate argument (see below).
+ *   - The string may end in a ':' followed by text, which will be added as a TextNode to the *current* element. The text ranges til the end of the string, and may contain any characters, including spaces and quotes.
+ *   - Alternatively, the string may end in a key followed by an '=' character, in which case the value is expected as a separate argument. The key/value pair is set according to the rules specified for `object` below. This is useful when the value is not a string or contains spaces or user data. Example: `$('button text="Click me" click=', () => alert('Clicked!'))` or `$('input.value=', someUserData, "placeholder=", "Type your stuff")`.
+ * - `function`: When a function (without argument nor a return value) is passed in, it will be reactively executed in its own observer scope, preserving the *current element*. So any `$()` invocations within this function will create DOM elements with our *current* element as parent. If the function reads observable data, and that data is changed later on, the function we re-execute (after side effects, such as DOM modifications through `$`, have been cleaned - see also {@link clean}).
  * - `object`: When an object is passed in, its key-value pairs are used to modify the *current* element in the following ways...
  *   - `{<attrName>: any}`: The common case is setting the value as an HTML attribute named key. So `{placeholder: "Your name"}` would add `placeholder="Your name"` to the current HTML element.
  *   - `{<propName>: boolean}` or `{value: any}` or `{selectedIndex: number}`: If the value is a boolean, or if the key is `value` or `selectedIndex`, it is set on the `current` element as a DOM property instead of an HTML attribute. For example `{checked: true}` would do `el.checked = true` for the *current* element.
@@ -1839,7 +1847,7 @@ const SPECIAL_PROPS: { [key: string]: (value: any) => void } = {
  *   - `{destroy: string}`: When the *current* element is a top-level element to be removed (due to reactivity cleanup), actual removal from the DOM is delayed by 2 seconds, and in the mean time the value string is added as a CSS class to the element, allowing for a deletion transition. The string may also contain multiple dot-separated CSS classes, such as `.fade.shrink`.
  *   - `{create: function}` and `{destroy: function}`: The function is invoked when the *current* element is the top-level element being created/destroyed. It can be used for more involved creation/deletion animations. In case of `destroy`, the function is responsible for actually removing the element from the DOM (eventually). See `transitions.ts` in the Aberdeen source code for some examples.
  *   - `{bind: <obsValue>}`: Create a two-way binding element between the `value` property of the given observable (proxy) variable, and the *current* input element (`<input>`, `<select>` or `<textarea>`). This is often used together with {@link ref}, in order to use properties other than `.value`.
- *   - `{<any>: <obsvalue>}`: Create a new observe scope and read the `value` property of the given observable (proxy) variable from within it, and apply the contained value using any of the other rules in this list. Example:
+ *   - `{<any>: <obsvalue>}`: Create a new observer scope and read the `value` property of the given observable (proxy) variable from within it, and apply the contained value using any of the other rules in this list. Example:
  *      ```typescript
  *      const myColor = proxy('red');
  *      $('p:Test', {$color: myColor, click: () => myColor.value = 'yellow'})
@@ -1861,6 +1869,14 @@ const SPECIAL_PROPS: { [key: string]: (value: any) => void } = {
  *   $color: 'red'
  * });
  * ```
+ * 
+ * Which can also be written as:
+ * ```typescript
+ * $('button.secondary.outline text=Submit $color=red disabled=', false, 'click=', () => console.log('Clicked!'));
+ * ```
+ * 
+ * We want to set `disabled` as a property instead of an attribute, so we must use the `key=` syntax in order to provide
+ * `false` as a boolean instead of a string.
  *
  * @example Create Nested Elements
  * ```typescript
@@ -1914,24 +1930,85 @@ export function $(
 	let savedCurrentScope: undefined | ContentScope;
 	let err: undefined | string;
 	let result: undefined | Element;
+	let nextArgIsProp: undefined | string;
 
 	for (let arg of args) {
-		if (arg == null || arg === false) continue;
-		if (typeof arg === "string") {
-			let text: undefined | string;
-			let classes: undefined | string;
-			const textPos = arg.indexOf(":");
-			if (textPos >= 0) {
-				text = arg.substring(textPos + 1);
-				arg = arg.substring(0, textPos);
-			}
-			const classPos = arg.indexOf(".");
-			if (classPos >= 0) {
-				classes = arg.substring(classPos + 1);
-				arg = arg.substring(0, classPos);
-			}
-			if (arg === "") {
-				// Add text or classes to parent
+		if (nextArgIsProp) {
+			applyArg(nextArgIsProp, arg);
+			nextArgIsProp = undefined;
+		} else if (arg == null || arg === false) {
+			// Ignore
+		} else if (typeof arg === "string") {
+			let pos = 0;
+			let argLen = arg.length;
+			while(pos < argLen) {
+				let nextSpace = arg.indexOf(" ", pos);
+				if (nextSpace < 0) nextSpace = arg.length;
+				let part = arg.substring(pos, nextSpace);
+				const oldPos = pos;
+				pos = nextSpace + 1;
+				
+				const firstIs = part.indexOf('=');
+				const firstColon = part.indexOf(':');
+				if (firstIs >= 0 && (firstColon < 0 || firstIs < firstColon)) {
+					const prop = part.substring(0, firstIs);
+					if (firstIs < part.length - 1) {
+						let value = part.substring(firstIs + 1);
+						if (value[0] === '"') {
+							const closeIndex = arg.indexOf('"', firstIs+2+oldPos);
+							if (closeIndex < 0) throw new Error(`Unterminated string for '${prop}'`);
+							value = arg.substring(firstIs+2+oldPos, closeIndex);
+							pos = closeIndex + 1;
+							if (arg[pos] === ' ') pos++;
+						}
+						applyArg(prop, value);
+						continue;
+					} else {
+						if (pos < argLen) throw new Error(`No value given for '${part}'`);
+						nextArgIsProp = prop;
+						break
+					}
+				}
+				
+				let text;
+				if (firstColon >= 0) {
+					// Read to the end of the arg, ignoring any spaces
+					text = arg.substring(firstColon + 1 + oldPos);
+					part = part.substring(0, firstColon);
+					if (!text) {
+						if (pos < argLen) throw new Error(`No value given for '${part}'`);
+						nextArgIsProp = 'text';
+						break;
+					}
+					pos = argLen;
+				}
+
+				let classes: undefined | string;
+				const classPos = part.indexOf(".");
+				if (classPos >= 0) {
+					classes = part.substring(classPos + 1);
+					part = part.substring(0, classPos);
+				}
+
+				if (part) { // Add an element
+					// Determine which namespace to use for element creation
+					const svg = currentScope.inSvgNamespace || part === 'svg';
+					if (svg) {
+						result = document.createElementNS('http://www.w3.org/2000/svg', part);
+					} else {
+						result = document.createElement(part);
+					}
+					addNode(result);
+					if (!savedCurrentScope) savedCurrentScope = currentScope;
+					const newScope = new ChainedScope(result, true);
+				
+					// SVG namespace should be inherited by children
+					if (svg) newScope.inSvgNamespace = true;
+					
+					if (topRedrawScope === currentScope) topRedrawScope = newScope;
+					currentScope = newScope;
+				}
+
 				if (text) addNode(document.createTextNode(text));
 				if (classes) {
 					const el = currentScope.parentElement;
@@ -1940,34 +2017,6 @@ export function $(
 						clean(() => el.classList.remove(...classes.split(".")));
 					}
 				}
-			} else if (arg.indexOf(" ") >= 0) {
-				err = `Tag '${arg}' cannot contain space`;
-				break;
-			} else {
-				// Determine which namespace to use for element creation
-				const useNamespace = currentScope.inSvgNamespace || arg === 'svg';
-				if (useNamespace) {
-					result = document.createElementNS('http://www.w3.org/2000/svg', arg);
-				} else {
-					result = document.createElement(arg);
-				}
-				
-				if (classes) result.className = classes.replaceAll(".", " ");
-				if (text) result.textContent = text;
-				addNode(result);
-				if (!savedCurrentScope) {
-					savedCurrentScope = currentScope;
-				}
-				const newScope = new ChainedScope(result, true);
-				
-				// If we're creating an SVG element, set the SVG namespace flag for child scopes
-				if (arg === 'svg') {
-					newScope.inSvgNamespace = true;
-				}
-				
-				newScope.lastChild = result.lastChild || undefined;
-				if (topRedrawScope === currentScope) topRedrawScope = newScope;
-				currentScope = newScope;
 			}
 		} else if (typeof arg === "object") {
 			if (arg.constructor !== Object) {
@@ -1984,7 +2033,7 @@ export function $(
 					break;
 				}
 			} else {
-				for (const key in arg) {
+				for (const key of Object.keys(arg)) {
 					const val = arg[key];
 					applyArg(key, val);
 				}
@@ -1996,9 +2045,8 @@ export function $(
 			break;
 		}
 	}
-	if (savedCurrentScope) {
-		currentScope = savedCurrentScope;
-	}
+	if (nextArgIsProp !== undefined) throw new Error(`No value given for '${nextArgIsProp}='`);
+	if (savedCurrentScope) currentScope = savedCurrentScope;
 	if (err) throw new Error(err);
 	return result;
 }
@@ -2072,7 +2120,7 @@ export function insertCss(style: object, global = false): string {
 function styleToCss(style: object, prefix: string): string {
 	let props = "";
 	let rules = "";
-	for (const kOr in style) {
+	for (const kOr of Object.keys(style)) {
 		const v = (style as any)[kOr];
 		for (const k of kOr.split(/, ?/g)) {
 			if (v && typeof v === "object") {
@@ -2147,7 +2195,7 @@ let onError: (error: Error) => boolean | undefined = defaultOnError;
 /**
  * Sets a custom error handler function for errors that occur asynchronously
  * within reactive scopes (e.g., during updates triggered by proxy changes in
- * {@link observe} or {@link $} render functions).
+ * {@link derive} or {@link $} render functions).
  *
  * The default handler logs the error to `console.error` and adds a simple
  * 'Error' message div to the DOM at the location where the error occurred (if possible).
@@ -2235,7 +2283,7 @@ export function getParentElement(): Element {
  * This is useful for releasing resources, removing manual event listeners, or cleaning up
  * side effects associated with the scope. Cleaners are run in reverse order of registration.
  *
- * Scopes are created by functions like {@link observe}, {@link mount}, {@link $} (when given a render function),
+ * Scopes are created by functions like {@link derive}, {@link mount}, {@link $} (when given a render function),
  * and internally by constructs like {@link onEach}.
  *
  * @param cleaner - The function to execute during cleanup.
@@ -2253,7 +2301,7 @@ export function getParentElement(): Element {
  *     peek(() => sum.value += item);
  *     // Clean gets called before each rerun for a certain item index
  *     // No need for peek here, as the clean code doesn't run in an
- *     // observe scope.
+ *     // observer scope.
  *     clean(() => sum.value -= item);
  * })
  *
@@ -2281,7 +2329,7 @@ export function clean(cleaner: () => void) {
  *
  * @param func - The function to execute reactively. Any DOM manipulations should typically
  *   be done using {@link $} within this function. Its return value will be made available as an
- *   observable returned by the `observe()` function.
+ *   observable returned by the `derive()` function.
  * @returns An observable object, with its `value` property containing whatever the last run of `func` returned.
  *
  * @example Observation creating a UI components
@@ -2292,7 +2340,7 @@ export function clean(cleaner: () => void) {
  *   console.log('Welcome');
  *   $('h3:Welcome, ' + data.user); // Reactive text
  *
- *   observe(() => {
+ *   derive(() => {
  *     // When data.notifications changes, only this inner scope reruns,
  *     // leaving the `<p>Welcome, ..</p>` untouched.
  *     console.log('Notifications');
@@ -2302,13 +2350,13 @@ export function clean(cleaner: () => void) {
  * });
  * ```
  *
- * ***Note*** that the above could just as easily be done using `$(func)` instead of `observe(func)`.
+ * ***Note*** that the above could just as easily be done using `$(func)` instead of `derive(func)`.
  *
  * @example Observation with return value
  * ```typescript
  * const counter = proxy(0);
  * setInterval(() => counter.value++, 1000);
- * const double = observe(() => counter.value * 2);
+ * const double = derive(() => counter.value * 2);
  *
  * $('h3', () => {
  *     $(`:counter=${counter.value} double=${double.value}`);
@@ -2318,42 +2366,10 @@ export function clean(cleaner: () => void) {
  * @overload
  * @param func Func without a return value.
  */
-export function observe<T>(func: () => T): ValueRef<T> {
+export function derive<T>(func: () => T): ValueRef<T> {
 	return new ResultScope<T>(currentScope.parentElement, func).result;
 }
 
-/**
- * Similar to {@link observe}, creates a reactive scope that re-executes the function
- * when its proxied dependencies change.
- *
- * **Difference:** Updates run **synchronously and immediately** after the proxy modification
- * that triggered the update occurs.
- *
- * **Caution:** Use sparingly. Immediate execution bypasses Aberdeen's usual batching and
- * ordering optimizations, which can lead to performance issues or observing inconsistent
- * intermediate states if multiple related updates are applied sequentially.
- * Prefer {@link observe} or {@link $} for most use cases.
- *
- * @param func - The function to execute reactively and synchronously.
- *
- * @example
- * ```javascript
- * const state = proxy({ single: 'A' });
- *
- * immediateObserve(() => {
- *   state.double = state.single + state.single
- * });
- * console.log(state.double); // 'AA'
- *
- * state.single = 'B';
- * // Synchronously:
- * console.log(state.double); // 'BB'
- * ```
- */
-export function immediateObserve(func: () => void) {
-	new ImmediateScope(currentScope.parentElement, func);
-}
-
 /**
  * Attaches a reactive Aberdeen UI fragment to an existing DOM element. Without the use of
  * this function, {@link $} will assume `document.body` as its root.
@@ -2363,11 +2379,11 @@ export function immediateObserve(func: () => void) {
  * will cause it to re-execute when the data changes, updating the DOM elements created within it.
  *
  * Calls to {@link $} inside `func` will append nodes to `parentElement`.
- * You can nest {@link observe} or other {@link $} scopes within `func`.
+ * You can nest {@link derive} or other {@link $} scopes within `func`.
  * Use {@link unmountAll} to clean up all mounted scopes and their DOM nodes.
  *
  * Mounting scopes happens reactively, meaning that if this function is called from within another
- * ({@link observe} or {@link $} or {@link mount}) scope that gets cleaned up, so will the mount.
+ * ({@link derive} or {@link $} or {@link mount}) scope that gets cleaned up, so will the mount.
  *
  * @param parentElement - The native DOM `Element` to which the UI fragment will be appended.
  * @param func - The function that defines the UI fragment, typically containing calls to {@link $}.
@@ -2403,7 +2419,7 @@ export function mount(parentElement: Element, func: () => void) {
 
 /**
  * Removes all Aberdeen-managed DOM nodes and stops all active reactive scopes
- * (created by {@link mount}, {@link observe}, {@link $} with functions, etc.).
+ * (created by {@link mount}, {@link derive}, {@link $} with functions, etc.).
  *
  * This effectively cleans up the entire Aberdeen application state.
  */
@@ -2413,20 +2429,21 @@ export function unmountAll() {
 }
 
 /**
- * Executes a function *without* creating subscriptions in the current reactive scope, and returns its result.
+ * Executes a function or retrieves a value *without* creating subscriptions in the current reactive scope, and returns its result.
  *
- * This is useful when you need to access reactive data inside a reactive scope (like {@link observe})
+ * This is useful when you need to access reactive data inside a reactive scope (like {@link $})
  * but do not want changes to that specific data to trigger a re-execute of the scope.
+ * 
+ * Note: You may also use {@link unproxy} to get to the raw underlying data structure, which can be used to similar effect.
  *
- * @template T The type of the return value of your function.
- *
- * @param func - The function to execute without creating subscriptions.
- * @returns Whatever `func` returns.
+ * @param target - Either a function to execute, or an object (which may also be an Array or a Map) to index.
+ * @param key - Optional key/index to use when `target` is an object.
+ * @returns The result of the function call, or the value at `target[key]` when `target` is an object or `target.get(key)` when it's a Map.
  *
- * @example Peeking within observe
+ * @example Peeking within observer
  * ```typescript
  * const data = proxy({ a: 1, b: 2 });
- * observe(() => {
+ * $(() => {
  *   // re-executes only when data.a changes, because data.b is peeked.
  *   const b = peek(() => data.b);
  *   console.log(`A is ${data.a}, B was ${b} when A changed.`);
@@ -2436,10 +2453,20 @@ export function unmountAll() {
  * ```
  *
  */
-export function peek<T>(func: () => T): T {
+
+export function peek<T extends object>(target: T, key: keyof T): T[typeof key];
+export function peek<K,V>(target: Map<K,V>, key: K): V | undefined;
+export function peek<T>(target: T[], key: number): T | undefined;
+export function peek<T>(target: () => T): T;
+
+export function peek(target: any, key?: any) {
 	peeking++;
 	try {
-		return func();
+		if (arguments.length === 1) {
+			return target();
+		} else {
+			return (target instanceof Map) ? target.get(key) : target[key];
+		}
 	} finally {
 		peeking--;
 	}
@@ -2450,16 +2477,16 @@ export function map<K, IN, OUT>(
 	source: Map<K, IN>,
 	func: (value: IN, key: K) => undefined | OUT,
 ): Map<K, OUT>;
-/** When using an object as `source`. */
-export function map<IN, const IN_KEY extends string | number | symbol, OUT>(
-	source: Record<IN_KEY, IN>,
-	func: (value: IN, index: KeyToString<IN_KEY>) => undefined | OUT,
-): Record<string | symbol, OUT>;
 /** When using an array as `source`. */
 export function map<IN, OUT>(
 	source: Array<IN>,
 	func: (value: IN, index: number) => undefined | OUT,
 ): Array<OUT>;
+/** When using an object as `source`. */
+export function map<IN, const IN_KEY extends string | number | symbol, OUT>(
+	source: Record<IN_KEY, IN>,
+	func: (value: IN, index: KeyToString<IN_KEY>) => undefined | OUT,
+): Record<string | symbol, OUT>;
 /**
  * Reactively maps/filters items from a proxied source array or object to a new proxied array or object.
  *
@@ -2483,7 +2510,7 @@ export function map<IN, OUT>(
  * const doubled = map(numbers, (n) => n * 2);
  * // doubled is proxy([2, 4, 6])
  *
- * observe(() => console.log(doubled)); // Logs updates
+ * $(() => console.log(doubled)); // Logs updates
  * numbers.push(4); // doubled becomes proxy([2, 4, 6, 8])
  * ```
  *
@@ -2497,7 +2524,7 @@ export function map<IN, OUT>(
  *
  * const activeUserNames = map(users, (user) => user.active ? user.name : undefined);
  * // activeUserNames is proxy({ u1: 'Alice', u3: 'Charlie' })
- * observe(() => console.log(Object.values(activeUserNames)));
+ * $(() => console.log(Object.values(activeUserNames)));
  *
  * users.u2.active = true;
  * // activeUserNames becomes proxy({ u1: 'Alice', u2: 'Bob', u3: 'Charlie' })
@@ -2601,9 +2628,9 @@ export function multiMap(
 	onEach(source, (item: any, key: symbol | string | number) => {
 		const pairs = func(item, key);
 		if (pairs) {
-			for (const key in pairs) out[key] = pairs[key];
+			for (const key of Object.keys(pairs)) out[key] = pairs[key];
 			clean(() => {
-				for (const key in pairs) delete out[key];
+				for (const key of Object.keys(pairs)) delete out[key];
 			});
 		}
 	});