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

package/src/state/cache/mark-state-cache-as-stale.ts

@@ -0,0 +1,53 @@
+import type { Lix } from "../../lix/open-lix.js";
+import { LixKeyValueSchema } from "../../key-value/schema.js";
+import { timestamp } from "../../deterministic/timestamp.js";
+import { updateUntrackedState } from "../untracked/update-untracked-state.js";
+
+const CACHE_STALE_KEY = "lix_state_cache_stale";
+
+export function markStateCacheAsStale(args: {
+	lix: Pick<Lix, "sqlite" | "db">;
+	timestamp?: string;
+}): void {
+	// Set the cache stale flag to "true" in untracked state
+	const snapshotContent = JSON.stringify({ key: CACHE_STALE_KEY, value: true });
+
+	updateUntrackedState({
+		lix: args.lix,
+		change: {
+			entity_id: CACHE_STALE_KEY,
+			schema_key: LixKeyValueSchema["x-lix-key"],
+			file_id: "lix",
+			plugin_key: "lix_own_entity",
+			snapshot_content: snapshotContent,
+			schema_version: LixKeyValueSchema["x-lix-version"],
+			created_at: args.timestamp ?? timestamp({ lix: args.lix }),
+		},
+		version_id: "global",
+	});
+}
+
+export function markStateCacheAsFresh(args: {
+	lix: Pick<Lix, "sqlite" | "db">;
+	timestamp?: string;
+}): void {
+	// Set the cache stale flag to "false" in untracked state
+	const snapshotContent = JSON.stringify({
+		key: CACHE_STALE_KEY,
+		value: false,
+	});
+
+	updateUntrackedState({
+		lix: args.lix,
+		change: {
+			entity_id: CACHE_STALE_KEY,
+			schema_key: LixKeyValueSchema["x-lix-key"],
+			file_id: "lix",
+			plugin_key: "lix_own_entity",
+			snapshot_content: snapshotContent,
+			schema_version: LixKeyValueSchema["x-lix-version"],
+			created_at: args.timestamp ?? timestamp({ lix: args.lix }),
+		},
+		version_id: "global",
+	});
+}

package/src/state/cache/populate-state-cache.test.ts

