doxum 0.1.30 → 0.1.31

package/dist/index.d.cts

@@ -29,6 +29,23 @@ declare function observe<T>(readable: Readable<T>): Projection<T>;
 declare function observe<S extends ObjectSchema<object>, P extends CollectionPath>(document: ReadonlyDocument<S>, selector: (path: SchemaPath<S>) => P): KeyedProjection<CollectionId<P>, ReadonlyValue<CollectionEntry<P>>>;
 declare function observe<S extends ObjectSchema<object>, P>(document: ReadonlyDocument<S>, selector: (path: SchemaPath<S>) => P): Projection<PathValueOf<P>>;
 //#endregion
+//#region core/src/projection/keyed/composition.d.ts
+type Equality$1<T> = (previous: T, next: T) => boolean;
+declare function createKeyedFrom<K extends string, V>(source: Projection<readonly V[]>, keyOf: (value: NoInfer<V>) => Synchronous<K>, equality?: Equality$1<V>): KeyedProjection<K, V>;
+declare function createKeyedFrom<K extends string, V>(source: readonly V[], keyOf: (value: NoInfer<V>) => Synchronous<K>, equality?: Equality$1<V>): KeyedProjection<K, V>;
+declare function createKeyedMerge<K extends string, V>(sources: readonly KeyedProjection<K, V>[], options: {
+  readonly conflict: 'error' | 'first' | 'last';
+  readonly equality?: Equality$1<V>;
+  readonly resolve?: never;
+} | {
+  readonly conflict: 'resolve';
+  readonly resolve: (contributions: readonly {
+    readonly sourceIndex: number;
+    readonly value: V;
+  }[], key: NoInfer<K>) => Synchronous<V>;
+  readonly equality?: Equality$1<V>;
+}): KeyedProjection<K, V>;
+//#endregion
 //#region core/src/projection/derive.d.ts
 type ProjectionDependencies = Readonly<Record<string, Projection<unknown>>>;
 type ProjectionValues<D extends ProjectionDependencies> = { readonly [K in keyof D]: D[K] extends Projection<infer T> ? T : never };
@@ -43,6 +60,8 @@ declare const derive: typeof createValueDerive & {
     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>;
+    from: typeof createKeyedFrom;
+    merge: typeof createKeyedMerge;
     groupBy: {
       <K extends string, V, G extends string>(source: KeyedProjection<K, V>, selector: (value: NoInfer<V>, key: NoInfer<K>) => Synchronous<G | readonly G[]>): KeyedProjection<G, readonly K[]>;
       <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[]>;

package/dist/index.d.ts

@@ -29,6 +29,23 @@ declare function observe<T>(readable: Readable<T>): Projection<T>;
 declare function observe<S extends ObjectSchema<object>, P extends CollectionPath>(document: ReadonlyDocument<S>, selector: (path: SchemaPath<S>) => P): KeyedProjection<CollectionId<P>, ReadonlyValue<CollectionEntry<P>>>;
 declare function observe<S extends ObjectSchema<object>, P>(document: ReadonlyDocument<S>, selector: (path: SchemaPath<S>) => P): Projection<PathValueOf<P>>;
 //#endregion
+//#region core/src/projection/keyed/composition.d.ts
+type Equality$1<T> = (previous: T, next: T) => boolean;
+declare function createKeyedFrom<K extends string, V>(source: Projection<readonly V[]>, keyOf: (value: NoInfer<V>) => Synchronous<K>, equality?: Equality$1<V>): KeyedProjection<K, V>;
+declare function createKeyedFrom<K extends string, V>(source: readonly V[], keyOf: (value: NoInfer<V>) => Synchronous<K>, equality?: Equality$1<V>): KeyedProjection<K, V>;
+declare function createKeyedMerge<K extends string, V>(sources: readonly KeyedProjection<K, V>[], options: {
+  readonly conflict: 'error' | 'first' | 'last';
+  readonly equality?: Equality$1<V>;
+  readonly resolve?: never;
+} | {
+  readonly conflict: 'resolve';
+  readonly resolve: (contributions: readonly {
+    readonly sourceIndex: number;
+    readonly value: V;
+  }[], key: NoInfer<K>) => Synchronous<V>;
+  readonly equality?: Equality$1<V>;
+}): KeyedProjection<K, V>;
+//#endregion
 //#region core/src/projection/derive.d.ts
 type ProjectionDependencies = Readonly<Record<string, Projection<unknown>>>;
 type ProjectionValues<D extends ProjectionDependencies> = { readonly [K in keyof D]: D[K] extends Projection<infer T> ? T : never };
@@ -43,6 +60,8 @@ declare const derive: typeof createValueDerive & {
     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>;
+    from: typeof createKeyedFrom;
+    merge: typeof createKeyedMerge;
     groupBy: {
       <K extends string, V, G extends string>(source: KeyedProjection<K, V>, selector: (value: NoInfer<V>, key: NoInfer<K>) => Synchronous<G | readonly G[]>): KeyedProjection<G, readonly K[]>;
       <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[]>;

package/dist/index.js

@@ -2774,6 +2774,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 (isProjection(source)) {
+		if (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 = snapshotArray(source);
+	}
+	const [projection] = 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);
+				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 = snapshotArray(sources);
+	for (let index = 0; index < capturedSources.length; index++) assertKeyedProjection(capturedSources[index], `derive.keyed.merge source ${index}`);
+	const compiled = compileMergeOptions(options);
+	const [projection] = 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);
+					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 (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;
+};
+//#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.`);
@@ -3220,40 +3493,13 @@ function createKeyedGroupBy(source, dependenciesOrSelector, maybeSelector) {
 	});
 	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,
+	from: createKeyedFrom,
+	merge: createKeyedMerge,
 	groupBy: createKeyedGroupBy,
 	singleton: createKeyedSingleton,
 	subset: createKeyedSubset,