@lix-js/sdk 0.0.1

package/src/change/apply-changes.test.ts

@@ -0,0 +1,268 @@
+import { expect, test, vi } from "vitest";
+import { openLixInMemory } from "../lix/open-lix-in-memory.js";
+import { applyChanges } from "./apply-changes.js";
+import type { LixPlugin } from "../plugin/lix-plugin.js";
+import { mockJsonSnapshot } from "../snapshot/mock-json-snapshot.js";
+import type { KeyValue } from "../key-value/database-schema.js";
+import { changeQueueSettled } from "../change-queue/change-queue-settled.js";
+
+test("it applies the given changes", async () => {
+	const lix = await openLixInMemory({});
+
+	// Prepare mock plugin
+	const mockPlugin: LixPlugin = {
+		key: "plugin1",
+		applyChanges: vi.fn(async ({ changes }) => {
+			return {
+				fileData: new TextEncoder().encode(`updated-data-${changes[0]?.id}`),
+			};
+		}),
+	};
+
+	vi.spyOn(lix.plugin, "getAll").mockResolvedValue([mockPlugin]);
+
+	// Insert a file and changes, marking only one as a leaf
+	const file = await lix.db
+		.insertInto("file")
+		.values({
+			id: "file1",
+			data: new TextEncoder().encode("initial-data"),
+			path: "/mock-path",
+		})
+		.returningAll()
+		.executeTakeFirstOrThrow();
+
+	const changes = await lix.db
+		.insertInto("change")
+		.values([
+			{
+				id: "changeA",
+				file_id: file.id,
+				plugin_key: mockPlugin.key,
+				snapshot_id: "no-content",
+				entity_id: "value1",
+				schema_key: "mock",
+			},
+		])
+		.returningAll()
+		.execute();
+
+	await applyChanges({ lix, changes });
+
+	// Verify file data was updated
+	const updatedFile = await lix.db
+		.selectFrom("file")
+		.where("id", "=", "file1")
+		.selectAll()
+		.executeTakeFirstOrThrow();
+
+	expect(new TextDecoder().decode(updatedFile.data)).toBe(
+		"updated-data-changeA"
+	);
+});
+
+test("applyChanges throws an error if plugin does not exist", async () => {
+	const lix = await openLixInMemory({});
+
+	const file = await lix.db
+		.insertInto("file")
+		.values({
+			id: "file1",
+			data: new TextEncoder().encode("initial-data"),
+			path: "/mock-path",
+		})
+		.returningAll()
+		.executeTakeFirstOrThrow();
+
+	const changes = await lix.db
+		.insertInto("change")
+		.values([
+			{
+				id: "changeA",
+				file_id: file.id,
+				plugin_key: "non-existent",
+				snapshot_id: "no-content",
+				entity_id: "value1",
+				schema_key: "mock",
+			},
+		])
+		.returningAll()
+		.execute();
+
+	// Apply changes and verify error for missing plugin
+	expect(applyChanges({ lix, changes })).rejects.toThrow(
+		"Plugin with key non-existent not found"
+	);
+});
+
+test("applyChanges throws an error if plugin does not support applying changes", async () => {
+	const lix = await openLixInMemory({});
+
+	// mock plugin has no applyChanges function
+	const mockPlugin = { key: "plugin1" };
+
+	vi.spyOn(lix.plugin, "getAll").mockResolvedValue([mockPlugin]);
+
+	const file = await lix.db
+		.insertInto("file")
+		.values({
+			id: "file1",
+			data: new TextEncoder().encode("initial-data"),
+			path: "/mock-path",
+		})
+		.returningAll()
+		.executeTakeFirstOrThrow();
+
+	const changes = await lix.db
+		.insertInto("change")
+		.values([
+			{
+				id: "changeA",
+				file_id: file.id,
+				plugin_key: mockPlugin.key,
+				snapshot_id: "no-content",
+				entity_id: "value1",
+				schema_key: "mock",
+			},
+		])
+		.returningAll()
+		.execute();
+
+	// Apply changes and verify error for unsupported applyChanges
+	expect(applyChanges({ lix, changes })).rejects.toThrow(
+		"Plugin with key plugin1 does not support applying changes"
+	);
+});
+
+test("it applies own entity changes", async () => {
+	const lix = await openLixInMemory({});
+
+	const snapshot = mockJsonSnapshot({
+		key: "mock-key",
+		value: "1+1=2",
+	} satisfies KeyValue);
+
+	await lix.db
+		.insertInto("snapshot")
+		.values({
+			content: snapshot.content,
+		})
+		.execute();
+
+	await applyChanges({
+		lix,
+		changes: [
+			{
+				id: "change0",
+				entity_id: "mock-key",
+				file_id: "null",
+				plugin_key: "lix_own_entity",
+				schema_key: "lix_key_value_table",
+				snapshot_id: snapshot.id,
+				created_at: "2021-01-01T00:00:00Z",
+			},
+		],
+	});
+
+	const keyValue = await lix.db
+		.selectFrom("key_value")
+		.where("key", "=", "mock-key")
+		.selectAll()
+		.executeTakeFirst();
+
+	expect(keyValue).toEqual({
+		key: "mock-key",
+		value: "1+1=2",
+	});
+});
+
+test("applies an insert change for a file if the file does not exist", async () => {
+	const mockTxtPlugin: LixPlugin = {
+		key: "mock_txt_plugin",
+		detectChangesGlob: "*.txt",
+		detectChanges: async ({ after }) => {
+			return [
+				{
+					entity_id: "txt_file",
+					snapshot: after
+						? {
+								text: new TextDecoder().decode(after?.data),
+							}
+						: null,
+					schema: {
+						type: "json",
+						key: "txt",
+					},
+				},
+			];
+		},
+
+		applyChanges: async ({ lix, changes }) => {
+			const snapshot = await lix.db
+				.selectFrom("snapshot")
+				.where("id", "=", changes.at(-1)!.snapshot_id)
+				.selectAll()
+				.executeTakeFirstOrThrow();
+
+			return {
+				fileData: new TextEncoder().encode(snapshot.content!.text),
+			};
+		},
+	};
+
+	const lix = await openLixInMemory({
+		providePlugins: [mockTxtPlugin],
+	});
+
+	// insertion change
+	const file1 = await lix.db
+		.insertInto("file")
+		.values({
+			path: "/test.txt",
+			data: new TextEncoder().encode("hello"),
+		})
+		.returningAll()
+		.executeTakeFirstOrThrow();
+
+	await changeQueueSettled({ lix });
+
+	const changes1 = await lix.db
+		.selectFrom("change")
+		.orderBy("id desc")
+		.selectAll()
+		.execute();
+
+	const snapshots1 = await lix.db.selectFrom("snapshot").selectAll().execute();
+
+	const lix2 = await openLixInMemory({
+		providePlugins: [mockTxtPlugin],
+	});
+
+	// the snapshots need to be in lix 2 to apply the changes
+	await lix2.db
+		.insertInto("snapshot")
+		.values(snapshots1.map((c) => ({ content: c.content })))
+		.onConflict((oc) => oc.doNothing())
+		.execute();
+
+	// the changes need to exist too to avoid foreign key constraint errors
+	// (applyChanges assumes that changes are existent in the lix)
+	await lix2.db.insertInto("change").values(changes1).execute();
+
+	await applyChanges({ lix: lix2, changes: changes1 });
+
+	const changes2 = await lix2.db
+		.selectFrom("change")
+		.orderBy("id desc")
+		.selectAll()
+		.execute();
+
+	const file2 = await lix2.db
+		.selectFrom("file")
+		.where("path", "=", "/test.txt")
+		.selectAll()
+		.executeTakeFirstOrThrow();
+
+	expect(changes1).toEqual(changes2);
+	expect(file1).toEqual(file2);
+});

