@lix-js/sdk 0.0.1

package/src/own-entity-change-control/database-triggers.test.ts

@@ -0,0 +1,259 @@
+import { expect, test } from "vitest";
+import { openLixInMemory } from "../lix/open-lix-in-memory.js";
+import { createAccount } from "../account/create-account.js";
+import { createChange } from "../change/create-change.js";
+
+test("it works for inserts, updates and deletions", async () => {
+	const lix = await openLixInMemory({});
+
+	// insert
+	await lix.db
+		.insertInto("key_value")
+		.values({ key: "key1", value: "value1" })
+		.execute();
+
+	// update
+	await lix.db
+		.updateTable("key_value")
+		.set("value", "value2")
+		.where("key", "=", "key1")
+		.execute();
+
+	// delete
+	await lix.db.deleteFrom("key_value").where("key", "=", "key1").execute();
+
+	const changes = await lix.db
+		.selectFrom("change")
+		.innerJoin("snapshot", "snapshot.id", "change.snapshot_id")
+		.where("schema_key", "=", "lix_key_value_table")
+		.selectAll()
+		.execute();
+
+	const snapshots = changes.map((change) => change.content);
+
+	expect(changes.length).toBe(3);
+
+	for (const change of changes) {
+		expect(change.entity_id).toBe("key1");
+		expect(change.file_id).toBe("null");
+		expect(change.plugin_key).toBe("lix_own_entity");
+		expect(change.schema_key).toBe("lix_key_value_table");
+	}
+
+	expect(snapshots).toStrictEqual([
+		// insert
+		{ key: "key1", value: "value1" },
+		// update
+		{ key: "key1", value: "value2" },
+		// delete
+		null,
+	]);
+});
+
+test("it works for compound entity ids like change_author", async () => {
+	const lix = await openLixInMemory({});
+
+	const account1 = await createAccount({ lix, name: "account1" });
+
+	const currentVersion = await lix.db
+		.selectFrom("current_version")
+		.selectAll()
+		.executeTakeFirstOrThrow();
+
+	await createChange({
+		lix,
+		version: currentVersion,
+		authors: [account1],
+		pluginKey: "mock-plugin",
+		schemaKey: "mock",
+		fileId: "mock",
+		entityId: "mock",
+		snapshotContent: null,
+	});
+
+	const changes = await lix.db
+		.selectFrom("change")
+		.where("schema_key", "=", "lix_change_author_table")
+		.innerJoin("snapshot", "snapshot.id", "change.snapshot_id")
+		.selectAll()
+		.execute();
+
+	expect(changes.length).toBe(1);
+});
+
+test("if the trigger throws, the transaction is rolled back", async () => {
+	const lix = await openLixInMemory({});
+
+	const account1 = await createAccount({ lix, name: "account1" });
+
+	const insertChange = await lix.db
+		.selectFrom("change")
+		.where("schema_key", "=", "lix_account_table")
+		.where("entity_id", "=", account1.id)
+		.selectAll()
+		.executeTakeFirstOrThrow();
+
+	expect(insertChange).toBeDefined();
+
+	// deleting the active accounts aka there will be no change author
+	// which will lead to a throw in the trigger
+	await lix.db.deleteFrom("active_account").execute();
+
+	// now we are deleting the account we just created
+	try {
+		await lix.db.deleteFrom("account").where("id", "=", account1.id).execute();
+	} catch (e) {
+		expect(e).toBeDefined();
+	}
+
+	const account1AfterFailedDeleted = await lix.db
+		.selectFrom("account")
+		.where("id", "=", account1.id)
+		.selectAll()
+		.executeTakeFirst();
+
+	const deleteChange = await lix.db
+		.selectFrom("change")
+		.where("schema_key", "=", "lix_account_table")
+		.where("entity_id", "=", account1.id)
+		.where("snapshot_id", "=", "no-content")
+		.selectAll()
+		.executeTakeFirst();
+
+	expect(account1AfterFailedDeleted).toBeDefined();
+	expect(account1AfterFailedDeleted).toStrictEqual(account1);
+	expect(deleteChange).toBeUndefined();
+});
+
+test("skips change control of key values if the key begins with `#`", async () => {
+	const lix = await openLixInMemory({});
+
+	await lix.db
+		.insertInto("key_value")
+		.values({ key: "#key1", value: "value1" })
+		.execute();
+
+	const key1 = await lix.db
+		.selectFrom("key_value")
+		.where("key", "=", "#key1")
+		.selectAll()
+		.executeTakeFirst();
+
+	const key1Change = await lix.db
+		.selectFrom("change")
+		.where("entity_id", "=", "#key1")
+		.selectAll()
+		.executeTakeFirst();
+
+	expect(key1).toBeDefined();
+	expect(key1Change).toBeUndefined();
+});
+
+// the sqlite jsonb representation should not be used externally
+// hence, we need to store the metadata as string in the snapshot
+test("file.metadata is tracked as json string, not binary.", async () => {
+	const lix = await openLixInMemory({});
+
+	const file = await lix.db
+		.insertInto("file")
+		.values({
+			data: new Uint8Array(),
+			path: "/mock.txt",
+			metadata: { key: "value" },
+		})
+		.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()
+		.executeTakeFirstOrThrow();
+
+	expect(change.content?.metadata).toStrictEqual({
+		key: "value",
+	});
+});
+
+test("file.data is not own change controlled as plugins handle the change control of file data", async () => {
+	const lix = await openLixInMemory({});
+
+	const file = await lix.db
+		.insertInto("file")
+		.values({
+			path: "/mock.txt",
+			data: new TextEncoder().encode("hello world"),
+		})
+		.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()
+		.executeTakeFirstOrThrow();
+
+	expect(change.content?.data).toBe(undefined);
+});
+
+test("updating file.data does not trigger own change control", async () => {
+	const lix = await openLixInMemory({});
+
+	const file = await lix.db
+		.insertInto("file")
+		.values({
+			id: "file1",
+			data: new TextEncoder().encode("hello world"),
+			path: "/mock.txt",
+			metadata: null,
+		})
+		.returningAll()
+		.executeTakeFirstOrThrow();
+
+	let changes = await lix.db
+		.selectFrom("change")
+		.where("schema_key", "=", "lix_file_table")
+		.where("entity_id", "=", file.id)
+		.selectAll()
+		.execute();
+
+	expect(changes.length).toBe(1);
+
+	await lix.db
+		.updateTable("file")
+		.set({ data: new TextEncoder().encode("hello world 2") })
+		.where("id", "=", file.id)
+		.execute();
+
+	changes = await lix.db
+		.selectFrom("change")
+		.where("schema_key", "=", "lix_file_table")
+		.where("entity_id", "=", file.id)
+		.selectAll()
+		.execute();
+
+	expect(changes.length).toBe(1);
+
+	// the metadata should be change controlled
+	// hence, this should trigger a change
+	await lix.db
+		.updateTable("file")
+		.set({
+			data: new TextEncoder().encode("hello world 3"),
+			metadata: { key: "value" },
+		})
+		.execute();
+
+	changes = await lix.db
+		.selectFrom("change")
+		.where("schema_key", "=", "lix_file_table")
+		.where("entity_id", "=", file.id)
+		.selectAll()
+		.execute();
+
+	expect(changes.length).toBe(2);
+});

