@lix-js/sdk 0.0.1

package/src/plugin/lix-plugin.ts

@@ -0,0 +1,128 @@
+import type {
+	ExperimentalChangeSchema,
+	ExperimentalInferType,
+} from "../change-schema/types.js";
+import { type Change, type LixFile } from "../database/schema.js";
+import type { Lix } from "../lix/open-lix.js";
+
+// named lixplugin to avoid conflict with built-in plugin type
+export type LixPlugin = {
+	key: string;
+	/**
+	 * The glob pattern that should invoke `detectChanges()`.
+	 *
+	 * @example
+	 *   `**\/*.json` for all JSON files
+	 *   `**\/*.inlang` for all inlang files
+	 */
+	detectChangesGlob?: string;
+	/**
+	 * Detects changes between the `before` and `after` file update(s).
+	 *
+	 * `Before` is `undefined` if the file did not exist before (
+	 * the file was created).
+	 *
+	 * `After` is always defined. Either the file was updated, or
+	 * deleted. If the file is deleted, lix own change control
+	 * will handle the deletion. Hence, `after` is always be defined.
+	 */
+	detectChanges?: (args: {
+		lix: LixReadonly;
+		before?: LixFile;
+		after: LixFile;
+	}) => Promise<Array<DetectedChange>>;
+	/**
+	 * UI components that are used to render the diff view.
+	 */
+	diffUiComponents?: [
+		{
+			schema_key: string;
+			component: HTMLElement;
+		},
+	];
+	/**
+	 * Detects changes from the source lix that conflict with changes in the target lix.
+	 */
+	detectConflicts?: (args: {
+		lix: LixReadonly;
+		changes: Array<Change>;
+	}) => Promise<DetectedConflict[]>;
+	applyChanges?: (args: {
+		lix: LixReadonly;
+		/**
+		 * The file to which the changes should be applied.
+		 *
+		 * The `file.data` might be undefined if the file does not
+		 * exist at the time of applying the changes. This can
+		 * happen when merging a version that created a new file
+		 * that did not exist in the target version. Or, a file
+		 * has been deleted and should be restored at a later point.
+		 */
+		file: Omit<LixFile, "data"> & { data?: LixFile["data"] };
+		changes: Array<Change>;
+	}) => Promise<{
+		fileData: LixFile["data"];
+	}>;
+	// // TODO multiple resolution strategies should be reported to the user
+	// // similar to fixable lint rules. We likely need to expose in
+	// // detect conflicts how conflicts could potentially be resolved.
+	// // `resolveConflict` would then be called with the selected strategy.
+	// tryResolveConflict?: () => Promise<
+	// 	{ success: true; change: Change } | { success: false }
+	// >;
+};
+
+/**
+ * A detected change that lix ingests in to the database.
+ *
+ * - If the `snapshot` is `undefined`, the change is considered to be a deletion.
+ * - The `schema` type can be narrowed by providing a change schema.
+ *
+ * @example
+ *   Type narrowing with a change schema:
+ *
+ *   ```
+ * 	 const FooV1Schema = {
+ *     key: "plugin-name-foo-v1",
+ *     type: "json",
+ *     schema: {
+ *       type: "object",
+ *       properties: {
+ *         name: { type: "string" },
+ * 		   }
+ *     }
+ *   } as const satisfies ChangeSchema;
+ *
+ *   const detectedChange: DetectedChange<typeof FooV1Schema>
+ *
+ *   detectedChange.snapshot.name // string
+ *   ```
+ */
+
+export type DetectedChange<Schema extends ExperimentalChangeSchema = any> = {
+	entity_id: string;
+	schema: Omit<ExperimentalChangeSchema, "schema">;
+	/**
+	 * The change is considered a deletion if `snapshot` is `undefined`.
+	 */
+
+	snapshot?: ExperimentalInferType<Schema>;
+};
+
+export type DetectedConflict = {
+	/**
+	 * @see {ChangeConflict.key}
+	 */
+	key: string;
+	/**
+	 * The changes that are conflicting.
+	 */
+	conflictingChangeIds: Set<Change["id"]>;
+};
+
+export type LixReadonly = Pick<Lix, "plugin"> & {
+	db: {
+		selectFrom: Lix["db"]["selectFrom"];
+		withRecursive: Lix["db"]["withRecursive"];
+	};
+};

package/src/plugin/load-plugin.ts

