@lix-js/sdk 0.0.1

package/src/query-filter/change-set-has-label.test.ts

@@ -0,0 +1,50 @@
+/* eslint-disable @typescript-eslint/no-unused-vars */
+import { test, expect } from "vitest";
+import { changeSetHasLabel } from "./change-set-has-label.js";
+import { openLixInMemory } from "../lix/open-lix-in-memory.js";
+import { createChangeSet } from "../change-set/create-change-set.js";
+import { mockChange } from "../change/mock-change.js";
+
+test("should only return change sets with the given label", async () => {
+	const lix = await openLixInMemory({});
+
+	await lix.db
+		.insertInto("change")
+		.values([mockChange({ id: "change1" }), mockChange({ id: "change2" })])
+		.execute();
+
+	// Create two change sets
+	const changeSet1 = await createChangeSet({
+		lix,
+		changes: [{ id: "change1" }],
+	});
+
+	const changeSet2 = await createChangeSet({
+		lix,
+		changes: [{ id: "change2" }],
+	});
+
+	// Insert a label
+	const label = await lix.db
+		.insertInto("label")
+		.values({ name: "mocked" })
+		.returningAll()
+		.executeTakeFirstOrThrow();
+
+	// Assign the label to one of the change sets
+	await lix.db
+		.insertInto("change_set_label")
+		.values({ change_set_id: changeSet1.id, label_id: label.id })
+		.execute();
+
+	// Query change sets with the label
+	const changeSets = await lix.db
+		.selectFrom("change_set")
+		.where(changeSetHasLabel("mocked"))
+		.selectAll()
+		.execute();
+
+	// Assertions
+	expect(changeSets).toHaveLength(1);
+	expect(changeSets[0]?.id).toBe(changeSet1.id);
+});

package/src/query-filter/change-set-has-label.ts

@@ -0,0 +1,36 @@
+import type { ExpressionBuilder, ExpressionWrapper, SqlBool } from "kysely";
+import type { LixDatabaseSchema } from "../database/schema.js";
+
+/**
+ * Selects change sets that have a label with the given name.
+ *
+ * @example
+ *   ```ts
+ *   await lix.db.selectFrom("change_set")
+ *      .where(changeSetHasLabel("confirmed"))
+ *      .selectAll()
+ *      .execute();
+ *   ```
+ *
+ * @example
+ *   You can use eb.not() to negate the filter.
+ *
+ *   ```ts
+ *   await lix.db.selectFrom("change_set")
+ * 		.where((eb) => eb.not(changeSetHasLabel("confirmed")))
+ * 		.selectAll()
+ * 		.execute();
+ *   ```
+ */
+export function changeSetHasLabel(name: string) {
+	return (
+		eb: ExpressionBuilder<LixDatabaseSchema, "change_set">
+	): ExpressionWrapper<LixDatabaseSchema, "change_set", SqlBool> =>
+		eb("change_set.id", "in", (subquery) =>
+			subquery
+				.selectFrom("change_set_label")
+				.innerJoin("label", "label.id", "change_set_label.label_id")
+				.select("change_set_label.change_set_id")
+				.where("label.name", "=", name)
+		);
+}

package/src/query-filter/index.ts

@@ -0,0 +1,8 @@
+export { changeConflictInVersion } from "./change-conflict-in-version.js";
+export { changeHasLabel } from "./change-has-label.js";
+export { changeIsLeaf } from "./change-is-leaf.js";
+export { changeIsLeafOf } from "./change-is-leaf-of.js";
+export { changeIsLeafInVersion } from "./change-is-leaf-in-version.js";
+export { changeInVersion } from "./change-in-version.js";
+export { changeIsLowestCommonAncestorOf } from "./change-is-lowest-common-ancestor-of.js";
+export { changeSetHasLabel } from "./change-set-has-label.js";

package/src/query-filter/version-change-in-difference.test.ts

