@lix-js/sdk 0.0.1

package/src/change/create-change.ts

@@ -0,0 +1,129 @@
+import { sql } from "kysely";
+import type { Account } from "../account/database-schema.js";
+import { executeSync } from "../database/execute-sync.js";
+import type { Change, Snapshot, Version } from "../database/schema.js";
+import type { Lix } from "../lix/open-lix.js";
+import { changeIsLeafInVersion } from "../query-filter/change-is-leaf-in-version.js";
+import { updateChangesInVersion } from "../version/update-changes-in-version.js";
+
+/**
+ * Programatically create a change in the database.
+ *
+ * Use this function to directly create a change from a lix app
+ * with bypassing of file-based change detection.
+ */
+export async function createChange(
+	args: {
+		lix: Pick<Lix, "db" | "sqlite">;
+		authors: Array<Pick<Account, "id">>;
+		version: Pick<Version, "id">;
+		entityId: Change["entity_id"];
+		fileId: Change["file_id"];
+		pluginKey: Change["plugin_key"];
+		schemaKey: Change["schema_key"];
+		snapshotContent: Snapshot["content"];
+	},
+	options?: {
+		/**
+		 * When true, the version changes will be updated.
+		 *
+		 * Defaults to true.
+		 */
+		updateVersionChanges?: boolean;
+	}
+): Promise<Change> {
+	const optionsWithDefaults = {
+		updateVersionChanges: true,
+		...options,
+	};
+
+	if (args.authors.length === 0) {
+		throw new Error("At least one author is required");
+	}
+
+	// const executeInTransaction = async (trx: Lix["db"]) => {
+	const snapshot = executeSync({
+		lix: args.lix,
+		query: args.lix.db
+			.insertInto("snapshot")
+			.values({
+				content: args.snapshotContent ?? null,
+			})
+			.onConflict((oc) =>
+				oc.doUpdateSet((eb) => ({
+					content: eb.ref("excluded.content"),
+				}))
+			)
+			.returningAll()
+			.returning(sql`json(content)`.as("content")),
+	})[0] as Snapshot;
+
+	snapshot.content = JSON.parse(snapshot.content as unknown as string);
+
+	const change = executeSync({
+		lix: args.lix,
+		query: args.lix.db
+			.insertInto("change")
+			.values({
+				entity_id: args.entityId,
+				plugin_key: args.pluginKey,
+				file_id: args.fileId,
+				schema_key: args.schemaKey,
+				snapshot_id: snapshot.id,
+			})
+			.returningAll(),
+	})[0] as Change;
+
+	const parentChange = executeSync({
+		lix: args.lix,
+		query: args.lix.db
+			.selectFrom("change")
+			.where("file_id", "=", change.file_id)
+			.where("schema_key", "=", change.schema_key)
+			.where("entity_id", "=", change.entity_id)
+			.where(changeIsLeafInVersion(args.version))
+			.select("id"),
+	})[0] as Change | undefined;
+
+	// If a parent exists, the change is a child of the parent
+	if (parentChange) {
+		executeSync({
+			lix: args.lix,
+			query: args.lix.db.insertInto("change_edge").values({
+				parent_id: parentChange.id,
+				child_id: change.id,
+			}),
+		});
+	}
+
+	for (const author of args.authors) {
+		try {
+			executeSync({
+				lix: args.lix,
+				query: args.lix.db.insertInto("change_author").values({
+					change_id: change.id,
+					account_id: author.id,
+				}),
+			});
+		} catch (e) {
+			console.log(e);
+		}
+	}
+
+	// update the version with the new change
+	if (optionsWithDefaults.updateVersionChanges) {
+		updateChangesInVersion({
+			lix: { ...args.lix },
+			changes: [change],
+			version: args.version,
+		});
+	}
+
+	return change;
+}
+// if (args.lix.db.isTransaction) {
+// 	return executeInTransaction(args.lix.db);
+// } else {
+// 	return args.lix.db.transaction().execute(executeInTransaction);
+// }
+// }

package/src/change/index.ts

@@ -0,0 +1,2 @@
+export { createChange } from "./create-change.js";
+export { applyChanges } from "./apply-changes.js";

package/src/change/mock-change.ts

