doxum 0.1.27 → 0.1.28

package/dist/index.js

@@ -1,4 +1,4 @@
-import { S as profile, _ as isProjection, a as ProjectionError, b as producerOf, c as createCollectionChange, d as snapshotDependencyValue, f as collectionView, g as defineSource, h as defineProcessor, i as ProjectionDisposedError, l as diffCollection, m as snapshotCollectionView, n as assertSynchronous, o as collectionChange, p as mapRead, r as createScheduler, s as collectionHasStructuralChange, t as assertScope, u as compileProjectionDependencies, v as outputDefinitionOf, x as projectionRef, y as ownProjections } from "./scheduler-vzf3OcjT.js";
+import { C as defineSource, D as projectionRef, E as producerOf, O as profile, S as defineProcessor, T as ownProjections, _ as compileProjectionDependencies, a as createKeyedDependencyRuntime, b as mapRead, c as assertScope, d as ProjectionDisposedError, f as ProjectionError, g as diffCollection, h as createCollectionChange, i as compileKeyedDependencies, l as assertSynchronous, m as collectionHasStructuralChange, n as keyedAbsent, o as outputKind, p as collectionChange, r as assertKeyedProjection, s as createKeyRelation, t as createKeyedTransform, u as createScheduler, v as snapshotDependencyValue, w as isProjection, x as snapshotCollectionView, y as collectionView } from "./transform-B4T3AcJr.js";
 import { n as isPlainObject, r as isRecord, t as installOwn } from "./record-B2yRhYsc.js";
 import { c as AddressIndex, d as invalidValue, f as children, g as validate, h as parent, i as contextOf, l as MutationRejected, m as is, o as decodeChanges, p as contains$1, r as bindContext, s as sealChanges, t as assertRuntimeWritable, u as fail } from "./driver-B5vdPohL.js";
 //#region core/src/schema/model.ts
@@ -2735,41 +2735,6 @@ const isExternalSource = (source) => {
 };
 //#endregion
 //#region core/src/projection/derive/keyed.ts
-const outputKind = (projection) => {
-	return outputDefinitionOf(projection).kind;
-};
-const assertKeyedProjection = (projection, role) => {
-	if (outputKind(projection) !== "collection") throw new TypeError(`${role} must be a keyed collection projection.`);
-};
-const isKeyedDependency = (value) => {
-	if (!value || typeof value !== "object" || isProjection(value)) return false;
-	const candidate = value;
-	return isProjection(candidate.source) && typeof candidate.key === "function";
-};
-const bindKey = (index, outputKey, sourceKey) => {
-	const previous = index.forward.get(outputKey);
-	if (previous === sourceKey) return;
-	if (previous !== void 0) {
-		const dependents = index.reverse.get(previous);
-		dependents?.delete(outputKey);
-		if (dependents?.size === 0) index.reverse.delete(previous);
-		index.forward.delete(outputKey);
-	}
-	if (sourceKey === void 0) return;
-	index.forward.set(outputKey, sourceKey);
-	const dependents = index.reverse.get(sourceKey);
-	if (dependents) dependents.add(outputKey);
-	else index.reverse.set(sourceKey, new Set([outputKey]));
-};
-const unbindKey = (indexes, outputKey) => {
-	for (const index of indexes) if (index) bindKey(index, outputKey, void 0);
-};
-const createBindingIndex = () => ({
-	forward: /* @__PURE__ */ new Map(),
-	reverse: /* @__PURE__ */ new Map()
-});
-const emptyKeyedDependencies = Object.freeze(Object.create(null));
-const absent = Symbol("keyed-transform-absent");
 const compileOrderedKeys = (value, role) => {
 	if (!Array.isArray(value)) throw new TypeError(`${role} must be an array of string keys.`);
 	const seen = /* @__PURE__ */ new Set();
@@ -2783,160 +2748,18 @@ const compileOrderedKeys = (value, role) => {
 		requested: seen
 	};
 };
