@lix-js/sdk 0.0.1

package/src/own-entity-change-control/apply-own-entity-change.test.ts

@@ -0,0 +1,365 @@
+import { test, expect } from "vitest";
+import { openLixInMemory } from "../lix/open-lix-in-memory.js";
+import type {
+	Change,
+	ChangeSet,
+	ChangeSetElement,
+} from "../database/schema.js";
+import { applyOwnEntityChanges } from "./apply-own-entity-change.js";
+import { mockJsonSnapshot } from "../snapshot/mock-json-snapshot.js";
+import { type KeyValue } from "../key-value/database-schema.js";
+
+test("it should apply insert changes correctly", async () => {
+	const lix = await openLixInMemory({});
+
+	const snapshot = mockJsonSnapshot({
+		key: "key1",
+		value: "value1",
+	});
+
+	const change: Change = {
+		id: "change1",
+		entity_id: "key1",
+		schema_key: "lix_key_value_table",
+		plugin_key: "lix_own_entity",
+		file_id: "null",
+		snapshot_id: snapshot.id,
+		created_at: "2021-01-01T00:00:00.000Z",
+	};
+
+	await lix.db
+		.insertInto("snapshot")
+		.values({ content: snapshot.content })
+		.execute();
+
+	await applyOwnEntityChanges({ lix, changes: [change] });
+
+	const result = await lix.db
+		.selectFrom("key_value")
+		.where("key", "=", "key1")
+		.selectAll()
+		.executeTakeFirst();
+
+	expect(result).toEqual({ key: "key1", value: "value1" });
+});
+
+test("it should apply update changes correctly", async () => {
+	const lix = await openLixInMemory({});
+
+	await lix.db
+		.insertInto("key_value")
+		.values({ key: "key1", value: "old_value" })
+		.execute();
+
+	const snapshot = mockJsonSnapshot({
+		key: "key1",
+		value: "new_value",
+	});
+
+	const change: Change = {
+		id: "change1",
+		schema_key: "lix_key_value_table",
+		entity_id: "key1",
+		file_id: "null",
+		created_at: "2021-01-01T00:00:00.000Z",
+		plugin_key: "lix_own_entity",
+		snapshot_id: snapshot.id,
+	};
+
+	await lix.db
+		.insertInto("snapshot")
+		.values({
+			content: snapshot.content,
+		})
+		.execute();
+
+	await applyOwnEntityChanges({ lix, changes: [change] });
+
+	const result = await lix.db
+		.selectFrom("key_value")
+		.where("key", "=", "key1")
+		.selectAll()
+		.executeTakeFirst();
+
+	expect(result).toEqual({ key: "key1", value: "new_value" });
+});
+
+test("it should apply delete changes correctly", async () => {
+	const lix = await openLixInMemory({});
+
+	await lix.db
+		.insertInto("key_value")
+		.values({ key: "key1", value: "value1" })
+		.execute();
+
+	const change: Change = {
+		id: "change1",
+		schema_key: "lix_key_value_table",
+		file_id: "null",
+		created_at: "2021-01-01T00:00:00.000Z",
+		entity_id: "key1",
+		plugin_key: "lix_own_entity",
+		snapshot_id: "no-content",
+	};
+
+	await applyOwnEntityChanges({ lix, changes: [change] });
+
+	const result = await lix.db
+		.selectFrom("key_value")
+		.where("key", "=", "key1")
+		.selectAll()
+		.executeTakeFirst();
+
+	expect(result).toBeUndefined();
+});
+
+test("it should throw an error for invalid plugin key", async () => {
+	const lix = await openLixInMemory({});
+
+	const change: Change = {
+		id: "change1",
+		schema_key: "lix_key_value_table",
+		entity_id: "key1",
+		file_id: "null",
+		created_at: "2021-01-01T00:00:00.000Z",
+		plugin_key: "invalid-plugin",
+		snapshot_id: "snapshot1",
+	};
+
+	const snapshot = mockJsonSnapshot({
+		key: "key1",
+		value: "value1",
+	});
+
+	await lix.db
+		.insertInto("snapshot")
+		.values({
+			content: snapshot.content,
+		})
+		.execute();
+
+	await expect(
+		applyOwnEntityChanges({ lix, changes: [change] })
+	).rejects.toThrow(
+		"Expected 'lix_own_entity' as plugin key but received invalid-plugin"
+	);
+});
+
+test("file.data is not changed by applyOwnEntityChanges", async () => {
+	const lix = await openLixInMemory({});
+
+	const file = await lix.db
+		.insertInto("file")
+		.values({
+			path: "/test.txt",
+			data: new TextEncoder().encode("hello"),
+			metadata: {
+				foo: "bar",
+			},
+		})
+		.returningAll()
+		.executeTakeFirstOrThrow();
+
+	const change = await lix.db
+		.selectFrom("change")
+		.innerJoin("snapshot", "snapshot.id", "change.snapshot_id")
+		.where("schema_key", "=", "lix_file_table")
+		.where("entity_id", "=", file.id)
+		.selectAll()
+		.executeTakeFirst();
+
+	expect(change).toBeDefined();
+	expect(change?.content?.metadata).toEqual({ foo: "bar" });
+
+	const snapshot = await lix.db
+		.insertInto("snapshot")
+		.values({
+			content: {
+				id: file.id,
+				path: "/test.txt",
+				metadata: {
+					foo: "baz",
+				},
+			},
+		})
+		.returningAll()
+		.executeTakeFirstOrThrow();
+
+	const mockChange: Change = {
+		id: "change1",
+		entity_id: file.id,
+		schema_key: "lix_file_table",
+		plugin_key: "lix_own_entity",
+		file_id: "null",
+		snapshot_id: snapshot.id,
+		created_at: "2021-01-01T00:00:00.000Z",
+	};
+
+	await applyOwnEntityChanges({ lix, changes: [mockChange] });
+
+	const result = await lix.db
+		.selectFrom("file")
+		.where("id", "=", file.id)
+		.selectAll()
+		.executeTakeFirst();
+
+	expect(result).toEqual({
+		id: file.id,
+		data: new TextEncoder().encode("hello"),
+		path: "/test.txt",
+		metadata: { foo: "baz" },
+	});
+});
+
+test("foreign key constraints are deferred to make the order of applying changes irrelevant", async () => {
+	const lix = await openLixInMemory({});
+
+	const snapshots = [
+		mockJsonSnapshot({
+			id: "change-set-1",
+		} satisfies ChangeSet),
+		mockJsonSnapshot({
+			change_id: "change0",
+			change_set_id: "change-set-1",
+		} satisfies ChangeSetElement),
+	] as const;
+
+	const mockChanges: Change[] = [
+		// applying changes in reverse order
+		{
+			id: "change2",
+			entity_id: "change-set-1,change0",
+			schema_key: "lix_change_set_element_table",
+			plugin_key: "lix_own_entity",
+			file_id: "null",
+			snapshot_id: snapshots[1].id,
+			created_at: "2021-01-01T00:00:00.000Z",
+		},
+		{
+			id: "change1",
+			entity_id: "change-set-1",
+			schema_key: "lix_change_set_table",
+			plugin_key: "lix_own_entity",
+			file_id: "null",
+			snapshot_id: snapshots[0].id,
+			created_at: "2021-01-01T00:00:00.000Z",
+		},
+	];
+
+	for (const snapshot of snapshots) {
+		// @ts-expect-error - 'cannot' insert into generated column error
+		delete snapshot.id;
+	}
+
+	await lix.db
+		.insertInto("snapshot")
+		.values(snapshots.map((s) => ({ content: s.content })))
+		.execute();
+
+	// insert change that the change set element references
+	await lix.db
+		.insertInto("change")
+		.values({
+			id: "change0",
+			plugin_key: "mock",
+			file_id: "null",
+			entity_id: "mock",
+			schema_key: "mock",
+			snapshot_id: "no-content",
+		})
+		.execute();
+
+	await expect(
+		applyOwnEntityChanges({ lix, changes: mockChanges })
+	).resolves.toBeUndefined();
+});
+
+test("foreign key constraints are obeyed", async () => {
+	const lix = await openLixInMemory({});
+
+	const snapshots = [
+		mockJsonSnapshot({
+			// both change 0 and the change set are missing
+			change_id: "change0",
+			change_set_id: "change-set-1",
+		} satisfies ChangeSetElement),
+	] as const;
+
+	const mockChanges: Change[] = [
+		{
+			id: "change2",
+			// the change set for this change does not exist
+			entity_id: "change-set-1,change0",
+			schema_key: "lix_change_set_element_table",
+			plugin_key: "lix_own_entity",
+			file_id: "null",
+			snapshot_id: snapshots[0].id,
+			created_at: "2021-01-01T00:00:00.000Z",
+		},
+	];
+
+	for (const snapshot of snapshots) {
+		// @ts-expect-error - 'cannot' insert into generated column error
+		delete snapshot.id;
+	}
+
+	await lix.db
+		.insertInto("snapshot")
+		.values(snapshots.map((s) => ({ content: s.content })))
+		.execute();
+
+	// insert change that the change set element references
+	await lix.db
+		.insertInto("change")
+		.values({
+			id: "change0",
+			plugin_key: "mock",
+			file_id: "null",
+			entity_id: "mock",
+			schema_key: "mock",
+			snapshot_id: "no-content",
+		})
+		.execute();
+
+	expect(
+		applyOwnEntityChanges({ lix, changes: mockChanges })
+	).rejects.toThrow();
+});
+
+// https://github.com/opral/lix-sdk/issues/185
+test("applying own entity changes doesn't lead to the creation of new 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();
+
+	const changesBefore = await lix.db.selectFrom("change").selectAll().execute();
+
+	await applyOwnEntityChanges({
+		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 changesAfter = await lix.db.selectFrom("change").selectAll().execute();
+
+	expect(changesBefore).toEqual(changesAfter);
+});

package/src/own-entity-change-control/apply-own-entity-change.ts

@@ -0,0 +1,110 @@
+import {
+	CompiledQuery,
+	type DeleteQueryBuilder,
+	type DeleteResult,
+	type InsertQueryBuilder,
+	type InsertResult,
+} from "kysely";
+import type { Change, LixDatabaseSchema } from "../database/schema.js";
+import type { Lix } from "../lix/open-lix.js";
+import {
+	changeControlledTableIds,
+	primaryKeysForEntityId,
+} from "./change-controlled-tables.js";
+import { withSkipOwnChangeControl } from "./with-skip-own-change-control.js";
+
+/**
+ * Applies own changes to lix itself.
+ */
+export async function applyOwnEntityChanges(args: {
+	lix: Pick<Lix, "db">;
+	changes: Change[];
+}): Promise<void> {
+	const executeInTransaction = async (trx: Lix["db"]) => {
+		await withSkipOwnChangeControl(trx, async (trx) => {
+			// defer foreign keys to avoid constraint violations
+			// until the end of the transaction. otherwise, we would
+			// need to apply the changes in the correct order.
+			await trx.executeQuery(
+				CompiledQuery.raw("PRAGMA defer_foreign_keys = ON;")
+			);
+
+			await Promise.all(
+				args.changes.map(async (change) => {
+					if (change.plugin_key !== "lix_own_entity") {
+						throw new Error(
+							"Expected 'lix_own_entity' as plugin key but received " +
+								change.plugin_key
+						);
+					}
+					const snapshot = await trx
+						.selectFrom("snapshot")
+						.where("id", "=", change.snapshot_id)
+						.select("content")
+						.executeTakeFirstOrThrow();
+
+					// remove the prefix and suffix from the schema key
+					// `lix_key_value_table` -> `key_value`
+					const tableName = change.schema_key
+						.replace(/^lix_/, "")
+						.replace(/_table$/, "") as keyof typeof changeControlledTableIds;
+
+					const primaryKeys = primaryKeysForEntityId(
+						tableName,
+						change.entity_id
+					);
+
+					let query:
+						| DeleteQueryBuilder<
+								LixDatabaseSchema,
+								keyof typeof changeControlledTableIds,
+								DeleteResult
+						  >
+						| InsertQueryBuilder<
+								LixDatabaseSchema,
+								keyof typeof changeControlledTableIds,
+								InsertResult
+						  >;
+
+					// deletion
+					if (snapshot.content === null) {
+						query = trx.deleteFrom(tableName);
+						for (const [key, value] of primaryKeys) {
+							query = query.where(key as any, "=", value);
+						}
+					}
+					// upsert
+					else {
+						// take the current file data if the table is `file`
+						// (can be optimized later to adjust the query instead)
+						if (tableName === "file") {
+							const data = await trx
+								.selectFrom("file")
+								.where("id", "=", change.entity_id)
+								.select("data")
+								.executeTakeFirst();
+
+							snapshot.content.data =
+								data?.data ??
+								// empty uint8array will trigger applyChanges() to pass an empty file to the plugin
+								new Uint8Array();
+						}
+
+						query = trx
+							.insertInto(tableName)
+							.values(snapshot.content)
+							.onConflict((oc) => oc.doUpdateSet(snapshot.content!));
+					}
+
+					await query.execute();
+				})
+			);
+		});
+	};
+
+	if (args.lix.db.isTransaction) {
+		return await executeInTransaction(args.lix.db);
+	} else {
+		return await args.lix.db.transaction().execute(executeInTransaction);
+	}
+}

package/src/own-entity-change-control/change-controlled-tables.test.ts

@@ -0,0 +1,69 @@
+import { test, expect } from "vitest";
+import type { LixDatabaseSchema } from "../database/schema.js";
+import {
+	changeControlledTableIds,
+	entityIdForRow,
+	primaryKeysForEntityId,
+	type PragmaTableInfo,
+} from "./change-controlled-tables.js";
+import { loadDatabaseInMemory } from "sqlite-wasm-kysely";
+import { newLixFile } from "../lix/new-lix.js";
+
+test("roundtrip entity_id test for single primary key", () => {
+	const tableName: keyof LixDatabaseSchema = "key_value";
+	const row = ["lix_mock_key", "value1"];
+
+	const entityId = entityIdForRow(tableName, ...row);
+	const primaryKeys = primaryKeysForEntityId(tableName, entityId);
+
+	expect(entityId).toBe("lix_mock_key");
+	expect(primaryKeys).toEqual([["key", "lix_mock_key"]]);
+});
+
+test("roundtrip entity_id test for compound primary keys", () => {
+	const tableName: keyof LixDatabaseSchema = "change_author";
+
+	const row = ["294u-2345", "0128-34928"];
+
+	const entityId = entityIdForRow(tableName, ...row);
+	const primaryKeys = primaryKeysForEntityId(tableName, entityId);
+
+	expect(entityId).toBe("294u-2345,0128-34928");
+	expect(primaryKeys).toEqual([
+		["change_id", "294u-2345"],
+		["account_id", "0128-34928"],
+	]);
+});
+
+// otherwise the change controlled entity_id will be wrong.
+//* if this tests fails, someone did a db schema change
+//* on the primary key order that should not have been done.
+test("the primary key order matches the order the primary keys in the database schema", async () => {
+	const sqlite = await loadDatabaseInMemory(
+		await (await newLixFile()).arrayBuffer()
+	);
+
+	const tableInfos: Record<string, PragmaTableInfo> = {};
+
+	for (const table of Object.keys(changeControlledTableIds)) {
+		tableInfos[table] = sqlite.exec({
+			sql: `PRAGMA table_info(${table});`,
+			returnValue: "resultRows",
+			rowMode: "object",
+		}) as PragmaTableInfo;
+	}
+
+	for (const table of Object.keys(changeControlledTableIds)) {
+		const tableInfo = tableInfos[table]!;
+
+		const primaryKeys = tableInfo
+			.filter((column) => column.pk)
+			.sort((a, b) => a.pk - b.pk)
+			.map((c) => c.name);
+
+		expect(primaryKeys).toEqual(
+			// @ts-expect-error - some type narrowing problem. not important
+			changeControlledTableIds[table]
+		);
+	}
+});

package/src/own-entity-change-control/change-controlled-tables.ts

@@ -0,0 +1,103 @@
+export const changeControlledTableIds = {
+	account: ["id"],
+	comment: ["id"],
+	change_set: ["id"],
+	change_author: ["change_id", "account_id"],
+	change_set_element: ["change_set_id", "change_id"],
+	change_set_label: ["label_id", "change_set_id"],
+	change_set_label_author: ["label_id", "change_set_id", "account_id"],
+	discussion: ["id"],
+	file: ["id"],
+	key_value: ["key"],
+	version: ["id"],
+	version_change: ["version_id", "change_id"],
+} as const;
+
+//
+// uo28ns,-3-9u2h
+
+/**
+ * The result of a PRAGMA table_info call.
+ *
+ * @example
+ *   	const tableInfo = sqlite.exec({
+ *		  sql: `PRAGMA table_info(change_author);`,
+ *		  returnValue: "resultRows",
+ *		  rowMode: "object",
+ *	  }) as PragmaTableInfo;
+ */
+export type PragmaTableInfo = Array<{
+	/**
+	 * The column name
+	 */
+	name: string;
+	/**
+	 * 0 if not a primary key
+	 * 1 if primary key
+	 * 2... if part of a multi-column primary key
+	 */
+	pk: number;
+}>;
+
+/**
+ * Returns the entity id for a row in a change controlled table.
+ */
+export function entityIdForRow(
+	/**
+	 * The name of the table.
+	 */
+	tableName: keyof typeof changeControlledTableIds,
+	/**
+	 * The values of the row.
+	 */
+	...values: any[]
+): string {
+	let entityId = "";
+
+	// only has one primary key
+	if (changeControlledTableIds[tableName]!.length === 1) {
+		const index = changeControlledTableIds[tableName]!.indexOf(
+			// @ts-expect-error - no clue why
+			changeControlledTableIds[tableName]![0]
+		);
+		entityId = values[index];
+	}
+	// has compound primary key that are joined with a comma.
+	else {
+		for (const column of changeControlledTableIds[tableName]!) {
+			const index = changeControlledTableIds[tableName]!.indexOf(
+				// @ts-expect-error - no clue why
+				column
+			);
+			if (entityId === "") {
+				entityId = values[index];
+			} else {
+				entityId = [entityId, values[index]].join(",");
+			}
+		}
+	}
+
+	return entityId;
+}
+
+/**
+ * Returns the primary keys for a row in a change controlled table.
+ */
+export function primaryKeysForEntityId(
+	/**
+	 * The name of the table.
+	 */
+	tableName: keyof typeof changeControlledTableIds,
+	/**
+	 * The values of the row.
+	 */
+	entitiyId: string
+): [string, any][] {
+	const primaryKeys = changeControlledTableIds[tableName]!;
+
+	if (primaryKeys.length === 1) {
+		return [[primaryKeys[0]!, entitiyId]];
+	} else {
+		return entitiyId.split(",").map((id, index) => [primaryKeys[index]!, id]);
+	}
+}