package/src/own-entity-change-control/database-triggers.ts

@@ -0,0 +1,189 @@
+import type { SqliteDatabase } from "sqlite-wasm-kysely";
+import type { LixDatabaseSchema, Snapshot } from "../database/schema.js";
+import type { Kysely } from "kysely";
+import {
+	changeControlledTableIds,
+	entityIdForRow,
+	type PragmaTableInfo,
+} from "./change-controlled-tables.js";
+import { createChange } from "../change/create-change.js";
+import { executeSync } from "../database/execute-sync.js";
+
+export function applyOwnEntityChangeControlTriggers(
+	sqlite: SqliteDatabase,
+	db: Kysely<LixDatabaseSchema>
+): void {
+	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;
+	}
+
+	sqlite.createFunction({
+		name: "handle_lix_own_entity_change",
+		arity: -1,
+		// @ts-expect-error - dynamic function
+		xFunc: (
+			_ctx: number,
+			tableName: keyof typeof changeControlledTableIds,
+			operation: "insert" | "update" | "delete",
+			...value
+		) => {
+			return handleLixOwnEntityChange(
+				db,
+				sqlite,
+				tableName,
+				tableInfos,
+				operation,
+				...value
+			);
+		},
+	});
+
+	for (const table of Object.keys(changeControlledTableIds)) {
+		const tableInfo = tableInfos[table]!;
+
+		const sql = `
+      CREATE TEMP TRIGGER IF NOT EXISTS ${table}_change_control_insert
+      AFTER INSERT ON ${table}
+      BEGIN
+        SELECT handle_lix_own_entity_change('${table}', 'insert', ${tableInfo.map((c) => "NEW." + c.name).join(", ")});
+      END;
+      
+      CREATE TEMP TRIGGER IF NOT EXISTS ${table}_change_control_update
+      AFTER UPDATE ON ${table}
+			${
+				// ignore update trigger if the change controlled properties
+				// did not change (a plugin likely called apply changes on the file.data)
+				table === "file"
+					? `
+			WHEN (
+				OLD.id IS NOT NEW.id OR
+				OLD.path IS NOT NEW.path OR
+				OLD.metadata IS NOT NEW.metadata
+			)`
+					: ""
+			}
+      BEGIN
+        SELECT handle_lix_own_entity_change('${table}', 'update', ${tableInfo.map((c) => "NEW." + c.name).join(", ")});
+      END;
+
+      CREATE TEMP TRIGGER IF NOT EXISTS ${table}_change_control_delete
+      AFTER DELETE ON ${table}
+      BEGIN
+        SELECT handle_lix_own_entity_change('${table}', 'delete', ${tableInfo.map((c) => "OLD." + c.name).join(", ")});
+      END;
+      `;
+
+		sqlite.exec(sql);
+	}
+}
+
+function handleLixOwnEntityChange(
+	db: Kysely<LixDatabaseSchema>,
+	sqlite: SqliteDatabase,
+	tableName: keyof typeof changeControlledTableIds,
+	tableInfos: Record<keyof typeof changeControlledTableIds, PragmaTableInfo>,
+	operation: "insert" | "update" | "delete",
+	...values: any[]
+): void {
+	const lix = { db, sqlite };
+
+	// keys starting with `#` are not change controlled
+	if (tableName === "key_value" && values[0].startsWith("#")) {
+		return;
+	}
+
+	const shouldSkip =
+		executeSync({
+			lix,
+			query: db
+				.selectFrom("key_value")
+				.where("key", "=", "#lix_skip_own_change_control")
+				.select("value"),
+		})[0]?.value === "true";
+
+	if (shouldSkip) {
+		return;
+	}
+
+	// need to break the loop if own changes are detected
+	const change = executeSync({
+		lix,
+		query: db
+			.selectFrom("change")
+			.where("id", "=", values[0])
+			.select("plugin_key"),
+	})[0];
+
+	if (change?.plugin_key === "lix_own_entity") {
+		return;
+	}
+
+	const currentVersion = executeSync({
+		lix,
+		query: db
+			.selectFrom("current_version")
+			.innerJoin("version", "current_version.id", "version.id")
+			.selectAll("version"),
+	})[0];
+
+	const authors = executeSync({
+		lix,
+		query: db.selectFrom("active_account").selectAll(),
+	});
+
+	if (authors.length === 0) {
+		console.error(tableName, change);
+		throw new Error("At least one author is required");
+	}
+
+	let snapshotContent: Snapshot["content"] | null;
+
+	if (operation === "delete") {
+		snapshotContent = null;
+	} else {
+		snapshotContent = {};
+		// construct the values as json for the snapshot
+		for (const [index, column] of tableInfos[tableName]!.entries()) {
+			snapshotContent[column.name] = values[index];
+		}
+	}
+
+	if (tableName === "file" && snapshotContent) {
+		// sqlite has it's own jsonb format
+		// hence, need to query sqlite to convert
+		// to json
+		const json = sqlite.exec("SELECT json(?)", {
+			bind: [snapshotContent.metadata],
+			returnValue: "resultRows",
+		})[0]![0];
+
+		snapshotContent["metadata"] = JSON.parse(json as string);
+
+		// remove the data field which is change controlled by plugins, not lix itself
+		delete snapshotContent.data;
+	}
+
+	const entityId = entityIdForRow(tableName, ...values);
+
+	createChange(
+		{
+			lix,
+			authors: authors,
+			version: currentVersion,
+			entityId,
+			fileId: "null",
+			pluginKey: "lix_own_entity",
+			schemaKey: `lix_${tableName}_table`,
+			snapshotContent,
+		},
+		{
+			updateVersionChanges: tableName === "version_change" ? false : true,
+		}
+	);
+}

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

