@lix-js/sdk 0.0.1

package/src/change-conflict/detect-diverging-entity-conflict.test.ts

@@ -0,0 +1,228 @@
+import { expect, test } from "vitest";
+import type { Change } from "../database/schema.js";
+import { openLixInMemory } from "../lix/open-lix-in-memory.js";
+import {
+	detectDivergingEntityConflict,
+	LIX_DIVERGING_ENTITY_CONFLICT_KEY,
+} from "./detect-diverging-entity-conflict.js";
+import type { DetectedConflict } from "../plugin/lix-plugin.js";
+
+test("it should detect a diverging entity conflict", async () => {
+	const lix = await openLixInMemory({});
+
+	const mockChanges = [
+		{
+			id: "change0",
+			created_at: "mock",
+			plugin_key: "plugin1",
+			schema_key: "mock",
+			file_id: "mock",
+			entity_id: "value1",
+			snapshot_id: "no-content",
+		},
+		{
+			id: "change1",
+			created_at: "mock",
+			plugin_key: "plugin1",
+			file_id: "mock",
+			entity_id: "value1",
+			schema_key: "mock",
+			snapshot_id: "no-content",
+		},
+		{
+			id: "change2",
+			created_at: "mock",
+			plugin_key: "plugin1",
+			file_id: "mock",
+			entity_id: "value1",
+			schema_key: "mock",
+			snapshot_id: "no-content",
+		},
+	] as const satisfies Change[];
+
+	await lix.db
+		.insertInto("change")
+		.values(mockChanges)
+		.returningAll()
+		.execute();
+
+	await lix.db
+		.insertInto("change_edge")
+		.values([
+			{ parent_id: "change0", child_id: "change1" },
+			{ parent_id: "change0", child_id: "change2" },
+		])
+		.execute();
+
+	const result = await detectDivergingEntityConflict({
+		lix: lix,
+		changes: [mockChanges[1], mockChanges[2]],
+	});
+
+	expect(result).toEqual({
+		key: LIX_DIVERGING_ENTITY_CONFLICT_KEY,
+		conflictingChangeIds: new Set(["change1", "change2"]),
+	} satisfies DetectedConflict);
+});
+
+test("it should return a conflict if no common ancestor is found (two clients created different entities without being aware of it (aka distributed system))", async () => {
+	const lix = await openLixInMemory({});
+
+	const mockChanges = [
+		{
+			id: "change0",
+			created_at: "mock",
+			plugin_key: "plugin1",
+			schema_key: "mock",
+			file_id: "mock",
+			entity_id: "value1",
+			snapshot_id: "no-content",
+		},
+		{
+			id: "change1",
+			created_at: "mock",
+			plugin_key: "plugin1",
+			schema_key: "mock",
+			file_id: "mock",
+			entity_id: "value1",
+			snapshot_id: "no-content",
+		},
+		{
+			id: "change2",
+			created_at: "mock",
+			plugin_key: "plugin1",
+			schema_key: "mock",
+			file_id: "mock",
+			entity_id: "value2",
+			snapshot_id: "no-content",
+		},
+	] as const satisfies Change[];
+
+	await lix.db
+		.insertInto("change")
+		.values(mockChanges)
+		.returningAll()
+		.execute();
+
+	const result = await detectDivergingEntityConflict({
+		lix: lix,
+		changes: [mockChanges[0], mockChanges[1]],
+	});
+
+	expect(result).toEqual({
+		key: LIX_DIVERGING_ENTITY_CONFLICT_KEY,
+		conflictingChangeIds: new Set(["change0", "change1"]),
+	} satisfies DetectedConflict);
+});
+
+test("it should return undefined if one of either change is the lowest common ancestor", async () => {
+	const lix = await openLixInMemory({});
+
+	const mockChanges = [
+		{
+			id: "change0",
+			created_at: "mock",
+			plugin_key: "plugin1",
+			schema_key: "mock",
+			file_id: "mock",
+			entity_id: "value1",
+			snapshot_id: "no-content",
+		},
+		{
+			id: "change1",
+			created_at: "mock",
+			plugin_key: "plugin1",
+			file_id: "mock",
+			entity_id: "value1",
+			schema_key: "mock",
+			snapshot_id: "no-content",
+		},
+	] as const satisfies Change[];
+
+	await lix.db
+		.insertInto("change")
+		.values(mockChanges)
+		.returningAll()
+		.execute();
+
+	await lix.db
+		.insertInto("change_edge")
+		.values([
+			// change 1 is the lowest common ancestor of change2
+			{ parent_id: "change0", child_id: "change1" },
+		])
+		.execute();
+
+	const result = await detectDivergingEntityConflict({
+		lix: lix,
+		changes: [mockChanges[0], mockChanges[1]],
+	});
+
+	expect(result).toBeUndefined();
+});
+
+test("it should detect a diverging entity conflict with multiple divering entity changes", async () => {
+	const lix = await openLixInMemory({});
+
+	const mockChanges = [
+		{
+			id: "change0",
+			created_at: "mock",
+			plugin_key: "plugin1",
+			schema_key: "mock",
+			file_id: "mock",
+			entity_id: "value1",
+			snapshot_id: "no-content",
+		},
+		{
+			id: "change1",
+			created_at: "mock",
+			plugin_key: "plugin1",
+			file_id: "mock",
+			entity_id: "value1",
+			schema_key: "mock",
+			snapshot_id: "no-content",
+		},
+		{
+			id: "change2",
+			created_at: "mock",
+			plugin_key: "plugin1",
+			file_id: "mock",
+			entity_id: "value1",
+			schema_key: "mock",
+			snapshot_id: "no-content",
+		},
+		{
+			id: "change3",
+			created_at: "mock",
+			plugin_key: "plugin1",
+			file_id: "mock",
+			entity_id: "value1",
+			schema_key: "mock",
+			snapshot_id: "no-content",
+		},
+	] as const satisfies Change[];
+
+	await lix.db.insertInto("change").values(mockChanges).execute();
+
+	await lix.db
+		.insertInto("change_edge")
+		.values([
+			// change 0 is the lowest common ancestor of change1, change2, and change3
+			// which means that 1,2,3 are diverging
+			{ parent_id: "change0", child_id: "change1" },
+			{ parent_id: "change0", child_id: "change2" },
+			{ parent_id: "change0", child_id: "change3" },
+		])
+		.execute();
+
+	const result = await detectDivergingEntityConflict({
+		lix: lix,
+		changes: [mockChanges[1], mockChanges[2], mockChanges[3]],
+	});
+
+	expect(result).toEqual({
+		key: LIX_DIVERGING_ENTITY_CONFLICT_KEY,
+		conflictingChangeIds: new Set(["change1", "change2", "change3"]),
+	} satisfies DetectedConflict);
+});

