doxum 0.1.37 → 0.1.39

package/README.md

@@ -322,6 +322,16 @@ const ids = derive.keyed.keys(records);
 const all = derive.keyed.values(records);
 const entries = derive.keyed.entries(records);
 const active = derive.keyed.get(records, activeRecordId);
+const selectedRecords = derive.keyed.subset(
+  records,
+  { selection },
+  ({ selection }) => selection.recordIds
+);
+const selectedRecord = derive.keyed.get(
+  records,
+  { selection },
+  ({ selection }) => selection.activeRecordId
+);
 const rowsFromArray = derive.keyed.from(rowArray, row => row.id);
 const effectiveRows = derive.keyed.merge([baseRows, rowOverrides], { conflict: 'last' });
 const visible = derive.keyed.filter(records, record => record.visible);
@@ -342,6 +352,15 @@ source-relative order. `compact` omits keys whose selected value is `undefined`
 uses its optional equality for present values. `filter` and `compact` support the same
 named global/dynamic keyed dependency object as ordinary `derive.keyed`.
 
+`get` accepts a static key, a key projection, or `(source, dependencies, selectKey, equality?)`.
+`subset` accepts a static ordered key array, a key-array projection, or
+`(source, dependencies, selectOrderedKeys)`. Named selectors run when their declared
+dependencies change; source-only updates use the selected keys to filter deltas.
+Missing requested keys remain live for later adds. Subset preserves source value
+references and requested order, and has no value equality option. Unrelated source
+updates may wake the processor to inspect deltas, but do not rerun selectors or rebuild
+the subset. See [Keyed selection](docs/projections.md#keyed-selection).
+
 `from` turns either a static readonly array or `Projection<readonly V[]>` into a keyed
 projection using `keyOf(value)`. Input order becomes formal keyed order; duplicate keys
 are errors rather than implicit overwrites. Static outer arrays are snapshotted at
@@ -362,6 +381,20 @@ and group keys are ordered by the earliest current source member that belongs to
 If several groups first appear on the same source member, they follow that member's
 selector-result order. Source membership/order changes may therefore reorder group keys.
 `singleton` converts an optional scalar projection into a zero-or-one keyed projection.
+It also computes an optional member directly from named dependencies:
+
+```ts
+const preview = derive.keyed.singleton(
+  { record: activeRecord, enabled: previewEnabled },
+  ({ record, enabled }) => (!enabled || record === undefined ? undefined : [record.id, record])
+);
+```
+
+The named form returns one readonly `[key, value]` tuple or `undefined` for no member.
+`[key, undefined]` is a present member. Optional equality compares values under the
+same key and preserves equivalent references; it cannot suppress a key change.
+Use `singleton` for zero or one result, and `fromEntries` for a complete result with
+arbitrary membership. See [Singleton](docs/projections.md#zero-or-one-keyed-member).
 
 All keyed projection producers use the public `KeyedProjection<K,V>` handle, including
 collection `observe`, `derive.keyed`, `incremental.collection`, and collection leaves

package/dist/advanced.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_transform = require("./transform-D45KWMzj.cjs");
+const require_transform = require("./transform-BnQZlLRP.cjs");
 const require_record = require("./record-ChYUi8PP.cjs");
 //#region core/src/projection/advanced.ts
 const resetCollectionChange = Object.freeze({ kind: "reset" });

package/dist/advanced.js

@@ -1,4 +1,4 @@
-import { D as defineProcessor, S as compileProjectionDependencies, _ as assertSynchronous, r as collectionChange, t as createKeyedTransform, w as collectionView } from "./transform-3mj0eStL.js";
+import { D as defineProcessor, S as compileProjectionDependencies, _ as assertSynchronous, r as collectionChange, t as createKeyedTransform, w as collectionView } from "./transform-Cl7CSsdR.js";
 import { n as isPlainObject } from "./record-B2yRhYsc.js";
 //#region core/src/projection/advanced.ts
 const resetCollectionChange = Object.freeze({ kind: "reset" });

package/dist/index.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_transform = require("./transform-D45KWMzj.cjs");
+const require_transform = require("./transform-BnQZlLRP.cjs");
 const require_record = require("./record-ChYUi8PP.cjs");
 const require_driver = require("./driver-CN3dGxQI.cjs");
 //#region core/src/schema/model.ts
@@ -2883,6 +2883,163 @@ function createKeyedFlatMap(source, dependenciesOrSelect, selectOrEquality, mayb
 	return projection;
 }
 //#endregion
+//#region core/src/projection/keyed/selection.ts
+/** Compiles selection inputs; runtime instances retain only the request and its dependency revisions.
+* Source slot zero belongs to the collection being queried, not to the selection expression.
+*/
+const compileSelection = (input, named, select, normalize, name) => {
+	let projections;
+	let compute;
+	let initial;
+	if (named) {
+		const compiled = require_transform.compileProjectionDependencies(input, name);
+		if (typeof select !== "function") throw new TypeError(`${name} requires a selection callback.`);
+		projections = compiled.projections;
+		const selectValues = select;
+		compute = (sources) => selectValues(require_transform.snapshotProjectionValues(compiled.names, sources, 1));
+	} else if (require_transform.isProjection(input)) {
+		if (require_transform.outputKind(input) !== "value") throw new TypeError(`${name} selection must be a scalar projection.`);
+		projections = [input];
+		compute = (sources) => {
+			const source = sources[1];
+			if (source?.kind !== "value") throw new Error(`${name} resolved a non-scalar selection.`);
+			return source.value;
+		};
+	} else {
+		projections = [];
+		initial = normalize(input);
+	}
+	return {
+		projections,
+		create: () => {
+			let initialized = compute === void 0;
+			let current = initial;
+			const revisions = new Array(projections.length).fill(-1);
+			return {
+				get value() {
+					if (!initialized) throw new Error(`${name} selection was not initialized.`);
+					return current;
+				},
+				refresh(sources) {
+					if (!compute) return false;
+					let dirty = !initialized;
+					for (let index = 0; index < revisions.length; index++) {
+						const source = sources[index + 1];
+						if (source.reset || source.revision !== revisions[index]) dirty = true;
+					}
+					if (!dirty) return false;
+					const candidate = compute(sources);
+					require_transform.assertSynchronous(candidate);
+					const next = normalize(candidate, current);
+					const changed = !initialized || !Object.is(current, next);
+					current = next;
+					initialized = true;
+					for (let index = 0; index < revisions.length; index++) revisions[index] = sources[index + 1].revision;
+					return changed;
+				}
+			};
+		}
+	};
+};
+const normalizeKey = (value) => {
+	if (value !== void 0 && typeof value !== "string") throw new TypeError("derive.keyed.get key must be a string or undefined.");
+	return value;
+};
+const normalizeOrderedKeys = (value, previous) => {
+	if (!Array.isArray(value)) throw new TypeError("derive.keyed.subset ordered keys must be an array.");
+	if (previous && require_transform.sameArray(previous.keys, value)) return previous;
+	const requested = /* @__PURE__ */ new Set();
+	for (const key of value) {
+		if (typeof key !== "string") throw new TypeError("derive.keyed.subset keys must be strings.");
+		if (requested.has(key)) throw new TypeError("derive.keyed.subset keys must not contain duplicate keys.");
+		requested.add(key);
+	}
+	return {
+		keys: require_transform.snapshotArray(value),
+		requested
+	};
+};
+function createKeyedGet(source, input, selectOrEquality, maybeEquality) {
+	const name = "derive.keyed.get";
+	require_transform.assertKeyedProjection(source, `${name} source`);
+	const named = !require_transform.isProjection(input) && typeof input !== "string" && input !== void 0;
+	const selection = compileSelection(input, named, named ? selectOrEquality : void 0, normalizeKey, name);
+	const equality = named ? maybeEquality : selectOrEquality;
+	if (equality !== void 0 && typeof equality !== "function") throw new TypeError(`${name} equality must be a function.`);
+	const [projection] = require_transform.defineProcessor({
+		dependencies: [source, ...selection.projections],
+		outputs: [{
+			kind: "value",
+			equality: equality ?? Object.is
+		}],
+		name,
+		create: () => {
+			const selected = selection.create();
+			return { evaluate: (evaluation) => {
+				const collection = evaluation.sources[0];
+				const output = evaluation.outputs[0];
+				if (collection.kind !== "collection" || output.kind !== "value") throw new Error(`${name} resolved invalid input/output kinds.`);
+				const keyChanged = selected.refresh(evaluation.sources);
+				const key = selected.value;
+				const change = collection.change;
+				if (evaluation.reset || keyChanged || change?.kind === "reset" || key !== void 0 && change && require_transform.collectionChangeTouchesKey(change, key)) output.output.set(key === void 0 ? void 0 : collection.read.get(key));
+			} };
+		}
+	});
+	return projection;
+}
+function createKeyedSubset(source, input, selectOrderedKeys) {
+	const name = "derive.keyed.subset";
+	require_transform.assertKeyedProjection(source, `${name} source`);
+	const selection = compileSelection(input, !require_transform.isProjection(input) && !Array.isArray(input), selectOrderedKeys, normalizeOrderedKeys, name);
+	const [projection] = require_transform.defineProcessor({
+		dependencies: [source, ...selection.projections],
+		outputs: [{
+			kind: "collection",
+			equality: Object.is
+		}],
+		name,
+		create: () => {
+			const selected = selection.create();
+			return { evaluate: (evaluation) => {
+				const driver = evaluation.sources[0];
+				const output = evaluation.outputs[0];
+				if (driver.kind !== "collection" || output.kind !== "collection") throw new Error(`${name} requires collection input and output.`);
+				const keysChanged = selected.refresh(evaluation.sources);
+				const { keys, requested } = selected.value;
+				const change = driver.change;
+				if (evaluation.reset || change?.kind === "reset") {
+					const present = keys.filter((key) => driver.read.has(key));
+					for (const key of present) output.output.set(key, driver.read.get(key));
+					output.output.order(present);
+					return;
+				}
+				let orderChanged = keysChanged;
+				if (keysChanged) {
+					for (const key of output.previous.ids()) if (!requested.has(key) || !driver.read.has(key)) output.output.remove(key);
+					for (const key of keys) if (!output.previous.has(key) && driver.read.has(key)) output.output.set(key, driver.read.get(key));
+				} else if (change) {
+					for (const entry of change.removed) {
+						if (!requested.has(entry.key)) continue;
+						output.output.remove(entry.key);
+						orderChanged = true;
+					}
+					for (const entry of change.added) {
+						if (!requested.has(entry.key)) continue;
+						output.output.set(entry.key, entry.after);
+						orderChanged = true;
+					}
+				}
+				if (change) {
+					for (const entry of change.updated) if (requested.has(entry.key) && (!keysChanged || output.previous.has(entry.key))) output.output.set(entry.key, entry.after);
+				}
+				if (orderChanged) output.output.order(keys.filter((key) => driver.read.has(key)));
+			} };
+		}
+	});
+	return projection;
+}
+//#endregion
 //#region core/src/projection/keyed/composition.ts
 const assertEquality = (equality, role) => {
 	if (equality !== void 0 && typeof equality !== "function") throw new TypeError(`${role} equality must be a function.`);
@@ -3158,50 +3315,59 @@ function createKeyedMerge(sources, options) {
 	});
 	return projection;
 }
-const createKeyedSingleton = (source, keyOf, equality = Object.is) => {
-	if (require_transform.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.");
+function createKeyedSingleton(sourceOrDependencies, compute, equality) {
+	const name = "derive.keyed.singleton";
+	const selection = require_transform.isProjection(sourceOrDependencies) ? {
+		kind: "scalar",
+		source: sourceOrDependencies,
+		keyOf: compute
+	} : {
+		kind: "named",
+		compiled: require_transform.compileProjectionDependencies(sourceOrDependencies, name),
+		computeEntry: compute
+	};
+	if (selection.kind === "scalar" && require_transform.outputKind(selection.source) !== "value") throw new TypeError(`${name} source must be a scalar projection.`);
+	if (typeof compute !== "function") throw new TypeError(`${name} requires a ${selection.kind === "scalar" ? "key selector" : "compute callback"}.`);
+	const outputEquality = assertEquality(equality, name);
 	const [projection] = require_transform.defineProcessor({
-		dependencies: [source],
+		dependencies: selection.kind === "named" ? selection.compiled.projections : [selection.source],
 		outputs: [{
 			kind: "collection",
-			equality
+			equality: outputEquality
 		}],
 		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;
+			if (output.kind !== "collection") throw new Error(`${name} requires a collection output.`);
+			let key;
+			let value;
+			if (selection.kind === "named") {
+				const entry = selection.computeEntry(require_transform.snapshotProjectionValues(selection.compiled.names, evaluation.sources));
+				require_transform.assertSynchronous(entry);
+				if (entry !== void 0) {
+					assertKeyedEntry(entry, name);
+					key = entry[0];
+					value = entry[1];
+				}
+			} else {
+				const scalar = evaluation.sources[0];
+				if (scalar?.kind !== "value") throw new Error(`${name} resolved a non-scalar input.`);
+				value = scalar.value;
+				if (value !== void 0) {
+					key = selection.keyOf(value);
+					require_transform.assertSynchronous(key);
+					if (typeof key !== "string") throw new TypeError(`${name} key selector must return a string.`);
+				}
 			}
-			const key = keyOf(scalar.value);
-			require_transform.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]);
+			const previousKey = output.previous.ids()[0];
+			if (previousKey !== void 0 && previousKey !== key) output.output.remove(previousKey);
+			if (key !== void 0) output.output.set(key, value);
 		} }),
-		name: "derive.keyed.singleton"
+		name
 	});
 	return projection;