@@ -0,0 +1 @@
+export { withSkipOwnChangeControl } from "./with-skip-own-change-control.js";

package/src/own-entity-change-control/with-skip-own-change-control.test.ts

@@ -0,0 +1,57 @@
+import { test, expect } from "vitest";
+import { openLixInMemory } from "../lix/open-lix-in-memory.js";
+import { withSkipOwnChangeControl } from "./with-skip-own-change-control.js";
+
+test("skipping works", async () => {
+	const lix = await openLixInMemory({});
+
+	await withSkipOwnChangeControl(lix.db, async (trx) => {
+		await trx
+			.insertInto("key_value")
+			.values({ key: "foo", value: "bar" })
+			.execute();
+		await trx
+			.insertInto("key_value")
+			.values({ key: "foo2", value: "bar2" })
+			.execute();
+	});
+
+	const keyValues = await lix.db.selectFrom("key_value").selectAll().execute();
+	const changes = await lix.db
+		.selectFrom("change")
+		.where("schema_key", "=", "lix_key_value_table")
+		.selectAll()
+		.execute();
+
+	expect(keyValues.find((kv) => kv.key === "foo")).toBeDefined();
+	expect(keyValues.find((kv) => kv.key === "foo2")).toBeDefined();
+
+	console.log(changes);
+	expect(changes).toHaveLength(0);
+});
+
+test("if an outside transaction sets the value to true, no conflict should arise", async () => {
+	const lix = await openLixInMemory({});
+
+	// simulating an outside transaction setting the value to true
+	await withSkipOwnChangeControl(lix.db, async (trx) => {
+		// and an inside transaction setting the value to true as well
+		await withSkipOwnChangeControl(trx, async (trx2) => {
+			await trx2
+				.insertInto("key_value")
+				.values({ key: "foo", value: "bar" })
+				.execute();
+		});
+	});
+
+	const keyValues = await lix.db.selectFrom("key_value").selectAll().execute();
+	const changes = await lix.db
+		.selectFrom("change")
+		.where("schema_key", "=", "lix_key_value_table")
+		.where("entity_id", "=", "foo")
+		.selectAll()
+		.execute();
+
+	expect(changes).toHaveLength(0);
+	expect(keyValues.find((kv) => kv.key === "foo")).toBeDefined();
+});

