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

package/src/entity-views/entity-state-history.test.ts

@@ -72,13 +72,13 @@ describe("createEntityHistoryViewIfNotExists", () => {
 		const activeVersion = await lix.db
 			.selectFrom("active_version")
 			.innerJoin("version", "active_version.version_id", "version.id")
-			.select("version.change_set_id")
+			.select("version.commit_id")
 			.executeTakeFirstOrThrow();
 
 		// Query the history view
 		const historyResult = await lix.db
 			.selectFrom("test_entity_history" as any)
-			.where("lixcol_change_set_id", "=", activeVersion.change_set_id)
+			.where("lixcol_commit_id", "=", activeVersion.commit_id)
 			.selectAll()
 			.execute();
 
@@ -91,15 +91,15 @@ describe("createEntityHistoryViewIfNotExists", () => {
 		expect(historyEntity).toHaveProperty("value", 42);
 
 		// History-specific columns
-		expect(historyEntity).toHaveProperty("entity_id", "test_id");
-		expect(historyEntity).toHaveProperty("schema_key", "test_entity");
+		expect(historyEntity).toHaveProperty("lixcol_entity_id", "test_id");
+		expect(historyEntity).toHaveProperty("lixcol_schema_key", "test_entity");
 		expect(historyEntity).toHaveProperty("lixcol_file_id", "test_file");
 		expect(historyEntity).toHaveProperty("lixcol_plugin_key", "test_plugin");
 		expect(historyEntity).toHaveProperty("lixcol_schema_version", "1.0");
 		expect(historyEntity).toHaveProperty("lixcol_change_id");
 		expect(historyEntity).toHaveProperty(
-			"lixcol_change_set_id",
-			activeVersion.change_set_id
+			"lixcol_commit_id",
+			activeVersion.commit_id
 		);
 		expect(historyEntity).toHaveProperty("lixcol_depth", 0);
 	});
@@ -135,13 +135,13 @@ describe("createEntityHistoryViewIfNotExists", () => {
 		const activeVersion = await lix.db
 			.selectFrom("active_version")
 			.innerJoin("version", "active_version.version_id", "version.id")
-			.select("version.change_set_id")
+			.select("version.commit_id")
 			.executeTakeFirstOrThrow();
 
 		// Test that we can query the view using the schema key + _history name
 		const result = await lix.db
 			.selectFrom("test_entity_history" as any)
-			.where("lixcol_change_set_id", "=", activeVersion.change_set_id)
+			.where("lixcol_commit_id", "=", activeVersion.commit_id)
 			.selectAll()
 			.execute();
 
@@ -216,14 +216,14 @@ describe("createEntityHistoryViewIfNotExists", () => {
 		const activeVersion = await lix.db
 			.selectFrom("active_version")
 			.innerJoin("version", "active_version.version_id", "version.id")
-			.select("version.change_set_id")
+			.select("version.commit_id")
 			.executeTakeFirstOrThrow();
 
 		// Query all history for this entity
 		const historyResult = await lix.db
 			.selectFrom("test_history" as any)
-			.where("entity_id", "=", "tracked_entity")
-			.where("lixcol_change_set_id", "=", activeVersion.change_set_id)
+			.where("lixcol_entity_id", "=", "tracked_entity")
+			.where("lixcol_commit_id", "=", activeVersion.commit_id)
 			.orderBy("lixcol_depth", "asc")
 			.selectAll()
 			.execute();
@@ -292,14 +292,14 @@ describe("createEntityHistoryViewIfNotExists", () => {
 		const activeVersion = await lix.db
 			.selectFrom("active_version")
 			.innerJoin("version", "active_version.version_id", "version.id")
-			.select("version.change_set_id")
+			.select("version.commit_id")
 			.executeTakeFirstOrThrow();
 
 		// Verify we can read the data
 		const readResult = await lix.db
 			.selectFrom("readonly_history" as any)
-			.where("entity_id", "=", "test_id")
-			.where("lixcol_change_set_id", "=", activeVersion.change_set_id)
+			.where("lixcol_entity_id", "=", "test_id")
+			.where("lixcol_commit_id", "=", activeVersion.commit_id)
 			.selectAll()
 			.execute();
 
@@ -309,7 +309,7 @@ describe("createEntityHistoryViewIfNotExists", () => {
 		await expect(
 			lix.db
 				.updateTable("readonly_history" as any)
-				.where("entity_id", "=", "test_id")
+				.where("lixcol_entity_id", "=", "test_id")
 				.set({ name: "updated_name" })
 				.execute()
 		).rejects.toThrow();
@@ -318,8 +318,70 @@ describe("createEntityHistoryViewIfNotExists", () => {
 		await expect(
 			lix.db
 				.deleteFrom("readonly_history" as any)
-				.where("entity_id", "=", "test_id")
+				.where("lixcol_entity_id", "=", "test_id")
 				.execute()
 		).rejects.toThrow();
 	});
+
+	test("should expose lixcol_entity_id, lixcol_schema_key, lixcol_file_id, and lixcol_plugin_key in history view", async () => {
+		const lix = await openLix({});
+
+		createEntityStateHistoryView({
+			lix,
+			schema: testSchema,
+			overrideName: "test_history_view",
+		});
+
+		// Insert test data
+		await lix.db
+			.insertInto("state_all")
+			.values({
+				entity_id: "test_id",
+				schema_key: "test_entity",
+				file_id: "test_file",
+				plugin_key: "test_plugin",
+				snapshot_content: {
+					id: "test_id",
+					name: "test_name",
+					value: 42,
+				},
+				schema_version: "1.0",
+				version_id: lix.db.selectFrom("active_version").select("version_id"),
+			})
+			.execute();
+
+		// Get the active version's change set
+		const activeVersion = await lix.db
+			.selectFrom("active_version")
+			.innerJoin("version", "active_version.version_id", "version.id")
+			.select("version.commit_id")
+			.executeTakeFirstOrThrow();
+
+		// Query the history view to verify all entity identification columns are exposed
+		const result = await lix.db
+			.selectFrom("test_history_view" as any)
+			.where("lixcol_commit_id", "=", activeVersion.commit_id)
+			.where("lixcol_entity_id", "=", "test_id")
+			.select([
+				"id",
+				"name",
+				"lixcol_entity_id",
+				"lixcol_schema_key",
+				"lixcol_file_id",
+				"lixcol_plugin_key",
+				"lixcol_commit_id",
+				"lixcol_depth",
+			])
+			.executeTakeFirst();
+
+		expect(result).toBeDefined();
+
+		// Verify all required lixcol_ columns are present and have correct values
+		expect(result?.lixcol_entity_id).toBe("test_id");
+		expect(result?.lixcol_schema_key).toBe("test_entity");
+		expect(result?.lixcol_file_id).toBe("test_file");
+		expect(result?.lixcol_plugin_key).toBe("test_plugin");
+		expect(result?.lixcol_commit_id).toBe(activeVersion.commit_id);
+		expect(result?.lixcol_depth).toBe(0);
+	});
 });

package/src/entity-views/entity-state-history.ts

@@ -20,16 +20,30 @@ import type {
  *   name: string;
  * } & StateEntityHistoryView;
  *
- * // Query entity history at a specific change set
+ * // Query entity history at a specific commit
  * const history = await lix.db
  *   .selectFrom("account_history")
- *   .where("lixcol_change_set_id", "=", changeSetId)
- *   .where("lixcol_depth", "=", 0) // Get the state at this exact change set
+ *   .where("lixcol_commit_id", "=", commitId)
+ *   .where("lixcol_depth", "=", 0) // Get the state at this exact commit
  *   .selectAll()
  *   .execute();
  * ```
  */
 export type StateEntityHistoryView = {
+	/**
+	 * The unique identifier for this entity within its schema and file.
+	 *
+	 * This is the primary identifier used to reference this specific entity.
+	 */
+	lixcol_entity_id: Generated<string>;
+
+	/**
+	 * The schema key that defines the structure and type of this entity.
+	 *
+	 * This references the schema definition that validates and types this entity.
+	 */
+	lixcol_schema_key: Generated<string>;
+
 	/**
 	 * File identifier where this entity is stored.
 	 *
@@ -63,19 +77,28 @@ export type StateEntityHistoryView = {
 	lixcol_change_id: Generated<string>;
 
 	/**
-	 * Change set ID that serves as the query root for depth calculation.
+	 * Commit ID that serves as the query root for depth calculation.
 	 *
 	 * When querying history, this represents the "perspective" from which
 	 * you're viewing the entity's history. The depth is calculated relative
-	 * to this change set.
+	 * to this commit.
+	 */
+	lixcol_commit_id: Generated<string>;
+
+	/**
+	 * The root commit ID used as the starting point for traversing history.
+	 *
+	 * When querying history from a specific commit, this field contains that
+	 * commit ID for all returned rows. Used with `depth` to understand how
+	 * far back in history each entity state is from this root.
 	 */
-	lixcol_change_set_id: Generated<string>;
+	lixcol_root_commit_id: Generated<string>;
 
 	/**
-	 * Depth of this entity state relative to the queried change_set_id.
+	 * Depth of this entity state relative to the queried commit_id.
 	 *
-	 * - `0`: The entity state at the exact queried change set
-	 * - `1`: The entity state one change before the queried change set
+	 * - `0`: The entity state at the exact queried commit
+	 * - `1`: The entity state one commit before the queried commit
 	 * - `2+`: Earlier states, going back in history
 	 *
 	 * This is useful for blame functionality and understanding how an entity
@@ -101,6 +124,20 @@ export type StateEntityHistoryView = {
  * ```
  */
 export type StateEntityHistoryColumns = {
+	/**
+	 * The unique identifier for this entity within its schema and file.
+	 *
+	 * This is the primary identifier used to reference this specific entity.
+	 */
+	lixcol_entity_id: LixGenerated<string>;
+
+	/**
+	 * The schema key that defines the structure and type of this entity.
+	 *
+	 * This references the schema definition that validates and types this entity.
+	 */
+	lixcol_schema_key: LixGenerated<string>;
+
 	/**
 	 * File identifier where this entity is stored.
 	 *
@@ -134,19 +171,28 @@ export type StateEntityHistoryColumns = {
 	lixcol_change_id: LixGenerated<string>;
 
 	/**
-	 * Change set ID that serves as the query root for depth calculation.
+	 * Commit ID that serves as the query root for depth calculation.
 	 *
 	 * When querying history, this represents the "perspective" from which
 	 * you're viewing the entity's history. The depth is calculated relative
-	 * to this change set.
+	 * to this commit.
+	 */
+	lixcol_commit_id: LixGenerated<string>;
+
+	/**
+	 * The root commit ID used as the starting point for traversing history.
+	 *
+	 * When querying history from a specific commit, this field contains that
+	 * commit ID for all returned rows. Used with `depth` to understand how
+	 * far back in history each entity state is from this root.
 	 */
-	lixcol_change_set_id: LixGenerated<string>;
+	lixcol_root_commit_id: LixGenerated<string>;
 
 	/**
-	 * Depth of this entity state relative to the queried change_set_id.
+	 * Depth of this entity state relative to the queried commit_id.
 	 *
-	 * - `0`: The entity state at the exact queried change set
-	 * - `1`: The entity state one change before the queried change set
+	 * - `0`: The entity state at the exact queried commit
+	 * - `1`: The entity state one commit before the queried commit
 	 * - `2+`: Earlier states, going back in history
 	 *
 	 * This is useful for blame functionality and understanding how an entity
@@ -198,25 +244,28 @@ export function createEntityStateHistoryView(args: {
 	}
 
 	const view_name = args.overrideName ?? args.schema["x-lix-key"] + "_history";
+	// Quote the view name to handle SQL reserved keywords
+	const quoted_view_name = `"${view_name}"`;
 	const schema_key = args.schema["x-lix-key"];
 	const properties = Object.keys((args.schema as any).properties);
 
 	// Generated SQL query for history view
 	const sqlQuery = `
-    CREATE VIEW IF NOT EXISTS ${view_name} AS
+    CREATE VIEW IF NOT EXISTS ${quoted_view_name} AS
       SELECT
         ${properties
 					.map(
 						(prop) => `json_extract(snapshot_content, '$.${prop}') AS ${prop}`
 					)
 					.join(",\n        ")},
-        entity_id,
-        schema_key,
+        entity_id AS lixcol_entity_id,
+        schema_key AS lixcol_schema_key,
         file_id AS lixcol_file_id,
         plugin_key AS lixcol_plugin_key,
         schema_version AS lixcol_schema_version,
         change_id AS lixcol_change_id,
-        change_set_id AS lixcol_change_set_id,
+        commit_id AS lixcol_commit_id,
+        root_commit_id AS lixcol_root_commit_id,
         depth AS lixcol_depth
       FROM state_history
       WHERE schema_key = '${schema_key}';

package/src/entity-views/entity-state.test.ts

@@ -96,6 +96,7 @@ describe("createEntityViewIfNotExists", () => {
 		expect(entity).toHaveProperty("lixcol_file_id", "test_file");
 		expect(entity).toHaveProperty("lixcol_untracked");
 		expect(entity?.lixcol_untracked).toBe(0); // Default value is false (0)
+		expect(entity).toHaveProperty("lixcol_commit_id");
 	});
 
 	test("should create CRUD triggers", async () => {
@@ -336,7 +337,7 @@ describe("createEntityViewIfNotExists", () => {
 			.execute();
 
 		expect(stateData).toHaveLength(1);
-		expect(stateData[0]?.entity_id).toBe("cat1::id1"); // Composite key joined with ::
+		expect(stateData[0]?.entity_id).toBe("cat1~id1"); // Composite key joined with ~
 
 		// Update with composite key
 		await lix.db
@@ -589,4 +590,143 @@ describe("createEntityViewIfNotExists", () => {
 		expect(onlyTracked).toHaveLength(1);
 		expect(onlyTracked[0]?.id).toBe("tracked_entity");
 	});
+
+	test("should expose lixcol_commit_id for history queries", async () => {
+		const lix = await openLix({});
+
+		// First, store the test schema
+		await lix.db
+			.insertInto("stored_schema")
+			.values({ key: "test_entity", value: testSchema as any })
+			.execute();
+
+		createEntityStateView({
+			lix,
+			schema: testSchema,
+			overrideName: "test_view",
+			pluginKey: "test_plugin",
+			hardcodedFileId: "test_file",
+		});
+
+		// Insert test data through the view (uses active version)
+		await lix.db
+			.insertInto("test_view" as any)
+			.values({
+				id: "test_id",
+				name: "test_name",
+				value: 42,
+			})
+			.execute();
+
+		// Query the view and verify lixcol_commit_id is exposed
+		const result = await lix.db
+			.selectFrom("test_view" as any)
+			.selectAll()
+			.execute();
+
+		expect(result).toHaveLength(1);
+		const entity = result[0];
+
+		// Verify that lixcol_commit_id is exposed
+		expect(entity).toHaveProperty("lixcol_commit_id");
+		// The change_set_id should be populated (either from a change set or 'untracked')
+		expect(entity?.lixcol_commit_id).toBeDefined();
+		expect(typeof entity?.lixcol_commit_id).toBe("string");
+
+		// Verify we can query by lixcol_commit_id
+		const queryByChangeSetId = await lix.db
+			.selectFrom("test_view" as any)
+			.where("lixcol_commit_id", "=", entity?.lixcol_commit_id)
+			.selectAll()
+			.execute();
+
+		expect(queryByChangeSetId).toHaveLength(1);
+		expect(queryByChangeSetId[0]?.id).toBe("test_id");
+	});
+
+	test("should expose lixcol_entity_id, lixcol_schema_key, lixcol_file_id, and lixcol_plugin_key", async () => {
+		const lix = await openLix({});
+
+		createEntityStateView({
+			lix,
+			schema: testSchema,
+			overrideName: "test_view",
+			pluginKey: "test_plugin",
+			hardcodedFileId: "test_file",
+		});
+
+		// Insert test data
+		await lix.db
+			.insertInto("test_view" as any)
+			.values({
+				id: "test_id",
+				name: "test_name",
+				value: 42,
+			})
+			.execute();
+
+		// Query the view to verify all entity identification columns are exposed
+		const result = await lix.db
+			.selectFrom("test_view" as any)
+			.select([
+				"id",
+				"name",
+				"lixcol_entity_id",
+				"lixcol_schema_key",
+				"lixcol_file_id",
+				"lixcol_plugin_key",
+			])
+			.executeTakeFirst();
+
+		expect(result).toBeDefined();
+
+		// Verify all required lixcol_ columns are present and have correct values
+		expect(result?.lixcol_entity_id).toBe("test_id");
+		expect(result?.lixcol_schema_key).toBe("test_entity");
+		expect(result?.lixcol_file_id).toBe("test_file");
+		expect(result?.lixcol_plugin_key).toBe("test_plugin");
+	});
+
+	test("should expose entity identification columns for composite primary keys", async () => {
+		const lix = await openLix({});
+
+		createEntityStateView({
+			lix,
+			schema: compositeKeySchema,
+			overrideName: "composite_view",
+			pluginKey: "test_plugin",
+			hardcodedFileId: "test_file",
+		});
+
+		// Insert data with composite key
+		await lix.db
+			.insertInto("composite_view" as any)
+			.values({
+				category: "cat1",
+				id: "id1",
+				data: "test_data",
+			})
+			.execute();
+
+		// Query to verify lixcol_ columns
+		const result = await lix.db
+			.selectFrom("composite_view" as any)
+			.select([
+				"category",
+				"id",
+				"lixcol_entity_id",
+				"lixcol_schema_key",
+				"lixcol_file_id",
+				"lixcol_plugin_key",
+			])
+			.executeTakeFirst();
+
+		expect(result).toBeDefined();
+
+		// For composite keys, entity_id is joined with ~
+		expect(result?.lixcol_entity_id).toBe("cat1~id1");
+		expect(result?.lixcol_schema_key).toBe("composite_entity");
+		expect(result?.lixcol_file_id).toBe("test_file");
+		expect(result?.lixcol_plugin_key).toBe("test_plugin");
+	});
 });