-};
+}
 //#endregion
 //#region core/src/projection/derive/keyed.ts
-const compileOrderedKeys = (value, role) => {
-	if (!Array.isArray(value)) throw new TypeError(`${role} must be an array of string keys.`);
-	const seen = /* @__PURE__ */ new Set();
-	for (const key of value) {
-		if (typeof key !== "string") throw new TypeError(`${role} must contain only string keys.`);
-		if (seen.has(key)) throw new TypeError(`${role} must not contain duplicate keys.`);
-		seen.add(key);
-	}
-	return {
-		keys: value,
-		requested: seen
-	};
-};
 function createKeyedDerive(source, dependenciesOrSelect, selectOrEquality, maybeEquality) {
 	const dependencySpecs = typeof dependenciesOrSelect === "function" ? void 0 : dependenciesOrSelect;
 	const select = dependencySpecs === void 0 ? dependenciesOrSelect : selectOrEquality;
@@ -3306,44 +3472,6 @@ const createOrderedSnapshot = (source, name, make) => {
 };
 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) => {
-	require_transform.assertKeyedProjection(source, "derive.keyed.get source");
-	if (require_transform.outputKind(key) !== "value") throw new TypeError("derive.keyed.get key must be a scalar projection.");
-	const [projection] = require_transform.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) affected = require_transform.collectionChangeTouchesKey(change, selected);
-				}
-				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;
-};
 function createKeyedFilter(source, dependenciesOrPredicate, maybePredicate) {
 	const dependencySpecs = typeof dependenciesOrPredicate === "function" ? void 0 : dependenciesOrPredicate;
 	const predicate = dependencySpecs === void 0 ? dependenciesOrPredicate : maybePredicate;
@@ -3378,101 +3506,6 @@ function createKeyedCompact(source, dependenciesOrSelect, selectOrEquality, mayb
 		}
 	});
 }