@@ -0,0 +1,259 @@
+import { test, expect } from "vitest";
+import { openLix } from "../../lix/open-lix.js";
+import { populateStateCache } from "./populate-state-cache.js";
+import { clearStateCache } from "./clear-state-cache.js";
+import type { Kysely } from "kysely";
+import type { LixInternalDatabaseSchema } from "../../database/schema.js";
+import { createVersion } from "../../version/create-version.js";
+
+test("should populate cache for a specific version_id", async () => {
+	// Test that populateStateCache({ version_id: "global" }) populates only global version
+	const lix = await openLix({
+		keyValues: [
+			{
+				key: "lix_deterministic_mode",
+				value: { enabled: true, bootstrap: true },
+			},
+		],
+	});
+
+	// Add some test data to the global version
+	await lix.db
+		.insertInto("key_value_all")
+		.values({
+			key: "test-key",
+			value: "test-value",
+			lixcol_version_id: "global",
+		})
+		.execute();
+
+	// Clear any existing cache
+	clearStateCache({ lix });
+
+	// Populate cache for global version only
+	populateStateCache(lix.sqlite, { version_id: "global" });
+
+	// Query cache directly for our test entity using Kysely
+	const cacheEntry = await (
+		lix.db as unknown as Kysely<LixInternalDatabaseSchema>
+	)
+		.selectFrom("internal_state_cache")
+		.selectAll()
+		.where("entity_id", "=", "test-key")
+		.where("schema_key", "=", "lix_key_value")
+		.execute();
+
+	expect(cacheEntry).toHaveLength(1);
+
+	// Should find our test data in the cache
+	expect(cacheEntry[0]?.entity_id).toBe("test-key");
+	expect(cacheEntry[0]?.version_id).toBe("global");
+	expect(cacheEntry[0]?.schema_key).toBe("lix_key_value");
+
+	// Verify the snapshot content contains our data
+	const snapshot = cacheEntry[0]!.snapshot_content! as any;
+	expect(snapshot.key).toBe("test-key");
+	expect(snapshot.value).toBe("test-value");
+});
+
+test("should filter by entity_id when provided", async () => {
+	// Test that populateStateCache({ version_id: "global", entity_id: "specific-entity" })
+	// only populates cache entries for that specific entity
+});
+
+test("should filter by schema_key when provided", async () => {
+	// Test that populateStateCache({ version_id: "global", schema_key: "lix_version" })
+	// only populates cache entries for that specific schema
+});
+
+test("should filter by file_id when provided", async () => {
+	// Test that populateStateCache({ version_id: "global", file_id: "lix" })
+	// only populates cache entries for that specific file
+});
+
+test("should combine multiple filters correctly", async () => {
+	// Test that populateStateCache({ version_id: "global", entity_id: "x", schema_key: "y" })
+	// applies all filters together with AND logic
+});
+
+test("should delete existing cache entries before populating", async () => {
+	// Test that existing cache entries matching the filters are cleared before new ones are inserted
+	// This prevents duplicates
+});
+
+test("should handle empty materialization results gracefully", async () => {
+	// Test behavior when the materializer returns no results for the given filters
+	// Should clear matching cache entries but not error
+});
+
+test("should populate cache with correct inheritance relationships", async () => {
+	// Test that inherited state is correctly populated with proper inherited_from_version_id values
+	// Verify that inheritance_delete_marker is set to 0 (from materializer)
+});
+
+test("should handle version that doesn't exist in materializer", async () => {
+	// Test behavior when requesting a version_id that has no materialized state
+	// Should clear cache entries for that version but not error
+});
+
+test("should populate cache with all required columns", async () => {
+	// Test that all expected columns are populated correctly:
+	// entity_id, schema_key, file_id, version_id, plugin_key, snapshot_content,
+	// schema_version, created_at, updated_at, inherited_from_version_id,
+	// inheritance_delete_marker, change_id, commit_id
+});
+
+test("should implement copy-on-write semantics by only caching direct entries", async () => {
+	const lix = await openLix({
+		keyValues: [
+			{
+				key: "lix_deterministic_mode",
+				value: { enabled: true, bootstrap: true },
+			},
+		],
+	});
+
+	// Add some test data to global version
+	await lix.db
+		.insertInto("key_value")
+		.values({
+			key: "test-key",
+			value: "test-value",
+		})
+		.execute();
+
+	// Clear any existing cache
+	clearStateCache({ lix });
+
+	// Populate cache - should only copy direct entries (copy-on-write)
+	populateStateCache(lix.sqlite);
+
+	// Note: We don't check materializer entries here since internal_state_materializer
+	// is not part of the public schema, but we verify cache behavior
+
+	// Check what's in the cache - should only have direct entries
+	const cacheEntries = await (
+		lix.db as unknown as Kysely<LixInternalDatabaseSchema>
+	)
+		.selectFrom("internal_state_cache")
+		.selectAll()
+		.where("entity_id", "=", "test-key")
+		.where("schema_key", "=", "lix_key_value")
+		.execute();
+
+	// Cache should only contain direct entries (inherited_from_version_id IS NULL)
+	expect(cacheEntries).toHaveLength(1);
+	expect(cacheEntries[0]?.inherited_from_version_id).toBeNull();
+
+	// Populate cache multiple times - should not create duplicates due to DELETE before INSERT
+	populateStateCache(lix.sqlite);
+	populateStateCache(lix.sqlite);
+
+	const cacheEntriesAfterMultiplePopulate = await (
+		lix.db as unknown as Kysely<LixInternalDatabaseSchema>
+	)
+		.selectFrom("internal_state_cache")
+		.selectAll()
+		.where("entity_id", "=", "test-key")
+		.where("schema_key", "=", "lix_key_value")
+		.execute();
+
+	// Should still have exactly one entry (no duplicates)
+	expect(cacheEntriesAfterMultiplePopulate).toHaveLength(1);
+
+	// Verify copy-on-write: check that all cache entries have inherited_from_version_id = null
+	const allCacheEntries = await (
+		lix.db as unknown as Kysely<LixInternalDatabaseSchema>
+	)
+		.selectFrom("internal_state_cache")
+		.selectAll()
+		.execute();
+
+	for (const entry of allCacheEntries) {
+		expect(entry.inherited_from_version_id).toBeNull();
+	}
+});
+
+test("should cache tombstones (delete markers) when they are direct entries", async () => {
+	const lix = await openLix({
+		keyValues: [
+			{
+				key: "lix_deterministic_mode",
+				value: { enabled: true, bootstrap: true },
+			},
+		],
+	});
+
+	// First, create an entity in the global version
+	await lix.db
+		.insertInto("key_value_all")
+		.values({
+			key: "to-be-deleted",
+			value: "original-value",
+			lixcol_version_id: "global",
+		})
+		.execute();
+
+	await createVersion({
+		lix: lix,
+		id: "feature-version",
+	});
+
+	// Create a delete marker (tombstone) in the feature version
+	await lix.db
+		.deleteFrom("key_value_all")
+		.where("key", "=", "to-be-deleted")
+		.where("lixcol_version_id", "=", "feature-version")
+		.execute();
+
+	// Clear cache and populate for the feature version
+	clearStateCache({ lix });
+
+	populateStateCache(lix.sqlite, { version_id: "feature-version" });
+
+	// Check cache entries for the deleted entity in feature version
+	const cacheEntries = await (
+		lix.db as unknown as Kysely<LixInternalDatabaseSchema>
+	)
+		.selectFrom("internal_state_cache")
+		.selectAll()
+		.where("entity_id", "=", "to-be-deleted")
+		.where("schema_key", "=", "lix_key_value")
+		.where("version_id", "=", "feature-version")
+		.execute();
+
+	// Should have a cache entry for the tombstone since it's a direct entry in feature-version
+	expect(cacheEntries).toHaveLength(1);
+	expect(cacheEntries[0]?.inherited_from_version_id).toBeNull();
+	expect(cacheEntries[0]?.version_id).toBe("feature-version");
+
+	// The snapshot content should be null for tombstones
+	expect(cacheEntries[0]?.snapshot_content).toBeNull();
+
+	// Check resolved state for global version - should have the entity
+	const globalResolvedState = await lix.db
+		.selectFrom("state_all")
+		.selectAll()
+		.where("entity_id", "=", "to-be-deleted")
+		.where("schema_key", "=", "lix_key_value")
+		.where("version_id", "=", "global")
+		.execute();
+
+	expect(globalResolvedState).toHaveLength(1);
+	expect((globalResolvedState[0]?.snapshot_content as any)?.value).toBe(
+		"original-value"
+	);
+
+	// Check resolved state for feature-version - should NOT have the entity (it's deleted)
+	const featureResolvedState = await lix.db
+		.selectFrom("state_all")
+		.selectAll()
+		.where("entity_id", "=", "to-be-deleted")
+		.where("schema_key", "=", "lix_key_value")
+		.where("version_id", "=", "feature-version")
+		.execute();
+
+	// The resolved state should NOT include tombstones - they should be filtered out
+	// Only the cache should include tombstones for proper deletion handling
+	expect(featureResolvedState).toHaveLength(0);
+});

