@lix-js/sdk 0.4.6 → 0.5.0-preview.0

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

@@ -0,0 +1,149 @@
+import type { Lix } from "../lix/index.js";
+import type { ChangeSet } from "./schema.js";
+import { changeSetElementIsLeafOf } from "../query-filter/change-set-element-is-leaf-of.js";
+import { changeSetElementInAncestryOf } from "../query-filter/change-set-element-in-ancestry-of.js";
+import { createChangeSet } from "./create-change-set.js";
+
+/**
+ * Creates a change set that enables a transition from a source state
+ * (defined by `sourceChangeSet`) to a target state (defined by `targetChangeSet`).
+ *
+ * Applying the returned change set to the source state will result in a state
+ * that matches the target state.
+ *
+ * - switch between state (switching versions, checkpoints, etc.)
+ * - restore old state (applying the transition set on top of current state)
+ */
+export async function createTransitionChangeSet(args: {
+	lix: Lix;
+	sourceChangeSet: Pick<ChangeSet, "id">;
+	targetChangeSet: Pick<ChangeSet, "id">;
+}): Promise<ChangeSet> {
+	const executeInTransaction = async (trx: Lix["db"]) => {
+		// 1. Find leaf changes defining the state AT the *target* change set
+		const leafChangesToApply = await trx
+			.selectFrom("change")
+			.innerJoin(
+				"change_set_element",
+				"change_set_element.change_id",
+				"change.id"
+			)
+			.where(changeSetElementInAncestryOf([args.targetChangeSet]))
+			.where(changeSetElementIsLeafOf([args.targetChangeSet]))
+			.select([
+				"change.id",
+				"change.entity_id",
+				"change.schema_key",
+				"change.file_id",
+			])
+			.distinct()
+			.execute();
+
+		// 2. Find leaf changes that are present in the *source* state but NOT in the *target* state,
+		//    AND whose entity is not being restored by a different change in the target state.
+		const leafEntitiesToDelete = await trx
+			.selectFrom("change")
+			.innerJoin(
+				"change_set_element",
+				"change_set_element.change_id",
+				"change.id"
+			)
+			// Condition A: The change must be a leaf in the *source* state
+			.where(changeSetElementInAncestryOf([{ id: args.sourceChangeSet.id }]))
+			.where(changeSetElementIsLeafOf([{ id: args.sourceChangeSet.id }]))
+			// Condition B: The change must NOT be a leaf in the *target* state
+			.where(({ not, exists, selectFrom }) =>
+				not(
+					exists(
+						selectFrom("change as target_leaf_check")
+							.innerJoin(
+								"change_set_element as target_cs_elem",
+								"target_cs_elem.change_id",
+								"target_leaf_check.id"
+							)
+							.whereRef("target_leaf_check.id", "=", "change.id")
+							// *** Swapped target and source here relative to previous version ***
+							.where(changeSetElementInAncestryOf([args.targetChangeSet]))
+							.where(changeSetElementIsLeafOf([args.targetChangeSet]))
+							.select("target_leaf_check.id")
+					)
+				)
+			)
+			// Condition C: No other change for the *same entity* is a leaf in the *target* state
+			.where(({ not, exists, selectFrom }) =>
+				not(
+					exists(
+						selectFrom("change as restored_entity_check")
+							.innerJoin(
+								"change_set_element as restored_cs_elem",
+								"restored_cs_elem.change_id",
+								"restored_entity_check.id"
+							)
+							.whereRef(
+								"restored_entity_check.entity_id",
+								"=",
+								"change.entity_id"
+							)
+							// Check if any change for this entity is a leaf AT THE TARGET change set
+							// *** Swapped target and source here relative to previous version ***
+							.where(changeSetElementInAncestryOf([args.targetChangeSet]))
+							.where(changeSetElementIsLeafOf([args.targetChangeSet]))
+							.select("restored_entity_check.id")
+					)
+				)
+			)
+			.select([
+				"change.id",
+				"change.entity_id",
+				"change.plugin_key",
+				"change.schema_version",
+				"change.schema_key",
+				"change.file_id",
+			])
+			.distinct()
+			.execute();
+
+		const deleteChanges =
+			leafEntitiesToDelete.length > 0
+				? await trx
+						.insertInto("change")
+						.values(
+							leafEntitiesToDelete.map((c) => ({
+								schema_key: c.schema_key,
+								schema_version: c.schema_version,
+								plugin_key: c.plugin_key,
+								entity_id: c.entity_id,
+								file_id: c.file_id,
+								// delete change
+								snapshot_id: "no-content",
+							}))
+						)
+						.returning(["id", "entity_id", "schema_key", "file_id"])
+						.execute()
+				: [];
+
+		const combinedChanges = [...leafChangesToApply, ...deleteChanges];
+
+		if (combinedChanges.length === 0) {
+			throw new Error("No changes to apply in the transition change set.");
+		}
+
+		const transitionChangeSet = await createChangeSet({
+			lix: { ...args.lix, db: trx },
+			elements: combinedChanges.map((change) => ({
+				change_id: change.id,
+				entity_id: change.entity_id,
+				schema_key: change.schema_key,
+				file_id: change.file_id,
+			})),
+		});
+
+		return transitionChangeSet;
+	};
+
+	if (args.lix.db.isTransaction) {
+		return executeInTransaction(args.lix.db);
+	} else {
+		return args.lix.db.transaction().execute(executeInTransaction);
+	}
+}

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