@@ -0,0 +1,28 @@
+import type { LixDatabaseSchema, LixFile } from "../database/schema.js";
+import type { LixPlugin } from "./lix-plugin.js";
+import { Kysely, sql } from "kysely";
+
+export async function loadPlugins(
+	db: Kysely<LixDatabaseSchema>
+): Promise<LixPlugin[]> {
+	const pluginFiles = (
+		await sql`
+    SELECT * FROM file
+    WHERE path GLOB 'lix/plugin/*'
+  `.execute(db)
+	).rows as unknown as LixFile[];
+
+	const decoder = new TextDecoder("utf8");
+	const plugins: LixPlugin[] = [];
+	for (const plugin of pluginFiles) {
+		const text = btoa(decoder.decode(plugin.data));
+		const pluginModule = await import(
+			/* @vite-ignore */ "data:text/javascript;base64," + text
+		);
+		plugins.push(pluginModule.default);
+		if (pluginModule.default.setup) {
+			await pluginModule.default.setup();
+		}
+	}
+	return plugins as LixPlugin[];
+}

package/src/plugin/with-transaction.ts

@@ -0,0 +1,22 @@
+import type { Transaction } from "kysely";
+import type { LixDatabaseSchema } from "../database/schema.js";
+import type { Lix } from "../lix/open-lix.js";
+import type { LixReadonly } from "./lix-plugin.js";
+
+/**
+ * Turns a `Lix` into a `LixReadonly`.
+ *
+ * TODO https://github.com/opral/lix-sdk/issues/123
+ */
+export function withTransaction(
+	lix: Lix,
+	trx: Transaction<LixDatabaseSchema>
+): LixReadonly {
+	return {
+		db: {
+			selectFrom: trx.selectFrom,
+			withRecursive: trx.withRecursive,
+		},
+		plugin: lix.plugin,
+	};
+}

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

@@ -0,0 +1,62 @@
+import { test, expect } from "vitest";
+import { openLixInMemory } from "../lix/open-lix-in-memory.js";
+import { createChangeConflict } from "../change-conflict/create-change-conflict.js";
+import { changeConflictInVersion } from "./change-conflict-in-version.js";
+import { createVersion } from "../version/create-version.js";
+
+test("should find conflicts in the given version", async () => {
+	const lix = await openLixInMemory({});
+
+	// Insert changes
+	await lix.db
+		.insertInto("change")
+		.values([
+			{
+				id: "change0",
+				plugin_key: "mock-plugin",
+				schema_key: "mock",
+				file_id: "mock",
+				entity_id: "value0",
+				snapshot_id: "no-content",
+			},
+			{
+				id: "change1",
+				plugin_key: "mock-plugin",
+				schema_key: "mock",
+				file_id: "mock",
+				entity_id: "value1",
+				snapshot_id: "no-content",
+			},
+		])
+		.execute();
+
+	const version0 = await createVersion({ lix, name: "version0" });
+
+	const version1 = await createVersion({ lix, name: "version1" });
+
+	// Create change conflicts
+	const mockConflict0 = await createChangeConflict({
+		lix,
+		version: version0,
+		key: "mock-conflict0",
+		conflictingChangeIds: new Set(["change0", "change1"]),
+	});
+
+	// conflict in another version that should not be returned
+	await createChangeConflict({
+		lix,
+		version: version1,
+		key: "mock-conflict1",
+		conflictingChangeIds: new Set(["change0"]),
+	});
+
+	// Query conflicts in the version
+	const conflictsInversion = await lix.db
+		.selectFrom("change_conflict")
+		.where(changeConflictInVersion(version0))
+		.selectAll()
+		.execute();
+
+	expect(conflictsInversion.length).toBe(1);
+	expect(conflictsInversion[0]?.id).toBe(mockConflict0.id);
+});

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

@@ -0,0 +1,25 @@
+import type { ExpressionBuilder, ExpressionWrapper, SqlBool } from "kysely";
+import type { Version, LixDatabaseSchema } from "../database/schema.js";
+
+/**
+ * Filters if a conflict is in the given version.
+ *
+ * @example
+ *   ```ts
+ *   const conflicts = await lix.db.selectFrom("change_conflict")
+ *      .where(changeConflictInVersion(currentVersion))
+ *      .selectAll()
+ *      .execute();
+ *   ```
+ */
+export function changeConflictInVersion(version: Pick<Version, "id">) {
+	return (
+		eb: ExpressionBuilder<LixDatabaseSchema, "change_conflict">
+	): ExpressionWrapper<LixDatabaseSchema, "change_conflict", SqlBool> =>
+		eb("change_conflict.id", "in", (subquery) =>
+			subquery
+				.selectFrom("version_change_conflict")
+				.select("change_conflict_id")
+				.where("version_change_conflict.version_id", "=", version.id)
+		);
+}

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

