@lix-js/sdk 0.0.1 → 0.2.0

package/src/services/telemetry/capture.ts

@@ -0,0 +1,99 @@
+import { ENV_VARIABLES } from "../env-variables/index.js";
+
+/**
+ * List of telemetry events for typesafety.
+ *
+ * - prefix with `SDK` to avoid collisions with other apps
+ * - use past tense to indicate that the event is completed
+ */
+type TelemetryEvent = "LIX-SDK lix opened";
+
+/**
+ * Capture an event.
+ *
+ * - manually calling the PostHog API because the SDKs were not platform angostic (and generally bloated)
+ */
+export const capture = async (
+	event: TelemetryEvent,
+	args: {
+		lixId: string;
+		accountId: string;
+		/**
+		 * The value of the telemetry key-value pair.
+		 *
+		 * @example
+		 *   const telemetryKeyValue = await lix.db.selectFrom("key_value").select("value").where("key", "=", "lix_telemetry").executeTakeFirstOrThrow();
+		 *   await capture("LIX-SDK opened lix", { lixId: "test", accountId: "test", telemetryKeyValue: telemetryKeyValue.value, properties: {} });
+		 */
+		telemetryKeyValue: string;
+		/**
+		 * Please use snake_case for property names.
+		 */
+		properties: Record<string, any>;
+	}
+): Promise<void> => {
+	if (ENV_VARIABLES.LIX_SDK_POSTHOG_TOKEN === undefined) {
+		return;
+	} else if (args.telemetryKeyValue === "off") {
+		return;
+	}
+	try {
+		await fetch("https://eu.posthog.com/capture/", {
+			method: "POST",
+			body: JSON.stringify({
+				api_key: ENV_VARIABLES.LIX_SDK_POSTHOG_TOKEN,
+				event,
+				distinct_id: args.accountId,
+				properties: {
+					$groups: { lix_id: args.lixId },
+					...args.properties,
+				},
+			}),
+		});
+		await identifyLix({
+			lixId: args.lixId,
+			accountId: args.accountId,
+			// using the id for now as a name but can be changed in the future
+			// we need at least one property to make a project visible in the dashboard
+			properties: { name: args.lixId },
+		});
+	} catch {
+		//
+	}
+};
+
+/**
+ * Identifying a project is needed.
+ *
+ * Otherwise, the project will not be visible in the PostHog dashboard.
+ */
+const identifyLix = async (args: {
+	lixId: string;
+	accountId: string;
+	properties: Record<string, string>;
+}) => {
+	// do not send events if the token is not set
+	// (assuming this eases testing)
+	if (ENV_VARIABLES.LIX_SDK_POSTHOG_TOKEN === undefined) {
+		return;
+	}
+	try {
+		await fetch("https://eu.posthog.com/capture/", {
+			method: "POST",
+			body: JSON.stringify({
+				api_key: ENV_VARIABLES.LIX_SDK_POSTHOG_TOKEN,
+				event: "$groupidentify",
+				distinct_id: args.accountId,
+				properties: {
+					$group_type: "lix",
+					$group_key: args.lixId,
+					$group_set: {
+						...args.properties,
+					},
+				},
+			}),
+		});
+	} catch {
+		//
+	}
+};

package/src/sync/pull-from-server.test.ts

@@ -4,11 +4,14 @@ import { openLixInMemory } from "../lix/open-lix-in-memory.js";
 import { pullFromServer } from "./pull-from-server.js";
 import { mockJsonSnapshot } from "../snapshot/mock-json-snapshot.js";
 import { createLsaInMemoryEnvironment } from "../server-api-handler/environment/create-in-memory-environment.js";