@@ -0,0 +1,21 @@
+import type { Change, NewChange } from "../database/schema.js";
+
+/**
+ * Creates a mock change object with the given properties.
+ *
+ * @example
+ *   const change = mockChange({ id: "change1" });
+ *   await lix.db.insertInto("change").values(change).execute();
+ */
+export function mockChange(args: Partial<NewChange>): Change {
+	return {
+		id: "mock",
+		created_at: "mock",
+		plugin_key: "mock",
+		file_id: "mock",
+		entity_id: "mock",
+		schema_key: "mock",
+		snapshot_id: "no-content",
+		...args,
+	};
+}

package/src/change-conflict/create-change-conflict.test.ts

@@ -0,0 +1,173 @@
+import { expect, test } from "vitest";
+import { openLixInMemory } from "../lix/open-lix-in-memory.js";
+import { createChangeConflict } from "./create-change-conflict.js";
+import { createVersion } from "../version/create-version.js";
+
+test("conflicts should be de-duplicated based on the change_conflict.key and version", async () => {
+	const lix = await openLixInMemory({});
+
+	const version0 = await createVersion({ lix, name: "version0" });
+
+	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",
+				file_id: "mock",
+				entity_id: "value1",
+				schema_key: "mock",
+				snapshot_id: "no-content",
+			},
+		])
+		.execute();
+
+	const changeConflict = await createChangeConflict({
+		lix,
+		version: version0,
+		key: "mock-conflict",
+		conflictingChangeIds: new Set(["change0", "change1"]),
+	});
+
+	// Check that no new conflict is created
+	const conflictsAfter1Creation = await lix.db
+		.selectFrom("change_conflict")
+		.where("change_conflict.key", "=", "mock-conflict")
+		.selectAll()
+		.execute();
+
+	expect(conflictsAfter1Creation.length).toBe(1);
+	expect(conflictsAfter1Creation[0]?.id).toBe(changeConflict.id);
+	expect(conflictsAfter1Creation[0]?.key).toBe("mock-conflict");
+
+	// Create a second conflict
+	const changeConflict2 = await createChangeConflict({
+		lix,
+		version: version0,
+		key: "mock-conflict",
+		conflictingChangeIds: new Set(["change0", "change1"]),
+	});
+
+	// Check that no new conflict is created
+	const conflictsAfter2Creation = await lix.db
+		.selectFrom("change_conflict")
+		.where("change_conflict.key", "=", "mock-conflict")
+		.selectAll()
+		.execute();
+
+	expect(conflictsAfter2Creation.length).toBe(1);
+	expect(conflictsAfter2Creation[0]?.id).toBe(changeConflict2.id);
+	expect(conflictsAfter2Creation[0]?.key).toBe("mock-conflict");
+});
+
+test("if a conflict contains the same changes for a given key and version, no new conflict should be created", async () => {
+	const lix = await openLixInMemory({});
+
+	const version0 = await createVersion({ lix, name: "version0" });
+
+	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",
+				file_id: "mock",
+				entity_id: "value1",
+				schema_key: "mock",
+				snapshot_id: "no-content",
+			},
+			{
+				id: "change2",
+				plugin_key: "mock-plugin",
+				file_id: "mock",
+				entity_id: "value1",
+				schema_key: "mock",
+				snapshot_id: "no-content",
+			},
+		])
+		.execute();
+
+	const changeConflict = await createChangeConflict({
+		lix,
+		version: version0,
+		key: "mock-conflict",
+		conflictingChangeIds: new Set(["change0", "change1"]),
+	});
+
+	// Check that no new conflict is created
+	const conflictElements = await lix.db
+		.selectFrom("change_set_element")
+		.innerJoin(
+			"change_conflict",
+			"change_conflict.change_set_id",
+			"change_set_element.change_set_id"
+		)
+		.where("change_conflict.id", "=", changeConflict.id)
+		.selectAll()
+		.execute();
+
+	expect(conflictElements.length).toBe(2);
+	expect(conflictElements[0]?.change_id).toBe("change0");
+	expect(conflictElements[1]?.change_id).toBe("change1");
+
+	const changeConflict2 = await createChangeConflict({
+		lix,
+		version: version0,
+		key: "mock-conflict",
+		conflictingChangeIds: new Set(["change0", "change1"]),
+	});
+
+	expect(changeConflict2.id).toBe(changeConflict.id);
+
+	const changeConflict3 = await createChangeConflict({
+		lix,
+		version: version0,
+		key: "mock-conflict-other",
+		// 2 was preivously not in the conflict
+		conflictingChangeIds: new Set(["change1", "change2"]),
+	});
+
+	// Check that no new conflict is created
+	const conflictsAfter3Creation = await lix.db
+		.selectFrom("change_conflict")
+		.selectAll()
+		.execute();
+
+	const conflictElementsAfter3Creation = await lix.db
+		.selectFrom("change_set_element")
+		.innerJoin(
+			"change_conflict",
+			"change_conflict.change_set_id",
+			"change_set_element.change_set_id"
+		)
+		.where("change_conflict.id", "=", changeConflict.id)
+		.selectAll()
+		.execute();
+
+	expect(conflictsAfter3Creation.length).toBe(2);
+	expect(conflictsAfter3Creation.map((c) => c.key)).toStrictEqual([
+		"mock-conflict",
+		"mock-conflict-other",
+	]);
+	expect(conflictsAfter3Creation.map((c) => c.id)).toStrictEqual([
+		changeConflict.id,
+		changeConflict3.id,
+	]);
+	expect(conflictElementsAfter3Creation.length).toBe(2);
+});