-const createKeyedTransform = (source, dependencySpecs, select, equality, name) => {
-	assertKeyedProjection(source, "Keyed derive source");
-	const dependencies = [source];
-	const dependencyNames = [];
-	const keyed = [];
-	if (dependencySpecs !== void 0) {
-		if (!isPlainObject(dependencySpecs) || isProjection(dependencySpecs)) throw new TypeError("Keyed derive dependencies must be a plain object.");
-		for (const name of Reflect.ownKeys(dependencySpecs)) {
-			if (typeof name !== "string") throw new TypeError("Keyed derive dependency names must be strings.");
-			const descriptor = Object.getOwnPropertyDescriptor(dependencySpecs, name);
-			if (!descriptor?.enumerable || !("value" in descriptor)) throw new TypeError("Keyed derive dependencies must be enumerable data properties.");
-			const dependency = descriptor.value;
-			dependencyNames.push(name);
-			if (isProjection(dependency)) {
-				dependencies.push(dependency);
-				keyed.push(void 0);
-				continue;
-			}
-			if (!isKeyedDependency(dependency)) throw new TypeError("Keyed derive dependencies must be projections or keyed lookups.");
-			assertKeyedProjection(dependency.source, "Dynamic keyed dependency source");
-			dependencies.push(dependency.source);
-			keyed.push(dependency);
-		}
-	}
-	const [projection] = defineProcessor({
-		dependencies,
-		outputs: [{
-			kind: "collection",
-			equality: equality ?? Object.is
-		}],
-		create: () => {
-			const bindings = keyed.map((dependency) => dependency ? createBindingIndex() : void 0);
-			const globalValues = keyed.map(() => void 0);
-			const revisions = [];
-			const clearBindings = () => {
-				for (const index of bindings) {
-					index?.forward.clear();
-					index?.reverse.clear();
-				}
-			};
-			const rememberRevisions = (sources) => {
-				revisions.length = sources.length;
-				for (let index = 0; index < sources.length; index++) revisions[index] = sources[index].revision;
-			};
-			return {
-				evaluate: (evaluation) => {
-					const driver = evaluation.sources[0];
-					const output = evaluation.outputs[0];
-					if (driver.kind !== "collection" || output.kind !== "collection") throw new Error("Keyed derive requires collection input and output.");
-					for (let index = 0; index < keyed.length; index++) {
-						if (keyed[index]) continue;
-						const dependencySource = evaluation.sources[index + 1];
-						if (evaluation.reset || revisions[index + 1] !== dependencySource.revision) globalValues[index] = snapshotDependencyValue(dependencySource);
-					}
-					const project = (key) => {
-						if (!driver.read.has(key)) return;
-						const value = driver.read.get(key);
-						let dependencyValues = emptyKeyedDependencies;
-						if (keyed.length) {
-							const values = Object.create(null);
-							for (let index = 0; index < keyed.length; index++) {
-								const dependency = keyed[index];
-								if (!dependency) {
-									values[dependencyNames[index]] = globalValues[index];
-									continue;
-								}
-								const sourceContext = evaluation.sources[index + 1];
-								if (sourceContext.kind !== "collection") throw new TypeError("Dynamic keyed dependency resolved to a non-collection source.");
-								const selectedKey = dependency.key(value, key);
-								assertSynchronous(selectedKey);
-								if (selectedKey !== void 0 && typeof selectedKey !== "string") throw new TypeError("Dynamic keyed dependency keys must be strings or undefined.");
-								bindKey(bindings[index], key, selectedKey);
-								values[dependencyNames[index]] = selectedKey === void 0 ? void 0 : sourceContext.read.get(selectedKey);
-							}
-							dependencyValues = Object.freeze(values);
-						}
-						const next = select(value, key, dependencyValues);
-						assertSynchronous(next);
-						if (next === absent) output.output.remove(key);
-						else output.output.set(key, next);
-					};
-					if (evaluation.reset) {
-						clearBindings();
-						const ids = driver.read.ids();
-						for (const key of ids) project(key);
-						output.output.order(ids.filter((key) => output.next.has(key)));
-						rememberRevisions(evaluation.sources);
-						return;
-					}
-					const dirty = /* @__PURE__ */ new Set();
-					let all = false;
-					let updateOrder = false;
-					let membershipChanged = false;
-					if (revisions[0] !== driver.revision) {
-						const change = driver.change;
-						if (!change || change.kind === "reset") {
-							all = true;
-							updateOrder = true;
-						} else {
-							for (const entry of change.removed) {
-								membershipChanged ||= output.previous.has(entry.key);
-								output.output.remove(entry.key);
-								unbindKey(bindings, entry.key);
-								dirty.delete(entry.key);
-							}
-							for (const entry of change.added) dirty.add(entry.key);
-							for (const entry of change.updated) dirty.add(entry.key);
-							updateOrder = Boolean(change.order);
-						}
-					}
-					for (let index = 0; index < keyed.length; index++) {
-						const sourceContext = evaluation.sources[index + 1];
-						if (revisions[index + 1] === sourceContext.revision) continue;
-						if (!keyed[index]) {
-							all = true;
-							continue;
-						}
-						if (sourceContext.kind !== "collection" || !sourceContext.change) {
-							all = true;
-							continue;
-						}
-						if (sourceContext.change.kind === "reset") {
-							all = true;
-							continue;
-						}
-						const reverse = bindings[index].reverse;
-						for (const sourceKey of collectionChange.keys(sourceContext.change)) for (const outputKey of reverse.get(sourceKey) ?? []) dirty.add(outputKey);
-					}
-					if (all) for (const key of driver.read.ids()) dirty.add(key);
-					for (const key of dirty) {
-						if (!driver.read.has(key)) continue;
-						const beforePresent = output.previous.has(key);
-						project(key);
-						membershipChanged ||= beforePresent !== output.next.has(key);
-					}
-					if (updateOrder || membershipChanged) output.output.order(driver.read.ids().filter((key) => output.next.has(key)));
-					rememberRevisions(evaluation.sources);
-				},
-				release: () => {
-					clearBindings();
-					revisions.length = 0;
-				}
-			};
-		},
-		name
-	});
-	return projection;
-};
 function createKeyedDerive(source, dependenciesOrSelect, selectOrEquality, maybeEquality) {
 	const dependencySpecs = typeof dependenciesOrSelect === "function" ? void 0 : dependenciesOrSelect;
 	const select = dependencySpecs === void 0 ? dependenciesOrSelect : selectOrEquality;
 	const equality = dependencySpecs === void 0 ? selectOrEquality : maybeEquality;
 	if (typeof select !== "function") throw new TypeError("Keyed derive requires a selector.");
-	return createKeyedTransform(source, dependencySpecs, (value, key, dependencies) => dependencySpecs === void 0 ? select(value, key) : select(value, key, dependencies), equality, "derive.keyed");
+	return createKeyedTransform({
+		source,
+		dependencies: dependencySpecs,
+		equality,
+		name: "derive.keyed",
+		evaluate: ({ value, key, dependencies }) => dependencySpecs === void 0 ? select(value, key) : select(value, key, dependencies)
+	});
 }
 const createKeyedKeys = (source) => {
 	assertKeyedProjection(source, "Keyed keys source");
@@ -2956,8 +2779,8 @@ const createKeyedKeys = (source) => {
 	});
 	return projection;
 };
