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

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

@@ -0,0 +1,325 @@
+import { test, expect, describe } from "vitest";
+import { openLix } from "../lix/open-lix.js";
+import { createEntityStateHistoryView } from "./entity-state-history.js";
+import type { LixSchemaDefinition } from "../schema-definition/definition.js";
+
+describe("createEntityHistoryViewIfNotExists", () => {
+	const testSchema: LixSchemaDefinition = {
+		"x-lix-key": "test_entity",
+		"x-lix-version": "1.0",
+		"x-lix-primary-key": ["id"],
+		type: "object",
+		properties: {
+			id: { type: "string" },
+			name: { type: "string" },
+			value: { type: "number" },
+		},
+		required: ["id", "name"],
+		additionalProperties: false,
+	} as const;
+
+	test("should throw error if schema has no primary key", async () => {
+		const lix = await openLix({});
+
+		const invalidSchema: LixSchemaDefinition = {
+			"x-lix-key": "invalid_schema",
+			"x-lix-version": "1.0",
+			type: "object",
+			additionalProperties: false,
+			properties: {
+				name: { type: "string" },
+			},
+		} as const;
+
+		expect(() => {
+			createEntityStateHistoryView({
+				lix,
+				schema: invalidSchema,
+			});
+		}).toThrow(
+			"Schema must define 'x-lix-primary-key' for entity history view generation"
+		);
+	});
+
+	test("should create history view with correct columns", async () => {
+		const lix = await openLix({});
+
+		createEntityStateHistoryView({
+			lix,
+			schema: testSchema,
+			overrideName: "test_entity_history",
+		});
+
+		// Insert some test data into state to create history
+		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 to query history
+		const activeVersion = await lix.db
+			.selectFrom("active_version")
+			.innerJoin("version", "active_version.version_id", "version.id")
+			.select("version.change_set_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)
+			.selectAll()
+			.execute();
+
+		expect(historyResult).toHaveLength(1);
+		const historyEntity = historyResult[0];
+
+		// Business logic columns
+		expect(historyEntity).toHaveProperty("id", "test_id");
+		expect(historyEntity).toHaveProperty("name", "test_name");
+		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_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
+		);
+		expect(historyEntity).toHaveProperty("lixcol_depth", 0);
+	});
+
+	test("should use schema key + _history as default view name", async () => {
+		const lix = await openLix({});
+
+		createEntityStateHistoryView({
+			lix,
+			schema: testSchema,
+			// No overrideName - should use schema["x-lix-key"] + "_history"
+		});
+
+		// 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 to query history
+		const activeVersion = await lix.db
+			.selectFrom("active_version")
+			.innerJoin("version", "active_version.version_id", "version.id")
+			.select("version.change_set_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)
+			.selectAll()
+			.execute();
+
+		expect(result).toHaveLength(1);
+		expect(result[0]).toMatchObject({
+			id: "test_id",
+			name: "test_name",
+			value: 42,
+		});
+	});
+
+	test("should query historical states at different depths", async () => {
+		const lix = await openLix({});
+
+		// Add stored schema first
+		const mockSchema: LixSchemaDefinition = {
+			"x-lix-key": "test_entity",
+			"x-lix-version": "1.0",
+			type: "object",
+			additionalProperties: false,
+			properties: {
+				id: { type: "string" },
+				name: { type: "string" },
+				value: { type: "number" },
+			},
+		};
+
+		await lix.db
+			.insertInto("stored_schema")
+			.values({ value: mockSchema })
+			.execute();
+
+		createEntityStateHistoryView({
+			lix,
+			schema: testSchema,
+			overrideName: "test_history",
+		});
+
+		// Insert initial state
+		await lix.db
+			.insertInto("state_all")
+			.values({
+				entity_id: "tracked_entity",
+				schema_key: "test_entity",
+				file_id: "test_file",
+				plugin_key: "test_plugin",
+				snapshot_content: { id: "tracked_entity", name: "initial", value: 1 },
+				schema_version: "1.0",
+				version_id: lix.db.selectFrom("active_version").select("version_id"),
+			})
+			.execute();
+
+		// Update to create history
+		await lix.db
+			.updateTable("state_all")
+			.set({
+				snapshot_content: { id: "tracked_entity", name: "updated", value: 2 },
+			})
+			.where("entity_id", "=", "tracked_entity")
+			.execute();
+
+		// Update again to create more history
+		await lix.db
+			.updateTable("state_all")
+			.set({
+				snapshot_content: { id: "tracked_entity", name: "final", value: 3 },
+			})
+			.where("entity_id", "=", "tracked_entity")
+			.execute();
+
+		// Get the active version's change set to query history
+		const activeVersion = await lix.db
+			.selectFrom("active_version")
+			.innerJoin("version", "active_version.version_id", "version.id")
+			.select("version.change_set_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)
+			.orderBy("lixcol_depth", "asc")
+			.selectAll()
+			.execute();
+
+		expect(historyResult.length).toBeGreaterThan(0);
+
+		// Current state should be at depth 0
+		const currentState = historyResult.find((h: any) => h.lixcol_depth === 0);
+		expect(currentState).toBeDefined();
+		expect(currentState).toMatchObject({
+			name: "final",
+			value: 3,
+		});
+
+		// Check that different depths exist if there's history
+		if (historyResult.length > 1) {
+			const depthValues = historyResult.map((h: any) => h.lixcol_depth);
+			expect(depthValues).toContain(0); // Current state
+			expect(Math.max(...depthValues)).toBeGreaterThan(0); // At least one historical state
+		}
+	});
+
+	test("should be read-only (no CRUD triggers)", async () => {
+		const lix = await openLix({});
+
+		createEntityStateHistoryView({
+			lix,
+			schema: testSchema,
+			overrideName: "readonly_history",
+		});
+
+		// History views should be read-only, so INSERT/UPDATE/DELETE should fail
+		// This test verifies that no CRUD triggers were created
+
+		// Attempt to insert should fail (no INSERT trigger)
+		await expect(
+			lix.db
+				.insertInto("readonly_history" as any)
+				.values({
+					id: "test_id",
+					name: "test_name",
+					value: 42,
+				})
+				.execute()
+		).rejects.toThrow();
+
+		// Insert some data directly into state for testing UPDATE/DELETE
+		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.change_set_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)
+			.selectAll()
+			.execute();
+
+		expect(readResult).toHaveLength(1);
+
+		// Attempt to update should fail (no UPDATE trigger)
+		await expect(
+			lix.db
+				.updateTable("readonly_history" as any)
+				.where("entity_id", "=", "test_id")
+				.set({ name: "updated_name" })
+				.execute()
+		).rejects.toThrow();
+
+		// Attempt to delete should fail (no DELETE trigger)
+		await expect(
+			lix.db
+				.deleteFrom("readonly_history" as any)
+				.where("entity_id", "=", "test_id")
+				.execute()
+		).rejects.toThrow();
+	});
+});

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

@@ -0,0 +1,226 @@
+import type { Generated } from "kysely";
+import type { Lix } from "../lix/open-lix.js";
+import type {
+	LixGenerated,
+	LixSchemaDefinition,
+} from "../schema-definition/definition.js";
+
+/**
+ * Base type for entity history views that include historical data from the state_history table.
+ * These views provide access to entity states at different points in change set history,
+ * enabling features like blame functionality and historical diffs.
+ *
+ * History views are read-only and show how entities evolved over time through changes.
+ *
+ * @example
+ * ```typescript
+ * // Define an entity history view type
+ * export type AccountHistoryView = {
+ *   id: Generated<string>;
+ *   name: string;
+ * } & StateEntityHistoryView;
+ *
+ * // Query entity history at a specific change set
+ * 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
+ *   .selectAll()
+ *   .execute();
+ * ```
+ */
+export type StateEntityHistoryView = {
+	/**
+	 * File identifier where this entity is stored.
+	 *
+	 * This references the file_id in the state_history table and links the entity
+	 * to a specific file in the Lix file system.
+	 */
+	lixcol_file_id: Generated<string>;
+
+	/**
+	 * Plugin identifier that manages this entity type.
+	 *
+	 * This identifies which plugin is responsible for this entity's behavior
+	 * and schema definition.
+	 */
+	lixcol_plugin_key: Generated<string>;
+
+	/**
+	 * Version of the schema used for this entity at this point in history.
+	 *
+	 * Format: "major.minor" (e.g., "1.0", "2.1")
+	 * This allows tracking schema evolution over time.
+	 */
+	lixcol_schema_version: Generated<string>;
+
+	/**
+	 * ID of the change that created this specific entity state.
+	 *
+	 * Each modification to an entity creates a new change, and this ID
+	 * references that specific change in the change table.
+	 */
+	lixcol_change_id: Generated<string>;
+
+	/**
+	 * Change set 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.
+	 */
+	lixcol_change_set_id: Generated<string>;
+
+	/**
+	 * Depth of this entity state relative to the queried change_set_id.
+	 *
+	 * - `0`: The entity state at the exact queried change set
+	 * - `1`: The entity state one change before the queried change set
+	 * - `2+`: Earlier states, going back in history
+	 *
+	 * This is useful for blame functionality and understanding how an entity
+	 * evolved to reach its current state.
+	 */
+	lixcol_depth: Generated<number>;
+};
+
+/**
+ * Base type for entity history views using LixGenerated markers instead of Kysely's Generated type.
+ * This type is compatible with the Lix SDK's type transformation system and provides
+ * access to historical entity states.
+ *
+ * History views are read-only and show how entities evolved over time through changes.
+ *
+ * @example
+ * ```typescript
+ * // Define an entity history type
+ * export type AccountHistory = {
+ *   id: string;  // No LixGenerated marker in history views
+ *   name: string;
+ * } & StateEntityHistoryColumns;
+ * ```
+ */
+export type StateEntityHistoryColumns = {
+	/**
+	 * File identifier where this entity is stored.
+	 *
+	 * This references the file_id in the state_history table and links the entity
+	 * to a specific file in the Lix file system.
+	 */
+	lixcol_file_id: LixGenerated<string>;
+
+	/**
+	 * Plugin identifier that manages this entity type.
+	 *
+	 * This identifies which plugin is responsible for this entity's behavior
+	 * and schema definition.
+	 */
+	lixcol_plugin_key: LixGenerated<string>;
+
+	/**
+	 * Version of the schema used for this entity at this point in history.
+	 *
+	 * Format: "major.minor" (e.g., "1.0", "2.1")
+	 * This allows tracking schema evolution over time.
+	 */
+	lixcol_schema_version: LixGenerated<string>;
+
+	/**
+	 * ID of the change that created this specific entity state.
+	 *
+	 * Each modification to an entity creates a new change, and this ID
+	 * references that specific change in the change table.
+	 */
+	lixcol_change_id: LixGenerated<string>;
+
+	/**
+	 * Change set 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.
+	 */
+	lixcol_change_set_id: LixGenerated<string>;
+
+	/**
+	 * Depth of this entity state relative to the queried change_set_id.
+	 *
+	 * - `0`: The entity state at the exact queried change set
+	 * - `1`: The entity state one change before the queried change set
+	 * - `2+`: Earlier states, going back in history
+	 *
+	 * This is useful for blame functionality and understanding how an entity
+	 * evolved to reach its current state.
+	 */
+	lixcol_depth: LixGenerated<number>;
+};
+
+/**
+ * Creates SQL view for entity history based on its schema definition.
+ *
+ * This function generates a read-only view that extracts JSON properties from the state_history table,
+ * providing access to historical entity states at different points in change set history.
+ *
+ * The view supports:
+ * - Querying entity states at specific change sets
+ * - Traversing entity history by depth (blame functionality)
+ * - Filtering by change set ancestry relationships
+ *
+ * @throws Error if schema type is not "object" or x-lix-primary-key is not defined
+ *
+ * @example
+ * ```typescript
+ * // Basic usage for key-value entities
+ * createEntityHistoryViewIfNotExists({
+ *   lix,
+ *   schema: LixKeyValueSchema,
+ *   overrideName: "key_value_history",
+ * });
+ *
+ * // Usage for account entities
+ * createEntityHistoryViewIfNotExists({
+ *   lix,
+ *   schema: LixAccountSchema,
+ *   overrideName: "account_history",
+ * });
+ * ```
+ */
+export function createEntityStateHistoryView(args: {
+	lix: Pick<Lix, "sqlite">;
+	schema: LixSchemaDefinition;
+	/** Overrides the view name which defaults to schema["x-lix-key"] + "_history" */
+	overrideName?: string;
+}): void {
+	if (!args.schema["x-lix-primary-key"]) {
+		throw new Error(
+			`Schema must define 'x-lix-primary-key' for entity history view generation`
+		);
+	}
+
+	const view_name = args.overrideName ?? args.schema["x-lix-key"] + "_history";
+	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
+      SELECT
+        ${properties
+					.map(
+						(prop) => `json_extract(snapshot_content, '$.${prop}') AS ${prop}`
+					)
+					.join(",\n        ")},
+        entity_id,
+        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,
+        depth AS lixcol_depth
+      FROM state_history
+      WHERE schema_key = '${schema_key}';
+    `;
+
+	args.lix.sqlite.exec(sqlQuery);
+}