package/src/change-conflict/create-change-conflict.ts

@@ -0,0 +1,105 @@
+import type { Version, Change, ChangeConflict } from "../database/schema.js";
+import type { Lix } from "../lix/open-lix.js";
+
+/**
+ * Creates a new change conflict with the given conflicting changes.
+ *
+ * @param args.key - The key of the change conflict.
+ * @param args.conflictingChanges - The conflicting changes.
+ */
+export async function createChangeConflict(args: {
+	lix: Pick<Lix, "db">;
+	key: string;
+	version: Pick<Version, "id">;
+	conflictingChangeIds: Set<Change["id"]>;
+}): Promise<ChangeConflict> {
+	const executeInTransaction = async (trx: Lix["db"]) => {
+		// Check if a conflict with the same key and identical change IDs already exists
+		const existingConflict = await trx
+			.selectFrom("change_conflict")
+			.innerJoin(
+				"version_change_conflict",
+				"version_change_conflict.change_conflict_id",
+				"change_conflict.id"
+			)
+			// the version should point to the conflict
+			.where("version_change_conflict.version_id", "=", args.version.id)
+			// which has the identical key
+			.where("change_conflict.key", "=", args.key)
+			// and same set of changes
+			.where((eb) =>
+				eb.exists(
+					trx
+						.selectFrom("change_set_element")
+						.innerJoin("change_conflict", (join) =>
+							join.onRef(
+								"change_conflict.change_set_id",
+								"=",
+								"change_set_element.change_set_id"
+							)
+						)
+						.where(
+							"change_set_element.change_id",
+							"in",
+							Array.from(args.conflictingChangeIds)
+						)
+						.groupBy("change_set_element.change_set_id")
+						.having(
+							trx.fn.count("change_set_element.change_id"),
+							"=",
+							args.conflictingChangeIds.size
+						)
+						.select("change_set_element.change_set_id")
+				)
+			)
+			.selectAll()
+			.executeTakeFirst();
+
+		if (existingConflict) {
+			// Return the existing conflict if it already exists
+			return existingConflict;
+		}
+
+		const newChangeSet = await trx
+			.insertInto("change_set")
+			.defaultValues()
+			.returning("id")
+			.executeTakeFirstOrThrow();
+
+		const newConflict = await trx
+			.insertInto("change_conflict")
+			.values({
+				key: args.key,
+				change_set_id: newChangeSet.id,
+			})
+			.returningAll()
+			.executeTakeFirstOrThrow();
+
+		await trx
+			.insertInto("change_set_element")
+			.values(
+				Array.from(args.conflictingChangeIds).map((id) => ({
+					change_id: id,
+					change_set_id: newConflict.change_set_id,
+				}))
+			)
+			// Ignore if the conflict element already exists
+			.onConflict((oc) => oc.doNothing())
+			.execute();
+
+		await trx
+			.insertInto("version_change_conflict")
+			.values({
+				version_id: args.version.id,
+				change_conflict_id: newConflict.id,
+			})
+			.execute();
+
+		return newConflict;
+	};
+
+	if (args.lix.db.isTransaction) {
+		return executeInTransaction(args.lix.db);
+	}
+	return args.lix.db.transaction().execute(executeInTransaction);
+}

package/src/change-conflict/detect-change-conflicts.test.ts