@@ -0,0 +1,52 @@
+import { test, expect } from "vitest";
+import { changeHasLabel } from "./change-has-label.js";
+import { openLixInMemory } from "../lix/open-lix-in-memory.js";
+import { createChangeSet } from "../change-set/create-change-set.js";
+
+test("should only return changes with the given label", async () => {
+	const lix = await openLixInMemory({});
+
+	await lix.db
+		.insertInto("change")
+		.values([
+			{
+				id: "change1",
+				snapshot_id: "no-content",
+				entity_id: "mock",
+				file_id: "mock",
+				plugin_key: "mock",
+				schema_key: "mock",
+			},
+			{
+				id: "change2",
+				snapshot_id: "no-content",
+				entity_id: "mock",
+				file_id: "mock",
+				plugin_key: "mock",
+				schema_key: "mock",
+			},
+		])
+		.execute();
+
+	const set = await createChangeSet({ lix, changes: [{ id: "change1" }] });
+
+	const label = await lix.db
+		.insertInto("label")
+		.values({ name: "mocked" })
+		.returningAll()
+		.executeTakeFirstOrThrow();
+
+	await lix.db
+		.insertInto("change_set_label")
+		.values({ change_set_id: set.id, label_id: label.id })
+		.execute();
+
+	const changes = await lix.db
+		.selectFrom("change")
+		.where(changeHasLabel("mocked"))
+		.selectAll()
+		.execute();
+
+	expect(changes).toHaveLength(1);
+	expect(changes[0]?.id).toBe("change1");
+});

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

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

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

@@ -0,0 +1,82 @@
+import { expect, test } from "vitest";
+import { openLixInMemory } from "../lix/open-lix-in-memory.js";
+import { changeInVersion } from "./change-in-version.js";
+import { createVersion } from "../version/create-version.js";
+import { updateChangesInVersion } from "../version/update-changes-in-version.js";
+
+test("select changeInVersion should retrieve all changes in the version including ancestors", async () => {
+	const lix = await openLixInMemory({});
+
+	const version = await createVersion({ lix });
+
+	// Insert changes and create a parent-child chain in change_edge
+	const [, , changeC] = await lix.db
+		.insertInto("change")
+		.values([
+			{
+				id: "changeA",
+				entity_id: "entity1",
+				schema_key: "type1",
+				file_id: "file1",
+				plugin_key: "plugin1",
+				snapshot_id: "no-content",
+			},
+			{
+				id: "changeB",
+				entity_id: "entity1",
+				schema_key: "type1",
+				file_id: "file1",
+				plugin_key: "plugin1",
+				snapshot_id: "no-content",
+			},
+			{
+				id: "changeC",
+				entity_id: "entity1",
+				schema_key: "type1",
+				file_id: "file1",
+				plugin_key: "plugin1",
+				snapshot_id: "no-content",
+			},
+			{
+				id: "changeD",
+				entity_id: "entity1",
+				schema_key: "type1",
+				file_id: "file1",
+				plugin_key: "plugin1",
+				snapshot_id: "no-content",
+			},
+		])
+		.returningAll()
+		.execute();
+
+	// Link changes in change_edge (C <- B <- A)
+	await lix.db
+		.insertInto("change_edge")
+		.values([
+			{ parent_id: "changeA", child_id: "changeB" },
+			{ parent_id: "changeB", child_id: "changeC" },
+		])
+		.execute();
+
+	// Point the version to changeC, which should include changeA and changeB as ancestors
+	await updateChangesInVersion({
+		lix,
+		version,
+		changes: [changeC!],
+	});
+
+	const changes = await lix.db
+		.selectFrom("change")
+		.where(changeInVersion(version))
+		.selectAll()
+		.execute();
+
+	// Verify the returned changes include changeC and its ancestors changeA and changeB
+	const changeIds = changes.map((change) => change.id);
+
+	// change D is not pointed at in th version, so it should not be included
+	expect(changes).toHaveLength(3);
+	expect(changeIds).toContain("changeA");
+	expect(changeIds).toContain("changeB");
+	expect(changeIds).toContain("changeC");
+});

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