@@ -0,0 +1,96 @@
+import { test, expect } from "vitest";
+import { openLixInMemory } from "../lix/open-lix-in-memory.js";
+import type { VersionChange } from "../database/schema.js";
+import { mockChange } from "../change/mock-change.js";
+import { createVersion } from "../version/create-version.js";
+import { versionChangeInDifference } from "./version-change-in-difference.js";
+
+test("should return the difference between two versions", async () => {
+	const lix = await openLixInMemory({});
+
+	const versionA = await createVersion({ lix });
+	const versionB = await createVersion({ lix });
+
+	await lix.db
+		.insertInto("change")
+		.values([
+			mockChange({ id: "change1" }),
+			mockChange({ id: "change2" }),
+			mockChange({ id: "change3" }),
+			mockChange({ id: "change4" }),
+		])
+		.returningAll()
+		.execute();
+
+	const changesA: VersionChange[] = [
+		{ version_id: versionA.id, change_id: "change1" },
+		{ version_id: versionA.id, change_id: "change2" },
+	];
+
+	const changesB: VersionChange[] = [
+		{ version_id: versionB.id, change_id: "change2" },
+		{ version_id: versionB.id, change_id: "change3" },
+	];
+
+	await lix.db
+		.insertInto("version_change")
+		.values([...changesA, ...changesB])
+		.execute();
+
+	const result = await lix.db
+		.selectFrom("version_change")
+		.where(versionChangeInDifference(versionA, versionB))
+		.selectAll()
+		.execute();
+
+	expect(result).toEqual([
+		// change1 is in A but not in B
+		{ version_id: versionA.id, change_id: "change1" },
+	] satisfies VersionChange[]);
+});
+
+test("should return an empty array if there are no differences", async () => {
+	const lix = await openLixInMemory({});
+
+	const versionA = await createVersion({ lix });
+	const versionB = await createVersion({ lix });
+
+	await lix.db
+		.insertInto("change")
+		.values([mockChange({ id: "change1" }), mockChange({ id: "change2" })])
+		.returningAll()
+		.execute();
+
+	const changes: VersionChange[] = [
+		{ version_id: versionA.id, change_id: "change1" },
+		{ version_id: versionA.id, change_id: "change2" },
+		{ version_id: versionB.id, change_id: "change1" },
+		{ version_id: versionB.id, change_id: "change2" },
+	];
+
+	await lix.db.insertInto("version_change").values(changes).execute();
+
+	const result = await lix.db
+		.selectFrom("version_change")
+		.where(versionChangeInDifference(versionA, versionB))
+		.selectAll()
+		.execute();
+
+	expect(result).toEqual([]);
+});
+
+test("should handle empty versions", async () => {
+	const lix = await openLixInMemory({});
+
+	const versionA = await createVersion({ lix });
+	const versionB = await createVersion({ lix });
+
+	const result = await lix.db
+		.selectFrom("version_change")
+		.where(versionChangeInDifference(versionA, versionB))
+		.selectAll()
+		.execute();
+
+	// Verify the results
+	expect(result).toEqual([]);
+});

package/src/query-filter/version-change-in-difference.ts

@@ -0,0 +1,37 @@
+import type { ExpressionBuilder, ExpressionWrapper, SqlBool } from "kysely";
+import type { Version, LixDatabaseSchema } from "../database/schema.js";
+
+/**
+ * Returns the difference between two versions for the version_change table.
+ *
+ * The difference is the set of changes that exist in version `a` but not in version `b`.
+ * Modeled after https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set/difference
+ *
+ * @example
+ *   ```ts
+ *   await lix.db.selectFrom("version_change")
+ *     .where(versionChangeInDifference(a: versionA, b: versionB))
+ *     .selectAll()
+ *     .execute();
+ *   ```
+ */
+export function versionChangeInDifference(
+	a: Pick<Version, "id">,
+	b: Pick<Version, "id">
+) {
+	return (
+		eb: ExpressionBuilder<LixDatabaseSchema, "version_change">
+	): ExpressionWrapper<LixDatabaseSchema, "version_change", SqlBool> =>
+		eb("version_change.change_id", "in", (subquery) =>
+			subquery
+				.selectFrom("version_change as A")
+				.leftJoin("version_change as B", (join) =>
+					join
+						.onRef("A.change_id", "=", "B.change_id")
+						.on("B.version_id", "=", b.id)
+				)
+				.where("A.version_id", "=", a.id)
+				.where("B.change_id", "is", null)
+				.select("A.change_id")
+		);
+}