-const createKeyedSubset = (source, orderedKeys) => {
-	require_transform.assertKeyedProjection(source, "Keyed subset source");
-	const keyProjection = require_transform.isProjection(orderedKeys) ? orderedKeys : void 0;
-	if (keyProjection && require_transform.outputKind(keyProjection) !== "value") throw new TypeError("Keyed subset ordered keys must be a value projection.");
-	const staticSelection = keyProjection ? void 0 : (() => {
-		const compiled = compileOrderedKeys(orderedKeys, "Keyed subset ordered keys");
-		return {
-			keys: Object.freeze([...compiled.keys]),
-			requested: compiled.requested
-		};
-	})();
-	const [projection] = require_transform.defineProcessor({
-		dependencies: keyProjection ? [source, keyProjection] : [source],
-		outputs: [{
-			kind: "collection",
-			equality: Object.is
-		}],
-		create: () => {
-			let keys = staticSelection?.keys;
-			let requested = staticSelection?.requested;
-			let keyRevision = -1;
-			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.subset requires collection input and output.");
-					let keysChanged = false;
-					if (keyProjection) {
-						const sourceContext = evaluation.sources[1];
-						if (sourceContext?.kind !== "value") throw new TypeError("Keyed subset ordered keys resolved to a collection.");
-						if (keys === void 0 || sourceContext.reset || keyRevision !== sourceContext.revision) {
-							const compiled = compileOrderedKeys(sourceContext.value, "Keyed subset ordered keys");
-							keys = compiled.keys;
-							requested = compiled.requested;
-							keyRevision = sourceContext.revision;
-							keysChanged = true;
-						}
-					}
-					if (!keys || !requested) throw new Error("Keyed subset keys were not initialized.");
-					const activeKeys = keys;
-					const activeRequested = requested;
-					const orderedPresentKeys = () => activeKeys.filter((key) => driver.read.has(key));
-					const rebuild = () => {
-						const nextKeys = orderedPresentKeys();
-						for (const key of nextKeys) output.output.set(key, driver.read.get(key));
-						output.output.order(nextKeys);
-					};
-					const reconcileKeys = () => {
-						const nextKeys = orderedPresentKeys();
-						for (const key of output.previous.ids()) if (!activeRequested.has(key) || !driver.read.has(key)) output.output.remove(key);
-						for (const key of nextKeys) if (!output.previous.has(key)) output.output.set(key, driver.read.get(key));
-						output.output.order(nextKeys);
-					};
-					const change = driver.change;
-					if (evaluation.reset || change?.kind === "reset") rebuild();
-					else if (keysChanged) {
-						reconcileKeys();
-						if (change) for (const entry of change.updated) {
-							const key = entry.key;
-							if (activeRequested.has(key) && output.previous.has(key)) output.output.set(key, entry.after);
-						}
-					} else if (change) {
-						let updateOrder = false;
-						for (const entry of change.removed) {
-							const key = entry.key;
-							if (!activeRequested.has(key)) continue;
-							output.output.remove(key);
-							updateOrder = true;
-						}
-						for (const entry of change.added) {
-							const key = entry.key;
-							if (!activeRequested.has(key)) continue;
-							output.output.set(key, entry.after);
-							updateOrder = true;
-						}
-						for (const entry of change.updated) {
-							const key = entry.key;
-							if (activeRequested.has(key)) output.output.set(key, entry.after);
-						}
-						if (updateOrder) output.output.order(orderedPresentKeys());
-					}
-				},
-				release: () => {
-					if (keyProjection) {
-						keys = void 0;
-						requested = void 0;
-						keyRevision = -1;
-					}
-				}
-			};
-		},
-		name: "derive.keyed.subset"
-	});
-	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.");

package/dist/index.d.cts

@@ -33,6 +33,13 @@ declare function observe<S extends ObjectSchema<object>, P>(document: ReadonlyDo
 type ProjectionDependencies = Readonly<Record<string, Projection<unknown>>> & Partial<Record<keyof Projection<unknown>, never>>;
 type ProjectionValues<D extends ProjectionDependencies> = { readonly [K in keyof D]: D[K] extends Projection<infer T> ? T : never };
 //#endregion
+//#region core/src/projection/keyed/selection.d.ts
+type Equality$3<T> = (previous: T, next: T) => boolean;
+declare function createKeyedGet<K extends string, V>(source: KeyedProjection<K, V>, key: NoInfer<K> | undefined | Projection<NoInfer<K> | undefined>, equality?: Equality$3<NoInfer<V> | undefined>): Projection<V | undefined>;
+declare function createKeyedGet<K extends string, V, const D extends ProjectionDependencies>(source: KeyedProjection<K, V>, dependencies: D, selectKey: (values: ProjectionValues<D>) => Synchronous<NoInfer<K> | undefined>, equality?: Equality$3<NoInfer<V> | undefined>): Projection<V | undefined>;
+declare function createKeyedSubset<K extends string, V>(source: KeyedProjection<K, V>, orderedKeys: Projection<readonly NoInfer<K>[]> | readonly NoInfer<K>[]): KeyedProjection<K, V>;
+declare function createKeyedSubset<K extends string, V, const D extends ProjectionDependencies>(source: KeyedProjection<K, V>, dependencies: D, selectOrderedKeys: (values: ProjectionValues<D>) => Synchronous<readonly NoInfer<K>[]>): KeyedProjection<K, V>;
+//#endregion
 //#region core/src/projection/keyed/entries.d.ts
 type KeyedEntries<K extends string, V> = readonly (readonly [K, V])[];
 //#endregion
@@ -53,6 +60,8 @@ declare function createKeyedMerge<K extends string, V>(sources: readonly KeyedPr
   }[], key: NoInfer<K>) => Synchronous<V>;
   readonly equality?: Equality$2<V>;
 }): KeyedProjection<K, V>;
+declare function createKeyedSingleton<const K extends string, V>(source: Projection<V | undefined>, keyOf: (value: V) => K, equality?: Equality$2<V>): KeyedProjection<K, V>;
+declare function createKeyedSingleton<const D extends ProjectionDependencies, K extends string, V>(dependencies: D, computeEntry: (values: ProjectionValues<D>) => Synchronous<readonly [K, V] | undefined>, equality?: Equality$2<V>): KeyedProjection<K, V>;
 //#endregion
 //#region core/src/projection/keyed/flat-map.d.ts
 type Equality$1<V> = (previous: V, next: V) => boolean;
@@ -70,7 +79,7 @@ declare const derive: typeof createValueDerive & {
     keys: <K extends string, V>(source: KeyedProjection<K, V>) => Projection<readonly K[]>;
     values: <K extends string, V>(source: KeyedProjection<K, V>) => Projection<readonly V[]>;
     entries: <K extends string, V>(source: KeyedProjection<K, V>) => Projection<readonly (readonly [K, V])[]>;
-    get: <K extends string, V>(source: KeyedProjection<K, V>, key: Projection<NoInfer<K> | undefined>, equality?: (previous: V | undefined, next: V | undefined) => boolean) => Projection<V | undefined>;
+    get: typeof createKeyedGet;
     from: typeof createKeyedFrom;
     fromEntries: typeof createKeyedFromEntries;
     merge: typeof createKeyedMerge;
@@ -79,8 +88,8 @@ declare const derive: typeof createValueDerive & {
       <K extends string, V, const D extends object, G extends string>(source: KeyedProjection<K, V>, dependencies: D & KeyedDependencies<NoInfer<K>, NoInfer<V>, D>, selector: (value: NoInfer<V>, key: NoInfer<K>, dependencies: KeyedDependencyValues<D>) => Synchronous<G | readonly G[]>): KeyedProjection<G, readonly K[]>;
     };
     flatMap: typeof createKeyedFlatMap;
-    singleton: <K extends string, V>(source: Projection<V | undefined>, keyOf: (value: V) => Synchronous<K>, equality?: (previous: V, next: V) => boolean) => KeyedProjection<K, V>;
-    subset: <K extends string, V>(source: KeyedProjection<K, V>, orderedKeys: Projection<readonly K[]> | readonly K[]) => KeyedProjection<K, V>;
+    singleton: typeof createKeyedSingleton;
+    subset: typeof createKeyedSubset;
     filter: {
       <K extends string, V>(source: KeyedProjection<K, V>, predicate: (value: NoInfer<V>, key: NoInfer<K>) => Synchronous<boolean>): KeyedProjection<K, V>;
       <K extends string, V, const D extends object>(source: KeyedProjection<K, V>, dependencies: D & KeyedDependencies<NoInfer<K>, NoInfer<V>, D>, predicate: (value: NoInfer<V>, key: NoInfer<K>, dependencies: KeyedDependencyValues<D>) => Synchronous<boolean>): KeyedProjection<K, V>;

package/dist/index.d.ts

@@ -33,6 +33,13 @@ declare function observe<S extends ObjectSchema<object>, P>(document: ReadonlyDo
 type ProjectionDependencies = Readonly<Record<string, Projection<unknown>>> & Partial<Record<keyof Projection<unknown>, never>>;
 type ProjectionValues<D extends ProjectionDependencies> = { readonly [K in keyof D]: D[K] extends Projection<infer T> ? T : never };
 //#endregion
+//#region core/src/projection/keyed/selection.d.ts
+type Equality$3<T> = (previous: T, next: T) => boolean;
+declare function createKeyedGet<K extends string, V>(source: KeyedProjection<K, V>, key: NoInfer<K> | undefined | Projection<NoInfer<K> | undefined>, equality?: Equality$3<NoInfer<V> | undefined>): Projection<V | undefined>;
+declare function createKeyedGet<K extends string, V, const D extends ProjectionDependencies>(source: KeyedProjection<K, V>, dependencies: D, selectKey: (values: ProjectionValues<D>) => Synchronous<NoInfer<K> | undefined>, equality?: Equality$3<NoInfer<V> | undefined>): Projection<V | undefined>;
+declare function createKeyedSubset<K extends string, V>(source: KeyedProjection<K, V>, orderedKeys: Projection<readonly NoInfer<K>[]> | readonly NoInfer<K>[]): KeyedProjection<K, V>;
+declare function createKeyedSubset<K extends string, V, const D extends ProjectionDependencies>(source: KeyedProjection<K, V>, dependencies: D, selectOrderedKeys: (values: ProjectionValues<D>) => Synchronous<readonly NoInfer<K>[]>): KeyedProjection<K, V>;
+//#endregion
 //#region core/src/projection/keyed/entries.d.ts
 type KeyedEntries<K extends string, V> = readonly (readonly [K, V])[];
 //#endregion
@@ -53,6 +60,8 @@ declare function createKeyedMerge<K extends string, V>(sources: readonly KeyedPr
   }[], key: NoInfer<K>) => Synchronous<V>;
   readonly equality?: Equality$2<V>;
 }): KeyedProjection<K, V>;