package/src/change/apply-changes.ts

@@ -0,0 +1,114 @@
+import { withSkipChangeQueue } from "../change-queue/with-skip-change-queue.js";
+import type { Change } from "../database/schema.js";
+import type { Lix } from "../lix/open-lix.js";
+import { applyOwnEntityChanges } from "../own-entity-change-control/apply-own-entity-change.js";
+
+/**
+ * Applies the given changes to the lix.
+ *
+ * Calls the `applyChanges` method of the corresponding plugin for each change.
+ * **Carefull**, the changes are not validated before applying them. It is up to
+ * the caller to ensure that the changes are valid. Usually, only the leaf changes
+ * of a given version should be applied.
+ *
+ * @example
+ *   ```ts
+ *   const changes = await lix.db.selectFrom("change")
+ *      .where(changeIsLeafInVersion(currentVersion))
+ *      .selectAll()
+ *      .execute();
+ *
+ *   await applyChanges({ lix, changes });
+ *   ```
+ */
+export async function applyChanges(args: {
+	lix: Pick<Lix, "db" | "plugin">;
+	changes: Change[];
+}): Promise<void> {
+	const executeInTransaction = async (trx: Lix["db"]) => {
+		const groupByFile = Object.groupBy(
+			args.changes,
+			(change) => change.file_id
+		);
+
+		// Lix own changes need to be applied first.
+		//
+		// Plugin changes depend on lix changes like the file
+		// data for example. Therefore, the lix changes need
+		// to be applied first.
+		const lixOwnChanges = groupByFile["null"] ?? [];
+		delete groupByFile["null"];
+
+		const plugins = await args.lix.plugin.getAll();
+
+		// TODO make detection of which plugin to use easier
+		// https://linear.app/opral/issue/LIXDK-104/add-detectedchangeschema
+		for (const [fileId, changes] of [
+			// applying lix own changes first
+			["null", lixOwnChanges] as [string, Change[]],
+			...Object.entries(groupByFile),
+		]) {
+			if (changes === undefined || changes.length === 0) {
+				continue;
+			}
+			// Skip own entity changes which have a file id 'null' and
+			// plugin key 'lix_own_entity' as they are not associated with a file
+			if (fileId === "null" && changes[0]?.plugin_key === "lix_own_entity") {
+				await applyOwnEntityChanges({ lix: { ...args.lix, db: trx }, changes });
+				continue;
+			}
+
+			const groupByPlugin = Object.groupBy(changes, (c) => c.plugin_key);
+
+			// Applying lix own changes first ensures that the file
+			// exists when querying the file here.
+			const file = await trx
+				.selectFrom("file")
+				.where("id", "=", fileId)
+				.selectAll()
+				.executeTakeFirst();
+
+			// lix own change control deleted the file
+			// no plugin needs to apply changes
+			if (file === undefined) {
+				continue;
+			} else if (file.data.byteLength === 0) {
+				// @ts-expect-error - the plugin will handle undefined file.data
+				delete file.data;
+			}
+
+			for (const [pluginKey, changes] of Object.entries(groupByPlugin)) {
+				if (changes === undefined) {
+					continue;
+				}
+				const plugin = plugins.find((plugin) => plugin.key === pluginKey);
+				if (!plugin) {
+					throw new Error(`Plugin with key ${pluginKey} not found`);
+				} else if (!plugin.applyChanges) {
+					throw new Error(
+						`Plugin with key ${pluginKey} does not support applying changes`
+					);
+				}
+				const { fileData } = await plugin.applyChanges({
+					lix: { ...args.lix, db: trx },
+					file,
+					changes,
+				});
+
+				await withSkipChangeQueue(trx, async (trx) => {
+					await trx
+						.updateTable("file")
+						.set({ data: fileData })
+						.where("id", "=", fileId)
+						.execute();
+				});
+			}
+		}
+	};
+
+	if (args.lix.db.isTransaction) {
+		return executeInTransaction(args.lix.db);
+	} else {
+		return args.lix.db.transaction().execute(executeInTransaction);
+	}
+}

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

