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

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

@@ -0,0 +1,365 @@
+import { test, expect } from "vitest";
+import { openLix } from "../lix/open-lix.js";
+import { createChangeSet } from "../change-set/create-change-set.js";
+import { commitIsDescendantOf } from "./commit-is-descendant-of.js";
+import { commitIsAncestorOf } from "./commit-is-ancestor-of.js";
+import { uuidV7 } from "../deterministic/uuid-v7.js";
+import type { Lix } from "../lix/open-lix.js";
+
+// Utility function to create a commit with optional parent
+async function createCommitWithParent(args: {
+	lix: Lix;
+	changeSetId: string;
+	parentCommitId?: string;
+	versionId?: string;
+}): Promise<string> {
+	const commitId = uuidV7({ lix: args.lix });
+	const versionId = args.versionId || "global";
+
+	// Create the commit
+	await args.lix.db
+		.insertInto("commit_all")
+		.values({
+			id: commitId,
+			change_set_id: args.changeSetId,
+			lixcol_version_id: versionId,
+		})
+		.execute();
+
+	// Create edge if parent is provided
+	if (args.parentCommitId) {
+		await args.lix.db
+			.insertInto("commit_edge_all")
+			.values({
+				parent_id: args.parentCommitId,
+				child_id: commitId,
+				lixcol_version_id: versionId,
+			})
+			.execute();
+	}
+
+	return commitId;
+}
+
+test("selects all descendants excluding the current commit", async () => {
+	const lix = await openLix({});
+
+	// Create a linear chain of commits: c0 <- c1 <- c2
+	const cs0 = await createChangeSet({
+		lix,
+		lixcol_version_id: "global",
+		elements: [],
+	});
+	const c0Id = await createCommitWithParent({ lix, changeSetId: cs0.id });
+
+	const cs1 = await createChangeSet({
+		lix,
+		lixcol_version_id: "global",
+		elements: [],
+	});
+	const c1Id = await createCommitWithParent({
+		lix,
+		changeSetId: cs1.id,
+		parentCommitId: c0Id,
+	});
+
+	const cs2 = await createChangeSet({
+		lix,
+		lixcol_version_id: "global",
+		elements: [],
+	});
+	const c2Id = await createCommitWithParent({
+		lix,
+		changeSetId: cs2.id,
+		parentCommitId: c1Id,
+	});
+
+	// Should select c1, c2 as descendants of c0
+	const results = await lix.db
+		.selectFrom("commit")
+		.where(commitIsDescendantOf({ id: c0Id }))
+		.select("id")
+		.execute();
+
+	expect(results.map((r) => r.id).sort()).toEqual([c1Id, c2Id].sort());
+});
+
+test("respects the optional depth limit", async () => {
+	const lix = await openLix({});
+
+	// c0 <- c1 <- c2
+	const cs0 = await createChangeSet({
+		lix,
+		lixcol_version_id: "global",
+		elements: [],
+	});
+	const c0Id = uuidV7({ lix });
+	await lix.db
+		.insertInto("commit_all")
+		.values({
+			id: c0Id,
+			change_set_id: cs0.id,
+			lixcol_version_id: "global",
+		})
+		.execute();
+
+	const cs1 = await createChangeSet({
+		lix,
+		lixcol_version_id: "global",
+		elements: [],
+	});
+	const c1Id = uuidV7({ lix });
+	await lix.db
+		.insertInto("commit_all")
+		.values({
+			id: c1Id,
+			change_set_id: cs1.id,
+			lixcol_version_id: "global",
+		})
+		.execute();
+	await lix.db
+		.insertInto("commit_edge_all")
+		.values({
+			parent_id: c0Id,
+			child_id: c1Id,
+			lixcol_version_id: "global",
+		})
+		.execute();
+
+	const cs2 = await createChangeSet({
+		lix,
+		lixcol_version_id: "global",
+		elements: [],
+	});
+	const c2Id = uuidV7({ lix });
+	await lix.db
+		.insertInto("commit_all")
+		.values({
+			id: c2Id,
+			change_set_id: cs2.id,
+			lixcol_version_id: "global",
+		})
+		.execute();
+	await lix.db
+		.insertInto("commit_edge_all")
+		.values({
+			parent_id: c1Id,
+			child_id: c2Id,
+			lixcol_version_id: "global",
+		})
+		.execute();
+
+	// With depth: 1 starting from c0, we expect c1 only
+	const results = await lix.db
+		.selectFrom("commit")
+		.where(commitIsDescendantOf({ id: c0Id }, { depth: 1 }))
+		.select("id")
+		.execute();
+
+	expect(results.map((r) => r.id).sort()).toEqual([c1Id].sort());
+});
+
+test("can be combined with ancestor filter to select commits between two points", async () => {
+	const lix = await openLix({});
+
+	// Create a linear chain: c0 <- c1 <- c2 <- c3
+	const cs0 = await createChangeSet({
+		lix,
+		lixcol_version_id: "global",
+		elements: [],
+	});
+	const c0Id = await createCommitWithParent({ lix, changeSetId: cs0.id });
+
+	const cs1 = await createChangeSet({
+		lix,
+		lixcol_version_id: "global",
+		elements: [],
+	});
+	const c1Id = await createCommitWithParent({
+		lix,
+		changeSetId: cs1.id,
+		parentCommitId: c0Id,
+	});
+
+	const cs2 = await createChangeSet({
+		lix,
+		lixcol_version_id: "global",
+		elements: [],
+	});
+	const c2Id = await createCommitWithParent({
+		lix,
+		changeSetId: cs2.id,
+		parentCommitId: c1Id,
+	});
+
+	const cs3 = await createChangeSet({
+		lix,
+		lixcol_version_id: "global",
+		elements: [],
+	});
+	const c3Id = await createCommitWithParent({
+		lix,
+		changeSetId: cs3.id,
+		parentCommitId: c2Id,
+	});
+
+	// Select commits that are descendants of c1 AND ancestors of c3
+	const results = await lix.db
+		.selectFrom("commit")
+		.where(commitIsDescendantOf({ id: c1Id }))
+		.where(commitIsAncestorOf({ id: c3Id }))
+		.select("id")
+		.execute();
+
+	expect(results.map((r) => r.id).sort()).toEqual([c2Id].sort());
+});
+
+test("selects descendants including the current commit when includeSelf is true", async () => {
+	const lix = await openLix({});
+
+	// Setup: c0 <- c1 <- c2
+	const cs0 = await createChangeSet({
+		lix,
+		lixcol_version_id: "global",
+		elements: [],
+	});
+	const c0Id = uuidV7({ lix });
+	await lix.db
+		.insertInto("commit_all")
+		.values({
+			id: c0Id,
+			change_set_id: cs0.id,
+			lixcol_version_id: "global",
+		})
+		.execute();
+
+	const cs1 = await createChangeSet({
+		lix,
+		lixcol_version_id: "global",
+		elements: [],
+	});
+	const c1Id = uuidV7({ lix });
+	await lix.db
+		.insertInto("commit_all")
+		.values({
+			id: c1Id,
+			change_set_id: cs1.id,
+			lixcol_version_id: "global",
+		})
+		.execute();
+	await lix.db
+		.insertInto("commit_edge_all")
+		.values({
+			parent_id: c0Id,
+			child_id: c1Id,
+			lixcol_version_id: "global",
+		})
+		.execute();
+
+	const cs2 = await createChangeSet({
+		lix,
+		lixcol_version_id: "global",
+		elements: [],
+	});
+	const c2Id = uuidV7({ lix });
+	await lix.db
+		.insertInto("commit_all")
+		.values({
+			id: c2Id,
+			change_set_id: cs2.id,
+			lixcol_version_id: "global",
+		})
+		.execute();
+	await lix.db
+		.insertInto("commit_edge_all")
+		.values({
+			parent_id: c1Id,
+			child_id: c2Id,
+			lixcol_version_id: "global",
+		})
+		.execute();
+
+	// Should select c0, c1, c2 when includeSelf: true starting from c0
+	const results = await lix.db
+		.selectFrom("commit")
+		.where(commitIsDescendantOf({ id: c0Id }, { includeSelf: true }))
+		.select("id")
+		.execute();
+
+	expect(results.map((r) => r.id).sort()).toEqual([c0Id, c1Id, c2Id].sort());
+});
+
+test("respects depth limit when includeSelf is true", async () => {
+	const lix = await openLix({});
+
+	// Setup: c0 <- c1 <- c2
+	const cs0 = await createChangeSet({
+		lix,
+		lixcol_version_id: "global",
+		elements: [],
+	});
+	const c0Id = uuidV7({ lix });
+	await lix.db
+		.insertInto("commit_all")
+		.values({
+			id: c0Id,
+			change_set_id: cs0.id,
+			lixcol_version_id: "global",
+		})
+		.execute();
+
+	const cs1 = await createChangeSet({
+		lix,
+		lixcol_version_id: "global",
+		elements: [],
+	});
+	const c1Id = uuidV7({ lix });
+	await lix.db
+		.insertInto("commit_all")
+		.values({
+			id: c1Id,
+			change_set_id: cs1.id,
+			lixcol_version_id: "global",
+		})
+		.execute();
+	await lix.db
+		.insertInto("commit_edge_all")
+		.values({
+			parent_id: c0Id,
+			child_id: c1Id,
+			lixcol_version_id: "global",
+		})
+		.execute();
+
+	const cs2 = await createChangeSet({
+		lix,
+		lixcol_version_id: "global",
+		elements: [],
+	});
+	const c2Id = uuidV7({ lix });
+	await lix.db
+		.insertInto("commit_all")
+		.values({
+			id: c2Id,
+			change_set_id: cs2.id,
+			lixcol_version_id: "global",
+		})
+		.execute();
+	await lix.db
+		.insertInto("commit_edge_all")
+		.values({
+			parent_id: c1Id,
+			child_id: c2Id,
+			lixcol_version_id: "global",
+		})
+		.execute();
+
+	// With depth: 1 and includeSelf: true starting from c0, we expect c0 and c1
+	const results = await lix.db
+		.selectFrom("commit")
+		.where(commitIsDescendantOf({ id: c0Id }, { depth: 1, includeSelf: true }))
+		.select("id")
+		.execute();
+
+	expect(results.map((r) => r.id).sort()).toEqual([c0Id, c1Id].sort());
+});