+declare function createKeyedSingleton<const K extends string, V>(source: Projection<V | undefined>, keyOf: (value: V) => K, equality?: Equality$2<V>): KeyedProjection<K, V>;
+declare function createKeyedSingleton<const D extends ProjectionDependencies, K extends string, V>(dependencies: D, computeEntry: (values: ProjectionValues<D>) => Synchronous<readonly [K, V] | undefined>, equality?: Equality$2<V>): KeyedProjection<K, V>;
 //#endregion
 //#region core/src/projection/keyed/flat-map.d.ts
 type Equality$1<V> = (previous: V, next: V) => boolean;
@@ -70,7 +79,7 @@ declare const derive: typeof createValueDerive & {
     keys: <K extends string, V>(source: KeyedProjection<K, V>) => Projection<readonly K[]>;
     values: <K extends string, V>(source: KeyedProjection<K, V>) => Projection<readonly V[]>;
     entries: <K extends string, V>(source: KeyedProjection<K, V>) => Projection<readonly (readonly [K, V])[]>;
-    get: <K extends string, V>(source: KeyedProjection<K, V>, key: Projection<NoInfer<K> | undefined>, equality?: (previous: V | undefined, next: V | undefined) => boolean) => Projection<V | undefined>;
+    get: typeof createKeyedGet;
     from: typeof createKeyedFrom;
     fromEntries: typeof createKeyedFromEntries;
     merge: typeof createKeyedMerge;
@@ -79,8 +88,8 @@ declare const derive: typeof createValueDerive & {
       <K extends string, V, const D extends object, G extends string>(source: KeyedProjection<K, V>, dependencies: D & KeyedDependencies<NoInfer<K>, NoInfer<V>, D>, selector: (value: NoInfer<V>, key: NoInfer<K>, dependencies: KeyedDependencyValues<D>) => Synchronous<G | readonly G[]>): KeyedProjection<G, readonly K[]>;
     };
     flatMap: typeof createKeyedFlatMap;
-    singleton: <K extends string, V>(source: Projection<V | undefined>, keyOf: (value: V) => Synchronous<K>, equality?: (previous: V, next: V) => boolean) => KeyedProjection<K, V>;
-    subset: <K extends string, V>(source: KeyedProjection<K, V>, orderedKeys: Projection<readonly K[]> | readonly K[]) => KeyedProjection<K, V>;
+    singleton: typeof createKeyedSingleton;
+    subset: typeof createKeyedSubset;
     filter: {
       <K extends string, V>(source: KeyedProjection<K, V>, predicate: (value: NoInfer<V>, key: NoInfer<K>) => Synchronous<boolean>): KeyedProjection<K, V>;
       <K extends string, V, const D extends object>(source: KeyedProjection<K, V>, dependencies: D & KeyedDependencies<NoInfer<K>, NoInfer<V>, D>, predicate: (value: NoInfer<V>, key: NoInfer<K>, dependencies: KeyedDependencyValues<D>) => Synchronous<boolean>): KeyedProjection<K, V>;

package/dist/index.js

@@ -1,4 +1,4 @@
-import { A as ownProjections, C as snapshotProjectionValues, D as defineProcessor, E as snapshotCollectionView, M as projectionRef, N as profile, O as defineSource, S as compileProjectionDependencies, T as mapRead, _ as assertSynchronous, a as collectionChangeTouchesKey, b as ProjectionError, c as assertKeyedProjection, d as outputKind, f as createKeyRelation, g as assertScope, h as snapshotArray, i as collectionChangeIntersects, j as producerOf, k as isProjection, l as compileKeyedDependencies, m as sameArray, n as keyedAbsent, o as collectionHasStructuralChange, p as iterableMatchesArray, s as createCollectionChange, t as createKeyedTransform, u as createKeyedDependencyRuntime, v as createScheduler, w as collectionView, x as collectKeyedInvalidation, y as ProjectionDisposedError } from "./transform-3mj0eStL.js";
+import { A as ownProjections, C as snapshotProjectionValues, D as defineProcessor, E as snapshotCollectionView, M as projectionRef, N as profile, O as defineSource, S as compileProjectionDependencies, T as mapRead, _ as assertSynchronous, a as collectionChangeTouchesKey, b as ProjectionError, c as assertKeyedProjection, d as outputKind, f as createKeyRelation, g as assertScope, h as snapshotArray, i as collectionChangeIntersects, j as producerOf, k as isProjection, l as compileKeyedDependencies, m as sameArray, n as keyedAbsent, o as collectionHasStructuralChange, p as iterableMatchesArray, s as createCollectionChange, t as createKeyedTransform, u as createKeyedDependencyRuntime, v as createScheduler, w as collectionView, x as collectKeyedInvalidation, y as ProjectionDisposedError } from "./transform-Cl7CSsdR.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-B7RR-VfX.js";
 //#region core/src/schema/model.ts
@@ -2882,6 +2882,163 @@ function createKeyedFlatMap(source, dependenciesOrSelect, selectOrEquality, mayb
 	return projection;
 }
 //#endregion
+//#region core/src/projection/keyed/selection.ts
+/** Compiles selection inputs; runtime instances retain only the request and its dependency revisions.
+* Source slot zero belongs to the collection being queried, not to the selection expression.
+*/
+const compileSelection = (input, named, select, normalize, name) => {
+	let projections;
+	let compute;
+	let initial;
+	if (named) {
+		const compiled = compileProjectionDependencies(input, name);
+		if (typeof select !== "function") throw new TypeError(`${name} requires a selection callback.`);
+		projections = compiled.projections;
+		const selectValues = select;
+		compute = (sources) => selectValues(snapshotProjectionValues(compiled.names, sources, 1));
+	} else if (isProjection(input)) {
+		if (outputKind(input) !== "value") throw new TypeError(`${name} selection must be a scalar projection.`);
+		projections = [input];
+		compute = (sources) => {
+			const source = sources[1];
+			if (source?.kind !== "value") throw new Error(`${name} resolved a non-scalar selection.`);
+			return source.value;
+		};
+	} else {
+		projections = [];
+		initial = normalize(input);
+	}
+	return {
+		projections,
+		create: () => {
+			let initialized = compute === void 0;
+			let current = initial;
+			const revisions = new Array(projections.length).fill(-1);
+			return {
+				get value() {
+					if (!initialized) throw new Error(`${name} selection was not initialized.`);
+					return current;
+				},
+				refresh(sources) {
+					if (!compute) return false;
+					let dirty = !initialized;
+					for (let index = 0; index < revisions.length; index++) {
+						const source = sources[index + 1];
+						if (source.reset || source.revision !== revisions[index]) dirty = true;
+					}
+					if (!dirty) return false;
+					const candidate = compute(sources);
+					assertSynchronous(candidate);
+					const next = normalize(candidate, current);
+					const changed = !initialized || !Object.is(current, next);
+					current = next;
+					initialized = true;
+					for (let index = 0; index < revisions.length; index++) revisions[index] = sources[index + 1].revision;
+					return changed;
+				}
+			};
+		}
+	};
+};
+const normalizeKey = (value) => {
+	if (value !== void 0 && typeof value !== "string") throw new TypeError("derive.keyed.get key must be a string or undefined.");
+	return value;
+};
+const normalizeOrderedKeys = (value, previous) => {
+	if (!Array.isArray(value)) throw new TypeError("derive.keyed.subset ordered keys must be an array.");
+	if (previous && sameArray(previous.keys, value)) return previous;
+	const requested = /* @__PURE__ */ new Set();
+	for (const key of value) {
+		if (typeof key !== "string") throw new TypeError("derive.keyed.subset keys must be strings.");
+		if (requested.has(key)) throw new TypeError("derive.keyed.subset keys must not contain duplicate keys.");
+		requested.add(key);
+	}
+	return {
+		keys: snapshotArray(value),
+		requested
+	};
+};
+function createKeyedGet(source, input, selectOrEquality, maybeEquality) {
+	const name = "derive.keyed.get";
+	assertKeyedProjection(source, `${name} source`);
+	const named = !isProjection(input) && typeof input !== "string" && input !== void 0;
+	const selection = compileSelection(input, named, named ? selectOrEquality : void 0, normalizeKey, name);
+	const equality = named ? maybeEquality : selectOrEquality;
+	if (equality !== void 0 && typeof equality !== "function") throw new TypeError(`${name} equality must be a function.`);
+	const [projection] = defineProcessor({
+		dependencies: [source, ...selection.projections],
+		outputs: [{
+			kind: "value",
+			equality: equality ?? Object.is
+		}],
+		name,
+		create: () => {
+			const selected = selection.create();
+			return { evaluate: (evaluation) => {
+				const collection = evaluation.sources[0];
+				const output = evaluation.outputs[0];
+				if (collection.kind !== "collection" || output.kind !== "value") throw new Error(`${name} resolved invalid input/output kinds.`);
+				const keyChanged = selected.refresh(evaluation.sources);
+				const key = selected.value;
+				const change = collection.change;
+				if (evaluation.reset || keyChanged || change?.kind === "reset" || key !== void 0 && change && collectionChangeTouchesKey(change, key)) output.output.set(key === void 0 ? void 0 : collection.read.get(key));
+			} };
+		}
+	});
+	return projection;
+}
+function createKeyedSubset(source, input, selectOrderedKeys) {
+	const name = "derive.keyed.subset";
+	assertKeyedProjection(source, `${name} source`);
+	const selection = compileSelection(input, !isProjection(input) && !Array.isArray(input), selectOrderedKeys, normalizeOrderedKeys, name);
+	const [projection] = defineProcessor({
+		dependencies: [source, ...selection.projections],
+		outputs: [{
+			kind: "collection",
+			equality: Object.is
+		}],
+		name,
+		create: () => {
+			const selected = selection.create();
+			return { evaluate: (evaluation) => {
+				const driver = evaluation.sources[0];
+				const output = evaluation.outputs[0];
+				if (driver.kind !== "collection" || output.kind !== "collection") throw new Error(`${name} requires collection input and output.`);
+				const keysChanged = selected.refresh(evaluation.sources);
+				const { keys, requested } = selected.value;
+				const change = driver.change;
+				if (evaluation.reset || change?.kind === "reset") {
+					const present = keys.filter((key) => driver.read.has(key));
+					for (const key of present) output.output.set(key, driver.read.get(key));
+					output.output.order(present);
+					return;
+				}
+				let orderChanged = keysChanged;
+				if (keysChanged) {
+					for (const key of output.previous.ids()) if (!requested.has(key) || !driver.read.has(key)) output.output.remove(key);
+					for (const key of keys) if (!output.previous.has(key) && driver.read.has(key)) output.output.set(key, driver.read.get(key));
+				} else if (change) {
+					for (const entry of change.removed) {
+						if (!requested.has(entry.key)) continue;
+						output.output.remove(entry.key);
+						orderChanged = true;
+					}
+					for (const entry of change.added) {
+						if (!requested.has(entry.key)) continue;
+						output.output.set(entry.key, entry.after);
+						orderChanged = true;
+					}
+				}
+				if (change) {
+					for (const entry of change.updated) if (requested.has(entry.key) && (!keysChanged || output.previous.has(entry.key))) output.output.set(entry.key, entry.after);
+				}
+				if (orderChanged) output.output.order(keys.filter((key) => driver.read.has(key)));
+			} };
+		}
+	});
+	return projection;
+}
+//#endregion
 //#region core/src/projection/keyed/composition.ts
 const assertEquality = (equality, role) => {
 	if (equality !== void 0 && typeof equality !== "function") throw new TypeError(`${role} equality must be a function.`);
@@ -3157,50 +3314,59 @@ function createKeyedMerge(sources, options) {
 	});
 	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.");
+function createKeyedSingleton(sourceOrDependencies, compute, equality) {
+	const name = "derive.keyed.singleton";
+	const selection = isProjection(sourceOrDependencies) ? {
+		kind: "scalar",
+		source: sourceOrDependencies,
+		keyOf: compute
+	} : {
+		kind: "named",
+		compiled: compileProjectionDependencies(sourceOrDependencies, name),
+		computeEntry: compute
+	};
+	if (selection.kind === "scalar" && outputKind(selection.source) !== "value") throw new TypeError(`${name} source must be a scalar projection.`);
+	if (typeof compute !== "function") throw new TypeError(`${name} requires a ${selection.kind === "scalar" ? "key selector" : "compute callback"}.`);
+	const outputEquality = assertEquality(equality, name);
 	const [projection] = defineProcessor({
-		dependencies: [source],
+		dependencies: selection.kind === "named" ? selection.compiled.projections : [selection.source],
 		outputs: [{
 			kind: "collection",
-			equality
+			equality: outputEquality
 		}],
 		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;
+			if (output.kind !== "collection") throw new Error(`${name} requires a collection output.`);
+			let key;
+			let value;
+			if (selection.kind === "named") {
+				const entry = selection.computeEntry(snapshotProjectionValues(selection.compiled.names, evaluation.sources));
+				assertSynchronous(entry);
+				if (entry !== void 0) {
+					assertKeyedEntry(entry, name);
+					key = entry[0];
+					value = entry[1];
+				}
+			} else {
+				const scalar = evaluation.sources[0];
+				if (scalar?.kind !== "value") throw new Error(`${name} resolved a non-scalar input.`);
+				value = scalar.value;
+				if (value !== void 0) {
+					key = selection.keyOf(value);
+					assertSynchronous(key);
+					if (typeof key !== "string") throw new TypeError(`${name} key selector must return a string.`);
+				}
 			}
-			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]);
+			const previousKey = output.previous.ids()[0];
+			if (previousKey !== void 0 && previousKey !== key) output.output.remove(previousKey);
+			if (key !== void 0) output.output.set(key, value);
 		} }),