@@ -0,0 +1,215 @@
+import { test, expect, vi } from "vitest";
+import { openLixInMemory } from "../lix/open-lix-in-memory.js";
+import type { Change } from "../database/schema.js";
+import { detectChangeConflicts } from "./detect-change-conflicts.js";
+import type { LixPlugin } from "../plugin/lix-plugin.js";
+
+test("should detect conflicts using plugins", async () => {
+	const lix = await openLixInMemory({});
+
+	const mockPlugin: LixPlugin = {
+		key: "mock-plugin",
+		detectConflicts: vi.fn().mockResolvedValue([
+			{
+				key: "mock-conflict",
+				conflictingChangeIds: new Set(["change0", "change1"]),
+			},
+		]),
+	};
+
+	// Mock the plugin.getAll method to return the mock plugin
+	lix.plugin.getAll = vi.fn().mockResolvedValue([mockPlugin]);
+
+	const changes = [
+		{
+			id: "change0",
+			entity_id: "entity0",
+			file_id: "file0",
+			schema_key: "type0",
+		},
+		{
+			id: "change1",
+			entity_id: "entity1",
+			file_id: "file1",
+			schema_key: "type1",
+		},
+	] as const satisfies Partial<Change>[];
+
+	const detectedConflicts = await detectChangeConflicts({
+		lix,
+		changes: changes as unknown as Change[],
+	});
+
+	expect(detectedConflicts.length).toBe(1);
+	expect(detectedConflicts[0]?.key).toBe("mock-conflict");
+	expect(detectedConflicts[0]?.conflictingChangeIds).toEqual(
+		new Set(["change0", "change1"])
+	);
+	expect(mockPlugin.detectConflicts).toHaveBeenCalledWith({
+		lix,
+		changes,
+	});
+});
+
+test("should handle no conflicts detected by plugins", async () => {
+	const lix = await openLixInMemory({});
+
+	const mockPlugin: LixPlugin = {
+		key: "mock-plugin",
+		detectConflicts: vi.fn().mockResolvedValue([]),
+	};
+
+	// Mock the plugin.getAll method to return the mock plugin
+	lix.plugin.getAll = vi.fn().mockResolvedValue([mockPlugin]);
+
+	const changes = [
+		{
+			id: "change0",
+			entity_id: "entity0",
+			file_id: "file0",
+			schema_key: "type0",
+		},
+		{
+			id: "change1",
+			entity_id: "entity1",
+			file_id: "file1",
+			schema_key: "type1",
+		},
+	] as const satisfies Partial<Change>[];
+
+	const detectedConflicts = await detectChangeConflicts({
+		lix,
+		changes: changes as unknown as Change[],
+	});
+
+	expect(detectedConflicts.length).toBe(0);
+	expect(mockPlugin.detectConflicts).toHaveBeenCalledWith({
+		lix,
+		changes,
+	});
+});
+
+test("should handle multiple plugins detecting conflicts", async () => {
+	const lix = await openLixInMemory({});
+
+	const mockPlugin1: LixPlugin = {
+		key: "mock-plugin1",
+		detectConflicts: vi.fn().mockResolvedValue([
+			{
+				key: "mock-conflict1",
+				conflictingChangeIds: new Set(["change0", "change1"]),
+			},
+		]),
+	};
+
+	const mockPlugin2: LixPlugin = {
+		key: "mock-plugin2",
+		detectConflicts: vi.fn().mockResolvedValue([
+			{
+				key: "mock-conflict2",
+				conflictingChangeIds: new Set(["change1", "change2"]),
+			},
+		]),
+	};
+
+	// Mock the plugin.getAll method to return the mock plugins
+	lix.plugin.getAll = vi.fn().mockResolvedValue([mockPlugin1, mockPlugin2]);
+
+	const changes = [
+		{
+			id: "change0",
+			entity_id: "entity0",
+			file_id: "file0",
+			schema_key: "type0",
+		},
+		{
+			id: "change1",
+			entity_id: "entity1",
+			file_id: "file1",
+			schema_key: "type1",
+		},
+		{
+			id: "change2",
+			entity_id: "entity2",
+			file_id: "file2",
+			schema_key: "type2",
+		},
+	] as const satisfies Partial<Change>[];
+
+	const detectedConflicts = await detectChangeConflicts({
+		lix,
+		changes: changes as unknown as Change[],
+	});
+
+	expect(detectedConflicts.length).toBe(2);
+	expect(detectedConflicts[0]?.key).toBe("mock-conflict1");
+	expect(detectedConflicts[0]?.conflictingChangeIds).toEqual(
+		new Set(["change0", "change1"])
+	);
+	expect(detectedConflicts[1]?.key).toBe("mock-conflict2");
+	expect(detectedConflicts[1]?.conflictingChangeIds).toEqual(
+		new Set(["change1", "change2"])
+	);
+	expect(mockPlugin1.detectConflicts).toHaveBeenCalledWith({
+		lix,
+		changes,
+	});
+	expect(mockPlugin2.detectConflicts).toHaveBeenCalledWith({
+		lix,
+		changes,
+	});
+});
+
+test("it should auto detect diverging entity conflicts", async () => {
+	const lix = await openLixInMemory({});
+
+	const changes = await lix.db
+		.insertInto("change")
+		.values([
+			{
+				id: "change0",
+				plugin_key: "plugin1",
+				schema_key: "mock",
+				file_id: "file0",
+				entity_id: "entity0",
+				snapshot_id: "no-content",
+			},
+			{
+				id: "change1",
+				plugin_key: "plugin1",
+				schema_key: "mock",
+				file_id: "file0",
+				entity_id: "entity0",
+				snapshot_id: "no-content",
+			},
+			{
+				id: "change2",
+				plugin_key: "plugin1",
+				file_id: "file0",
+				entity_id: "entity0",
+				schema_key: "mock",
+				snapshot_id: "no-content",
+			},
+		])
+		.returningAll()
+		.execute();
+
+	await lix.db
+		.insertInto("change_edge")
+		.values([
+			{ parent_id: "change0", child_id: "change1" },
+			{ parent_id: "change0", child_id: "change2" },
+		])
+		.execute();
+
+	const detectedConflicts = await detectChangeConflicts({
+		lix,
+		changes,
+	});
+
+	expect(detectedConflicts.length).toBe(1);
+	expect(detectedConflicts[0]?.key).toBe("lix-diverging-entity-conflict");
+	expect(detectedConflicts[0]?.conflictingChangeIds).toEqual(
+		new Set(["change1", "change2"])
+	);
+});