package/src/change-conflict/detect-diverging-entity-conflict.ts

@@ -0,0 +1,82 @@
+import type { Change } from "../database/schema.js";
+import type { DetectedConflict, LixReadonly } from "../plugin/lix-plugin.js";
+import { changeIsLowestCommonAncestorOf } from "../query-filter/change-is-lowest-common-ancestor-of.js";
+
+export const LIX_DIVERGING_ENTITY_CONFLICT_KEY =
+	"lix-diverging-entity-conflict";
+
+/**
+ * Detects a diverging entity conflict between two changes.
+ *
+ * When two changes are diverging, it means that they are
+ * based on the same entity state, but have different
+ * changes to the entity.
+ *
+ * A diverging entity conflict usually happens when two users
+ * are working on the same entity and both have made changes
+ * to the entity but are not in sync.
+ *
+ * @note
+ *   Filter out changes that are not based on the same entity
+ *   before calling this function to reduce the number of
+ *   comparisons.
+ *
+ * @example
+ *   const detectedConflict = await detectDivergingEntityConflict({
+ *      	lix: lix,
+ * 				changes: [changeA, changeB],
+ *   });
+ *
+ * @returns The detected conflict or undefined if no conflict was detected.
+ */
+export async function detectDivergingEntityConflict(args: {
+	lix: Pick<LixReadonly, "db">;
+	changes: Pick<Change, "id" | "entity_id" | "file_id" | "schema_key">[];
+}): Promise<DetectedConflict | undefined> {
+	const conflictingChangeIds = new Set<string>();
+
+	// iterate over all pairs of changes
+	for (let i = 0; i < args.changes.length; i++) {
+		for (let j = i + 1; j < args.changes.length; j++) {
+			const changeA = args.changes[i];
+			const changeB = args.changes[j];
+
+			if (changeA === undefined || changeB === undefined) {
+				continue;
+			}
+
+			// the primary key differs, the changes can't be diverging
+			// because they are based on different entities
+			if (
+				changeA.entity_id !== changeB.entity_id ||
+				changeA.file_id !== changeB.file_id ||
+				changeA.schema_key !== changeB.schema_key
+			) {
+				continue;
+			}
+
+			const lowestCommonAncestor = await args.lix.db
+				.selectFrom("change")
+				.where(changeIsLowestCommonAncestorOf([changeA, changeB]))
+				.select("id")
+				.executeTakeFirst();
+
+			// change a or b is the lowest common ancestor, aka no divergence
+			if (
+				changeA.id === lowestCommonAncestor?.id ||
+				changeB.id === lowestCommonAncestor?.id
+			) {
+				continue;
+			}
+			conflictingChangeIds.add(changeA.id);
+			conflictingChangeIds.add(changeB.id);
+		}
+	}
+	if (conflictingChangeIds.size === 0) {
+		return undefined;
+	}
+	return {
+		key: LIX_DIVERGING_ENTITY_CONFLICT_KEY,
+		conflictingChangeIds,
+	};
+}