+import { toBlob } from "../lix/to-blob.js";
 
 test("pull rows of multiple tables from server successfully and applies them", async () => {
 	const lixOnServer = await openLixInMemory({});
 
-	const lix = await openLixInMemory({ blob: await lixOnServer.toBlob() });
+	const lix = await openLixInMemory({
+		blob: await toBlob({ lix: lixOnServer }),
+	});
 
 	const { value: id } = await lixOnServer.db
 		.selectFrom("key_value")
@@ -38,7 +41,7 @@ test("pull rows of multiple tables from server successfully and applies them", a
 	await lsaHandler(
 		new Request("http://localhost:3000/lsa/new-v1", {
 			method: "POST",
-			body: await lixOnServer.toBlob(),
+			body: await toBlob({ lix: lixOnServer }),
 			headers: {
 				"Content-Type": "application/json",
 			},
@@ -66,13 +69,15 @@ test("pull rows of multiple tables from server successfully and applies them", a
 		.executeTakeFirstOrThrow();
 
 	expect(account).toEqual({ id: "account0", name: "test account" });
-	expect(mockKey).toEqual({ key: "mock-key", value: "mock-value" });
+	expect(mockKey).toMatchObject({ key: "mock-key", value: "mock-value" });
 });
 
 test("it handles snapshot.content being json binary", async () => {
 	const lixOnServer = await openLixInMemory({});
 
-	const lix = await openLixInMemory({ blob: await lixOnServer.toBlob() });
+	const lix = await openLixInMemory({
+		blob: await toBlob({ lix: lixOnServer }),
+	});
 
 	const { value: id } = await lixOnServer.db
 		.selectFrom("key_value")
@@ -101,7 +106,7 @@ test("it handles snapshot.content being json binary", async () => {
 	await lsaHandler(
 		new Request("http://localhost:3000/lsa/new-v1", {
 			method: "POST",
-			body: await lixOnServer.toBlob(),
+			body: await toBlob({ lix: lixOnServer }),
 			headers: {
 				"Content-Type": "application/json",
 			},
@@ -141,7 +146,9 @@ test("rows changed on the client more recently should not be updated", async ()
 		})
 		.executeTakeFirstOrThrow();
 
-	const lix = await openLixInMemory({ blob: await lixOnServer.toBlob() });
+	const lix = await openLixInMemory({
+		blob: await toBlob({ lix: lixOnServer }),
+	});
 
 	const environment = createLsaInMemoryEnvironment();
 	const lsaHandler = await createServerApiHandler({ environment });
@@ -152,7 +159,7 @@ test("rows changed on the client more recently should not be updated", async ()
 	await lsaHandler(
 		new Request("http://localhost:3000/lsa/new-v1", {
 			method: "POST",
-			body: await lixOnServer.toBlob(),
+			body: await toBlob({ lix: lixOnServer }),
 			headers: {
 				"Content-Type": "application/json",
 			},
@@ -179,7 +186,10 @@ test("rows changed on the client more recently should not be updated", async ()
 		.selectAll()
 		.executeTakeFirstOrThrow();
 
-	expect(mockKey).toEqual({ key: "mock-key", value: "mock-value-updated" });
+	expect(mockKey).toMatchObject({
+		key: "mock-key",
+		value: "mock-value-updated",
+	});
 });
 
 // the change table now models "change control". no more last edit wins needed
@@ -192,7 +202,9 @@ test.skip("rows changed on the server more recently should be updated on the cli
 
 	// create a lix and clone it for the client - so they share the same lix id
 	const remoteLix = await openLixInMemory({});
-	const localLix = await openLixInMemory({ blob: await remoteLix.toBlob() });
+	const localLix = await openLixInMemory({
+		blob: await toBlob({ lix: remoteLix }),
+	});
 
 	// insert mock data into server lix
 	await remoteLix.db
@@ -234,7 +246,7 @@ test.skip("rows changed on the server more recently should be updated on the cli
 	await lsaHandler(
 		new Request("http://localhost:3000/lsa/new-v1", {
 			method: "POST",
-			body: await remoteLix.toBlob(),
+			body: await toBlob({ lix: remoteLix }),
 			headers: {
 				"Content-Type": "application/json",
 			},
@@ -347,7 +359,7 @@ test("non-conflicting changes from the server should for the same version should
 
 	global.fetch = vi.fn((request) => lsaHandler(request));
 
-	const lixOnServer = await openLixInMemory({ blob: await lix.toBlob() });
+	const lixOnServer = await openLixInMemory({ blob: await toBlob({ lix }) });
 
 	// insert data on the server that the client does not have yet
 	await lixOnServer.db
@@ -369,7 +381,10 @@ test("non-conflicting changes from the server should for the same version should
 		expect.arrayContaining([
 			expect.objectContaining({
 				version_id: currentVersion.id,
-				content: { key: "mock-key", value: "mock-value" },
+				content: expect.objectContaining({
+					key: "mock-key",
+					value: "mock-value",
+				}),
 			}),
 		])
 	);
@@ -377,7 +392,7 @@ test("non-conflicting changes from the server should for the same version should
 	await lsaHandler(
 		new Request("http://localhost:3000/lsa/new-v1", {
 			method: "POST",
-			body: await lixOnServer.toBlob(),
+			body: await toBlob({ lix: lixOnServer }),
 			headers: {
 				"Content-Type": "application/json",
 			},
@@ -405,6 +420,6 @@ test("non-conflicting changes from the server should for the same version should
 		.select("snapshot.content as content")
 		.execute();
 
-	expect(mockKey).toEqual({ key: "mock-key", value: "mock-value" });
+	expect(mockKey).toMatchObject({ key: "mock-key", value: "mock-value" });
 	expect(versionChanges).toEqual(expect.arrayContaining(serverVersionChanges));
 });

package/src/sync/pull-from-server.ts

@@ -133,8 +133,6 @@ export async function pullFromServer(args: {
 		});
 
 		if (changesToApply.length > 0) {
-			// the changes already exists hence prevent own change control
-			// from creating new changes for the applied changes
 			await applyChanges({
 				lix: { ...args.lix, db: trx },
 				changes: changesToApply,

package/src/sync/push-to-server.test.ts

@@ -5,10 +5,11 @@ import { pushToServer } from "./push-to-server.js";
 import type { LixFile } from "../database/schema.js";
 import type { Account } from "../account/database-schema.js";
 import { newLixFile } from "../lix/new-lix.js";
-import type { KeyValue } from "../key-value/database-schema.js";
+import type { NewKeyValue } from "../key-value/database-schema.js";
 import { mockJsonSnapshot } from "../snapshot/mock-json-snapshot.js";
 import { pullFromServer } from "./pull-from-server.js";
 import { createLsaInMemoryEnvironment } from "../server-api-handler/environment/create-in-memory-environment.js";
+import { toBlob } from "../lix/to-blob.js";
 
 test("push rows of multiple tables to server successfully", async () => {
 	const lixBlob = await newLixFile();
@@ -30,7 +31,7 @@ test("push rows of multiple tables to server successfully", async () => {
 	await lsaHandler(
 		new Request("http://localhost:3000/lsa/new-v1", {
 			method: "POST",
-			body: await lix.toBlob(),
+			body: await toBlob({ lix }),
 		})
 	);
 
@@ -83,11 +84,11 @@ test("push rows of multiple tables to server successfully", async () => {
 		{ id: "account0", name: "some account" } satisfies Account,
 	]);
 	expect(keyValueChangesOnServer.map((c) => c.content)).toEqual([
-		{
+		expect.objectContaining({
 			key: "mock-key",
 			value: "mock-value",
-		},
-	] satisfies KeyValue[]);
+		}),
+	] satisfies NewKeyValue[]);
 });
 
 test("push-pull-push with two clients", async () => {
@@ -111,7 +112,7 @@ test("push-pull-push with two clients", async () => {
 	await lsaHandler(
 		new Request("http://localhost:3000/lsa/new-v1", {
 			method: "POST",
-			body: await client1.toBlob(),
+			body: await toBlob({ lix: client1 }),
 		})
 	);
 
@@ -165,10 +166,10 @@ test("push-pull-push with two clients", async () => {
 
 	expect(client2KeyValueAfterPull).toEqual(
 		expect.arrayContaining([
-			{
+			expect.objectContaining({
 				key: "mock-key",
 				value: "mock-value from client 1",
-			} satisfies KeyValue,
+			} satisfies NewKeyValue),
 		])
 	);
 
@@ -260,15 +261,18 @@ test("push-pull-push with two clients", async () => {
 
 	expect(keyValueChangesOnServer.map((c) => c.content)).toEqual(
 		expect.arrayContaining([
-			{
+			expect.objectContaining({
 				key: "mock-key",
 				value: "mock-value from client 1",
-			},
-			{
+			}),
+			expect.objectContaining({
 				key: "mock-key",
 				value: "mock-value from client 1 - updated by client 2",
-			},
-			{ key: "mock-key-2", value: "mock-value from client 2" },
+			}),
+			expect.objectContaining({
+				key: "mock-key-2",
+				value: "mock-value from client 2",
+			}),
 		])
 	);
 });
@@ -291,7 +295,7 @@ test("it should handle snapshots.content json binaries", async () => {
 	await lsaHandler(
 		new Request("http://localhost:3000/lsa/new-v1", {
 			method: "POST",
-			body: await lix.toBlob(),
+			body: await toBlob({ lix }),
 		})
 	);
 
@@ -345,7 +349,7 @@ test.todo("it should handle binary values", async () => {
 	await lsaHandler(
 		new Request("http://localhost:3000/lsa/new", {
 			method: "POST",
-			body: await lix.toBlob(),
+			body: await toBlob({ lix }),
 		})
 	);
 

package/src/sync/sync-process.test.ts

@@ -8,6 +8,7 @@ import { createVersion } from "../version/create-version.js";
 import { switchVersion } from "../version/switch-version.js";
 import type { Version } from "../database/schema.js";
 import { executeSync } from "../database/execute-sync.js";
+import { toBlob } from "../lix/to-blob.js";
 
 test("versions should be synced", async () => {
 	const environment = createLsaInMemoryEnvironment();
@@ -16,7 +17,7 @@ test("versions should be synced", async () => {
 	global.fetch = vi.fn((request) => lsaHandler(request));
 
 	const lix0 = await openLixInMemory({
-		keyValues: [{ key: "#lix_sync", value: "true" }],
+		keyValues: [{ key: "lix_server_url", value: "http://mock.com" }],
 	});
 
 	// @ts-expect-error - eases debugging
@@ -32,32 +33,26 @@ test("versions should be synced", async () => {
 	await lsaHandler(
 		new Request("http://mock.com/lsa/new-v1", {
 			method: "POST",
-			body: await lix0.toBlob(),
+			body: await toBlob({ lix: lix0 }),
 		})
 	);
 
 	// create a second client
 	const lix1 = await openLixInMemory({
-		blob: await lix0.toBlob(),
-		keyValues: [{ key: "#lix_sync", value: "true" }],
+		blob: await toBlob({ lix: lix0 }),
+		keyValues: [{ key: "lix_sync", value: "true" }],
 	});
 
 	// start syncing
-	await lix0.db
-		.insertInto("key_value")
-		.values({
-			key: "lix_server_url",
-			value: "http://mock.com",
-		})
-		.execute();
-
-	await lix1.db
-		.insertInto("key_value")
-		.values({
-			key: "lix_server_url",
-			value: "http://mock.com",
-		})
-		.execute();
+	await Promise.all(
+		[lix0, lix1].map((lix) =>
+			lix.db
+				.updateTable("key_value")
+				.where("key", "=", "lix_sync")
+				.set({ value: "true" })
+				.execute()
+		)
+	);
 
 	// @ts-expect-error - eases debugging
 	lix1.db.__name = "lix1";
@@ -74,7 +69,7 @@ test("versions should be synced", async () => {
 			.executeTakeFirstOrThrow();
 		version0 = await createVersion({
 			lix: { ...lix0, db: trx },
-			parent: currentVersion,
+			from: currentVersion,
 			name: "version0",
 		});
 		await switchVersion({ lix: { ...lix0, db: trx }, to: version0 });
@@ -113,17 +108,16 @@ test("versions should be synced", async () => {
 	expect(lix0Versions).toEqual(lix1Versions);
 
 	// expecting both lix0 and lix1 to have the same version changes
-	const lix0VersionChanges = await lix0.db
-		.selectFrom("version_change")
-		.orderBy("change_id", "desc")
-		.selectAll()
-		.execute();
-
-	const lix1VersionChanges = await lix1.db
-		.selectFrom("version_change")
-		.orderBy("change_id", "desc")
-		.selectAll()
-		.execute();
+	const [lix0VersionChanges, lix1VersionChanges] = await Promise.all(
+		[lix0, lix1].map((lix) =>
+			lix.db
+				.selectFrom("version_change")
+				.orderBy("change_id", "desc")
+				.orderBy("version_id", "desc")
+				.selectAll()
+				.execute()
+		)
+	);
 
 	expect(lix0VersionChanges).toEqual(lix1VersionChanges);
 });
@@ -137,7 +131,7 @@ test("switching synced versions should work", async () => {
 	global.executeSync = executeSync;
 
 	const lix0 = await openLixInMemory({
-		keyValues: [{ key: "#lix_sync", value: "true" }],
+		keyValues: [{ key: "lix_sync", value: "true" }],
 	});
 	// @ts-expect-error - eases debugging
 	lix0.db.__name = "lix0";
@@ -154,7 +148,7 @@ test("switching synced versions should work", async () => {
 	await lsaHandler(
 		new Request("http://mock.com/lsa/new-v1", {
 			method: "POST",
-			body: await lix0.toBlob(),
+			body: await toBlob({ lix: lix0 }),
 		})
 	);
 
@@ -169,8 +163,8 @@ test("switching synced versions should work", async () => {
 
 	// create a second client
 	const lix1 = await openLixInMemory({
-		blob: await lix0.toBlob(),
-		keyValues: [{ key: "#lix_sync", value: "true" }],
+		blob: await toBlob({ lix: lix0 }),
+		keyValues: [{ key: "lix_sync", value: "true" }],
 	});
 
 	// @ts-expect-error - eases debugging
@@ -187,7 +181,7 @@ test("switching synced versions should work", async () => {
 	const version0 = await createVersion({
 		lix: lix0,
 		name: "version0",
-		parent: currentVersion,
+		from: currentVersion,
 	});
 
 	await switchVersion({ lix: lix0, to: version0 });
@@ -239,13 +233,13 @@ test("switching synced versions should work", async () => {
 		.selectAll()
 		.executeTakeFirst();
 
-	expect(keyValue).toEqual({
+	expect(keyValue).toMatchObject({
 		key: "mock-key",
 		value: "mock",
 	});
 });
 
-test("doesnt sync if #lix_sync is not true", async () => {
+test("doesnt sync if lix_sync is not true", async () => {
 	const environment = createLsaInMemoryEnvironment();
 	const lsaHandler = await createServerApiHandler({ environment });
 	global.fetch = vi.fn((request) => lsaHandler(request));
@@ -262,14 +256,14 @@ test("doesnt sync if #lix_sync is not true", async () => {
 	await lsaHandler(
 		new Request("http://mock.com/lsa/new-v1", {
 			method: "POST",
-			body: await lix.toBlob(),
+			body: await toBlob({ lix }),
 		})
 	);
 
 	await lix.db
 		.updateTable("key_value")
 		.set({ value: "false" })
-		.where("key", "=", "#lix_sync")
+		.where("key", "=", "lix_sync")
 		.execute();
 
 	await lix.db
@@ -301,7 +295,7 @@ test("doesnt sync if #lix_sync is not true", async () => {
 	await lix.db
 		.updateTable("key_value")
 		.set({ value: "true" })
-		.where("key", "=", "#lix_sync")
+		.where("key", "=", "lix_sync")
 		.execute();
 
 	await new Promise((resolve) => setTimeout(resolve, 1010));
@@ -317,10 +311,10 @@ test("doesnt sync if #lix_sync is not true", async () => {
 	expect(keyValueChangesOnServerAfterSync).toEqual(
 		expect.arrayContaining([
 			expect.objectContaining({
-				content: {
+				content: expect.objectContaining({
 					key: "foo",
 					value: "bar",
-				},
+				}),
 			}),
 		])
 	);

package/src/sync/sync-process.ts

@@ -1,27 +1,21 @@
 import type { Lix } from "../lix/open-lix.js";
 import { pushToServer } from "./push-to-server.js";
 import { pullFromServer } from "./pull-from-server.js";
+import { toBlob } from "../lix/to-blob.js";
 
 export async function initSyncProcess(args: {
-	lix: Pick<Lix, "db" | "plugin" | "toBlob">;
-}): Promise<
-	| {
-			stop: () => void;
-	  }
-	| undefined
-> {
+	lix: Pick<Lix, "db" | "plugin" | "sqlite">;
+}): Promise<void> {
 	const lixId = await args.lix.db
 		.selectFrom("key_value")
 		.where("key", "=", "lix_id")
 		.select("value")
 		.executeTakeFirstOrThrow();
 
-	let stoped = false;
-
 	const pullAndPush = async () => {
 		const shouldSync = await args.lix.db
 			.selectFrom("key_value")
-			.where("key", "=", "#lix_sync")
+			.where("key", "=", "lix_sync")
 			.select("value")
 			.executeTakeFirst();
 
@@ -40,7 +34,6 @@ export async function initSyncProcess(args: {
 		if (!url) {
 			return;
 		}
-
 		try {
 			// console.log("----------- PULL FROM SERVER -------------");
 			const serverState = await pullFromServer({
@@ -64,7 +57,7 @@ export async function initSyncProcess(args: {
 			const response = await fetch(
 				new Request(url.value + "/lsa/new-v1", {
 					method: "POST",
-					body: await args.lix.toBlob(),
+					body: await toBlob({ lix: args.lix }),
 				})
 			);
 			if (!response.ok && response.status !== 409) {
@@ -77,21 +70,21 @@ export async function initSyncProcess(args: {
 	// naive implementation that syncs every second
 
 	function schedulePullAndPush() {
-		if (!stoped) {
-			pullAndPush().catch((e) => {
-				console.error("Error in sync process", e);
-			});
+		if (args.lix.sqlite.isOpen() === false) {
+			return;
 		}
+		pullAndPush().catch((e) => {
+			if (e instanceof Error && e.message.includes("DB has been closed.")) {
+				// stop the syncing process, the database has been closed.
+				return;
+			}
+			console.error("Error in sync process", e);
+		});
+		// schedule next sync
 		setTimeout(() => {
 			schedulePullAndPush();
-		}, 1000);
+		}, 750);
 	}
 
 	schedulePullAndPush();
-
-	return {
-		stop: () => {
-			stoped = true;
-		},
-	};
 }

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

@@ -42,7 +42,7 @@ test("it should copy the changes from the parent version", async () => {
 
 	const version1 = await createVersion({
 		lix,
-		parent: version0,
+		from: version0,
 	});
 
 	const changesInversion0 = await lix.db
@@ -132,7 +132,7 @@ test("it should copy change conflict pointers from the parent version", async ()
 
 	const version1 = await createVersion({
 		lix,
-		parent: version0,
+		from: version0,
 		name: "version1",
 	});