package/src/change-conflict/detect-change-conflicts.ts

@@ -0,0 +1,65 @@
+import type { Change } from "../database/schema.js";
+import type { DetectedConflict, LixReadonly } from "../plugin/lix-plugin.js";
+import { detectDivergingEntityConflict } from "./detect-diverging-entity-conflict.js";
+
+/**
+ * Detects conflicts in the given set of changes.
+ *
+ * The caller is responsible for filtering out changes
+ * that should not lead to conflicts before calling this function.
+ *
+ * For example, detecting conflicts between two versiones should
+ * only include changes that are different between the two versiones
+ * when calling this function.
+ *
+ * @example
+ *   const detectedConflicts = await detectChangeConflicts({
+ *        lix: lix,
+ *        changes: diffingChages,
+ *   });
+ */
+export async function detectChangeConflicts(args: {
+	lix: Pick<LixReadonly, "db" | "plugin">;
+	changes: Change[];
+}): Promise<DetectedConflict[]> {
+	const detectedConflicts: DetectedConflict[] = [];
+	const plugins = await args.lix.plugin.getAll();
+
+	// let plugin detect conflicts
+	await Promise.all(
+		plugins.map(async (plugin) => {
+			if (plugin.detectConflicts) {
+				const conflicts = await plugin.detectConflicts({
+					lix: args.lix,
+					changes: args.changes,
+				});
+				detectedConflicts.push(...conflicts);
+			}
+		})
+	);
+
+	// auto detect diverging entity conflicts
+
+	// group by the primary key (entity_id, file_id, type)
+	const groupedByEntity = Object.groupBy(
+		args.changes,
+		(change) => `${change.entity_id}_${change.file_id}_${change.schema_key}`
+	);
+	for (const changes of Object.values(groupedByEntity)) {
+		if (changes === undefined) {
+			continue;
+		}
+
+		if (changes.length > 1) {
+			const divergingEntityConflict = await detectDivergingEntityConflict({
+				lix: args.lix,
+				changes,
+			});
+			if (divergingEntityConflict) {
+				detectedConflicts.push(divergingEntityConflict);
+			}
+		}
+	}
+
+	return detectedConflicts;
+}