package/src/query-filter/commit-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 { LixCommit } from "../commit/schema.js";
+
+/**
+ * Filters commits that are descendants of the given commit.
+ *
+ * By default, this is **exclusive**, meaning it returns only commits strictly
+ * *after* the provided commit in the graph.
+ *
+ * Traverses the `commit_edge` graph recursively, starting from the provided commit
+ * (or its children if exclusive), and returns all commits 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 `commit` 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("commit")
+ *   .where(commitIsDescendantOf({ id: "c1" }))
+ *   .selectAll()
+ * ```
+ *
+ * @example Combining with commitIsAncestorOf to select commits between two points in time
+ * ```ts
+ * // Select all commits between startPoint and endPoint (inclusive)
+ * db.selectFrom("commit")
+ *   .where(commitIsDescendantOf({ id: "startPoint" }))
+ *   .where(commitIsAncestorOf({ id: "endPoint" }))
+ *   .selectAll()
+ * ```
+ */
+export function commitIsDescendantOf(
+	commit: Pick<LixCommit, "id">,
+	options?: { depth?: number; includeSelf?: boolean }
+): (
+	eb: ExpressionBuilder<LixDatabaseSchema, "commit">
+) => ExpressionWrapper<LixDatabaseSchema, "commit", SqlBool> {
+	const depthLimit = options?.depth;
+	const includeSelf = options?.includeSelf ?? false;
+
+	return () =>
+		sql<SqlBool>`
+			"commit".id IN (
+				WITH RECURSIVE dp(id, depth) AS (
+					SELECT id, 0 AS depth FROM "commit" WHERE id = ${sql.lit(commit.id)}
+					UNION ALL
+					SELECT commit_edge.child_id, dp.depth + 1
+					FROM commit_edge
+					JOIN dp ON commit_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,7 +1,5 @@
-export { changeHasLabel } from "./change-has-label.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";
+export { commitIsAncestorOf } from "./commit-is-ancestor-of.js";
+export { commitIsDescendantOf } from "./commit-is-descendant-of.js";

package/src/schema-definition/definition.test.ts

@@ -159,16 +159,22 @@ test("x-lix-foreign-keys with valid structure", () => {
 		type: "object",
 		"x-lix-key": "blog_post",
 		"x-lix-version": "1.0",
-		"x-lix-foreign-keys": {
-			author_id: {
-				schemaKey: "user_profile",
-				property: "id",
+		"x-lix-foreign-keys": [
+			{
+				properties: ["author_id"],
+				references: {
+					schemaKey: "user_profile",
+					properties: ["id"],
+				},
 			},
-			category_id: {
-				schemaKey: "post_category",
-				property: "id",
+			{
+				properties: ["category_id"],
+				references: {
+					schemaKey: "post_category",
+					properties: ["id"],
+				},
 			},
-		},
+		],
 		properties: {
 			id: { type: "string" },
 			author_id: { type: "string" },
@@ -188,13 +194,16 @@ test("x-lix-foreign-keys with schemaVersion", () => {
 		type: "object",
 		"x-lix-key": "comment",
 		"x-lix-version": "1.0",
-		"x-lix-foreign-keys": {
-			post_id: {
-				schemaKey: "blog_post",
-				property: "id",
-				schemaVersion: "1.0",
+		"x-lix-foreign-keys": [
+			{
+				properties: ["post_id"],
+				references: {
+					schemaKey: "blog_post",
+					properties: ["id"],
+					schemaVersion: "1.0",
+				},
 			},
-		},
+		],
 		properties: {
 			id: { type: "string" },
 			post_id: { type: "string" },
@@ -214,12 +223,12 @@ test("x-lix-foreign-keys fails without required fields", () => {
 		type: "object",
 		"x-lix-key": "blog_post",
 		"x-lix-version": "1.0",
-		"x-lix-foreign-keys": {
-			author_id: {
-				schemaKey: "user_profile",
-				// Missing required "property" field
+		"x-lix-foreign-keys": [
+			{
+				properties: ["author_id"],
+				// Missing required "references" field
 			},
-		},
+		],
 		properties: {
 			id: { type: "string" },
 			author_id: { type: "string" },
@@ -238,13 +247,16 @@ test("x-lix-foreign-keys fails with invalid schemaVersion format", () => {
 		type: "object",
 		"x-lix-key": "comment",
 		"x-lix-version": "1.0",
-		"x-lix-foreign-keys": {
-			post_id: {
-				schemaKey: "blog_post",
-				property: "id",
-				schemaVersion: "v1.0.0", // Invalid format
+		"x-lix-foreign-keys": [
+			{
+				properties: ["post_id"],
+				references: {
+					schemaKey: "blog_post",
+					properties: ["id"],
+					schemaVersion: "v1.0.0", // Invalid format
+				},
 			},
-		},
+		],
 		properties: {
 			id: { type: "string" },
 			post_id: { type: "string" },
@@ -258,6 +270,42 @@ test("x-lix-foreign-keys fails with invalid schemaVersion format", () => {
 	expect(valid).toBe(false);
 });
 
+test("x-lix-foreign-keys with composite key", () => {
+	const schema = {
+		type: "object",
+		"x-lix-key": "entity_label",
+		"x-lix-version": "1.0",
+		"x-lix-foreign-keys": [
+			{
+				properties: ["entity_id", "schema_key", "file_id"],
+				references: {
+					schemaKey: "state",
+					properties: ["entity_id", "schema_key", "file_id"],
+				},
+			},
+			{
+				properties: ["label_id"],
+				references: {
+					schemaKey: "lix_label",
+					properties: ["id"],
+				},
+			},
+		],
+		properties: {
+			entity_id: { type: "string" },
+			schema_key: { type: "string" },
+			file_id: { type: "string" },
+			label_id: { type: "string" },
+		},
+		required: ["entity_id", "schema_key", "file_id", "label_id"],
+		additionalProperties: false,
+	} as const satisfies LixSchemaDefinition;
+
+	const valid = ajv.validate(LixSchemaDefinition, schema);
+
+	expect(valid).toBe(true);
+});
+
 test("x-version is required", () => {
 	const schema = {
 		type: "object",