package/src/change-conflict/garbage-collect-change-conflicts.test.ts

@@ -0,0 +1,219 @@
+import { test, expect } from "vitest";
+import { openLixInMemory } from "../lix/open-lix-in-memory.js";
+import { garbageCollectChangeConflicts } from "./garbage-collect-change-conflicts.js";
+import { createChangeConflict } from "./create-change-conflict.js";
+import { createVersion } from "../version/create-version.js";
+import { updateChangesInVersion } from "../version/update-changes-in-version.js";
+
+// garbage collection is not used atm
+test.skip("should garbage collect conflicts that contain one or more changes that no version change pointer references (anymore)", async () => {
+	const lix = await openLixInMemory({});
+
+	const version0 = await createVersion({ lix, name: "version0" });
+
+	const changes = await lix.db
+		.insertInto("change")
+		.values([
+			{
+				id: "change0",
+				plugin_key: "mock-plugin",
+				schema_key: "mock",
+				file_id: "mock",
+				entity_id: "value0",
+				snapshot_id: "no-content",
+			},
+			{
+				id: "change1",
+				plugin_key: "mock-plugin",
+				schema_key: "mock",
+				file_id: "mock",
+				entity_id: "value1",
+				snapshot_id: "no-content",
+			},
+			{
+				id: "change2",
+				plugin_key: "mock-plugin",
+				schema_key: "mock",
+				file_id: "mock",
+				entity_id: "value2",
+				snapshot_id: "no-content",
+			},
+		])
+		.returningAll()
+		.execute();
+
+	// Create change conflicts
+	const mockConflict0 = await createChangeConflict({
+		lix,
+		version: version0,
+		key: "mock-conflict0",
+		conflictingChangeIds: new Set(["change0", "change1"]),
+	});
+
+	await createChangeConflict({
+		lix,
+		version: version0,
+		key: "mock-conflict1",
+		conflictingChangeIds: new Set(["change1", "change2"]),
+	});
+
+	// Insert version change pointers (only for change0 and change1)
+	// change2 is not referenced by any version change pointer
+	// and should be garbage collected
+	await updateChangesInVersion({
+		lix,
+		version: version0,
+		changes: [changes[0]!, changes[1]!],
+	});
+
+	// Run garbage collection
+	await garbageCollectChangeConflicts({ lix });
+
+	// Check remaining conflicts
+	const remainingConflicts = await lix.db
+		.selectFrom("change_conflict")
+		.selectAll()
+		.execute();
+
+	expect(remainingConflicts.length).toBe(1);
+	expect(remainingConflicts[0]?.id).toBe(mockConflict0.id);
+
+	// Check remaining conflict elements
+	const remainingConflictElements = await lix.db
+		.selectFrom("change_set_element")
+		.innerJoin(
+			"change_conflict",
+			"change_conflict.change_set_id",
+			"change_set_element.change_set_id"
+		)
+		.selectAll()
+		.execute();
+
+	expect(remainingConflictElements.length).toBe(2);
+	expect(remainingConflictElements[0]?.change_id).toBe(mockConflict0.id);
+	expect(remainingConflictElements[1]?.change_id).toBe(mockConflict0.id);
+
+	// Check remaining version change conflict pointers
+	const remainingVersionChangeConflictPointers = await lix.db
+		.selectFrom("version_change_conflict")
+		.selectAll()
+		.execute();
+
+	expect(remainingVersionChangeConflictPointers.length).toBe(1);
+	expect(remainingVersionChangeConflictPointers[0]?.change_conflict_id).toBe(
+		mockConflict0.id
+	);
+});
+
+test("should garbage collect conflicts that no version references", async () => {
+	const lix = await openLixInMemory({});
+
+	const changes = await lix.db
+		.insertInto("change")
+		.values([
+			{
+				id: "change0",
+				plugin_key: "mock-plugin",
+				schema_key: "mock",
+				file_id: "mock",
+				entity_id: "value0",
+				snapshot_id: "no-content",
+			},
+			{
+				id: "change1",
+				plugin_key: "mock-plugin",
+				schema_key: "mock",
+				file_id: "mock",
+				entity_id: "value1",
+				snapshot_id: "no-content",
+			},
+		])
+		.returningAll()
+		.execute();
+
+	const version0 = await createVersion({ lix, name: "version0" });
+
+	const mockConflict0 = await createChangeConflict({
+		lix,
+		version: version0,
+		key: "mock-conflict0",
+		conflictingChangeIds: new Set(["change0", "change1"]),
+	});
+
+	// version points to changes 0 and 1
+
+	await updateChangesInVersion({
+		lix,
+		version: version0,
+		changes: [changes[0]!, changes[1]!],
+	});
+
+	// delete the conflict pointers mockConflict0
+	await lix.db
+		.deleteFrom("version_change_conflict")
+		.where("change_conflict_id", "=", mockConflict0.id)
+		.execute();
+
+	// Run garbage collection
+	const gc0 = await garbageCollectChangeConflicts({ lix });
+
+	expect(gc0.deletedChangeConflicts.length).toBe(1);
+	expect(gc0.deletedChangeConflicts.length).toBe(1);
+	expect(gc0.deletedChangeConflicts[0]?.id).toBe(mockConflict0.id);
+});
+
+test("should NOT garbage collect conflicts that a version change conflict pointer references and where each change is referenced by a version change pointer", async () => {
+	const lix = await openLixInMemory({});
+
+	const changes = await lix.db
+		.insertInto("change")
+		.values([
+			{
+				id: "change0",
+				plugin_key: "mock-plugin",
+				schema_key: "mock",
+				file_id: "mock",
+				entity_id: "value0",
+				snapshot_id: "no-content",
+			},
+			{
+				id: "change1",
+				plugin_key: "mock-plugin",
+				schema_key: "mock",
+				file_id: "mock",
+				entity_id: "value1",
+				snapshot_id: "no-content",
+			},
+		])
+		.returningAll()
+		.execute();
+
+	const version0 = await createVersion({ lix, name: "version0" });
+
+	const mockConflict0 = await createChangeConflict({
+		lix,
+		version: version0,
+		key: "mock-conflict0",
+		conflictingChangeIds: new Set(["change0", "change1"]),
+	});
+
+	// version points to changes 0 and 1
+
+	await updateChangesInVersion({
+		lix,
+		version: version0,
+		changes: [changes[0]!, changes[1]!],
+	});
+
+	// Run garbage collection
+	const gc0 = await garbageCollectChangeConflicts({ lix });
+
+	expect(gc0.deletedChangeConflicts.length).toBe(0);
+
+	// delete all version change pointers
+	await lix.db.deleteFrom("version_change_conflict").execute();
+
+	const gc1 = await garbageCollectChangeConflicts({ lix });
+	expect(gc1.deletedChangeConflicts.length).toBe(1);
+	expect(gc1.deletedChangeConflicts[0]?.id).toBe(mockConflict0.id);
+});

