@lix-js/sdk 0.0.1

package/src/change-queue/with-skip-change-queue.ts

@@ -0,0 +1,33 @@
+import type { Lix } from "../lix/open-lix.js";
+
+export async function withSkipChangeQueue<T>(
+	db: Lix["db"],
+	operation: (trx: Lix["db"]) => Promise<T>
+): Promise<T> {
+	const executeInTransaction = async (trx: Lix["db"]) => {
+		const queryEntryBefore = await trx
+			.selectFrom("change_queue")
+			.selectAll()
+			.orderBy("id desc")
+			.executeTakeFirst();
+
+		// Perform the user's operation
+		const result = await operation(trx);
+
+		// delete queue entries that came after
+		// the queue entry before the transaction
+
+		await trx
+			.deleteFrom("change_queue")
+			.where("id", ">", queryEntryBefore?.id ?? 0)
+			.execute();
+
+		// Return the result of the operation
+		return result;
+	};
+	if (db.isTransaction) {
+		return executeInTransaction(db);
+	} else {
+		return db.transaction().execute(executeInTransaction);
+	}
+}

package/src/change-schema/README.md

@@ -0,0 +1,3 @@
+THIS IS EXPERIMENTAL AND NOT YET READY FOR USE.
+
+talk to @samuelstroschein if you want to know more.

package/src/change-schema/index.ts

@@ -0,0 +1,4 @@
+export {
+	type ExperimentalChangeSchema,
+	type ExperimentalInferType,
+} from "./types.js";

package/src/change-schema/types.test-d.ts

