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

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

@@ -1,50 +1,42 @@
-/* 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 { openLix } from "../lix/open-lix.js";
 import { createChangeSet } from "../change-set/create-change-set.js";
-import { mockChange } from "../change/mock-change.js";
+import { createLabel } from "../label/create-label.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();
+	const lix = await openLix({});
 
 	// Create two change sets
-	const changeSet1 = await createChangeSet({
+	const cs0 = await createChangeSet({
 		lix,
-		changes: [{ id: "change1" }],
+		id: "cs0",
+		elements: [],
 	});
 
-	const changeSet2 = await createChangeSet({
+	await createChangeSet({
 		lix,
-		changes: [{ id: "change2" }],
+		id: "cs1",
+		elements: [],
 	});
 
 	// Insert a label
-	const label = await lix.db
-		.insertInto("label")
-		.values({ name: "mocked" })
-		.returningAll()
-		.executeTakeFirstOrThrow();
+	const label = await createLabel({ lix, name: "mocked" });
 
 	// 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 })
+		.values({ change_set_id: cs0.id, label_id: label.id })
 		.execute();
 
 	// Query change sets with the label
 	const changeSets = await lix.db
 		.selectFrom("change_set")
-		.where(changeSetHasLabel("mocked"))
+		.where(changeSetHasLabel({ name: "mocked" }))
 		.selectAll()
 		.execute();
 
 	// Assertions
 	expect(changeSets).toHaveLength(1);
-	expect(changeSets[0]?.id).toBe(changeSet1.id);
+	expect(changeSets[0]?.id).toBe(cs0.id);
 });

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

@@ -7,7 +7,7 @@ import type { LixDatabaseSchema } from "../database/schema.js";
  * @example
  *   ```ts
  *   await lix.db.selectFrom("change_set")
- *      .where(changeSetHasLabel("checkpoint"))
+ *      .where(changeSetHasLabel({ name: "checkpoint" }))
  *      .selectAll()
  *      .execute();
  *   ```
@@ -17,12 +17,25 @@ import type { LixDatabaseSchema } from "../database/schema.js";
  *
  *   ```ts
  *   await lix.db.selectFrom("change_set")
- * 		.where((eb) => eb.not(changeSetHasLabel("checkpoint")))
+ * 		.where((eb) => eb.not(changeSetHasLabel({ name: "checkpoint" })))
+ * 		.selectAll()
+ * 		.execute();
+ *   ```
+ *
+ * @example
+ *   Id lookup also works:
+ *
+ *   ```ts
+ *   await lix.db.selectFrom("change_set")
+ * 		.where(changeSetHasLabel({ id: "39j9afj2" }))
  * 		.selectAll()
  * 		.execute();
  *   ```
  */