-const createKeyedValues = (source) => {
-	assertKeyedProjection(source, "Keyed values source");
+const createOrderedSnapshot = (source, name, make) => {
+	assertKeyedProjection(source, `${name} source`);
 	const [projection] = defineProcessor({
 		dependencies: [source],
 		outputs: [{
@@ -2968,33 +2791,32 @@ const createKeyedValues = (source) => {
 			let indexes = /* @__PURE__ */ new Map();
 			const rebuild = (driver) => {
 				const nextIndexes = /* @__PURE__ */ new Map();
-				const ids = driver.read.ids();
-				const values = Object.freeze(ids.map((key, index) => {
+				const result = Object.freeze(driver.read.ids().map((key, index) => {
 					nextIndexes.set(key, index);
-					return driver.read.get(key);
+					return make(key, driver.read.get(key));
 				}));
 				indexes = nextIndexes;
-				return values;
+				return result;
 			};
 			const rebuildIncremental = (driver, change, previous) => {
 				const changedValues = /* @__PURE__ */ new Map();
 				for (const entry of change.added) changedValues.set(entry.key, entry.after);
 				for (const entry of change.updated) changedValues.set(entry.key, entry.after);
 				const nextIndexes = /* @__PURE__ */ new Map();
-				const values = Object.freeze(driver.read.ids().map((key, index) => {
+				const result = Object.freeze(driver.read.ids().map((key, index) => {
 					nextIndexes.set(key, index);
-					if (changedValues.has(key)) return changedValues.get(key);
+					if (changedValues.has(key)) return make(key, changedValues.get(key));
 					const previousIndex = indexes.get(key);
-					return previousIndex === void 0 ? driver.read.get(key) : previous[previousIndex];
+					return previousIndex === void 0 ? make(key, driver.read.get(key)) : previous[previousIndex];
 				}));
 				indexes = nextIndexes;
-				return values;
+				return result;
 			};
 			return {
 				evaluate: (evaluation) => {
 					const driver = evaluation.sources[0];
 					const output = evaluation.outputs[0];
-					if (driver.kind !== "collection" || output.kind !== "value") throw new Error("derive.keyed.values requires collection input and value output.");
+					if (driver.kind !== "collection" || output.kind !== "value") throw new Error(`${name} requires collection input and value output.`);
 					const change = driver.change;
 					if (evaluation.reset || !change || change.kind === "reset") {
 						output.output.set(rebuild(driver));
@@ -3017,14 +2839,59 @@ const createKeyedValues = (source) => {
 							output.output.set(rebuild(driver));
 							return;
 						}
-						next[index] = entry.after;
+						next[index] = make(entry.key, entry.after);
 					}
 					output.output.set(Object.freeze(next));
 				},
 				release: () => indexes.clear()
 			};
 		},
-		name: "derive.keyed.values"
+		name
+	});
+	return projection;
+};
+const createKeyedValues = (source) => createOrderedSnapshot(source, "derive.keyed.values", (_key, value) => value);
+const createKeyedEntries = (source) => createOrderedSnapshot(source, "derive.keyed.entries", (key, value) => Object.freeze([key, value]));
+const createKeyedGet = (source, key, equality = Object.is) => {
+	assertKeyedProjection(source, "derive.keyed.get source");
+	if (outputKind(key) !== "value") throw new TypeError("derive.keyed.get key must be a scalar projection.");
+	const [projection] = defineProcessor({
+		dependencies: [source, key],
+		outputs: [{
+			kind: "value",
+			equality
+		}],
+		create: () => {
+			let sourceRevision = -1;
+			let keyRevision = -1;
+			let selected;
+			return { evaluate: (evaluation) => {
+				const collection = evaluation.sources[0];
+				const selectedKey = evaluation.sources[1];
+				const output = evaluation.outputs[0];
+				if (collection.kind !== "collection" || selectedKey.kind !== "value" || output.kind !== "value") throw new Error("derive.keyed.get resolved invalid input/output kinds.");
+				let affected = evaluation.reset;
+				if (evaluation.reset || keyRevision !== selectedKey.revision) {
+					const candidate = selectedKey.value;
+					if (candidate !== void 0 && typeof candidate !== "string") throw new TypeError("derive.keyed.get key must resolve to a string or undefined.");
+					selected = candidate;
+					affected = true;
+				} else if (sourceRevision !== collection.revision) {
+					const change = collection.change;
+					if (!change || change.kind === "reset") affected = true;
+					else if (selected !== void 0) {
+						for (const changedKey of collectionChange.keys(change)) if (changedKey === selected) {
+							affected = true;
+							break;
+						}
+					}
+				}
+				if (affected) output.output.set(selected === void 0 ? void 0 : collection.read.get(selected));
+				sourceRevision = collection.revision;
+				keyRevision = selectedKey.revision;
+			} };
+		},
+		name: "derive.keyed.get"
 	});
 	return projection;
 };
@@ -3032,23 +2899,35 @@ function createKeyedFilter(source, dependenciesOrPredicate, maybePredicate) {
 	const dependencySpecs = typeof dependenciesOrPredicate === "function" ? void 0 : dependenciesOrPredicate;
 	const predicate = dependencySpecs === void 0 ? dependenciesOrPredicate : maybePredicate;
 	if (typeof predicate !== "function") throw new TypeError("Keyed filter requires a predicate.");
-	return createKeyedTransform(source, dependencySpecs, (value, key, dependencies) => {
-		const included = dependencySpecs === void 0 ? predicate(value, key) : predicate(value, key, dependencies);
-		assertSynchronous(included);
-		if (typeof included !== "boolean") throw new TypeError("Keyed filter predicate must return boolean.");
-		return included ? value : absent;
-	}, Object.is, "derive.keyed.filter");
+	return createKeyedTransform({
+		source,
+		dependencies: dependencySpecs,
+		equality: Object.is,
+		name: "derive.keyed.filter",
+		evaluate: ({ value, key, dependencies }) => {
+			const included = dependencySpecs === void 0 ? predicate(value, key) : predicate(value, key, dependencies);
+			assertSynchronous(included);
+			if (typeof included !== "boolean") throw new TypeError("Keyed filter predicate must return boolean.");
+			return included ? value : keyedAbsent;
+		}
+	});
 }
 function createKeyedCompact(source, dependenciesOrSelect, selectOrEquality, maybeEquality) {
 	const dependencySpecs = typeof dependenciesOrSelect === "function" ? void 0 : dependenciesOrSelect;
 	const select = dependencySpecs === void 0 ? dependenciesOrSelect : selectOrEquality;
 	const equality = dependencySpecs === void 0 ? selectOrEquality : maybeEquality;
 	if (typeof select !== "function") throw new TypeError("Keyed compact requires a selector.");
-	return createKeyedTransform(source, dependencySpecs, (value, key, dependencies) => {
-		const next = dependencySpecs === void 0 ? select(value, key) : select(value, key, dependencies);
-		assertSynchronous(next);
-		return next === void 0 ? absent : next;
-	}, equality, "derive.keyed.compact");
+	return createKeyedTransform({
+		source,
+		dependencies: dependencySpecs,
+		equality,
+		name: "derive.keyed.compact",
+		evaluate: ({ value, key, dependencies }) => {
+			const next = dependencySpecs === void 0 ? select(value, key) : select(value, key, dependencies);
+			assertSynchronous(next);
+			return next === void 0 ? keyedAbsent : next;
+		}
+	});
 }
 const createKeyedSubset = (source, orderedKeys) => {
 	assertKeyedProjection(source, "Keyed subset source");
@@ -3145,9 +3024,198 @@ const createKeyedSubset = (source, orderedKeys) => {
 	});
 	return projection;
 };
+const normalizeGroups = (value) => {
+	const groups = typeof value === "string" ? [value] : value;
+	if (!Array.isArray(groups)) throw new TypeError("derive.keyed.groupBy selector must return a string or an array of strings.");
+	const seen = /* @__PURE__ */ new Set();
+	const result = [];
+	for (const group of groups) {
+		if (typeof group !== "string") throw new TypeError("derive.keyed.groupBy selector must return only string group keys.");
+		if (seen.has(group)) throw new TypeError("derive.keyed.groupBy selector must not return duplicate group keys.");
+		seen.add(group);
+		result.push(group);
+	}
+	return Object.freeze(result);
+};
+function createKeyedGroupBy(source, dependenciesOrSelector, maybeSelector) {
+	assertKeyedProjection(source, "derive.keyed.groupBy source");
+	const dependencySpecs = typeof dependenciesOrSelector === "function" ? void 0 : dependenciesOrSelector;
+	const selector = dependencySpecs === void 0 ? dependenciesOrSelector : maybeSelector;
+	if (typeof selector !== "function") throw new TypeError("derive.keyed.groupBy requires a selector.");
+	const compiled = compileKeyedDependencies(source, dependencySpecs, "derive.keyed.groupBy");
+	const [projection] = defineProcessor({
+		dependencies: compiled.projections,
+		outputs: [{
+			kind: "collection",
+			equality: (previous, next) => {
+				const left = previous;
+				const right = next;
+				return left.length === right.length && left.every((key, index) => key === right[index]);
+			}
+		}],
+		create: () => {
+			const dependencies = createKeyedDependencyRuntime(compiled);
+			const relation = createKeyRelation();
+			const orderIndex = /* @__PURE__ */ new Map();
+			const groupRanks = /* @__PURE__ */ new Map();
+			const refreshOrderIndex = (driver) => {
+				orderIndex.clear();
+				driver.read.ids().forEach((key, index) => orderIndex.set(key, index));
+			};
+			const selectGroups = (driver, sources, key, affected) => {
+				if (!driver.read.has(key)) return false;
+				const value = driver.read.get(key);
+				const dependencyValues = dependencies.resolve(value, key, sources);
+				const selected = dependencySpecs === void 0 ? selector(value, key) : selector(value, key, dependencyValues);
+				assertSynchronous(selected);
+				const next = normalizeGroups(selected);
+				const previous = relation.forward(key) ?? Object.freeze([]);
+				if (!relation.replace(key, next)) return false;
+				for (const group of previous) affected.add(group);
+				for (const group of next) affected.add(group);
+				return true;
+			};
+			const updateGroup = (group, output) => {
+				const reverse = relation.reverse(group);
+				if (!reverse?.size) {
+					groupRanks.delete(group);
+					output.output.remove(group);
+					return;
+				}
+				const members = [...reverse].sort((left, right) => (orderIndex.get(left) ?? Number.MAX_SAFE_INTEGER) - (orderIndex.get(right) ?? Number.MAX_SAFE_INTEGER));
+				const first = members[0];
+				const source = orderIndex.get(first);
+				const selector = relation.forward(first)?.indexOf(group) ?? -1;
+				if (source === void 0 || selector < 0) throw new Error("derive.keyed.groupBy relation is inconsistent with source order.");
+				groupRanks.set(group, {
+					source,
+					selector
+				});
+				output.output.set(group, Object.freeze(members));
+			};
+			const publishGroupOrder = (output) => {
+				const order = [...groupRanks.entries()].sort(([leftKey, left], [rightKey, right]) => {
+					if (left.source !== right.source) return left.source - right.source;
+					if (left.selector !== right.selector) return left.selector - right.selector;
+					return leftKey < rightKey ? -1 : leftKey > rightKey ? 1 : 0;
+				}).map(([group]) => group);
+				output.output.order(order);
+			};
+			const rebuild = (driver, sources, output) => {
+				dependencies.clearBindings();
+				relation.clear();
+				groupRanks.clear();
+				refreshOrderIndex(driver);
+				const affected = /* @__PURE__ */ new Set();
+				for (const key of driver.read.ids()) selectGroups(driver, sources, key, affected);
+				for (const key of output.previous.ids()) affected.add(key);
+				for (const group of affected) updateGroup(group, output);
+				publishGroupOrder(output);
+			};
+			const publishAffected = (affected, output, orderDirty) => {
+				for (const group of affected) updateGroup(group, output);
+				if (orderDirty) publishGroupOrder(output);
+			};
+			const removeSourceKey = (key, affected) => {
+				const previous = relation.forward(key);
+				if (!previous) return false;
+				for (const group of previous) affected.add(group);
+				return relation.delete(key);
+			};
+			const markAllGroups = (output, affected) => {
+				for (const group of relation.rights()) affected.add(group);
+				for (const group of output.previous.ids()) affected.add(group);
+			};
+			return {
+				evaluate: (evaluation) => {
+					const driver = evaluation.sources[0];
+					const output = evaluation.outputs[0];
+					if (driver.kind !== "collection" || output.kind !== "collection") throw new Error("derive.keyed.groupBy requires collection input and output.");
+					dependencies.prepare(evaluation.sources, evaluation.reset);
+					if (evaluation.reset) {
+						rebuild(driver, evaluation.sources, output);
+						dependencies.remember(evaluation.sources);
+						return;
+					}
+					const dirty = /* @__PURE__ */ new Set();
+					const affected = /* @__PURE__ */ new Set();
+					let all = false;
+					let structural = false;
+					let orderDirty = false;
+					if (dependencies.driverChanged(driver)) {
+						const change = driver.change;
+						if (!change || change.kind === "reset") {
+							rebuild(driver, evaluation.sources, output);
+							dependencies.remember(evaluation.sources);
+							return;
+						} else {
+							for (const entry of change.removed) {
+								orderDirty ||= removeSourceKey(entry.key, affected);
+								dependencies.remove(entry.key);
+								dirty.delete(entry.key);
+							}
+							for (const entry of change.added) dirty.add(entry.key);
+							for (const entry of change.updated) dirty.add(entry.key);
+							structural = Boolean(change.added.length || change.removed.length || change.order);
+							orderDirty ||= structural;
+							if (structural) refreshOrderIndex(driver);
+						}
+					}
+					all ||= dependencies.collectInvalidated(evaluation.sources, dirty);
+					if (all) for (const key of driver.read.ids()) dirty.add(key);
+					for (const key of dirty) orderDirty ||= selectGroups(driver, evaluation.sources, key, affected);
+					if (structural) markAllGroups(output, affected);
+					publishAffected(affected, output, orderDirty);
+					dependencies.remember(evaluation.sources);
+				},
+				release: () => {
+					relation.clear();
+					orderIndex.clear();
+					groupRanks.clear();
+					dependencies.release();
+				}
+			};
+		},
+		name: "derive.keyed.groupBy"
+	});
+	return projection;
+}
+const createKeyedSingleton = (source, keyOf, equality = Object.is) => {
+	if (outputKind(source) !== "value") throw new TypeError("derive.keyed.singleton source must be a scalar projection.");
+	if (typeof keyOf !== "function") throw new TypeError("derive.keyed.singleton requires a key selector.");
+	const [projection] = defineProcessor({
+		dependencies: [source],
+		outputs: [{
+			kind: "collection",
+			equality
+		}],
+		create: () => ({ evaluate: (evaluation) => {
+			const scalar = evaluation.sources[0];
+			const output = evaluation.outputs[0];
+			if (scalar.kind !== "value" || output.kind !== "collection") throw new Error("derive.keyed.singleton resolved invalid input/output kinds.");
+			const previous = output.previous.ids();
+			if (scalar.value === void 0) {
+				for (const key of previous) output.output.remove(key);
+				return;
+			}
+			const key = keyOf(scalar.value);
+			assertSynchronous(key);
+			if (typeof key !== "string") throw new TypeError("derive.keyed.singleton key selector must return a string.");
+			for (const previousKey of previous) if (previousKey !== key) output.output.remove(previousKey);
+			output.output.set(key, scalar.value);
+			if (previous.length !== 1 || previous[0] !== key) output.output.order([key]);
+		} }),
+		name: "derive.keyed.singleton"
+	});
+	return projection;
+};
 const keyedDerive = Object.assign(createKeyedDerive, {
 	keys: createKeyedKeys,
 	values: createKeyedValues,
+	entries: createKeyedEntries,
+	get: createKeyedGet,
+	groupBy: createKeyedGroupBy,
+	singleton: createKeyedSingleton,
 	subset: createKeyedSubset,
 	filter: createKeyedFilter,
 	compact: createKeyedCompact
@@ -3475,7 +3543,7 @@ const createCollectionOutput = (binding) => {
 			initialized = true;
 		},
 		emit: (call) => {
-			Array.from(listeners).forEach((listener) => call(listener));
+			Array.from(listeners).forEach((listener) => call(listener, change));
 		},
 		hasConsumers: () => consumers.size > 0,
 		forEachConsumer: (run) => consumers.forEach(run),
@@ -3585,7 +3653,7 @@ const createValueOutput = (binding) => {
 		},
 		emit: (call) => {
 			profile.materialized.notification();
-			Array.from(listeners).forEach((listener) => call(listener));
+			Array.from(listeners).forEach((listener) => call(listener, void 0));
 		},
 		hasConsumers: () => consumers.size > 0,
 		forEachConsumer: (run) => consumers.forEach(run),
@@ -3740,6 +3808,20 @@ const createProcessor = (scheduler, definition, dependencies) => {
 	return processor;
 };
 //#endregion
+//#region core/src/projection/readable/listeners.ts
+/** Exhaustively notifies one projection-readable listener snapshot. */
+const notifyProjectionListeners = (listeners, message) => {
+	const snapshot = [...listeners];
+	const failures = [];
+	for (const listener of snapshot) try {
+		listener();
+	} catch (error) {
+		failures.push(error);
+	}
+	if (failures.length === 1) throw failures[0];
+	if (failures.length) throw new AggregateError(failures, message);
+};
+//#endregion
 //#region core/src/projection/readable/selection.ts
 let activeTracker;
 const trackKey = (key) => {
@@ -3874,7 +3956,7 @@ const createSelectorReadable = (source, selector, equality = Object.is) => {
 			updateCollectionSnapshot();
 			return;
 		}
-		if (evaluate()) Array.from(listeners).forEach((listener) => listener());
+		if (evaluate()) notifyProjectionListeners(listeners, "Projection selector listeners failed.");
 	};
 	const installSource = () => {
 		if (!unsubscribeSource) unsubscribeSource = source.subscribe(onProjectionChange);
@@ -5131,6 +5213,212 @@ const createSourceRegistry = (scheduler) => {
 	};
 };
 //#endregion
+//#region core/src/projection/readable/keyed.ts
+const sameKeys = (previous, next) => previous.length === next.length && previous.every((key, index) => key === next[index]);
+/** Runtime-owned keyed consumer family over one materialized collection output. */
+const createProjectionItems = (source, checkOwner) => {
+	if (source.kind !== "collection") throw new TypeError("Projection items require a keyed collection projection.");
+	let disposed = false;
+	const active = /* @__PURE__ */ new Map();
+	const followers = /* @__PURE__ */ new Map();
+	const waiting = /* @__PURE__ */ new Map();
+	let keysValue = Object.freeze([...source.current().keys()]);
+	let keysRevision = 0;
+	const keyListeners = /* @__PURE__ */ new Set();
+	const check = () => {
+		if (disposed) throw new ProjectionDisposedError();
+		checkOwner();
+	};
+	const notifications = [];
+	const notify = (listeners) => {
+		for (const listener of listeners) notifications.push(listener);
+	};
+	const flushNotifications = () => {
+		notifyProjectionListeners(notifications.splice(0), "Projection item listeners failed.");
+	};
+	const unregisterWaiting = (state) => {
+		const states = waiting.get(state.key);
+		states?.delete(state);
+		if (states?.size === 0) waiting.delete(state.key);
+	};
+	const registerWaiting = (state) => {
+		if (state.tracked || state.ended) return;
+		const states = waiting.get(state.key);
+		if (states) states.add(state);
+		else waiting.set(state.key, new Set([state]));
+	};
+	const publishState = (state, value) => {
+		if (state.ended) return;
+		if (Object.is(state.value, value)) {
+			state.value = value;
+			return;
+		}
+		state.value = value;
+		state.revision++;
+		notify(state.listeners);
+	};
+	const attachActive = (state, value) => {
+		if (state.ended) return;
+		unregisterWaiting(state);
+		state.tracked = true;
+		const canonical = active.get(state.key);
+		if (!canonical) active.set(state.key, state);
+		else if (canonical !== state) {
+			const states = followers.get(state.key);
+			if (states) states.add(state);
+			else followers.set(state.key, new Set([state]));
+		}
+		publishState(state, value);
+	};
+	const terminateState = (state) => {
+		if (state.ended) return;
+		unregisterWaiting(state);
+		state.tracked = false;
+		publishState(state, void 0);
+		state.ended = true;
+	};
+	const statesFor = (key) => {
+		const result = [];
+		const canonical = active.get(key);
+		if (canonical) result.push(canonical);
+		const extra = followers.get(key);
+		if (extra) result.push(...extra);
+		return result;
+	};
+	const terminateKey = (key) => {
+		for (const state of statesFor(key)) terminateState(state);
+		active.delete(key);
+		followers.delete(key);
+	};
+	const activateWaiting = (key, value) => {
+		const states = waiting.get(key);
+		if (!states?.size) return;
+		waiting.delete(key);
+		for (const state of states) attachActive(state, value);
+	};
+	const updateKey = (key, value) => {
+		for (const state of statesFor(key)) publishState(state, value);
+	};
+	const updateKeys = (current) => {
+		const next = Object.freeze([...current.keys()]);
+		if (sameKeys(keysValue, next)) return;
+		keysValue = next;
+		keysRevision++;
+		notify(keyListeners);
+	};
+	const createItem = (key, initial) => {
+		const state = {
+			key,
+			listeners: /* @__PURE__ */ new Set(),
+			tracked: initial !== void 0,
+			ended: false,
+			value: initial?.value,
+			revision: 0
+		};
+		const ensureObserved = () => {
+			if (state.ended || state.tracked) return;
+			const current = source.current();
+			if (current.has(key)) attachActive(state, current.get(key));
+		};
+		state.readable = Object.freeze({
+			current: () => {
+				check();
+				ensureObserved();
+				return state.value;
+			},
+			revision: () => {
+				check();
+				ensureObserved();
+				return state.revision;
+			},
+			subscribe: (listener) => {
+				check();
+				ensureObserved();
+				state.listeners.add(listener);
+				if (!state.tracked && !state.ended) registerWaiting(state);
+				return () => {
+					state.listeners.delete(listener);
+					if (!state.listeners.size && !state.tracked) unregisterWaiting(state);
+				};
+			}
+		});
+		return state;
+	};
+	const reconcile = (current) => {
+		for (const key of [...active.keys()]) if (!current.has(key)) terminateKey(key);
+		else updateKey(key, current.get(key));
+		for (const key of [...waiting.keys()]) if (current.has(key)) activateWaiting(key, current.get(key));
+		updateKeys(current);
+	};
+	const onChange = (change) => {
+		check();
+		const current = source.current();
+		if (!change || change.kind === "reset") {
+			reconcile(current);
+			flushNotifications();
+			return;
+		}
+		for (const entry of change.removed) terminateKey(entry.key);
+		for (const entry of change.added) activateWaiting(entry.key, entry.after);
+		for (const entry of change.updated) updateKey(entry.key, entry.after);
+		if (change.added.length || change.removed.length || change.order) updateKeys(current);
+		flushNotifications();
+	};
+	const stop = source.subscribe(onChange);
+	const keys = Object.freeze({
+		current: () => {
+			check();
+			return keysValue;
+		},
+		revision: () => {
+			check();
+			return keysRevision;
+		},
+		subscribe: (listener) => {
+			check();
+			keyListeners.add(listener);
+			return () => keyListeners.delete(listener);
+		}
+	});
+	return {
+		items: Object.freeze({
+			keys,
+			get: (key) => {
+				check();
+				const canonical = active.get(key);
+				if (canonical) return canonical.readable;
+				const pending = waiting.get(key)?.values().next().value;
+				if (pending) return pending.readable;
+				const current = source.current();
+				if (current.has(key)) {
+					const state = createItem(key, {
+						present: true,
+						value: current.get(key)
+					});
+					active.set(key, state);
+					return state.readable;
+				}
+				return createItem(key).readable;
+			}
+		}),
+		dispose() {
+			if (disposed) return;
+			disposed = true;
+			stop();
+			keyListeners.clear();
+			const known = /* @__PURE__ */ new Set();
+			active.forEach((state) => known.add(state));
+			followers.forEach((states) => states.forEach((state) => known.add(state)));
+			waiting.forEach((states) => states.forEach((state) => known.add(state)));
+			known.forEach((state) => state.listeners.clear());
+			active.clear();
+			followers.clear();
+			waiting.clear();
+			notifications.length = 0;
+		}
+	};
+};
+//#endregion
 //#region core/src/projection/runtime.ts
 const createProjectionRuntime = (options) => {
 	const scheduler = createScheduler(options?.onError ?? (() => void 0));
@@ -5138,6 +5426,30 @@ const createProjectionRuntime = (options) => {
 	const materialized = /* @__PURE__ */ new WeakMap();
 	const publicViews = /* @__PURE__ */ new WeakMap();
 	const scopes = /* @__PURE__ */ new Set();
+	const rootItems = /* @__PURE__ */ new Map();
+	const disposeItemControllers = (registry, failures) => {
+		const controllers = [...registry.values()];
+		registry.clear();
+		for (const controller of controllers) try {
+			controller.dispose();
+		} catch (error) {
+			failures.push(error);
+		}
+	};
+	const disposeScopeConsumers = (state, failures) => {
+		disposeItemControllers(state.items, failures);
+		const subscriptions = [...state.subscriptions];
+		state.subscriptions.clear();
+		for (const unsubscribe of subscriptions) try {
+			unsubscribe();
+		} catch (error) {
+			failures.push(error);
+		}
+	};
+	const throwCleanupFailures = (failures, message) => {
+		if (failures.length === 1) throw failures[0];
+		if (failures.length) throw new AggregateError(failures, message);
+	};
 	const assertAccess = (definition, requester) => {
 		scheduler.assertActive();
 		const owner = definition.owner;
@@ -5223,6 +5535,19 @@ const createProjectionRuntime = (options) => {
 			subscribe: output.subscribe
 		});
 	};
+	const projectionItems = (projection, requester) => {
+		const output = resolveOutput(projection, requester);
+		if (output.kind !== "collection") throw new TypeError("Projection items require a keyed collection projection.");
+		const registry = requester?.items ?? rootItems;
+		const existing = registry.get(output);
+		if (existing) return existing.items;
+		const controller = createProjectionItems(readableSource(projection, requester), () => {
+			if (requester && !requester.active) throw new ProjectionDisposedError();
+			assertOutput(output);
+		});
+		registry.set(output, controller);
+		return controller.items;
+	};
 	const makeReadable = (projection, selector, equality, requester) => {
 		const source = readableSource(projection, requester);
 		return selector ? createSelectorReadable(source, selector, equality) : createDirectReadable(source);
@@ -5256,13 +5581,7 @@ const createProjectionRuntime = (options) => {
 		scheduler.assertIdle();
 		state.active = false;
 		const failures = [];
-		const subscriptions = [...state.subscriptions];
-		state.subscriptions.clear();
-		for (const unsubscribe of subscriptions) try {
-			unsubscribe();
-		} catch (error) {
-			failures.push(error);
-		}
+		disposeScopeConsumers(state, failures);
 		for (let index = state.materialized.length - 1; index >= 0; index--) {
 			const definition = state.materialized[index];
 			const current = materialized.get(definition);
@@ -5277,14 +5596,15 @@ const createProjectionRuntime = (options) => {
 		}
 		state.materialized.length = 0;
 		scopes.delete(state);
-		if (failures.length) throw failures[0];
+		throwCleanupFailures(failures, "Projection scope cleanup failed.");
 	};
 	const createScope = () => {
 		scheduler.assertIdle();
 		const state = {
 			active: true,
 			materialized: [],
-			subscriptions: /* @__PURE__ */ new Set()
+			subscriptions: /* @__PURE__ */ new Set(),
+			items: /* @__PURE__ */ new Map()
 		};
 		scopes.add(state);
 		const assertActive = () => {
@@ -5356,6 +5676,10 @@ const createProjectionRuntime = (options) => {
 				return readProjection(projection, state);
 			},
 			select: scopeSelect,
+			items: (projection) => {
+				assertActive();
+				return projectionItems(projection, state);
+			},
 			update: scopeUpdate,
 			batch: scopeBatch,
 			dispose: () => disposeScope(state)
@@ -5364,6 +5688,7 @@ const createProjectionRuntime = (options) => {
 	return Object.freeze({
 		read: readProjection,
 		select: selectProjection,
+		items: projectionItems,
 		update,
 		batch,
 		scope: createScope,
@@ -5373,16 +5698,11 @@ const createProjectionRuntime = (options) => {
 			const failures = [];
 			for (const scope of scopes) {
 				scope.active = false;
-				const subscriptions = [...scope.subscriptions];
-				scope.subscriptions.clear();
-				for (const unsubscribe of subscriptions) try {
-					unsubscribe();
-				} catch (error) {
-					failures.push(error);
-				}
+				disposeScopeConsumers(scope, failures);
 				scope.materialized.length = 0;
 			}
 			scopes.clear();
+			disposeItemControllers(rootItems, failures);
 			try {
 				sources.dispose();
 			} catch (error) {
@@ -5393,8 +5713,7 @@ const createProjectionRuntime = (options) => {
 			} catch (error) {
 				failures.push(error);
 			}
-			if (failures.length === 1) throw failures[0];
-			if (failures.length) throw new AggregateError(failures, "Projection cleanup failed.");
+			throwCleanupFailures(failures, "Projection cleanup failed.");
 		}
 	});
 };