doxum 0.1.29 → 0.1.31

package/README.md

@@ -300,6 +300,8 @@ 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 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);
 const orderedVisible = derive.keyed.subset(records, visibleIds);
 const definedContent = derive.keyed.compact(records, record => record.content);
@@ -318,10 +320,26 @@ 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`.
 
+`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
+definition creation, while key selection remains lazy. Same-key equality-equivalent
+values retain the previous published identity.
+
+`merge` combines a fixed list of keyed sources with union membership and an explicit
+`error`, `first`, `last`, or `resolve` conflict policy. Its formal order is the stable
+first occurrence from the sources' formal orders, independent of which source supplies
+the effective value. `derive.keyed.merge([base, overrides], { conflict: 'last' })` is
+therefore the standard sparse-override composition: shared override values win without
+moving their base positions, override-only keys join the union, and removing an override
+falls back to the base without breaking the key's merged membership lifecycle.
+
 `groupBy` is the general reverse-index primitive. A source entry may return one group
 key or several; each output bucket contains source keys in the source's formal order,
-and group order follows first appearance in that same order. `singleton` converts an
-optional scalar projection into a zero-or-one keyed projection.
+and group keys are ordered by the earliest current source member that belongs to them.
+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.
 
 All keyed projection producers use the public `KeyedProjection<K,V>` handle, including
 collection `observe`, `derive.keyed`, `incremental.collection`, and collection leaves
@@ -599,8 +617,9 @@ Builds produce root `dist` ESM/CJS/declarations for `doxum`,
 The runtime shares one transaction lifecycle; complete mutation operations are
 organized by domain under `core/src/mutation/operations`, with access, first-touch
 recording and publication retaining their own responsibilities.
-The published [runtime skill](skills/doxum-runtime/SKILL.md) includes English and
-Chinese application guidance.
+The published [runtime skill](skills/doxum-runtime/SKILL.md) is a source-free consumer
+contract with complete public API routing, lifecycle guidance, recipes, integration
+semantics and separate maintainer invariants.
 
 ## Release
 

package/dist/index.cjs

@@ -2775,6 +2775,279 @@ const isExternalSource = (source) => {
 	return (candidate.kind === "value" || candidate.kind === "collection") && typeof candidate.current === "function" && typeof candidate.revision === "function" && typeof candidate.subscribe === "function";
 };
 //#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.`);