@@ -0,0 +1,31 @@
+import { ExpressionWrapper, sql } from "kysely";
+import type { Version, LixDatabaseSchema } from "../database/schema.js";
+import type { SqlBool } from "kysely";
+
+/**
+ * Filters if a change is in the given Version.
+ *
+ * @example
+ *   ```ts
+ *   const changes = await lix.db.selectFrom("change")
+ *      .where(changeInVersion(currentVersion))
+ *      .selectAll()
+ *      .execute();
+ *   ```
+ */
+export function changeInVersion(version: Pick<Version, "id">) {
+	return sql`
+    change.id IN (
+      WITH RECURSIVE recursive_changes(id) AS (
+        SELECT change_id AS id
+        FROM version_change
+        WHERE version_id = ${version.id}
+        UNION ALL
+        SELECT change_edge.parent_id AS id
+        FROM change_edge
+        INNER JOIN recursive_changes ON recursive_changes.id = change_edge.child_id
+      )
+      SELECT id FROM recursive_changes
+    )
+  ` as unknown as ExpressionWrapper<LixDatabaseSchema, "change", SqlBool>;
+}

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

@@ -0,0 +1,77 @@
+import { test, expect } from "vitest";
+import { openLixInMemory } from "../lix/open-lix-in-memory.js";
+import { updateChangesInVersion } from "../version/update-changes-in-version.js";
+import { changeIsLeafInVersion } from "./change-is-leaf-in-version.js";
+import { createVersion } from "../version/create-version.js";
+
+test("it should return the leaf change for the given version", async () => {
+	const lix = await openLixInMemory({});
+
+	const version0 = await createVersion({ lix, name: "version0" });
+	const version1 = await createVersion({ lix, name: "version1" });
+
+	const insertedChanges = await lix.db
+		.insertInto("change")
+		.values([
+			{
+				id: "change1",
+				snapshot_id: "no-content",
+				entity_id: "mock1",
+				file_id: "mock",
+				plugin_key: "mock",
+				schema_key: "mock",
+			},
+			{
+				id: "change2",
+				snapshot_id: "no-content",
+				entity_id: "mock1",
+				file_id: "mock",
+				plugin_key: "mock",
+				schema_key: "mock",
+			},
+			{
+				id: "change3",
+				snapshot_id: "no-content",
+				entity_id: "mock1",
+				file_id: "mock",
+				plugin_key: "mock",
+				schema_key: "mock",
+			},
+		])
+		.returningAll()
+		.execute();
+
+	await lix.db
+		.insertInto("change_edge")
+		.values([
+			// including change1 for re-assurance
+			{ parent_id: "change1", child_id: "change2" },
+			{ parent_id: "change2", child_id: "change3" },
+		])
+		.execute();
+
+	await updateChangesInVersion({
+		lix,
+		version: version0,
+		// only point to the second change even though
+		// the third change is a child of the second change
+		changes: [insertedChanges[1]!],
+	});
+
+	// letting another version (version1) point to the third change
+	await updateChangesInVersion({
+		lix,
+		version: version1,
+		changes: [insertedChanges[2]!],
+	});
+
+	const changes = await lix.db
+		.selectFrom("change")
+		.where(changeIsLeafInVersion(version0))
+		.selectAll()
+		.execute();
+
+	// change 2 is the leaf change for the current version
+	expect(changes).toHaveLength(1);
+	expect(changes[0]?.id).toBe("change2");
+});

package/src/query-filter/change-is-leaf-in-version.ts

@@ -0,0 +1,36 @@
+import { sql, type ExpressionWrapper, type SqlBool } from "kysely";
+import type { Version, LixDatabaseSchema } from "../database/schema.js";
+
+/**
+ * Selects changes that are not a parent of any other change within the specified version.
+ *
+ *
+ * @example
+ *   ```ts
+ *   await lix.db.selectFrom("change")
+ *     .where(changeIsLeafInVersion(currentVersion))
+ *     .selectAll()
+ *     .execute();
+ *   ```
+ */
+export function changeIsLeafInVersion(version: Pick<Version, "id">) {
+	return sql`
+    change.id IN (
+      WITH RECURSIVE version_changes(id) AS (
+        SELECT change_id AS id
+        FROM version_change
+        WHERE version_id = ${version.id}
+        UNION ALL
+        SELECT change_edge.parent_id AS id
+        FROM change_edge
+        INNER JOIN version_changes ON version_changes.id = change_edge.child_id
+      )
+      SELECT id FROM version_changes
+      WHERE id NOT IN (
+        SELECT parent_id
+        FROM change_edge
+        WHERE child_id IN (SELECT id FROM version_changes)
+      )
+    )
+  ` as unknown as ExpressionWrapper<LixDatabaseSchema, "change", SqlBool>;
+}