package/src/state/cache/populate-state-cache.ts

@@ -0,0 +1,124 @@
+import type { SqliteWasmDatabase } from "sqlite-wasm-kysely";
+
+export interface PopulateStateCacheOptions {
+	version_id?: string; // Optional - if not provided, all active versions are populated
+	entity_id?: string; // Optional
+	schema_key?: string; // Optional
+	file_id?: string; // Optional
+}
+
+export function populateStateCache(
+	sqlite: SqliteWasmDatabase,
+	options: PopulateStateCacheOptions = {}
+): void {
+	// Build WHERE clause based on options
+	const whereConditions: string[] = [];
+	const bindParams: any[] = [];
+
+	if (options.version_id) {
+		whereConditions.push("m.version_id = ?");
+		bindParams.push(options.version_id);
+	} else {
+		// If no version_id specified, only populate active versions (with tips)
+		whereConditions.push(`EXISTS (
+			SELECT 1 FROM internal_materialization_version_tips vt
+			WHERE vt.version_id = m.version_id
+		)`);
+	}
+
+	if (options.entity_id) {
+		whereConditions.push("m.entity_id = ?");
+		bindParams.push(options.entity_id);
+	}
+	if (options.schema_key) {
+		whereConditions.push("m.schema_key = ?");
+		bindParams.push(options.schema_key);
+	}
+	if (options.file_id) {
+		whereConditions.push("m.file_id = ?");
+		bindParams.push(options.file_id);
+	}
+
+	// Delete existing cache entries that match the criteria
+	if (
+		options.version_id ||
+		options.entity_id ||
+		options.schema_key ||
+		options.file_id
+	) {
+		// Build delete conditions - only for specific filters, not for the EXISTS clause
+		const deleteConditions: string[] = [];
+		const deleteParams: any[] = [];
+
+		if (options.version_id) {
+			deleteConditions.push("version_id = ?");
+			deleteParams.push(options.version_id);
+		}
+		if (options.entity_id) {
+			deleteConditions.push("entity_id = ?");
+			deleteParams.push(options.entity_id);
+		}
+		if (options.schema_key) {
+			deleteConditions.push("schema_key = ?");
+			deleteParams.push(options.schema_key);
+		}
+		if (options.file_id) {
+			deleteConditions.push("file_id = ?");
+			deleteParams.push(options.file_id);
+		}
+
+		if (deleteConditions.length > 0) {
+			sqlite.exec({
+				sql: `DELETE FROM internal_state_cache WHERE ${deleteConditions.join(" AND ")}`,
+				bind: deleteParams,
+			});
+		}
+	} else {
+		// No specific filters - clear entire cache (populate all active versions)
+		sqlite.exec(`DELETE FROM internal_state_cache`);
+	}
+
+	// Populate cache from the materializer view for the specified version
+	// IMPORTANT: Only copy direct entries (inherited_from_version_id IS NULL)
+	// Inherited state should not be stored in the cache - inheritance is handled
+	// by the resolved state view at query time
+	const insertSql = `
+		INSERT INTO internal_state_cache (
+			entity_id,
+			schema_key,
+			file_id,
+			version_id,
+			plugin_key,
+			snapshot_content,
+			schema_version,
+			created_at,
+			updated_at,
+			inherited_from_version_id,
+			inheritance_delete_marker,
+			change_id,
+			commit_id
+		)
+		SELECT 
+			m.entity_id,
+			m.schema_key,
+			m.file_id,
+			m.version_id,
+			m.plugin_key,
+			m.snapshot_content,
+			m.schema_version,
+			m.created_at,
+			m.updated_at,
+			m.inherited_from_version_id,
+			0 as inheritance_delete_marker, -- No deletion markers from materializer
+			m.change_id,
+			m.commit_id
+		FROM internal_state_materializer m
+		WHERE ${whereConditions.join(" AND ")}
+		  AND m.inherited_from_version_id IS NULL  -- Only direct entries, no inherited state
+	`;
+
+	sqlite.exec({
+		sql: insertSql,
+		bind: bindParams,
+	});
+}