@@ -0,0 +1,52 @@
+/* eslint-disable @typescript-eslint/no-unused-vars */
+import type {
+	ExperimentalChangeSchema,
+	ExperimentalInferType,
+} from "./types.js";
+import { test, assertType } from "vitest";
+
+test("a json change schema should be infer the properties", () => {
+	const jsonChangeSchema = {
+		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 snapshot: ExperimentalInferType<typeof jsonChangeSchema> = {
+		name: "John",
+		age: 5,
+		location: {
+			city: "New York",
+			country: "USA",
+		},
+	};
+
+	assertType<{
+		[x: string]: unknown;
+		name: string;
+		age: number;
+		location: {
+			[x: string]: unknown;
+		};
+	}>(snapshot);
+});
+
+test("a blob change schema should be infer the properties", () => {
+	const blobChangeSchema = {
+		key: "mock",
+		type: "blob",
+	} as const satisfies ExperimentalChangeSchema;
+
+	const snapshot: ExperimentalInferType<typeof blobChangeSchema> =
+		new ArrayBuffer(0);
+
+	assertType<ArrayBuffer>(snapshot);
+});

package/src/change-schema/types.ts

@@ -0,0 +1,53 @@
+import type { FromSchema, JSONSchema } from "json-schema-to-ts";
+
+/**
+ * Infers the snapshot content type from the schema.
+ */
+export type ExperimentalInferType<ChangeSchema> =
+	// If the schema is a JSON schema and the schema is provided,
+	ChangeSchema extends {
+		type: "json";
+		schema: JSONSchema;
+	}
+		? // infer the type from the schema.
+			FromSchema<ChangeSchema["schema"]>
+		: // else if the schema is a JSON schema and the schema is not provided,
+			ChangeSchema extends { type: "json" }
+			? // infer the type as any.
+				any
+			: // else if the schema is a blob schema,
+				// infer the type as an ArrayBuffer.
+				ChangeSchema extends { type: "blob" }
+				? ArrayBuffer
+				: // else infer the type as never.
+					never;
+
+/**
+ * The schema of a detected change.
+ *
+ * The key is used to identify the schema. It is highly
+ * recommended to use a unique key for each schema and
+ * include a version number in the key when breaking
+ * changes are made.
+ *
+ * - use `as const` to narrow the types
+ * - use `... satisfies ChangeSchema` to get autocomplete
+ *
+ * @example
+ *   const FooV1 = {
+ *      key: "csv-plugin-foo-v1",
+ *      type: "json",
+ *      schema: jsonSchema,
+ *   } as const satisfies ChangeSchema;
+ */
+export type ExperimentalChangeSchema =
+	| {
+			key: string;
+			type: "json";
+			schema: JSONSchema;
+	  }
+	| {
+			key: string;
+			type: "blob";
+			schema?: undefined;
+	  };

package/src/change-set/change-set-element-in-symmetric-difference.test.ts

@@ -0,0 +1,128 @@
+import { test, expect } from "vitest";
+import { openLixInMemory } from "../lix/open-lix-in-memory.js";
+import { changeSetElementInSymmetricDifference } from "./change-set-element-in-symmetric-difference.js";
+import type { ChangeSet, ChangeSetElement } from "../database/schema.js";
+import { mockChange } from "../change/mock-change.js";
+
+test("should return the symmetric difference between two change sets", async () => {
+	const lix = await openLixInMemory({});
+
+	// Insert test data
+	const changeSetA: ChangeSet = { id: "changeSetA" };
+	const changeSetB: ChangeSet = { id: "changeSetB" };
+
+	await lix.db
+		.insertInto("change_set")
+		.values([changeSetA, changeSetB])
+		.execute();
+
+	await lix.db
+		.insertInto("change")
+		.values([
+			mockChange({ id: "change1" }),
+			mockChange({ id: "change2" }),
+			mockChange({ id: "change3" }),
+			mockChange({ id: "change4" }),
+		])
+		.returningAll()
+		.execute();
+
+	const changesA: ChangeSetElement[] = [
+		{ change_set_id: "changeSetA", change_id: "change1" },
+		{ change_set_id: "changeSetA", change_id: "change2" },
+	];
+
+	const changesB: ChangeSetElement[] = [
+		{ change_set_id: "changeSetB", change_id: "change2" },
+		{ change_set_id: "changeSetB", change_id: "change3" },
+	];
+
+	await lix.db
+		.insertInto("change_set_element")
+		.values([...changesA, ...changesB])
+		.execute();
+
+	const result = await lix.db
+		.selectFrom("change_set_element")
+		.where(changeSetElementInSymmetricDifference(changeSetA, changeSetB))
+		.selectAll()
+		.execute();
+
+	expect(result).toEqual([
+		// change 1 is in A but not in B
+		expect.objectContaining({
+			change_set_id: "changeSetA",
+			change_id: "change1",
+		}),
+		// change 3 is in B but not in A
+		expect.objectContaining({
+			change_set_id: "changeSetB",
+			change_id: "change3",
+		}),
+		// change 4 is in neither A nor B
+		// hence not in the symmetric difference
+	]);
+});
+
+test("should return an empty array if there are no differences", async () => {
+	const lix = await openLixInMemory({});
+
+	// Insert test data
+	const changeSetA: ChangeSet = { id: "changeSetA" };
+	const changeSetB: ChangeSet = { id: "changeSetB" };
+
+	await lix.db
+		.insertInto("change_set")
+		.values([changeSetA, changeSetB])
+		.execute();
+
+	await lix.db
+		.insertInto("change")
+		.values([
+			mockChange({ id: "change1" }),
+			mockChange({ id: "change2" }),
+			mockChange({ id: "change3" }),
+			mockChange({ id: "change4" }),
+		])
+		.returningAll()
+		.execute();
+
+	const changes: ChangeSetElement[] = [
+		{ change_set_id: "changeSetA", change_id: "change1" },
+		{ change_set_id: "changeSetA", change_id: "change2" },
+		{ change_set_id: "changeSetB", change_id: "change1" },
+		{ change_set_id: "changeSetB", change_id: "change2" },
+	];
+
+	await lix.db.insertInto("change_set_element").values(changes).execute();
+
+	const result = await lix.db
+		.selectFrom("change_set_element")
+		.where(changeSetElementInSymmetricDifference(changeSetA, changeSetB))
+		.selectAll()
+		.execute();
+
+	expect(result).toEqual([]);
+});
+
+test("should handle empty change sets", async () => {
+	const lix = await openLixInMemory({});
+
+	// Insert test data
+	const changeSetA: ChangeSet = { id: "changeSetA" };
+	const changeSetB: ChangeSet = { id: "changeSetB" };
+
+	await lix.db
+		.insertInto("change_set")
+		.values([changeSetA, changeSetB])
+		.execute();
+
+	const result = await lix.db
+		.selectFrom("change_set_element")
+		.where(changeSetElementInSymmetricDifference(changeSetA, changeSetB))
+		.selectAll()
+		.execute();
+
+	// Verify the results
+	expect(result).toEqual([]);
+});

package/src/change-set/change-set-element-in-symmetric-difference.ts

@@ -0,0 +1,52 @@
+import type { ExpressionBuilder, ExpressionWrapper, SqlBool } from "kysely";
+import type { ChangeSet, LixDatabaseSchema } from "../database/schema.js";
+
+/**
+ * Returns the symmetric difference between two change sets.
+ *
+ * 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("change_set_element")
+ *     .where(changeSetElementInSymmetricDifference(a: changeSetA, b: changeSetB))
+ *     .selectAll()
+ *     .execute();
+ *   ```
+ */
+export function changeSetElementInSymmetricDifference(
+	a: Pick<ChangeSet, "id">,
+	b: Pick<ChangeSet, "id">
+) {
+	return (
+		eb: ExpressionBuilder<LixDatabaseSchema, "change_set_element">
+	): ExpressionWrapper<LixDatabaseSchema, "change_set_element", SqlBool> =>
+		eb.or([
+			eb("change_set_element.change_id", "in", (subquery) =>
+				subquery
+					.selectFrom("change_set_element as A")
+					.leftJoin("change_set_element as B", (join) =>
+						join
+							.onRef("A.change_id", "=", "B.change_id")
+							.on("B.change_set_id", "=", b.id)
+					)
+					.where("A.change_set_id", "=", a.id)
+					.where("B.change_id", "is", null)
+					.select("A.change_id")
+			),
+			eb("change_set_element.change_id", "in", (subquery) =>
+				subquery
+					.selectFrom("change_set_element as B")
+					.leftJoin("change_set_element as A", (join) =>
+						join
+							.onRef("B.change_id", "=", "A.change_id")
+							.on("A.change_set_id", "=", a.id)
+					)
+					.where("B.change_set_id", "=", b.id)
+					.where("A.change_id", "is", null)
+					.select("B.change_id")
+			),
+		]);
+}

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

@@ -0,0 +1,43 @@
+import { test, expect } from "vitest";
+import { openLixInMemory } from "../lix/open-lix-in-memory.js";
+import { createChangeSet } from "./create-change-set.js";
+
+test("creating a change set should succeed", async () => {
+	const lix = await openLixInMemory({});
+
+	const mockChanges = await lix.db
+		.insertInto("change")
+		.values([
+			{
+				schema_key: "file",
+				entity_id: "value1",
+				file_id: "mock",
+				plugin_key: "mock-plugin",
+				snapshot_id: "no-content",
+			},
+			{
+				schema_key: "file",
+				entity_id: "value2",
+				file_id: "mock",
+				plugin_key: "mock-plugin",
+				snapshot_id: "no-content",
+			},
+		])
+		.returningAll()
+		.execute();
+
+	const changeSet = await createChangeSet({
+		lix: lix,
+		changes: mockChanges,
+	});
+
+	const changeSetMembers = await lix.db
+		.selectFrom("change_set_element")
+		.selectAll()
+		.where("change_set_id", "=", changeSet.id)
+		.execute();
+
+	expect(changeSetMembers.map((member) => member.change_id)).toEqual(
+		expect.arrayContaining([mockChanges[0]?.id, mockChanges[1]?.id])
+	);
+});

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

@@ -0,0 +1,41 @@
+import type { Change, ChangeSet } from "../database/schema.js";
+import type { Lix } from "../lix/open-lix.js";
+
+/**
+ * Creates a change set with the given changes, optionally within an open transaction.
+ *
+ * @example
+ *   ```ts
+ *   const changes = await lix.db.selectFrom("change").selectAll().execute();
+ *   const changeSet = await createChangeSet({ db: lix.db, changes });
+ *   ```
+ */
+export async function createChangeSet(args: {
+	lix: Pick<Lix, "db">;
+	changes: Pick<Change, "id">[];
+}): Promise<ChangeSet> {
+	const executeInTransaction = async (trx: Lix["db"]) => {
+		const changeSet = await trx
+			.insertInto("change_set")
+			.defaultValues()
+			.returningAll()
+			.executeTakeFirstOrThrow();
+
+		await trx
+			.insertInto("change_set_element")
+			.values(
+				args.changes.map((change) => ({
+					change_id: change.id,
+					change_set_id: changeSet.id,
+				}))
+			)
+			.execute();
+		return changeSet;
+	};
+
+	if (args.lix.db.isTransaction) {
+		return executeInTransaction(args.lix.db);
+	} else {
+		return args.lix.db.transaction().execute(executeInTransaction);
+	}
+}

package/src/change-set/index.ts

@@ -0,0 +1,2 @@
+export { changeSetElementInSymmetricDifference } from "./change-set-element-in-symmetric-difference.js";
+export { createChangeSet } from "./create-change-set.js";