-		name: "derive.keyed.singleton"
+		name
 	});
 	return projection;
-};
+}
 //#endregion
 //#region core/src/projection/derive/keyed.ts
-const compileOrderedKeys = (value, role) => {
-	if (!Array.isArray(value)) throw new TypeError(`${role} must be an array of string keys.`);
-	const seen = /* @__PURE__ */ new Set();
-	for (const key of value) {
-		if (typeof key !== "string") throw new TypeError(`${role} must contain only string keys.`);
-		if (seen.has(key)) throw new TypeError(`${role} must not contain duplicate keys.`);
-		seen.add(key);
-	}
-	return {
-		keys: value,
-		requested: seen
-	};
-};
 function createKeyedDerive(source, dependenciesOrSelect, selectOrEquality, maybeEquality) {
 	const dependencySpecs = typeof dependenciesOrSelect === "function" ? void 0 : dependenciesOrSelect;
 	const select = dependencySpecs === void 0 ? dependenciesOrSelect : selectOrEquality;
@@ -3305,44 +3471,6 @@ const createOrderedSnapshot = (source, name, make) => {
 };
 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) affected = collectionChangeTouchesKey(change, selected);
-				}
-				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;
-};
 function createKeyedFilter(source, dependenciesOrPredicate, maybePredicate) {
 	const dependencySpecs = typeof dependenciesOrPredicate === "function" ? void 0 : dependenciesOrPredicate;
 	const predicate = dependencySpecs === void 0 ? dependenciesOrPredicate : maybePredicate;
@@ -3377,101 +3505,6 @@ function createKeyedCompact(source, dependenciesOrSelect, selectOrEquality, mayb
 		}
 	});
 }