@@ -0,0 +1,329 @@
+import { expect, test } from "vitest";
+import { openLix } from "../lix/open-lix.js";
+import { createUndoChangeSet } from "./create-undo-change-set.js";
+import { createChangeSet } from "./create-change-set.js";
+import { applyChangeSet } from "./apply-change-set.js";
+import {
+	mockJsonPlugin,
+	MockJsonPropertySchema,
+} from "../plugin/mock-json-plugin.js";
+import { createCheckpoint } from "./create-checkpoint.js";
+
+test("it creates an undo change set that reverses the operations of the original change set", async () => {
+	// Create a Lix instance with the mockJsonPlugin
+	const lix = await openLix({
+		providePlugins: [mockJsonPlugin],
+	});
+
+	// Insert the schema that the mockJsonPlugin uses
+	await lix.db
+		.insertInto("stored_schema_all")
+		.values({
+			value: MockJsonPropertySchema,
+			lixcol_version_id: "global",
+		})
+		.execute();
+
+	// Create a file
+	await lix.db
+		.insertInto("file")
+		.values({
+			id: "file1",
+			data: new TextEncoder().encode("{}"),
+			path: "/test.json",
+		})
+		.execute();
+
+	const file = await lix.db
+		.selectFrom("file")
+		.where("id", "=", "file1")
+		.selectAll()
+		.executeTakeFirstOrThrow();
+
+	// Create changes for our initial change set
+	const changes = await lix.db
+		.insertInto("change")
+		.values([
+			{
+				id: "c1",
+				file_id: file.id,
+				plugin_key: mockJsonPlugin.key,
+				entity_id: "e1",
+				schema_key: "mock_json_property",
+				snapshot_content: { value: "Value 1" },
+				schema_version: "1.0",
+			},
+			{
+				id: "c2",
+				file_id: file.id,
+				plugin_key: mockJsonPlugin.key,
+				entity_id: "e2",
+				schema_key: "mock_json_property",
+				snapshot_content: { value: "Value 2" },
+				schema_version: "1.0",
+			},
+		])
+		.returningAll()
+		.execute();
+
+	// Create a change set with these changes
+	const cs0 = await createChangeSet({
+		lix,
+		id: "cs0",
+		lixcol_version_id: "global",
+		elements: changes.map((change) => ({
+			lixcol_version_id: "global",
+			change_id: change.id,
+			entity_id: change.entity_id,
+			schema_key: change.schema_key,
+			file_id: change.file_id,
+		})),
+	});
+
+	await applyChangeSet({
+		lix,
+		changeSet: cs0,
+	});
+
+	// Verify the file has the expected state
+	const fileAfterOriginal = await lix.db
+		.selectFrom("file")
+		.where("id", "=", file.id)
+		.selectAll()
+		.executeTakeFirstOrThrow();
+
+	const expectedJsonStateOriginal = {
+		e1: "Value 1",
+		e2: "Value 2",
+	};
+
+	const actualJsonStateOriginal = JSON.parse(
+		new TextDecoder().decode(fileAfterOriginal.data)
+	);
+
+	expect(actualJsonStateOriginal).toEqual(expectedJsonStateOriginal);
+
+	// Create the undo change set
+	const undoCs = await createUndoChangeSet({
+		lix,
+		changeSet: cs0,
+	});
+
+	// Verify the undo change set has no parents (the dev is reponsible or by calling applyChanges())
+	const edges = await lix.db
+		.selectFrom("change_set_edge")
+		.selectAll()
+		.where("child_id", "=", undoCs.id)
+		.execute();
+
+	expect(edges).toHaveLength(0);
+
+	await applyChangeSet({
+		lix,
+		changeSet: undoCs,
+	});
+
+	// Verify the file state after undo - should be empty again
+	const fileAfterUndo = await lix.db
+		.selectFrom("file")
+		.where("id", "=", file.id)
+		.selectAll()
+		.executeTakeFirstOrThrow();
+
+	const actualJsonStateAfterUndo = JSON.parse(
+		new TextDecoder().decode(fileAfterUndo.data)
+	);
+
+	expect(actualJsonStateAfterUndo).toEqual({});
+});
+
+test("it correctly undoes delete operations by restoring previous state", async () => {
+	// Create a Lix instance with the mockJsonPlugin
+	const lix = await openLix({
+		providePlugins: [mockJsonPlugin],
+	});
+
+	// Insert the schema that the mockJsonPlugin uses
+	await lix.db
+		.insertInto("stored_schema_all")
+		.values({
+			value: MockJsonPropertySchema,
+			lixcol_version_id: "global",
+		})
+		.execute();
+
+	// Create a file
+	await lix.db
+		.insertInto("file")
+		.values({
+			id: "file1",
+			data: new TextEncoder().encode("{}"),
+			path: "/test.json",
+		})
+		.execute();
+
+	const file = await lix.db
+		.selectFrom("file")
+		.where("id", "=", "file1")
+		.selectAll()
+		.executeTakeFirstOrThrow();
+
+	// First change set - add an entity
+	const initialChanges = await lix.db
+		.insertInto("change")
+		.values([
+			{
+				id: "c1",
+				file_id: file.id,
+				plugin_key: mockJsonPlugin.key,
+				entity_id: "e1",
+				schema_key: "mock_json_property",
+				schema_version: "1.0",
+				snapshot_content: { value: "Initial Value" },
+			},
+		])
+		.returningAll()
+		.execute();
+
+	const cs0 = await createChangeSet({
+		lix,
+		id: "cs0",
+		lixcol_version_id: "global",
+		elements: initialChanges.map((change) => ({
+			change_id: change.id,
+			lixcol_version_id: "global",
+			entity_id: change.entity_id,
+			schema_key: change.schema_key,
+			file_id: change.file_id,
+		})),
+	});
+
+	// Second change set - delete the entity
+	const deleteChanges = await lix.db
+		.insertInto("change")
+		.values([
+			{
+				id: "c2",
+				file_id: file.id,
+				plugin_key: mockJsonPlugin.key,
+				entity_id: "e1",
+				schema_key: "mock_json_property",
+				schema_version: "1.0",
+				snapshot_content: null, // This marks it as a delete operation
+			},
+		])
+		.returningAll()
+		.execute();
+
+	// Create cs1 with cs0 as parent (don't apply yet)
+	const cs1 = await createChangeSet({
+		lix,
+		id: "cs1",
+		lixcol_version_id: "global",
+		elements: deleteChanges.map((change) => ({
+			change_id: change.id,
+			lixcol_version_id: "global",
+			entity_id: change.entity_id,
+			schema_key: change.schema_key,
+			file_id: change.file_id,
+		})),
+		parents: [cs0],
+	});
+
+	// Create undo change set for the delete operation
+	const undoDeleteCs = await createUndoChangeSet({
+		lix,
+		changeSet: cs1,
+	});
+
+	await applyChangeSet({
+		lix,
+		changeSet: undoDeleteCs,
+	});
+
+	// Verify the entity is restored to its previous state
+	const fileAfterUndo = await lix.db
+		.selectFrom("file")
+		.where("id", "=", file.id)
+		.selectAll()
+		.executeTakeFirstOrThrow();
+
+	const stateAfterUndo = JSON.parse(
+		new TextDecoder().decode(fileAfterUndo.data)
+	);
+
+	expect(stateAfterUndo).toEqual({
+		e1: "Initial Value",
+	});
+});
+
+test.skip("does not naively create delete changes if a previous state existed", async () => {
+	const lix = await openLix({
+		providePlugins: [mockJsonPlugin],
+	});
+
+	const file = await lix.db
+		.insertInto("file")
+		.values({
+			id: "file1",
+			data: new TextEncoder().encode("{}"),
+			path: "/test.json",
+		})
+		.returningAll()
+		.executeTakeFirstOrThrow();
+
+	const checkpoints: Array<{ id: string }> = [];
+
+	// simulating an undo of peter which should restore { name: "samuel", age: 20 }
+	for (const state of [
+		{ name: "Samuel", age: 20 },
+		{ name: "Peter", age: 20 },
+	]) {
+		await lix.db
+			.updateTable("file")
+			.set({ data: new TextEncoder().encode(JSON.stringify(state)) })
+			.execute();
+
+		checkpoints.push(await createCheckpoint({ lix }));
+	}
+
+	const fileAfterEdits = await lix.db
+		.selectFrom("file")
+		.where("id", "=", file.id)
+		.selectAll()
+		.executeTakeFirstOrThrow();
+
+	const jsonStateAfterEdits = JSON.parse(
+		new TextDecoder().decode(fileAfterEdits.data)
+	);
+
+	expect(jsonStateAfterEdits).toEqual({
+		name: "Peter",
+		age: 20,
+	});
+
+	const undoChangeSet = await createUndoChangeSet({
+		lix,
+		changeSet: checkpoints[1]!,
+	});
+
+	await applyChangeSet({
+		lix,
+		changeSet: undoChangeSet!,
+	});
+
+	const fileAfterUndo = await lix.db
+		.selectFrom("file")
+		.where("id", "=", file.id)
+		.selectAll()
+		.executeTakeFirstOrThrow();
+
+	const jsonAfterUndo = JSON.parse(
+		new TextDecoder().decode(fileAfterUndo.data)
+	);
+
+	expect(jsonAfterUndo).toEqual({
+		name: "Samuel",
+		age: 20,
+	});
+});

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