package/src/query-filter/version-change-in-symmetric-difference.test.ts

@@ -0,0 +1,105 @@
+import { test, expect } from "vitest";
+import { openLixInMemory } from "../lix/open-lix-in-memory.js";
+import type { VersionChange } from "../database/schema.js";
+import { mockChange } from "../change/mock-change.js";
+import { createVersion } from "../version/create-version.js";
+import { versionChangeInSymmetricDifference } from "./version-change-in-symmetric-difference.js";
+
+test("should return the symmetric difference between two versions", async () => {
+	const lix = await openLixInMemory({});
+
+	const versionA = await createVersion({ lix });
+	const versionB = await createVersion({ lix });
+
+	await lix.db
+		.insertInto("change")
+		.values([
+			mockChange({ id: "change1" }),
+			mockChange({ id: "change2" }),
+			mockChange({ id: "change3" }),
+			mockChange({ id: "change4" }),
+		])
+		.returningAll()
+		.execute();
+
+	const changesA: VersionChange[] = [
+		{ version_id: versionA.id, change_id: "change1" },
+		{ version_id: versionA.id, change_id: "change2" },
+	];
+
+	const changesB: VersionChange[] = [
+		{ version_id: versionB.id, change_id: "change2" },
+		{ version_id: versionB.id, change_id: "change3" },
+	];
+
+	await lix.db
+		.insertInto("version_change")
+		.values([...changesA, ...changesB])
+		.execute();
+
+	const result = await lix.db
+		.selectFrom("version_change")
+		.where(versionChangeInSymmetricDifference(versionA, versionB))
+		.selectAll()
+		.execute();
+
+	expect(result).toEqual([
+		// change 1 is in A but not in B
+		{ version_id: versionA.id, change_id: "change1" },
+		// change 3 is in B but not in A
+		{ version_id: versionB.id, change_id: "change3" },
+		// change 4 is in neither A nor B
+		// hence not in the symmetric difference
+	] satisfies VersionChange[]);
+});
+
+test("should return an empty array if there are no differences", async () => {
+	const lix = await openLixInMemory({});
+
+	const versionA = await createVersion({ lix });
+	const versionB = await createVersion({ lix });
+
+	await lix.db
+		.insertInto("change")
+		.values([
+			mockChange({ id: "change1" }),
+			mockChange({ id: "change2" }),
+			mockChange({ id: "change3" }),
+			mockChange({ id: "change4" }),
+		])
+		.returningAll()
+		.execute();
+
+	const changes: VersionChange[] = [
+		{ version_id: versionA.id, change_id: "change1" },
+		{ version_id: versionA.id, change_id: "change2" },
+		{ version_id: versionB.id, change_id: "change1" },
+		{ version_id: versionB.id, change_id: "change2" },
+	];
+
+	await lix.db.insertInto("version_change").values(changes).execute();
+
+	const result = await lix.db
+		.selectFrom("version_change")
+		.where(versionChangeInSymmetricDifference(versionA, versionB))
+		.selectAll()
+		.execute();
+
+	expect(result).toEqual([]);
+});
+
+test("should handle empty versions", async () => {
+	const lix = await openLixInMemory({});
+
+	const versionA = await createVersion({ lix });
+	const versionB = await createVersion({ lix });
+
+	const result = await lix.db
+		.selectFrom("version_change")
+		.where(versionChangeInSymmetricDifference(versionA, versionB))
+		.selectAll()
+		.execute();
+
+	// Verify the results
+	expect(result).toEqual([]);
+});

package/src/query-filter/version-change-in-symmetric-difference.ts