-const createKeyedSubset = (source, orderedKeys) => {
-	assertKeyedProjection(source, "Keyed subset source");
-	const keyProjection = isProjection(orderedKeys) ? orderedKeys : void 0;
-	if (keyProjection && outputKind(keyProjection) !== "value") throw new TypeError("Keyed subset ordered keys must be a value projection.");
-	const staticSelection = keyProjection ? void 0 : (() => {
-		const compiled = compileOrderedKeys(orderedKeys, "Keyed subset ordered keys");
-		return {
-			keys: Object.freeze([...compiled.keys]),
-			requested: compiled.requested
-		};
-	})();
-	const [projection] = defineProcessor({
-		dependencies: keyProjection ? [source, keyProjection] : [source],
-		outputs: [{
-			kind: "collection",
-			equality: Object.is
-		}],
-		create: () => {
-			let keys = staticSelection?.keys;
-			let requested = staticSelection?.requested;
-			let keyRevision = -1;
-			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.subset requires collection input and output.");
-					let keysChanged = false;
-					if (keyProjection) {
-						const sourceContext = evaluation.sources[1];
-						if (sourceContext?.kind !== "value") throw new TypeError("Keyed subset ordered keys resolved to a collection.");
-						if (keys === void 0 || sourceContext.reset || keyRevision !== sourceContext.revision) {
-							const compiled = compileOrderedKeys(sourceContext.value, "Keyed subset ordered keys");
-							keys = compiled.keys;
-							requested = compiled.requested;
-							keyRevision = sourceContext.revision;
-							keysChanged = true;
-						}
-					}
-					if (!keys || !requested) throw new Error("Keyed subset keys were not initialized.");
-					const activeKeys = keys;
-					const activeRequested = requested;
-					const orderedPresentKeys = () => activeKeys.filter((key) => driver.read.has(key));
-					const rebuild = () => {
-						const nextKeys = orderedPresentKeys();
-						for (const key of nextKeys) output.output.set(key, driver.read.get(key));
-						output.output.order(nextKeys);
-					};
-					const reconcileKeys = () => {
-						const nextKeys = orderedPresentKeys();
-						for (const key of output.previous.ids()) if (!activeRequested.has(key) || !driver.read.has(key)) output.output.remove(key);
-						for (const key of nextKeys) if (!output.previous.has(key)) output.output.set(key, driver.read.get(key));
-						output.output.order(nextKeys);
-					};
-					const change = driver.change;
-					if (evaluation.reset || change?.kind === "reset") rebuild();
-					else if (keysChanged) {
-						reconcileKeys();
-						if (change) for (const entry of change.updated) {
-							const key = entry.key;
-							if (activeRequested.has(key) && output.previous.has(key)) output.output.set(key, entry.after);
-						}
-					} else if (change) {
-						let updateOrder = false;
-						for (const entry of change.removed) {
-							const key = entry.key;
-							if (!activeRequested.has(key)) continue;
-							output.output.remove(key);
-							updateOrder = true;
-						}
-						for (const entry of change.added) {
-							const key = entry.key;
-							if (!activeRequested.has(key)) continue;
-							output.output.set(key, entry.after);
-							updateOrder = true;
-						}
-						for (const entry of change.updated) {
-							const key = entry.key;
-							if (activeRequested.has(key)) output.output.set(key, entry.after);
-						}
-						if (updateOrder) output.output.order(orderedPresentKeys());
-					}
-				},
-				release: () => {
-					if (keyProjection) {
-						keys = void 0;
-						requested = void 0;
-						keyRevision = -1;
-					}
-				}
-			};
-		},
-		name: "derive.keyed.subset"
-	});
-	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.");

package/dist/{transform-D45KWMzj.cjs → transform-BnQZlLRP.cjs}