@@ -0,0 +1,147 @@
+import type { Lix } from "../lix/index.js";
+import type { ChangeSet } from "./schema.js";
+import { createChangeSet } from "./create-change-set.js";
+import type { Label } from "../label/schema.js";
+import type { NewChange } from "../change/schema.js";
+import { v7 } from "uuid";
+
+/**
+ * Creates a "reverse" change set that undoes the changes made by the specified change set.
+ *
+ * @example
+ *   ```ts
+ *   const undoChangeSet = await createUndoChangeSet({
+ *     lix,
+ *     changeSet: targetChangeSet
+ *   });
+ *
+ *   await applyChangeSet({
+ *     lix,
+ *     changeSet: undoChangeSet
+ *   });
+ *   ```
+ *
+ * @returns The newly created change set that contains the undo operations
+ */
+export async function createUndoChangeSet(args: {
+	lix: Lix;
+	changeSet: Pick<ChangeSet, "id">;
+	labels?: Pick<Label, "id">[];
+}): Promise<ChangeSet> {
+	const executeInTransaction = async (trx: Lix["db"]) => {
+		// Check for multiple parents (not supported yet)
+		const parents = await trx
+			.selectFrom("change_set_edge_all")
+			.where("lixcol_version_id", "=", "global")
+			.where("child_id", "=", args.changeSet.id)
+			.select("parent_id")
+			.execute();
+
+		if (parents.length > 1) {
+			throw new Error(
+				"Cannot undo change sets with multiple parents (merge scenarios not yet supported)"
+			);
+		}
+
+		// Get all changes in the target change set (direct changes only, non-recursive)
+		const targetChanges = await trx
+			.selectFrom("change")
+			.innerJoin(
+				"change_set_element_all",
+				"change_set_element_all.change_id",
+				"change.id"
+			)
+			.where("change_set_element_all.lixcol_version_id", "=", "global")
+			.where("change_set_element_all.change_set_id", "=", args.changeSet.id)
+			.selectAll("change")
+			.execute();
+
+		const undoChanges: Array<NewChange> = [];
+
+		for (const change of targetChanges) {
+			if (parents.length === 0) {
+				// No parent = this was the first change set, undo = delete everything
+				undoChanges.push({
+					entity_id: change.entity_id,
+					file_id: change.file_id,
+					plugin_key: change.plugin_key,
+					schema_key: change.schema_key,
+					schema_version: change.schema_version,
+					snapshot_content: null, // Mark as deletion
+				});
+			} else {
+				// Find the previous state in the parent change set
+				const parentChangeSet = parents[0]!.parent_id;
+
+				const previousChange = await trx
+					.selectFrom("change")
+					.innerJoin(
+						"change_set_element",
+						"change_set_element.change_id",
+						"change.id"
+					)
+					.where("change_set_element.change_set_id", "=", parentChangeSet)
+					.where("change_set_element.entity_id", "=", change.entity_id)
+					.where("change_set_element.file_id", "=", change.file_id)
+					.where("change_set_element.schema_key", "=", change.schema_key)
+					.selectAll("change")
+					.executeTakeFirst();
+
+				if (previousChange) {
+					// Restore to previous state
+					undoChanges.push({
+						id: v7(),
+						entity_id: change.entity_id,
+						file_id: change.file_id,
+						plugin_key: change.plugin_key,
+						schema_key: change.schema_key,
+						schema_version: change.schema_version,
+						snapshot_content: previousChange.snapshot_content, // Restore previous snapshot
+					});
+				} else {
+					// Entity didn't exist before, so delete it
+					undoChanges.push({
+						id: v7(),
+						entity_id: change.entity_id,
+						file_id: change.file_id,
+						plugin_key: change.plugin_key,
+						schema_key: change.schema_key,
+						schema_version: change.schema_version,
+						snapshot_content: null, // Mark as deletion
+					});
+				}
+			}
+		}
+
+		// Insert the undo changes
+		const createdUndoChanges =
+			undoChanges.length > 0
+				? await trx
+						.insertInto("change")
+						.values(undoChanges)
+						.returningAll()
+						.execute()
+				: [];
+
+		// Create the undo change set
+		const undoChangeSet = await createChangeSet({
+			lix: { ...args.lix, db: trx },
+			labels: args.labels,
+			lixcol_version_id: "global",
+			elements: createdUndoChanges.map((change) => ({
+				change_id: change.id,
+				entity_id: change.entity_id,
+				schema_key: change.schema_key,
+				file_id: change.file_id,
+			})),
+		});
+
+		return undoChangeSet;
+	};
+
+	if (args.lix.db.isTransaction) {
+		return executeInTransaction(args.lix.db);
+	} else {
+		return args.lix.db.transaction().execute(executeInTransaction);
+	}
+}

package/src/change-set/index.ts

@@ -1,2 +1,18 @@
-export { changeSetElementInSymmetricDifference } from "./change-set-element-in-symmetric-difference.js";
+export {
+	LixChangeSetSchema,
+	LixChangeSetElementSchema,
+	LixChangeSetEdgeSchema,
+	LixChangeSetLabelSchema,
+	LixChangeSetThreadSchema,
+	type ChangeSet,
+	type ChangeSetElement,
+	type ChangeSetEdge,
+	type ChangeSetLabel,
+	type ChangeSetThread,
+} from "./schema.js";
 export { createChangeSet } from "./create-change-set.js";
+export { applyChangeSet } from "./apply-change-set.js";
+export { createMergeChangeSet } from "./create-merge-change-set.js";
+export { createUndoChangeSet } from "./create-undo-change-set.js";
+export { createCheckpoint } from "./create-checkpoint.js";
+export { createTransitionChangeSet } from "./create-transition-change-set.js";