@@ -0,0 +1,52 @@
+import type { ExpressionBuilder, ExpressionWrapper, SqlBool } from "kysely";
+import type { Version, LixDatabaseSchema } from "../database/schema.js";
+
+/**
+ * Returns the symmetric difference between two versions for the version_change table.
+ *
+ * The symmetric difference is the set of changes
+ * that exist in either one version but not both.
+ * Modeled after https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set/symmetricDifference
+ *
+ * @example
+ *   ```ts
+ *   await lix.db.selectFrom("version_change")
+ *     .where(versionChangeInSymmetricDifference(a: versionA, b: versionB))
+ *     .selectAll()
+ *     .execute();
+ *   ```
+ */
+export function versionChangeInSymmetricDifference(
+	a: Pick<Version, "id">,
+	b: Pick<Version, "id">
+) {
+	return (
+		eb: ExpressionBuilder<LixDatabaseSchema, "version_change">
+	): ExpressionWrapper<LixDatabaseSchema, "version_change", SqlBool> =>
+		eb.or([
+			eb("version_change.change_id", "in", (subquery) =>
+				subquery
+					.selectFrom("version_change as A")
+					.leftJoin("version_change as B", (join) =>
+						join
+							.onRef("A.change_id", "=", "B.change_id")
+							.on("B.version_id", "=", b.id)
+					)
+					.where("A.version_id", "=", a.id)
+					.where("B.change_id", "is", null)
+					.select("A.change_id")
+			),
+			eb("version_change.change_id", "in", (subquery) =>
+				subquery
+					.selectFrom("version_change as B")
+					.leftJoin("version_change as A", (join) =>
+						join
+							.onRef("B.change_id", "=", "A.change_id")
+							.on("A.version_id", "=", a.id)
+					)
+					.where("B.version_id", "=", b.id)
+					.where("A.change_id", "is", null)
+					.select("B.change_id")
+			),
+		]);
+}

package/src/server-api-handler/create-server-api-handler.ts

@@ -0,0 +1,84 @@
+import { route as newRouteV1 } from "./routes/new-v1.js";
+import { route as pushRouteV1 } from "./routes/push-v1.js";
+import { route as pullRouteV1 } from "./routes/pull-v1.js";
+import { route as getRouteV1 } from "./routes/get-v1.js";
+import type { LsaEnvironment } from "./environment/environment.js";
+
+export type LixServerApiHandler = (request: Request) => Promise<Response>;
+
+export type LixServerApiHandlerContext = {
+	request: Request;
+	environment: LsaEnvironment;
+	params?: Record<string, string | undefined>;
+};
+
+export type LixServerApiHandlerRoute = (
+	context: LixServerApiHandlerContext
+) => Promise<Response>;
+
+/**
+ * The handler for the lix server protocol.
+ *
+ * @example
+ *   Usage with a server framework.
+ *
+ *   ```ts
+ * 	 // any server framework goes
+ *   // here, like express, polka, etc.
+ *   // frameworks that do not use
+ *   // web standard Request and Response
+ *   // objects will need to be mapped.
+ *   const app = new Hono();
+ *
+ *   const lsaHandler = createServerApiHandler({ storage });
+ *
+ *   app.use('/lsp/*', async (req) => {
+ *      await lsaHandler(req);
+ *   });
+ *   ```
+ *
+ * @example
+ *   Testing the handler.
+ *
+ *   ```ts
+ *   const lsaHandler = createServerApiHandler({ storage });
+ *   const request = new Request('/lsp/new', {
+ *     method: 'POST',
+ *     body: new Blob(['...']),
+ *   });
+ *
+ *   const response = await lsaHandler(request);
+ *
+ *   expect(response).to(...);
+ *   ```
+ */
+export async function createServerApiHandler(args: {
+	environment: LsaEnvironment;
+}): Promise<LixServerApiHandler> {
+	const context = { environment: args.environment };
+
+	return async (request) => {
+		try {
+			const path = new URL(request.url).pathname;
+			if (path === "/lsa/get-v1") {
+				return await getRouteV1({ ...context, request });
+			}
+			if (path === "/lsa/new-v1") {
+				return await newRouteV1({ ...context, request });
+			}
+			if (path === "/lsa/push-v1") {
+				return await pushRouteV1({ ...context, request });
+			}
+			if (path === "/lsa/pull-v1") {
+				return await pullRouteV1({ ...context, request });
+			}
+
+			return new Response(null, { status: 404 });
+		} catch (error) {
+			console.error(error);
+			return new Response(error as string, {
+				status: 500,
+			});
+		}
+	};
+}

package/src/server-api-handler/environment/create-in-memory-environment.test.ts