package/src/own-entity-change-control/with-skip-own-change-control.ts

@@ -0,0 +1,30 @@
+import type { Lix } from "../lix/open-lix.js";
+
+export async function withSkipOwnChangeControl<T>(
+	db: Lix["db"],
+	operation: (trx: Lix["db"]) => Promise<T>
+): Promise<T> {
+	const executeInTransaction = async (trx: Lix["db"]) => {
+		await trx
+			.insertInto("key_value")
+			.values({ key: "#lix_skip_own_change_control", value: "true" })
+			.onConflict((oc) => oc.doUpdateSet({ value: "true" }))
+			.execute();
+
+		// Perform the user's operation
+		const result = await operation(trx);
+
+		await trx
+			.deleteFrom("key_value")
+			.where("key", "=", "#lix_skip_own_change_control")
+			.execute();
+
+		// Return the result of the operation
+		return result;
+	};
+	if (db.isTransaction) {
+		return executeInTransaction(db);
+	} else {
+		return db.transaction().execute(executeInTransaction);
+	}
+}

package/src/plugin/index.ts

@@ -0,0 +1,6 @@
+export type {
+	LixPlugin,
+	DetectedChange,
+	DetectedConflict,
+	LixReadonly,
+} from "./lix-plugin.js";

package/src/plugin/lix-plugin.test-d.ts

@@ -0,0 +1,45 @@
+/* eslint-disable @typescript-eslint/no-unused-vars */
+import { assertType, test } from "vitest";
+import type { DetectedChange, LixPlugin } from "./lix-plugin.js";
+import type { ExperimentalChangeSchema } from "../change-schema/types.js";
+
+test("json schema type of a detected change", () => {
+	const MockChangeSchema = {
+		key: "mock",
+		type: "json",
+		schema: {
+			type: "object",
+			properties: {
+				name: { type: "string" },
+				age: { type: "number" },
+				location: { type: "object" },
+			},
+			required: ["name", "age", "location"],
+		},
+	} as const satisfies ExperimentalChangeSchema;
+
+	const change: DetectedChange<typeof MockChangeSchema> = {
+		entity_id: "123",
+		schema: MockChangeSchema,
+		snapshot: {
+			name: "John",
+			age: 5,
+			location: {
+				city: "New York",
+				country: "USA",
+			},
+		},
+	};
+
+	assertType(change);
+});
+
+test("file.data is potentially undefined", () => {
+	const plugin: LixPlugin = {
+		key: "plugin1",
+		applyChanges: async ({ file }) => {
+			assertType<ArrayBuffer | undefined>(file.data);
+			return { fileData: new Uint8Array() };
+		},
+	};
+});