-export function changeSetHasLabel(name: string) {
+export function changeSetHasLabel(
+	// lookup can happen via both id or name
+	label: { id: string; name?: string } | { name: string; id?: string }
+) {
 	return (
 		eb: ExpressionBuilder<LixDatabaseSchema, "change_set">
 	): ExpressionWrapper<LixDatabaseSchema, "change_set", SqlBool> =>
@@ -31,6 +44,7 @@ export function changeSetHasLabel(name: string) {
 				.selectFrom("change_set_label")
 				.innerJoin("label", "label.id", "change_set_label.label_id")
 				.select("change_set_label.change_set_id")
-				.where("label.name", "=", name)
+				.$if("name" in label, (eb) => eb.where("label.name", "=", label.name!))
+				.$if("id" in label, (eb) => eb.where("label.id", "=", label.id!))
 		);
 }

package/src/query-filter/change-set-is-ancestor-of.test.ts

@@ -0,0 +1,178 @@
+import { test, expect } from "vitest";
+import { openLix } from "../lix/open-lix.js";
+import { createChangeSet } from "../change-set/create-change-set.js";
+import { changeSetIsAncestorOf } from "./change-set-is-ancestor-of.js";
+
+test("selects all ancestors of the current change set", async () => {
+	const lix = await openLix({});
+
+	// Create a linear chain of change sets: cs0 <- cs1 <- cs2
+	const cs0 = await createChangeSet({
+		lix,
+		id: "cs0",
+		elements: [],
+	});
+	const cs1 = await createChangeSet({
+		lix,
+		id: "cs1",
+		elements: [],
+		parents: [cs0],
+	});
+	const cs2 = await createChangeSet({
+		lix,
+		id: "cs2",
+		elements: [],
+		parents: [cs1],
+	});
+
+	// Should select cs0, cs1 as ancestors of cs2
+	const results = await lix.db
+		.selectFrom("change_set")
+		.where(changeSetIsAncestorOf(cs2))
+		.select("id")
+		.execute();
+
+	expect(results.map((r) => r.id).sort()).toEqual([cs0.id, cs1.id].sort());
+});
+
+test("respects the optional depth limit", async () => {
+	const lix = await openLix({});
+
+	// cs0 <- cs1 <- cs2
+	const cs0 = await createChangeSet({
+		lix,
+		id: "cs0",
+		elements: [],
+	});
+	const cs1 = await createChangeSet({
+		lix,
+		id: "cs1",
+		elements: [],
+		parents: [cs0],
+	});
+	const cs2 = await createChangeSet({
+		lix,
+		id: "cs2",
+		elements: [],
+		parents: [cs1],
+	});
+
+	// With depth: 1, we expect cs1 only
+	const results = await lix.db
+		.selectFrom("change_set")
+		.where(changeSetIsAncestorOf(cs2, { depth: 1 }))
+		.select("id")
+		.execute();
+
+	expect(results.map((r) => r.id).sort()).toEqual([cs1.id].sort());
+});
+
+test("includeSelf true selects the current change set as well", async () => {
+	const lix = await openLix({});
+
+	// cs0 <- cs1 <- cs2
+	const cs0 = await createChangeSet({
+		lix,
+		id: "cs0",
+		elements: [],
+	});
+	const cs1 = await createChangeSet({
+		lix,
+		id: "cs1",
+		elements: [],
+		parents: [cs0],
+	});
+	const cs2 = await createChangeSet({
+		lix,
+		id: "cs2",
+		elements: [],
+		parents: [cs1],
+	});
+
+	// Should select cs0, cs1, cs2
+	const results = await lix.db
+		.selectFrom("change_set")
+		.where(changeSetIsAncestorOf(cs2, { includeSelf: true }))
+		.select("id")
+		.execute();
+
+	expect(results.map((r) => r.id).sort()).toEqual(
+		[cs0.id, cs1.id, cs2.id].sort()
+	);
+});
+
+test("can be combined with where(id = X) to check specific ancestry", async () => {
+	const lix = await openLix({});
+
+	// Create chain: cs1 <- cs2 <- cs3
+	const cs1 = await createChangeSet({
+		lix,
+		id: "cs1",
+		elements: [],
+	});
+	const cs2 = await createChangeSet({
+		lix,
+		id: "cs2",
+		elements: [],
+		parents: [cs1],
+	});
+	const cs3 = await createChangeSet({
+		lix,
+		id: "cs3",
+		elements: [],
+		parents: [cs2],
+	});
+
+	// Test: Check if cs2 is an ancestor of cs3 (should return cs2)
+	const cs2IsAncestorOfCs3 = await lix.db
+		.selectFrom("change_set")
+		.where("id", "=", cs2.id)
+		.where(changeSetIsAncestorOf(cs3))
+		.select("id")
+		.execute();
+
+	expect(cs2IsAncestorOfCs3).toHaveLength(1);
+	expect(cs2IsAncestorOfCs3[0]!.id).toBe(cs2.id);
+
+	// Test: Check if cs1 is an ancestor of cs3 (should return cs1)
+	const cs1IsAncestorOfCs3 = await lix.db
+		.selectFrom("change_set")
+		.where("id", "=", cs1.id)
+		.where(changeSetIsAncestorOf(cs3))
+		.select("id")
+		.execute();
+
+	expect(cs1IsAncestorOfCs3).toHaveLength(1);
+	expect(cs1IsAncestorOfCs3[0]!.id).toBe(cs1.id);
+
+	// Test: Check if cs3 is an ancestor of cs3 (should return empty - not inclusive by default)
+	const cs3IsAncestorOfCs3 = await lix.db
+		.selectFrom("change_set")
+		.where("id", "=", cs3.id)
+		.where(changeSetIsAncestorOf(cs3))
+		.select("id")
+		.execute();
+
+	expect(cs3IsAncestorOfCs3).toHaveLength(0);
+
+	// Test: Check if cs3 is an ancestor of cs1 (should return empty - wrong direction)
+	const cs3IsAncestorOfCs1 = await lix.db
+		.selectFrom("change_set")
+		.where("id", "=", cs3.id)
+		.where(changeSetIsAncestorOf(cs1))
+		.select("id")
+		.execute();
+
+	expect(cs3IsAncestorOfCs1).toHaveLength(0);
+
+	// Test: Check with includeSelf option
+	const cs3IsAncestorOfCs3Inclusive = await lix.db
+		.selectFrom("change_set")
+		.where("id", "=", cs3.id)
+		.where(changeSetIsAncestorOf(cs3, { includeSelf: true }))
+		.select("id")
+		.execute();
+
+	expect(cs3IsAncestorOfCs3Inclusive).toHaveLength(1);
+	expect(cs3IsAncestorOfCs3Inclusive[0]!.id).toBe(cs3.id);
+});

package/src/query-filter/change-set-is-ancestor-of.ts

@@ -0,0 +1,77 @@
+import {
+	sql,
+	type SqlBool,
+	type ExpressionBuilder,
+	type ExpressionWrapper,
+} from "kysely";
+import type { LixDatabaseSchema } from "../database/schema.js";
+import type { ChangeSet } from "../change-set/schema.js";
+
+/**
+ * Filters change sets that are ancestors of the given change set.
+ *
+ * By default, this is **exclusive**, meaning it returns only change sets strictly
+ * *before* the provided change set in the graph.
+ *
+ * Traverses the `change_set_edge` graph recursively, starting from the provided change set
+ * (or its parents if exclusive), and returns all change sets reachable via parent edges.
+ *
+ * This filter is typically used to scope the graph before applying filters like `changeIsLeaf()`.
+ *
+ * ⚠️ This filter only defines the traversal scope — it does not filter changes directly.
+ *
+ * --- Options ---
+ * - `includeSelf`: If `true`, includes the starting `changeSet` in the results. Defaults to `false`.
+ * - `depth`: Limits the traversal depth. `depth: 1` selects only immediate parents (if exclusive)
+ *   or the starting node and its immediate parents (if inclusive).
+ *
+ * --- Examples ---
+ *
+ * @example Selecting strict ancestors (default)
+ * ```ts
+ * db.selectFrom("change_set")
+ *   .where(changeSetIsAncestorOf({ id: "cs3" }))
+ *   .selectAll()
+ * ```
+ *
+ * @example Selecting inclusive ancestors
+ * ```ts
+ * db.selectFrom("change_set")
+ *   .where(changeSetIsAncestorOf({ id: "cs3" }, { includeSelf: true }))
+ *   .selectAll()
+ * ```
+ *
+ * @example Combining with changeSetIsDescendantOf to select change sets between two points in time
+ * ```ts
+ * // Select all change sets between startPoint and endPoint (inclusive)
+ * db.selectFrom("change_set")
+ *   .where(changeSetIsDescendantOf({ id: "startPoint" }))
+ *   .where(changeSetIsAncestorOf({ id: "endPoint" }))
+ *   .selectAll()
+ * ```
+ */
+export function changeSetIsAncestorOf(
+	changeSet: Pick<ChangeSet, "id">,
+	options?: { depth?: number; includeSelf?: boolean }
+): (
+	eb: ExpressionBuilder<LixDatabaseSchema, "change_set">
+) => ExpressionWrapper<LixDatabaseSchema, "change_set", SqlBool> {
+	const depthLimit = options?.depth;
+	const includeSelf = options?.includeSelf ?? false;
+
+	return () =>
+		sql<SqlBool>`
+			change_set.id IN (
+				WITH RECURSIVE ap(id, depth) AS (
+					SELECT id, 0 AS depth FROM change_set WHERE id = ${sql.lit(changeSet.id)}
+					UNION ALL
+					SELECT change_set_edge.parent_id, ap.depth + 1
+					FROM change_set_edge
+					JOIN ap ON change_set_edge.child_id = ap.id
+					${depthLimit !== undefined ? sql`WHERE ap.depth < ${sql.lit(depthLimit)}` : sql``}
+				)
+				-- Select based on the includeSelf flag
+				SELECT id FROM ap ${includeSelf ? sql`` : sql`WHERE depth > 0`}
+			)
+		` as any;
+}

package/src/query-filter/change-set-is-descendant-of.test.ts

@@ -0,0 +1,169 @@
+import { test, expect } from "vitest";
+import { openLix } from "../lix/open-lix.js";
+import { createChangeSet } from "../change-set/create-change-set.js";
+import { changeSetIsDescendantOf } from "./change-set-is-descendant-of.js";
+import { changeSetIsAncestorOf } from "./change-set-is-ancestor-of.js";
+
+test("selects all descendants excluding the current change set", async () => {
+	const lix = await openLix({});
+
+	// Create a linear chain of change sets: cs0 <- cs1 <- cs2
+	const cs0 = await createChangeSet({
+		lix,
+		elements: [],
+	});
+
+	const cs1 = await createChangeSet({
+		lix,
+		elements: [],
+		parents: [cs0],
+	});
+
+	const cs2 = await createChangeSet({
+		lix,
+		elements: [],
+		parents: [cs1],
+	});
+
+	// Should select cs0, cs1, cs2 as descendants of cs0
+	const results = await lix.db
+		.selectFrom("change_set")
+		.where(changeSetIsDescendantOf(cs0))
+		.select("id")
+		.execute();
+
+	expect(results.map((r) => r.id).sort()).toEqual([cs1.id, cs2.id].sort());
+});
+
+test("respects the optional depth limit", async () => {
+	const lix = await openLix({});
+
+	// cs0 <- cs1 <- cs2
+	const cs0 = await createChangeSet({
+		lix,
+		elements: [],
+	});
+
+	const cs1 = await createChangeSet({
+		lix,
+		elements: [],
+		parents: [cs0],
+	});
+
+	await createChangeSet({
+		lix,
+		elements: [],
+		parents: [cs1],
+	});
+
+	// With depth: 1 starting from cs0, we expect cs0 and cs1 only
+	const results = await lix.db
+		.selectFrom("change_set")
+		.where(changeSetIsDescendantOf(cs0, { depth: 1 }))
+		.select("id")
+		.execute();
+
+	expect(results.map((r) => r.id).sort()).toEqual([cs1.id].sort());
+});
+
+test("can be combined with ancestor filter to select sets between two points", async () => {
+	const lix = await openLix({});
+
+	// Create a linear chain: cs0 <- cs1 <- cs2 <- cs3
+	const cs0 = await createChangeSet({
+		lix,
+		elements: [],
+	});
+
+	const cs1 = await createChangeSet({
+		lix,
+		elements: [],
+		parents: [cs0],
+	});
+
+	const cs2 = await createChangeSet({
+		lix,
+		elements: [],
+		parents: [cs1],
+	});
+
+	const cs3 = await createChangeSet({
+		lix,
+		elements: [],
+		parents: [cs2],
+	});
+
+	// Select change sets that are descendants of cs1 AND ancestors of cs3
+	const results = await lix.db
+		.selectFrom("change_set")
+		.where(changeSetIsDescendantOf(cs1))
+		.where(changeSetIsAncestorOf(cs3))
+		.select("id")
+		.execute();
+
+	expect(results.map((r) => r.id).sort()).toEqual([cs2.id].sort());
+});
+
+test("selects descendants including the current change set when includeSelf is true", async () => {
+	const lix = await openLix({});
+
+	// Setup: cs0 <- cs1 <- cs2
+	const cs0 = await createChangeSet({
+		lix,
+		elements: [],
+	});
+
+	const cs1 = await createChangeSet({
+		lix,
+		elements: [],
+		parents: [cs0],
+	});
+
+	const cs2 = await createChangeSet({
+		lix,
+		elements: [],
+		parents: [cs1],
+	});
+
+	// Should select cs0, cs1, cs2 when includeSelf: true starting from cs0
+	const results = await lix.db
+		.selectFrom("change_set")
+		.where(changeSetIsDescendantOf(cs0, { includeSelf: true }))
+		.select("id")
+		.execute();
+
+	expect(results.map((r) => r.id).sort()).toEqual(
+		[cs0.id, cs1.id, cs2.id].sort()
+	);
+});
+
+test("respects depth limit when includeSelf is true", async () => {
+	const lix = await openLix({});
+
+	// Setup: cs0 <- cs1 <- cs2
+	const cs0 = await createChangeSet({
+		lix,
+		elements: [],
+	});
+
+	const cs1 = await createChangeSet({
+		lix,
+		elements: [],
+		parents: [cs0],
+	});
+
+	await createChangeSet({
+		lix,
+		elements: [],
+		parents: [cs1],
+	});
+
+	// With depth: 1 and includeSelf: true starting from cs0, we expect cs0 and cs1
+	const results = await lix.db
+		.selectFrom("change_set")
+		.where(changeSetIsDescendantOf(cs0, { depth: 1, includeSelf: true }))
+		.select("id")
+		.execute();
+
+	expect(results.map((r) => r.id).sort()).toEqual([cs0.id, cs1.id].sort());
+});

package/src/query-filter/change-set-is-descendant-of.ts

@@ -0,0 +1,70 @@
+import {
+	sql,
+	type SqlBool,
+	type ExpressionBuilder,
+	type ExpressionWrapper,
+} from "kysely";
+import type { LixDatabaseSchema } from "../database/schema.js";
+import type { ChangeSet } from "../change-set/schema.js";
+
+/**
+ * Filters change sets that are descendants of the given change set.
+ *
+ * By default, this is **exclusive**, meaning it returns only change sets strictly
+ * *after* the provided change set in the graph.
+ *
+ * Traverses the `change_set_edge` graph recursively, starting from the provided change set
+ * (or its children if exclusive), and returns all change sets reachable via child edges.
+ *
+ * This filter is useful for finding changes made *after* a specific point in time (e.g., a checkpoint).
+ *
+ * ⚠️ This filter only defines the traversal scope — it does not filter changes directly.
+ *
+ * --- Options ---
+ * - `includeSelf`: If `true`, includes the starting `changeSet` in the results. Defaults to `false`.
+ * - `depth`: Limits the traversal depth. `depth: 1` selects only immediate children (if exclusive)
+ *   or the starting node and its immediate children (if includeSelf is true).
+ *
+ * --- Examples ---
+ *
+ * @example Selecting strict descendants (default)
+ * ```ts
+ * db.selectFrom("change_set")
+ *   .where(changeSetIsDescendantOf({ id: "cs1" }))
+ *   .selectAll()
+ * ```
+ *
+ * @example Combining with changeSetIsAncestorOf to select change sets between two points in time
+ * ```ts
+ * // Select all change sets between startPoint and endPoint (inclusive)
+ * db.selectFrom("change_set")
+ *   .where(changeSetIsDescendantOf({ id: "startPoint" }))
+ *   .where(changeSetIsAncestorOf({ id: "endPoint" }))
+ *   .selectAll()
+ * ```
+ */
+export function changeSetIsDescendantOf(
+	changeSet: Pick<ChangeSet, "id">,
+	options?: { depth?: number; includeSelf?: boolean }
+): (
+	eb: ExpressionBuilder<LixDatabaseSchema, "change_set">
+) => ExpressionWrapper<LixDatabaseSchema, "change_set", SqlBool> {
+	const depthLimit = options?.depth;
+	const includeSelf = options?.includeSelf ?? false;
+
+	return () =>
+		sql<SqlBool>`
+			change_set.id IN (
+				WITH RECURSIVE dp(id, depth) AS (
+					SELECT id, 0 AS depth FROM change_set WHERE id = ${sql.lit(changeSet.id)}
+					UNION ALL
+					SELECT change_set_edge.child_id, dp.depth + 1
+					FROM change_set_edge
+					JOIN dp ON change_set_edge.parent_id = dp.id
+					${depthLimit !== undefined ? sql`WHERE dp.depth < ${sql.lit(depthLimit)}` : sql``}
+				)
+				-- Select based on the includeSelf flag
+				SELECT id FROM dp ${includeSelf ? sql`` : sql`WHERE depth > 0`}
+			)
+		` as any;
+}

package/src/query-filter/index.ts

@@ -1,8 +1,7 @@
-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 { changeSetElementInAncestryOf } from "./change-set-element-in-ancestry-of.js";
 export { changeSetHasLabel } from "./change-set-has-label.js";
+export { changeSetIsAncestorOf } from "./change-set-is-ancestor-of.js";
+export { changeSetIsDescendantOf } from "./change-set-is-descendant-of.js";
+export { changeSetElementIsLeafOf } from "./change-set-element-is-leaf-of.js";
+export { changeSetElementInSymmetricDifference } from "./change-set-element-in-symmetric-difference.js";