@@ -0,0 +1,130 @@
+import { test, expect } from "vitest";
+import { createLsaInMemoryEnvironment } from "./create-in-memory-environment.js";
+import { openLixInMemory } from "../../lix/open-lix-in-memory.js";
+
+test("opening a lix works", async () => {
+	const environment = createLsaInMemoryEnvironment();
+
+	const mockLix = await openLixInMemory({});
+
+	const { value: lixId } = await mockLix.db
+		.selectFrom("key_value")
+		.where("key", "=", "lix_id")
+		.select("value")
+		.executeTakeFirstOrThrow();
+
+	// initialize the env with the lix file
+	environment.setLix({ id: lixId, blob: await mockLix.toBlob() });
+
+	const open0 = await environment.openLix({ id: lixId });
+
+	const mockInsert = await open0.lix.db
+		.insertInto("key_value")
+		.values({ key: "foo", value: "bar" })
+		.returningAll()
+		.executeTakeFirstOrThrow();
+
+	expect(mockInsert).toEqual({
+		key: "foo",
+		value: "bar",
+	});
+
+	await environment.closeLix({
+		id: lixId,
+		connectionId: open0.connectionId,
+	});
+
+	const open1 = await environment.openLix({
+		id: lixId,
+	});
+
+	const mockSelect = await open1.lix.db
+		.selectFrom("key_value")
+		.where("key", "=", "foo")
+		.selectAll()
+		.executeTakeFirstOrThrow();
+
+	expect(mockSelect).toEqual({ key: "foo", value: "bar" });
+
+	await environment.closeLix({ id: lixId, connectionId: open1.connectionId });
+});
+
+test("it handles concurrent connections", async () => {
+	const environment = createLsaInMemoryEnvironment();
+
+	const mockLix = await openLixInMemory({});
+
+	const { value: lixId } = await mockLix.db
+		.selectFrom("key_value")
+		.where("key", "=", "lix_id")
+		.select("value")
+		.executeTakeFirstOrThrow();
+
+	// initialize the env with the lix file
+	environment.setLix({ id: lixId, blob: await mockLix.toBlob() });
+
+	const open0 = await environment.openLix({ id: lixId });
+	const open1 = await environment.openLix({ id: lixId });
+
+	const mockInsert = await open0.lix.db
+		.insertInto("key_value")
+		.values({ key: "foo", value: "bar" })
+		.returningAll()
+		.executeTakeFirstOrThrow();
+
+	expect(mockInsert).toEqual({
+		key: "foo",
+		value: "bar",
+	});
+
+	const mockSelect = await open1.lix.db
+		.selectFrom("key_value")
+		.where("key", "=", "foo")
+		.selectAll()
+		.executeTakeFirstOrThrow();
+
+	expect(mockSelect).toEqual({ key: "foo", value: "bar" });
+
+	// test both writing at the same time
+
+	await Promise.all([
+		open0.lix.db.transaction().execute(async (trx) => {
+			await trx
+				.updateTable("key_value")
+				.where("key", "=", "foo")
+				.set("value", "bar2")
+				.execute();
+			// Introduce a delay to simulate processing time
+			// and keep the transaction open
+			return await new Promise((resolve) => setTimeout(resolve, 100));
+		}),
+		open1.lix.db.transaction().execute((trx) => {
+			// expecting bar3 to be the final value
+			// even though it's processing faster than
+			// the other transaction but it's the last one to commit
+			return trx
+				.updateTable("key_value")
+				.where("key", "=", "foo")
+				.set("value", "bar3")
+				.execute();
+		}),
+	]);
+
+	await environment.closeLix({ id: lixId, connectionId: open0.connectionId });
+
+	await environment.closeLix({ id: lixId, connectionId: open1.connectionId });
+
+	const open2 = await environment.openLix({
+		id: lixId,
+	});
+
+	const mockSelect2 = await open2.lix.db
+		.selectFrom("key_value")
+		.where("key", "=", "foo")
+		.selectAll()
+		.executeTakeFirstOrThrow();
+
+	expect(mockSelect2).toEqual({ key: "foo", value: "bar3" });
+
+	await environment.closeLix({ id: lixId, connectionId: open2.connectionId });
+});