package/src/change-conflict/garbage-collect-change-conflicts.ts

@@ -0,0 +1,96 @@
+import { sql } from "kysely";
+import type { ChangeConflict } from "../database/schema.js";
+import type { Lix } from "../lix/open-lix.js";
+
+/**
+ * Garbage collects change conflicts.
+ *
+ * A change conflict is considered garbage if the conflict
+ * contains changes that no version change pointer points to.
+ */
+export async function garbageCollectChangeConflicts(args: {
+	lix: Pick<Lix, "db">;
+}): Promise<{
+	deletedChangeConflicts: ChangeConflict[];
+}> {
+	const executeInTransaction = async (trx: Lix["db"]) => {
+		// no versions are pointing to the change conflict anymore
+		// this can happen if a version is deleted or if the conflict is outdated
+		// -> delete the conflict
+		const conflictsWithVersionPointer = await trx
+			.selectFrom("change_conflict")
+			.leftJoin(
+				"version_change_conflict",
+				"change_conflict.id",
+				"version_change_conflict.change_conflict_id"
+			)
+			.where("version_change_conflict.change_conflict_id", "is", null)
+			.selectAll()
+			.execute();
+
+		// Find change conflicts where no version change pointer points to any of its elements
+		const outdatedConflicts = await trx
+			.selectFrom("change_conflict")
+			.leftJoin(
+				"change_set_element as conflict_elements",
+				"change_conflict.change_set_id",
+				"conflict_elements.change_set_id"
+			)
+			.leftJoin(
+				"change_set_element as version_elements",
+				"conflict_elements.change_id",
+				"version_elements.change_id"
+			)
+			.groupBy("change_conflict.id")
+			// TODO assumes that each change conflict element is a unique entity change
+			// TODO watch out if this assumption holds true in the future
+			//
+			// if the number of changes in the conflict that have a corresponding version change pointer
+			// is less than the total number of changes in the conflict, then there is at least one change
+			// that no version change pointer references, aka the conflict is outdated.
+			.having(
+				sql`count(version_elements.change_id)`,
+				// the number of changes in the conflict that have a corresponding version change pointer.
+				"<",
+				// the total number of changes in the conflict.
+				sql`count(conflict_elements.change_id)`
+			)
+			.selectAll("change_conflict")
+			.execute();
+
+		const conflictsToDelete = [
+			...conflictsWithVersionPointer,
+			...outdatedConflicts,
+		];
+
+		// Delete the identified change conflicts and their associated pointers
+		if (conflictsToDelete.length > 0) {
+			const conflictIds = conflictsToDelete.map((conflict) => conflict.id);
+			await trx
+				.deleteFrom("change_conflict")
+				.where("id", "in", conflictIds)
+				.execute();
+
+			await trx
+				.deleteFrom("change_set_element")
+				.where(
+					"change_set_element.change_set_id",
+					"in",
+					conflictsToDelete.map((conflict) => conflict.change_set_id)
+				)
+				.execute();
+
+			await trx
+				.deleteFrom("version_change_conflict")
+				.where("change_conflict_id", "in", conflictIds)
+				.execute();
+		}
+		return { deletedChangeConflicts: conflictsToDelete };
+	};
+
+	if (args.lix.db.isTransaction) {
+		return await executeInTransaction(args.lix.db);
+	} else {
+		return await args.lix.db.transaction().execute(executeInTransaction);
+	}
+}

package/src/change-conflict/index.ts

@@ -0,0 +1,3 @@
+export { createChangeConflict } from "./create-change-conflict.js";
+export { detectChangeConflicts } from "./detect-change-conflicts.js";
+export { resolveChangeConflictBySelecting } from "./resolve-conflict-by-selecting.js";