+	return equality ?? Object.is;
+};
+const compileMergeOptions = (options) => {
+	if (options === null || typeof options !== "object") throw new TypeError("derive.keyed.merge requires conflict options.");
+	const equality = assertEquality(options.equality, "derive.keyed.merge");
+	switch (options.conflict) {
+		case "error":
+		case "first":
+		case "last":
+			if ("resolve" in options && options.resolve !== void 0) throw new TypeError("derive.keyed.merge resolve is only valid when conflict is \"resolve\".");
+			return Object.freeze({
+				conflict: options.conflict,
+				equality
+			});
+		case "resolve":
+			if (typeof options.resolve !== "function") throw new TypeError("derive.keyed.merge requires a resolver when conflict is \"resolve\".");
+			return Object.freeze({
+				conflict: options.conflict,
+				equality,
+				resolve: options.resolve
+			});
+		default: throw new TypeError("derive.keyed.merge conflict must be \"error\", \"first\", \"last\", or \"resolve\".");
+	}
+};
+const assertCollectionSources = (sources, expected) => {
+	if (sources.length !== expected) throw new Error("derive.keyed.merge resolved an invalid dependency count.");
+	for (const source of sources) if (source.kind !== "collection") throw new Error("derive.keyed.merge requires collection inputs.");
+};
+function createKeyedFrom(source, keyOf, equality) {
+	if (typeof keyOf !== "function") throw new TypeError("derive.keyed.from requires a key selector.");
+	const outputEquality = assertEquality(equality, "derive.keyed.from");
+	let dependency;
+	let staticValues;
+	if (require_transform.isProjection(source)) {
+		if (require_transform.outputKind(source) !== "value") throw new TypeError("derive.keyed.from source projection must be scalar.");
+		dependency = source;
+	} else {
+		if (!Array.isArray(source)) throw new TypeError("derive.keyed.from source must be a scalar projection or readonly array.");
+		staticValues = require_transform.snapshotArray(source);
+	}
+	const [projection] = require_transform.defineProcessor({
+		dependencies: dependency ? [dependency] : [],
+		outputs: [{
+			kind: "collection",
+			equality: outputEquality
+		}],
+		create: () => ({ evaluate: (evaluation) => {
+			const output = evaluation.outputs[0];
+			if (output.kind !== "collection") throw new Error("derive.keyed.from requires a collection output.");
+			let values = staticValues;
+			if (dependency) {
+				const scalar = evaluation.sources[0];
+				if (scalar?.kind !== "value") throw new Error("derive.keyed.from resolved a non-scalar input.");
+				if (!Array.isArray(scalar.value)) throw new TypeError("derive.keyed.from source value must be an array.");
+				values = scalar.value;
+			}
+			if (!values) throw new Error("derive.keyed.from has no source values.");
+			const seen = /* @__PURE__ */ new Set();
+			const order = new Array(values.length);
+			for (let index = 0; index < values.length; index++) {
+				const value = values[index];
+				const key = keyOf(value);
+				require_transform.assertSynchronous(key);
+				if (typeof key !== "string") throw new TypeError("derive.keyed.from key selector must return a string.");
+				if (seen.has(key)) throw new TypeError(`derive.keyed.from duplicate key ${JSON.stringify(key)}.`);
+				seen.add(key);
+				order[index] = key;
+				output.output.set(key, value);
+			}
+			for (const previousKey of output.previous.ids()) if (!seen.has(previousKey)) output.output.remove(previousKey);
+			output.output.order(order);
+		} }),
+		name: "derive.keyed.from"
+	});
+	return projection;
+}
+function createKeyedMerge(sources, options) {
+	if (!Array.isArray(sources)) throw new TypeError("derive.keyed.merge sources must be an array of keyed projections.");
+	const capturedSources = require_transform.snapshotArray(sources);
+	for (let index = 0; index < capturedSources.length; index++) require_transform.assertKeyedProjection(capturedSources[index], `derive.keyed.merge source ${index}`);
+	const compiled = compileMergeOptions(options);
+	const [projection] = require_transform.defineProcessor({
+		dependencies: capturedSources,
+		outputs: [{
+			kind: "collection",
+			equality: compiled.equality
+		}],
+		create: () => {
+			const revisions = new Array(capturedSources.length).fill(-1);
+			const remember = (sources) => {
+				for (let index = 0; index < revisions.length; index++) revisions[index] = sources[index].revision;
+			};
+			const writeEffective = (sources, output, key) => {
+				if (compiled.conflict === "first") {
+					for (let sourceIndex = 0; sourceIndex < sources.length; sourceIndex++) {
+						const source = sources[sourceIndex];
+						if (source.kind !== "collection") throw new Error("derive.keyed.merge requires collection inputs.");
+						if (!source.read.has(key)) continue;
+						output.set(key, source.read.get(key));
+						return;
+					}
+					output.remove(key);
+					return;
+				}
+				let present = false;
+				let selected;
+				let firstSourceIndex = -1;
+				let contributions;
+				for (let sourceIndex = 0; sourceIndex < sources.length; sourceIndex++) {
+					const source = sources[sourceIndex];
+					if (source.kind !== "collection") throw new Error("derive.keyed.merge requires collection inputs.");
+					if (!source.read.has(key)) continue;
+					const value = source.read.get(key);
+					if (!present) {
+						present = true;
+						selected = value;
+						firstSourceIndex = sourceIndex;
+						continue;
+					}
+					if (compiled.conflict === "error") throw new TypeError(`derive.keyed.merge duplicate key ${JSON.stringify(key)}.`);
+					if (compiled.conflict === "last") {
+						selected = value;
+						continue;
+					}
+					if (!contributions) contributions = [Object.freeze({
+						sourceIndex: firstSourceIndex,
+						value: selected
+					}), Object.freeze({
+						sourceIndex,
+						value
+					})];
+					else contributions.push(Object.freeze({
+						sourceIndex,
+						value
+					}));
+				}
+				if (!present) {
+					output.remove(key);
+					return;
+				}
+				if (compiled.conflict === "resolve" && contributions) {
+					const resolved = compiled.resolve(Object.freeze(contributions), key);
+					require_transform.assertSynchronous(resolved);
+					output.set(key, resolved);
+					return;
+				}
+				output.set(key, selected);
+			};
+			const rebuild = (sources, output, previousIds, reset) => {
+				const seen = /* @__PURE__ */ new Set();
+				const order = [];
+				const conflicts = compiled.conflict === "resolve" ? /* @__PURE__ */ new Set() : void 0;
+				for (let sourceIndex = 0; sourceIndex < sources.length; sourceIndex++) {
+					const source = sources[sourceIndex];
+					if (source.kind !== "collection") throw new Error("derive.keyed.merge requires collection inputs.");
+					for (const key of source.read.ids()) {
+						const duplicate = seen.has(key);
+						if (!duplicate) {
+							seen.add(key);
+							order.push(key);
+						}
+						if (compiled.conflict === "error") {
+							if (duplicate) throw new TypeError(`derive.keyed.merge duplicate key ${JSON.stringify(key)}.`);
+							output.set(key, source.read.get(key));
+							continue;
+						}
+						if (compiled.conflict === "first") {
+							if (!duplicate) output.set(key, source.read.get(key));
+							continue;
+						}
+						if (compiled.conflict === "last") {
+							output.set(key, source.read.get(key));
+							continue;
+						}
+						if (!duplicate) output.set(key, source.read.get(key));
+						else conflicts.add(key);
+					}
+				}
+				if (conflicts) for (const key of conflicts) writeEffective(sources, output, key);
+				if (!reset) {
+					for (const previousKey of previousIds) if (!seen.has(previousKey)) output.remove(previousKey);
+				}
+				output.order(order);
+			};
+			const rebuildOrder = (sources, output) => {
+				const seen = /* @__PURE__ */ new Set();
+				const order = [];
+				for (const source of sources) {
+					if (source.kind !== "collection") throw new Error("derive.keyed.merge requires collection inputs.");
+					for (const key of source.read.ids()) {
+						if (seen.has(key)) continue;
+						seen.add(key);
+						order.push(key);
+					}
+				}
+				output.order(order);
+			};
+			return {
+				evaluate: (evaluation) => {
+					const output = evaluation.outputs[0];
+					if (output.kind !== "collection") throw new Error("derive.keyed.merge requires a collection output.");
+					assertCollectionSources(evaluation.sources, capturedSources.length);
+					if (evaluation.reset) {
+						rebuild(evaluation.sources, output.output, output.previous.ids(), true);
+						remember(evaluation.sources);
+						return;
+					}
+					const affected = /* @__PURE__ */ new Set();
+					let fullRebuild = false;
+					let orderDirty = false;
+					for (let sourceIndex = 0; sourceIndex < evaluation.sources.length; sourceIndex++) {
+						const source = evaluation.sources[sourceIndex];
+						if (revisions[sourceIndex] === source.revision) continue;
+						if (source.kind !== "collection") throw new Error("derive.keyed.merge requires collection inputs.");
+						const change = source.change;
+						if (!change || change.kind === "reset") {
+							fullRebuild = true;
+							continue;
+						}
+						for (const entry of change.added) affected.add(entry.key);
+						for (const entry of change.updated) affected.add(entry.key);
+						for (const entry of change.removed) affected.add(entry.key);
+						if (Boolean(change.added.length || change.removed.length || change.order)) orderDirty = true;
+					}
+					if (fullRebuild) {
+						rebuild(evaluation.sources, output.output, output.previous.ids(), false);
+						remember(evaluation.sources);
+						return;
+					}
+					for (const key of affected) writeEffective(evaluation.sources, output.output, key);
+					if (orderDirty) rebuildOrder(evaluation.sources, output.output);
+					remember(evaluation.sources);
+				},
+				release: () => revisions.fill(-1)
+			};
+		},
+		name: "derive.keyed.merge"
+	});
+	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.");
+	const [projection] = require_transform.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);
+			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]);
+		} }),
+		name: "derive.keyed.singleton"
+	});
+	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.`);
@@ -3187,7 +3460,8 @@ function createKeyedGroupBy(source, dependenciesOrSelector, maybeSelector) {
 							return;
 						} else {
 							for (const entry of change.removed) {
-								orderDirty ||= removeSourceKey(entry.key, affected);
+								const changed = removeSourceKey(entry.key, affected);
+								orderDirty ||= changed;
 								dependencies.remove(entry.key);
 								dirty.delete(entry.key);
 							}
@@ -3200,7 +3474,10 @@ function createKeyedGroupBy(source, dependenciesOrSelector, maybeSelector) {
 					}
 					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);
+					for (const key of dirty) {
+						const changed = selectGroups(driver, evaluation.sources, key, affected);
+						orderDirty ||= changed;
+					}
 					if (structural) markAllGroups(output, affected);
 					publishAffected(affected, output, orderDirty);
 					dependencies.remember(evaluation.sources);
@@ -3217,40 +3494,13 @@ function createKeyedGroupBy(source, dependenciesOrSelector, maybeSelector) {
 	});
 	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.");
-	const [projection] = require_transform.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);
-			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]);
-		} }),
-		name: "derive.keyed.singleton"
-	});
-	return projection;
-};
 const keyedDerive = Object.assign(createKeyedDerive, {
 	keys: createKeyedKeys,
 	values: createKeyedValues,
 	entries: createKeyedEntries,
 	get: createKeyedGet,
+	from: createKeyedFrom,
+	merge: createKeyedMerge,
 	groupBy: createKeyedGroupBy,
 	singleton: createKeyedSingleton,
 	subset: createKeyedSubset,