@@ -186,9 +186,9 @@ const readNamedDependencyEntries = (dependencies, label) => {
 /** Creates the durable dependency value exposed to pure derive callbacks. */
 const snapshotDependencyValue = (source) => source.kind === "value" ? source.value : snapshotCollectionView(source.read);
 /** Builds the same readonly named value boundary for scalar and keyed pure computations. */
-const snapshotProjectionValues = (names, sources) => {
+const snapshotProjectionValues = (names, sources, offset = 0) => {
 	const values = Object.create(null);
-	for (let index = 0; index < names.length; index++) values[names[index]] = snapshotDependencyValue(sources[index]);
+	for (let index = 0; index < names.length; index++) values[names[index]] = snapshotDependencyValue(sources[offset + index]);
 	return Object.freeze(values);
 };
 /** Compiles the shared named Projection dependency declaration contract. */

package/dist/{transform-3mj0eStL.js → transform-Cl7CSsdR.js}

@@ -186,9 +186,9 @@ const readNamedDependencyEntries = (dependencies, label) => {
 /** Creates the durable dependency value exposed to pure derive callbacks. */
 const snapshotDependencyValue = (source) => source.kind === "value" ? source.value : snapshotCollectionView(source.read);
 /** Builds the same readonly named value boundary for scalar and keyed pure computations. */
-const snapshotProjectionValues = (names, sources) => {
+const snapshotProjectionValues = (names, sources, offset = 0) => {
 	const values = Object.create(null);
-	for (let index = 0; index < names.length; index++) values[names[index]] = snapshotDependencyValue(sources[index]);
+	for (let index = 0; index < names.length; index++) values[names[index]] = snapshotDependencyValue(sources[offset + index]);
 	return Object.freeze(values);
 };
 /** Compiles the shared named Projection dependency declaration contract. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "doxum",
-  "version": "0.1.37",
+  "version": "0.1.39",
   "private": false,
   "license": "MIT",
   "description": "Doxum is a typed runtime for complex mutable documents.",

package/skills/doxum-runtime/SKILL.md

@@ -44,8 +44,8 @@ Follow these choices unless the requirement says otherwise:
 3. Use `read` for one synchronous document read and `select` for a document `Readable` with dynamic dependency tracking.
 4. Use `observe` to bring a document/readable/external source into the projection graph.
 5. Use named-object `derive` for pure aggregate values.
-6. Use `derive.keyed.from` to turn an ordered scalar/static collection into a keyed projection. Use `derive.keyed.fromEntries({ inputs }, compute)` when named projections compute a complete keyed result; use `flatMap` when individual keyed parents must recompute independently. Use `derive.keyed.merge` to compose multiple keyed projections; for base + sparse overrides, use `{ conflict: 'last' }`.
-7. Use `derive.keyed` when one keyed source owns output membership/order. Prefer its built-in `keys`, `values`, `entries`, `get`, `from`, `fromEntries`, `merge`, `subset`, `filter`, `compact`, `groupBy`, `flatMap`, and `singleton` primitives over hand-written incremental collection patches.
+6. Use `derive.keyed.from` to turn an ordered scalar/static collection into a keyed projection. Use `derive.keyed.singleton({ inputs }, computeEntry)` for zero or one computed member (`[key, value]` or `undefined`), and `derive.keyed.fromEntries({ inputs }, compute)` for a complete keyed result of arbitrary size; use `flatMap` when individual keyed parents must recompute independently. Use `derive.keyed.merge` to compose multiple keyed projections; for base + sparse overrides, use `{ conflict: 'last' }`.
+7. Use `derive.keyed` when one keyed source owns output membership/order. Use `get(source, dependencies, selectKey)` or `subset(source, dependencies, selectOrderedKeys)` when named projections determine which existing members to read; static keys/key arrays and existing scalar selection projections also work. Prefer the keyed family's built-in primitives over hand-written incremental collection patches.
 8. Express per-output-key joins through `{ source }` for same-key lookup, `{ source, key }` for one mapped key, or `{ source, keys }` for several mapped keys. Let the Runtime own binding and reverse invalidation; do not maintain an application `Map` just to route dependency changes.
 9. Use `runtime.items(keyedProjection)` or `scope.items(...)` for stable per-membership item `Readable`s.
 10. Use `incremental.keyed` for independent retained state per driver key. Use `incremental.collection` or `incremental.group` only when direct incremental output patching or shared retained state is required.

package/skills/doxum-runtime/references/projections.md

@@ -167,9 +167,26 @@ Produces ordered readonly `[key,value]` tuples. Value-only updates publish corre
 
 ```ts
 const active = derive.keyed.get(rows, activeId);
+const fixed = derive.keyed.get(rows, rowId);
+const selected = derive.keyed.get(rows, { selection }, ({ selection }) => selection.activeRowId);
 ```
 
-`activeId` is a scalar `Projection<K | undefined>`. The derive binds exactly the selected key. If the key is absent, the result is `undefined` while the binding remains live for later add.
+`activeId` may be a static `K | undefined` or scalar `Projection<K | undefined>`.
+Named form accepts ordinary projection dependencies, including `{}`, and a synchronous
+callback returning `K | undefined`. The source owns K/V; callback results, key projections
+and equality must agree with those domains. The result is `Projection<V | undefined>`.
+An absent selected key remains requested for later add; undefined selects no key.
+Optional result equality defaults to `Object.is` and retains equivalent references.
+
+Named selectors run on initialization, declared dependency changes or recovery. Source
+updates inspect deltas for the selected key; source-only reorder is ignored. Unrelated
+updates can wake the processor but do not rerun selectors or change output. Keyed named
+dependencies are whole snapshots: explicitly declaring the queried source as a named
+dependency also makes its changes relevant to the selector. Public Runtime reads and
+driver-relative dependency specs are not allowed inside this protocol. Callback, key
+validation and equality failures follow normal recovery without partial publication.
+Definitions are lazy, scoped and isolated per runtime; current batch reads and deferred
+notifications use the ordinary runtime contract.
 
 Use this for active entity, editor target, selected record, or current-cell lookups.
 
@@ -242,11 +259,32 @@ Value-only source changes only recompute affected keys. Structural or source-ord
 
 ```ts
 const visibleRows = derive.keyed.subset(rows, orderedVisibleIds);
+const selectedRows = derive.keyed.subset(rows, { selection }, ({ selection }) => selection.rowIds);
 ```
 
 Output order is `orderedVisibleIds ∩ source membership`. Missing requested ids remain latent and appear later if the source adds them. Duplicate requested keys are invalid. Values are source values and are not re-derived.
 
-Use `subset` when another projection or static array already owns the requested order.
+The second argument may be a static readonly key array or a scalar key-array projection.
+Named form accepts ordinary projection dependencies (including `{}`) and a synchronous
+callback returning `readonly K[]`. The source owns K/V; selection cannot widen the key
+domain. `[]` is empty; undefined, malformed arrays and duplicate keys (even absent ones)
+are errors. Static arrays are snapshotted at definition time; dynamic arrays are captured
+when accepted. Equal sequences reuse request state, regardless of array identity.
+
+Dependency changes rerun the selector. Source-only updates filter the existing request;
+they do not rerun selectors. Selected values update with the source's original identity,
+missing keys join when added, and source-only reorder is ignored. Subset has no value
+or keys equality option. A selection change and value change in one evaluation both
+take effect, even when the key sequence remains equal. Reset/recovery, scope disposal,
+runtime isolation and notification-boundary item lifecycles follow the normal contract.
+
+Each get/subset uses one processor and one output. Source-delta filtering can cost
+O(delta size + selection dependency count); the processor can wake for unrelated source
+changes. It does not scan all source members. Structural changes/reset may scan requested
+keys and prior output. Selection changes pay callback, normalization and dependency
+snapshot costs. Named keyed dependencies are whole snapshots; including the queried
+source explicitly can rerun the selector on its changes. Use `get`/`subset` to select
+existing members and `singleton`/`fromEntries` to construct new keyed results.
 
 ### `filter`
 
@@ -280,9 +318,41 @@ Use this for domain-neutral reverse indexing such as record→sections, node→e
 
 ```ts
 const activeEntity = derive.keyed.singleton(activeRecord, record => record.id);
+
+const preview = derive.keyed.singleton(
+  { record: activeRecord, enabled: previewEnabled },
+  ({ record, enabled }) => (!enabled || record === undefined ? undefined : [record.id, record])
+);
+
+const fixed = derive.keyed.singleton({}, () => ['fixed', 1]);
 ```
 
-Input is `Projection<V | undefined>`. `undefined` becomes empty membership; a present value becomes exactly one keyed entry.
+Scalar form accepts `Projection<V | undefined>` and `keyOf(value)`. Undefined sources
+are empty and skip `keyOf`; present values are preserved as one member. Named form
+accepts ordinary `derive` dependencies, including `{}`, and a synchronous callback
+returning a readonly `[K, V]` tuple or `undefined`. `undefined` means no member;
+`[key, undefined]` is a present member. Keys must be strings. `null`, `false`, `[]`,
+malformed tuples and thenables are errors. Formal order is empty or the sole key.
+
+Optional equality defaults to `Object.is` and compares same-key values, retaining equal
+references. Changing the key removes the old member and adds the new one regardless of
+value equality. Typed equality participates in inference and must accept every emitted
+variant; inline tuples, optional branches and union values do not require an output
+projection annotation. Use a declared value type or `as const` when object discriminants
+would otherwise widen under normal TypeScript rules.
+
+Dependencies are captured at definition time; callback values are readonly. Keyed named
+inputs are whole durable map snapshots. For a precise active-entry dependency, compose
+`derive.keyed.get(records, activeId)` first; driver-relative specs do not belong here.
+Public Runtime reads in callbacks remain forbidden. Callback, validation and equality
+failures install no partial output and follow normal processor recovery. Definitions
+are lazy, isolated per runtime and compatible with scopes. Current reads can evaluate
+multiple times in a batch; item lifecycles end only at the notification boundary.
+
+Both forms use one processor and one collection output. Singleton's member coordination
+is O(1), plus callback and dependency snapshot costs. Use this primitive for optional
+previews, selections and active members instead of manually building zero-or-one arrays
+or staging collection patches. Use `fromEntries` when more than one member is possible.
 
 ## Runtime read/select
 

package/skills/doxum-runtime/references/public-api.md

@@ -331,7 +331,7 @@ The keyed family:
 | `merge`       | Multiple keyed projections → union with explicit conflict policy |
 | `flatMap`     | Ordered pure one-to-many keyed expansion                         |
 | `groupBy`     | One-to-many reverse index                                        |
-| `singleton`   | Optional scalar → zero-or-one keyed projection                   |
+| `singleton`   | Optional scalar or named dependencies → zero-or-one keyed result |
 | `subset`      | Externally ordered keyed subset                                  |
 | `filter`      | Predicate-controlled membership preserving source values         |
 | `compact`     | Map values while dropping `undefined` results                    |
@@ -345,7 +345,9 @@ derive.keyed(source, dependencies, (value, key, dependencies) => result, equalit
 derive.keyed.keys(source): Projection<readonly K[]>
 derive.keyed.values(source): Projection<readonly V[]>
 derive.keyed.entries(source): Projection<readonly (readonly [K,V])[]>
-derive.keyed.get(source, keyProjection, equality?): Projection<V | undefined>
+derive.keyed.get(source, keyOrProjection, equality?): Projection<V | undefined>
+derive.keyed.get(source, dependencies, selectKey, equality?): Projection<V | undefined>
+// selectKey(readonlyNamedValues) returns Synchronous<K | undefined>
 derive.keyed.from(source: Projection<readonly V[]>, keyOf, equality?): KeyedProjection<K,V>
 derive.keyed.from(source: readonly V[], keyOf, equality?): KeyedProjection<K,V>
 derive.keyed.fromEntries(dependencies, compute, equality?): KeyedProjection<K,V>
@@ -354,6 +356,8 @@ derive.keyed.fromEntries(dependencies, compute, equality?): KeyedProjection<K,V>
 derive.keyed.merge(sources, { conflict: 'error' | 'first' | 'last', equality? }): KeyedProjection<K,V>
 derive.keyed.merge(sources, { conflict: 'resolve', resolve, equality? }): KeyedProjection<K,V>
 derive.keyed.subset(source, orderedKeysOrProjection): KeyedProjection<K,V>
+derive.keyed.subset(source, dependencies, selectOrderedKeys): KeyedProjection<K,V>
+// selectOrderedKeys(readonlyNamedValues) returns Synchronous<readonly K[]>
 derive.keyed.filter(source, predicate): KeyedProjection<K,V>
 derive.keyed.filter(source, dependencies, predicate): KeyedProjection<K,V>
 derive.keyed.compact(source, selector, equality?): KeyedProjection<K,T>
@@ -364,12 +368,18 @@ derive.keyed.flatMap(source, dependencies, select, equality?): KeyedProjection<O
 derive.keyed.groupBy(source, selector): KeyedProjection<GroupKey, readonly K[]>
 derive.keyed.groupBy(source, dependencies, selector): KeyedProjection<GroupKey, readonly K[]>
 derive.keyed.singleton(sourceProjection, keyOf, equality?): KeyedProjection<K,V>
+derive.keyed.singleton(dependencies, computeEntry, equality?): KeyedProjection<K,V>
+// computeEntry(readonlyNamedValues) returns Synchronous<readonly [K,V] | undefined>
 ```
 
+`get` and `subset` accept named ordinary projection dependencies, including `{}`, to compute one optional key or an ordered key array. Source defines K/V; selectors and equality cannot widen them. Source-only updates filter deltas without rerunning selectors. Missing keys remain requested. Subset preserves source values and requested order, rejects duplicate keys, and has no equality option. Equal key sequences reuse request state. Get's optional result equality defaults to `Object.is`. Callback/validation/equality failure follows normal recovery without partial publication. Processors may inspect unrelated source deltas; this is not scheduler-level key subscription. A keyed named dependency is a whole snapshot, including when it is also the queried source. See [Precise scalar lookup](projections.md#precise-scalar-lookup) and [Subset](projections.md#subset).
+
 `from` uses `keyOf(value)` as member identity and preserves the input array's formal order. Duplicate keys are processor errors; there is no silent first/last overwrite. Static arrays are shallow-snapshotted at definition creation while `keyOf` remains lazy. For a scalar array projection, each scalar publication is scanned because the source has no per-entry delta. Equality defaults to `Object.is`; an equality-equivalent value under the same key retains the previous published value identity.
 
 `fromEntries` accepts the same named projection object as `derive`, including `{}` and keyed projections. Single inputs use `{ source }`; direct-source, static-array and driver-relative dependency specs are not overloads. The callback receives readonly named values and returns the complete ordered tuple array synchronously. Empty arrays mean no members; missing keys are removed; present `undefined` is valid. Duplicate string keys, malformed tuples and callback/equality failures follow processor error/recovery rules without partial installation. Per-entry equality defaults to `Object.is` and retains equivalent value references without suppressing membership or order. Computation scans the complete old/new result, while downstream publication is incremental. A keyed dependency is a whole collection, not automatically tracked by `get`; compose `derive.keyed.get` for precise scalar lookup. See [Projections](projections.md#keyed-results-from-named-dependencies) for lifecycle, cost and examples.
 
+`singleton` returns at most one member. Scalar form accepts `Projection<V | undefined>`, omits undefined sources and preserves the source value under `keyOf(value)`. Named form uses ordinary `derive` dependencies (including `{}`), returning `[key, value]` or `undefined`; `[key, undefined]` is present. Keys are strings; empty arrays, null, false, malformed tuples and thenables are rejected. Typed equality participates in inference and compares same-key values only, preserving equivalent references. Key changes remain membership changes. Both forms share normal processor recovery and notification-boundary item lifecycles. Keyed named inputs are whole snapshots; compose `derive.keyed.get` for precise lookup. See [Singleton](projections.md#singleton) for examples and costs.
+
 `merge` has union membership and requires an explicit conflict policy. `first` and `last` use source-list priority. `error` rejects overlapping keys. `resolve` calls `resolve(contributions, key)` only for keys with two or more current contributions; contributions are ordered by source priority and have `{ sourceIndex, value }`. A single contribution passes through unchanged. The source list is fixed at definition time.
 
 Merged formal order is always `stableUnique(S0.ids() ++ S1.ids() ++ ... ++ Sn.ids())`, independent of which source supplies the effective value. Therefore `derive.keyed.merge([base, overrides], { conflict: 'last' })` is the standard base + sparse-override composition: override values win for shared keys without moving their base positions; override-only keys are included after earlier-source first occurrences. Removing an override does not end the merged membership lifecycle while another source still contains the key.

package/skills/doxum-runtime/references/recipes.md

@@ -323,10 +323,31 @@ Shared keys use override values while keeping the first formal position from `ba
 ```ts
 const activeId = input<RowId | undefined>(undefined);
 const activeRow = derive.keyed.get(rows, activeId);
+const selectedRow = derive.keyed.get(rows, { selection }, ({ selection }) => selection.activeRowId);
 ```
 
 The binding remains meaningful while the selected key is absent and reacts if that key appears later.
 
+Use a static key directly for a fixed lookup. Use named dependencies when an existing
+selection projection owns the key; an intermediate scalar derive is unnecessary.
+
+## Ordered selected members
+
+```ts
+const selectedNodes = derive.keyed.subset(
+  graph.node,
+  { selection },
+  ({ selection }) => selection.nodeIds
+);
+```
+
+Output follows `selection.nodeIds` order, including requested members that appear later
+in the source. Selected source values pass through by identity. Source-only updates do
+not rerun the selector; a new selection with equal keys does not produce a fake change.
+Use `[]` to select nothing and avoid duplicate keys. Keep source out of named dependencies
+unless computing the keys actually needs the entire source collection. The processor can
+still inspect unrelated source deltas; it does not rebuild the whole subset for them.
+
 ## Reverse index / groupBy
 
 ```ts
@@ -337,13 +358,24 @@ Output is keyed by section id; each value is ordered source record ids. Use this
 
 Group keys follow first appearance in the source's formal order. If one source record returns several groups, those groups use the selector's returned order for that record when they first appear together.
 
-## Optional scalar to keyed singleton
+## Zero or one keyed member
 
 ```ts
 const activeRecordCollection = derive.keyed.singleton(activeRecord, record => record.id);
+
+const preview = derive.keyed.singleton(
+  { record: activeRecord, enabled: previewEnabled },
+  ({ record, enabled }) => (!enabled || record === undefined ? undefined : [record.id, record])
+);
 ```
 
-`undefined` becomes empty membership; present value becomes one keyed member.
+Scalar form turns an undefined source into empty membership. Named form returns a
+tuple for a present member or `undefined` for no member; `[key, undefined]` is present.
+Use the named form when several projections determine the member. Pass a value equality
+callback when constructing equivalent objects; it preserves same-key value references
+but cannot suppress a key change. For a precise dynamic input, obtain `activeRecord`
+with `derive.keyed.get(records, activeId)`. Do not wrap dependencies in an intermediate
+scalar derive or use `fromEntries` solely to wrap one tuple in an array.
 
 ## Stable keyed item Readables