@@ -0,0 +1,296 @@
+import { expect, test } from "vitest";
+import { openLixInMemory } from "../lix/open-lix-in-memory.js";
+import { createChange } from "./create-change.js";
+import type { Change } from "../database/schema.js";
+import { createAccount } from "../account/create-account.js";
+import { createVersion } from "../version/create-version.js";
+import { switchVersion } from "../version/switch-version.js";
+
+test("should create a change with the correct values", async () => {
+	const lix = await openLixInMemory({});
+
+	const version0 = await createVersion({ lix, name: "version0" });
+
+	const author = await createAccount({
+		lix,
+		name: "author",
+	});
+
+	await switchVersion({ lix, to: version0 });
+
+	const change = await createChange({
+		lix,
+		authors: [author],
+		entityId: "entity1",
+		version: version0,
+		fileId: "file1",
+		pluginKey: "plugin1",
+		schemaKey: "schema1",
+		snapshotContent: { text: "snapshot-content" },
+	});
+
+	const changes = await lix.db
+		.selectFrom("change")
+		.where("change.id", "=", change.id)
+		.selectAll()
+		.execute();
+
+	expect(changes.length).toBe(1);
+	expect(changes[0]?.entity_id).toBe("entity1");
+	expect(changes[0]?.file_id).toBe("file1");
+	expect(changes[0]?.plugin_key).toBe("plugin1");
+	expect(changes[0]?.schema_key).toBe("schema1");
+	expect(changes[0]?.snapshot_id).toBe(change.snapshot_id);
+});
+
+test("should create a snapshot with the correct content", async () => {
+	const lix = await openLixInMemory({});
+
+	const version0 = await createVersion({ lix, name: "version0" });
+
+	await switchVersion({ lix, to: version0 });
+
+	const author = await createAccount({
+		lix,
+		name: "author",
+	});
+
+	const change = await createChange({
+		lix,
+		authors: [author],
+		version: version0,
+		entityId: "entity1",
+		fileId: "file1",
+		pluginKey: "plugin1",
+		schemaKey: "schema1",
+		snapshotContent: { text: "snapshot-content" },
+	});
+
+	const snapshots = await lix.db
+		.selectFrom("snapshot")
+		.where("snapshot.id", "=", change.snapshot_id)
+		.selectAll()
+		.execute();
+
+	expect(snapshots.length).toBe(1);
+	expect(snapshots[0]?.content).toStrictEqual({ text: "snapshot-content" });
+});
+
+test("should create a change and a snapshot in a transaction", async () => {
+	const lix = await openLixInMemory({});
+
+	const version0 = await createVersion({ lix, name: "version0" });
+
+	await switchVersion({ lix, to: version0 });
+
+	const author = await createAccount({
+		lix,
+		name: "author",
+	});
+
+	let change: Change;
+
+	await lix.db.transaction().execute(async (trx) => {
+		change = await createChange({
+			lix: { ...lix, db: trx },
+			authors: [author],
+			version: version0,
+			entityId: "entity1",
+			fileId: "file1",
+			pluginKey: "plugin1",
+			schemaKey: "schema1",
+			snapshotContent: { text: "snapshot-content" },
+		});
+	});
+
+	const changes = await lix.db
+		.selectFrom("change")
+		.where("change.id", "=", change!.id)
+		.selectAll()
+		.execute();
+
+	const snapshots = await lix.db
+		.selectFrom("snapshot")
+		.where("snapshot.id", "=", change!.snapshot_id)
+		.selectAll()
+		.execute();
+
+	expect(changes.length).toBe(1);
+	expect(snapshots.length).toBe(1);
+	expect(changes[0]?.snapshot_id).toBe(snapshots[0]?.id);
+});
+
+test("should create the change authors", async () => {
+	const lix = await openLixInMemory({});
+
+	const version0 = await createVersion({ lix, name: "version0" });
+
+	await switchVersion({ lix, to: version0 });
+
+	const account1 = await createAccount({
+		lix,
+		name: "account1",
+	});
+
+	const account2 = await createAccount({
+		lix,
+		name: "account2",
+	});
+
+	await lix.db
+		.insertInto("active_account")
+		.values([account1, account2])
+		.execute();
+
+	const change = await createChange({
+		lix,
+		version: version0,
+		authors: [account1, account2],
+		entityId: "entity1",
+		fileId: "file1",
+		pluginKey: "plugin1",
+		schemaKey: "schema1",
+		snapshotContent: { text: "snapshot-content" },
+	});
+
+	const changeAuthors = await lix.db
+		.selectFrom("change_author")
+		.where("change_id", "=", change.id)
+		.selectAll()
+		.execute();
+
+	expect(changeAuthors.length).toBe(2);
+	expect(changeAuthors).toMatchObject([
+		{ change_id: change.id, account_id: account1.id },
+		{ change_id: change.id, account_id: account2.id },
+	]);
+});
+
+test("should correctly identify parentChange and create change_edge", async () => {
+	const lix = await openLixInMemory({});
+
+	const version0 = await createVersion({ lix, name: "version0" });
+
+	const author = await createAccount({
+		lix,
+		name: "author",
+	});
+
+	const parentChange = await createChange({
+		lix,
+		version: version0,
+		authors: [author],
+		entityId: "entity1",
+		fileId: "file1",
+		pluginKey: "plugin1",
+		schemaKey: "schema1",
+		snapshotContent: { text: "parent-snapshot-content" },
+	});
+
+	const change = await createChange({
+		lix,
+		version: version0,
+		authors: [author],
+		entityId: "entity1",
+		fileId: "file1",
+		pluginKey: "plugin1",
+		schemaKey: "schema1",
+		snapshotContent: { text: "child-snapshot-content" },
+	});
+
+	const changeEdges = await lix.db
+		.selectFrom("change_edge")
+		.where("change_edge.child_id", "=", change.id)
+		.selectAll()
+		.execute();
+
+	expect(changeEdges.length).toBe(1);
+	expect(changeEdges[0]?.parent_id).toBe(parentChange.id);
+});
+
+test("should update versionChanges with the new change", async () => {
+	const lix = await openLixInMemory({});
+
+	const version0 = await createVersion({ lix, name: "version0" });
+
+	const author = await createAccount({
+		lix,
+		name: "author",
+	});
+
+	const change = await createChange({
+		lix,
+		version: version0,
+		authors: [author],
+		entityId: "entity1",
+		fileId: "file1",
+		pluginKey: "plugin1",
+		schemaKey: "schema1",
+		snapshotContent: { text: "snapshot-content" },
+	});
+
+	const versionChanges = await lix.db
+		.selectFrom("version_change")
+		.where("version_change.version_id", "=", version0.id)
+		.selectAll()
+		.execute();
+
+	expect(versionChanges.length).toBe(1);
+	expect(versionChanges[0]?.change_id).toBe(change.id);
+});
+
+test("should throw an error if authors array is empty", async () => {
+	const lix = await openLixInMemory({});
+
+	const version0 = await createVersion({ lix, name: "version0" });
+
+	await expect(
+		createChange({
+			lix,
+			authors: [],
+			version: version0,
+			entityId: "entity1",
+			fileId: "file1",
+			pluginKey: "plugin1",
+			schemaKey: "schema1",
+			snapshotContent: { text: "snapshot-content" },
+		})
+	).rejects.toThrow("At least one author is required");
+});
+
+test("option to create a change without updating the version changes", async () => {
+	const lix = await openLixInMemory({});
+
+	const version0 = await createVersion({ lix, name: "version0" });
+
+	const author = await createAccount({
+		lix,
+		name: "author",
+	});
+
+	const change = await createChange(
+		{
+			lix,
+			version: version0,
+			authors: [author],
+			entityId: "entity1",
+			fileId: "file1",
+			pluginKey: "plugin1",
+			schemaKey: "schema1",
+			snapshotContent: { text: "snapshot-content" },
+		},
+		{
+			updateVersionChanges: false,
+		}
+	);
+
+	const versionChanges = await lix.db
+		.selectFrom("version_change")
+		.where("version_change.version_id", "=", version0.id)
+		.selectAll()
+		.execute();
+
+	expect(
+		versionChanges.find((vc) => vc.change_id === change.id)
+	).toBeUndefined();
+});