package/src/state/cache/schema.ts

@@ -0,0 +1,41 @@
+import type { Selectable } from "kysely";
+import type { Lix } from "../../lix/open-lix.js";
+
+export function applyStateCacheSchema(lix: Pick<Lix, "sqlite">): void {
+	lix.sqlite.exec(`
+    CREATE TABLE IF NOT EXISTS internal_state_cache (
+    entity_id TEXT NOT NULL,
+    schema_key TEXT NOT NULL,
+    file_id TEXT NOT NULL,
+    version_id TEXT NOT NULL,
+    plugin_key TEXT NOT NULL,
+    snapshot_content TEXT, -- Allow NULL for deletions
+    schema_version TEXT NOT NULL,
+    created_at TEXT NOT NULL,
+    updated_at TEXT NOT NULL,
+    inherited_from_version_id TEXT,
+    inheritance_delete_marker INTEGER DEFAULT 0, -- Flag for copy-on-write deletion markers
+    change_id TEXT,
+    commit_id TEXT, -- Allow NULL until commit is created
+    PRIMARY KEY (entity_id, schema_key, file_id, version_id)
+  ) strict;
+`);
+}
+
+export type InternalStateCacheRow = Selectable<InternalStateCacheTable>;
+
+export type InternalStateCacheTable = {
+	entity_id: string;
+	schema_key: string;
+	file_id: string;
+	version_id: string;
+	plugin_key: string;
+	snapshot_content: string | null; // JSON string, NULL for deletions
+	schema_version: string;
+	created_at: string;
+	updated_at: string;
+	inherited_from_version_id: string | null;
+	inheritance_delete_marker: number; // 1 for copy-on-write deletion markers, 0 otherwise
+	change_id: string;
+	commit_id: string | null;
+};