@lix-js/sdk 0.5.1 → 0.6.0-preview.0

package/src/state/cache-v2/create-schema-cache-table.test.ts

@@ -1,96 +0,0 @@
-import { test, expect } from "vitest";
-import { openLix } from "../../lix/open-lix.js";
-import {
-	createSchemaCacheTableV2,
-	schemaKeyToCacheTableNameV2,
-} from "./create-schema-cache-table.js";
-import { CACHE_COLUMNS } from "./cache-columns.js";
-import type { LixSchemaDefinition } from "../../schema-definition/definition.js";
-
-const exampleSchema: LixSchemaDefinition = {
-	$schema: "http://json-schema.org/draft-07/schema#",
-	type: "object",
-	additionalProperties: false,
-	properties: {
-		id: { type: "string" },
-		name: { type: "string" },
-		count: { type: "integer" },
-	},
-	"x-lix-key": "lix_test_create",
-	"x-lix-version": "1.0",
-	"x-lix-primary-key": ["/id"],
-};
-
-test("createSchemaCacheTableV2 creates table with core indexes and is idempotent", async () => {
-	const lix = await openLix({});
-
-	const tableName = schemaKeyToCacheTableNameV2("lix_test_create", "1.0");
-
-	// First call should create the table and indexes
-	createSchemaCacheTableV2({
-		engine: lix.engine!,
-		schema: exampleSchema,
-		tableName,
-	});
-
-	// Verify table exists and WITHOUT ROWID
-	const tbl = lix.engine!.sqlite.exec({
-		sql: `SELECT name, sql FROM sqlite_schema WHERE type='table' AND name = ?`,
-		bind: [tableName],
-		returnValue: "resultRows",
-		rowMode: "object",
-	}) as any[];
-
-	expect(tbl?.[0]?.name).toBe(tableName);
-	expect(String(tbl?.[0]?.sql || "")).toMatch(/WITHOUT ROWID/);
-
-	// Verify core indexes exist
-	const idxRows = lix.engine!.sqlite.exec({
-		sql: `SELECT name, sql FROM sqlite_schema WHERE type='index' AND tbl_name = ? ORDER BY name`,
-		bind: [tableName],
-		returnValue: "resultRows",
-		rowMode: "object",
-	}) as { name: string; sql: string }[];
-
-	const names = new Set(idxRows.map((r) => r.name));
-	expect(Array.from(names)).toEqual(
-		expect.arrayContaining([
-			`idx_${tableName}_version_id`,
-			`idx_${tableName}_vfe`,
-			`idx_${tableName}_fv`,
-		])
-	);
-
-	// Second call should be a no-op (idempotent)
-	createSchemaCacheTableV2({
-		engine: lix.engine!,
-		schema: exampleSchema,
-		tableName,
-	});
-
-	// Property columns are created for schema properties
-	const columns = lix.engine!.sqlite.exec({
-		sql: `SELECT name FROM pragma_table_info('${tableName}')`,
-		returnValue: "resultRows",
-	}) as Array<[string]>;
-	const columnNames = new Set(columns.map((row) => row[0]));
-
-	for (const core of CACHE_COLUMNS) {
-		expect(columnNames.has(core)).toBe(true);
-	}
-	for (const propertyColumn of ["x_id", "x_name", "x_count"]) {
-		expect(columnNames.has(propertyColumn)).toBe(true);
-	}
-
-	const idxRows2 = lix.engine!.sqlite.exec({
-		sql: `SELECT name FROM sqlite_schema WHERE type='index' AND tbl_name = ?`,
-		bind: [tableName],
-		returnValue: "resultRows",
-	}) as string[][];
-
-	// Still contains the same three core indexes (no duplicates)
-	const idxCount = idxRows2.filter((r) =>
-		String(r?.[0] || "").startsWith(`idx_${tableName}_`)
-	).length;
-	expect(idxCount).toBeGreaterThanOrEqual(3);
-});

package/src/state/cache-v2/create-schema-cache-table.ts

@@ -1,205 +0,0 @@
-import type { LixEngine } from "../../engine/boot.js";
-import type { LixSchemaDefinition } from "../../schema-definition/definition.js";
-import {
-	extractPropertySchema,
-	mapSchemaPropertyToSqliteType,
-} from "./sqlite-type-mapper.js";
-
-/**
- * Creates (or updates) a per-schema internal state cache table with core indexes.
- * Idempotent: safe to call multiple times and on existing tables.
- *
- * Core choices:
- * - STRICT + WITHOUT ROWID for compact storage and fast PK lookups
- * - Metadata columns reuse the canonical state column names (`entity_id`, `version_id`, ...)
- * - Property columns are created using sanitized schema property names prefixed with `x_`
- * - Indexes continue to accelerate hot access patterns (version/file scans, tombstones)
- *
- * @example
- * createSchemaCacheTableV2({
- *   engine,
- *   schema,
- *   tableName: schemaKeyToCacheTableNameV2("lix.commit", "1.0")
- * });
- */
-export function createSchemaCacheTableV2(args: {
-	engine: Pick<LixEngine, "executeSync">;
-	schema: LixSchemaDefinition | null | undefined;
-	tableName: string;
-}): void {
-	const { engine, tableName, schema } = args;
-
-	if (!schema) {
-		throw new Error(
-			"createSchemaCacheTableV2: schema definition is required for cache table creation."
-		);
-	}
-
-	const existingInfo = engine.executeSync({
-		sql: `PRAGMA table_info(${tableName})`,
-	}).rows as Array<{ name: string }> | undefined;
-
-	if (existingInfo && existingInfo.length > 0) {
-		const hasNormalizedColumns = existingInfo.some(
-			(column) => column?.name === "entity_id"
-		);
-		if (!hasNormalizedColumns) {
-			engine.executeSync({ sql: `DROP TABLE ${tableName}` });
-		}
-	}
-
-	const propertyColumns = extractPropertyColumns(schema);
-	const propertyColumnSql =
-		propertyColumns.length > 0
-			? `${propertyColumns
-					.map(
-						(column) =>
-							`${column.column} ${mapSchemaPropertyToSqliteType(column.definition)}`
-					)
-					.join(",\n      ")},\n      `
-			: "";
-
-	const createTableSql = `
-    CREATE TABLE IF NOT EXISTS ${tableName} (
-      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,
-      schema_version TEXT NOT NULL,
-      created_at TEXT NOT NULL,
-      updated_at TEXT NOT NULL,
-      inherited_from_version_id TEXT,
-      is_tombstone INTEGER DEFAULT 0,
-      change_id TEXT,
-      commit_id TEXT,
-      ${propertyColumnSql}PRIMARY KEY (entity_id, file_id, version_id)
-    ) STRICT, WITHOUT ROWID;
-  `;
-
-	engine.executeSync({ sql: createTableSql });
-
-	// Core static indexes for common access patterns
-	// 1) Fast version-scoped lookups (frequent)
-	engine.executeSync({
-		sql: `CREATE INDEX IF NOT EXISTS idx_${tableName}_version_id ON ${tableName} (version_id)`,
-	});
-
-	// 2) Fast lookups by (version_id, file_id, entity_id) – complements PK order
-	engine.executeSync({
-		sql: `CREATE INDEX IF NOT EXISTS idx_${tableName}_vfe ON ${tableName} (version_id, file_id, entity_id)`,
-	});
-
-	// 3) Fast scans by file within a version
-	engine.executeSync({
-		sql: `CREATE INDEX IF NOT EXISTS idx_${tableName}_fv ON ${tableName} (file_id, version_id)`,
-	});
-
-	// 4) Partial index for live rows only to skip tombstones when applying predicates
-	engine.executeSync({
-		sql: `CREATE INDEX IF NOT EXISTS idx_${tableName}_live_vfe
-			ON ${tableName} (version_id, file_id, entity_id)
-			WHERE is_tombstone = 0`,
-	});
-
-	// 5) Partial index for tombstones when they are queried explicitly
-	engine.executeSync({
-		sql: `CREATE INDEX IF NOT EXISTS idx_${tableName}_tomb_vfe
-			ON ${tableName} (version_id, file_id, entity_id)
-			WHERE is_tombstone = 1`,
-	});
-
-	// Update planner stats
-	engine.executeSync({ sql: `ANALYZE ${tableName}` });
-}
-
-/**
- * Utility to sanitize a schema_key for use in a physical cache table name.
- *
- * @example
- * const tableName = schemaKeyToCacheTableNameV2("lix.commit", "1.0");
- */
-export function schemaKeyToCacheTableNameV2(
-	schema_key: string,
-	schema_version: string
-): string {
-	const sanitizedKey = sanitizeIdentifier(schema_key);
-	const versionSuffix = formatSchemaVersion(schema_version);
-	return `lix_internal_state_cache_v2_${sanitizedKey}_${versionSuffix}`;
-}
-
-type PropertyColumn = {
-	column: string;
-	definition: Record<string, unknown> | undefined;
-};
-
-function extractPropertyColumns(
-	schema: LixSchemaDefinition | null | undefined
-): PropertyColumn[] {
-	if (!schema || typeof schema !== "object") return [];
-	const properties = schema.properties;
-	if (!properties || typeof properties !== "object") {
-		return [];
-	}
-	const columns: PropertyColumn[] = [];
-	for (const key of Object.keys(properties)) {
-		columns.push({
-			column: propertyNameToColumn(key),
-			definition: extractPropertySchema(schema, key),
-		});
-	}
-	return columns;
-}
-
-export function propertyNameToColumn(property: string): string {
-	const base = sanitizeIdentifier(property);
-	const normalized = /^[0-9]/.test(base) ? `_${base}` : base;
-	return `x_${normalized}`;
-}
-
-export function sanitizeIdentifier(value: string): string {
-	const sanitized = value.replace(/[^a-zA-Z0-9]/g, "_");
-	return sanitized.length === 0 ? "value" : sanitized;
-}
-
-/**
- * Returns schema property column names in insertion order.
- *
- * @example
- * const columns = getSchemaPropertyColumnNames(schema);
- */
-export function getSchemaPropertyColumnNames(
-	schema: LixSchemaDefinition | null | undefined
-): string[] {
-	return extractPropertyColumns(schema).map((column) => column.column);
-}
-
-/**
- * Resolves the x-lix-version string from a schema.
- *
- * @example
- * const version = getSchemaVersion(schema); // "1.0"
- */
-export function getSchemaVersion(
-	schema: LixSchemaDefinition | null | undefined
-): string {
-	const rawVersion = (schema as Record<string, unknown> | null | undefined)?.[
-		"x-lix-version"
-	];
-	if (typeof rawVersion === "string" && rawVersion.trim().length > 0) {
-		return rawVersion;
-	}
-	throw new Error(
-		"createSchemaCacheTableV2: schema version (x-lix-version) is required."
-	);
-}
-
-function formatSchemaVersion(schemaVersion: string): string {
-	const trimmed = schemaVersion.trim();
-	const match = /^(\d+)\.(\d+)$/.exec(trimmed);
-	if (match) {
-		return `v${match[1]}_${match[2]}`;
-	}
-	const sanitized = sanitizeIdentifier(trimmed);
-	return sanitized.startsWith("v") ? sanitized : `v${sanitized}`;
-}

package/src/state/cache-v2/is-stale-state-cache.test.ts

@@ -1,39 +0,0 @@
-import { test, expect } from "vitest";
-import { isStaleStateCacheV2 } from "./is-stale-state-cache.js";
-import { clearStateCacheV2 } from "./clear-state-cache.js";
-import {
-	markStateCacheAsFreshV2,
-	markStateCacheAsStaleV2,
-} from "./mark-state-cache-as-stale.js";
-import { openLix } from "../../lix/open-lix.js";
-
-test("cache v2 is stale after cache clear", async () => {
-	const lix = await openLix({});
-
-	// Start with a known fresh flag and warm the cached value
-	markStateCacheAsStaleV2({ engine: lix.engine! });
-	markStateCacheAsFreshV2({ engine: lix.engine! });
-	await Promise.resolve();
-	expect(isStaleStateCacheV2({ engine: lix.engine! })).toBe(false);
-
-	// Clearing should flip the flag back to stale and invalidate the memoized result
-	clearStateCacheV2({ engine: lix.engine! });
-	await Promise.resolve();
-	expect(isStaleStateCacheV2({ engine: lix.engine! })).toBe(true);
-});
-
-test("cached stale flag invalidates when the key toggles", async () => {
-	const lix = await openLix({});
-
-	markStateCacheAsStaleV2({ engine: lix.engine! });
-	await Promise.resolve();
-	expect(isStaleStateCacheV2({ engine: lix.engine! })).toBe(true);
-
-	markStateCacheAsFreshV2({ engine: lix.engine! });
-	await Promise.resolve();
-	expect(isStaleStateCacheV2({ engine: lix.engine! })).toBe(false);
-
-	markStateCacheAsStaleV2({ engine: lix.engine! });
-	await Promise.resolve();
-	expect(isStaleStateCacheV2({ engine: lix.engine! })).toBe(true);
-});

package/src/state/cache-v2/is-stale-state-cache.ts

@@ -1,86 +0,0 @@
-import { sql } from "kysely";
-import type { LixEngine } from "../../engine/boot.js";
-import { internalQueryBuilder } from "../../engine/internal-query-builder.js";
-
-const CACHE_STALE_KEY = "lix_state_cache_stale";
-const CACHE_SCHEMA_KEY = "lix_key_value";
-
-const staleStateCache = new WeakMap<any, boolean>();
-const hookListeners = new WeakSet<object>();
-
-/**
- * Memoize the stale flag for a given SQLite connection.
- */
-export function setStaleStateCacheMemoV2(args: {
-	engine: Pick<LixEngine, "executeSync">;
-	value: boolean;
-}): void {
-	staleStateCache.set(args.engine.executeSync, args.value);
-}
-
-/**
- * Remove the cached stale flag so the next read re-queries SQLite.
- */
-export function invalidateStaleStateCacheMemoV2(args: {
-	engine: Pick<LixEngine, "executeSync">;
-}): void {
-	staleStateCache.delete(args.engine.executeSync);
-}
-
-function readStaleFlag(engine: Pick<LixEngine, "executeSync">): boolean {
-	const res = engine.executeSync(
-		internalQueryBuilder
-			.selectFrom("lix_internal_state_vtable")
-			.where("entity_id", "=", CACHE_STALE_KEY)
-			.where("schema_key", "=", CACHE_SCHEMA_KEY)
-			.where("version_id", "=", "global")
-			.where("inherited_from_version_id", "is", null)
-			.where("snapshot_content", "is not", null)
-			.select(sql`json_extract(snapshot_content, '$.value')`.as("value"))
-			.compile()
-	).rows;
-
-	if (!res || res.length === 0) {
-		return true;
-	}
-
-	return res[0]?.value == true;
-}
-
-/**
- * Determine whether the state cache needs to be repopulated.
- *
- * The result is cached per SQLite connection and automatically invalidated
- * whenever the `lix_state_cache_stale` key changes via `onStateCommit`.
- *
- * @example
- * const stale = isStaleStateCacheV2({ engine: lix.engine! });
- */
-export function isStaleStateCacheV2(args: {
-	engine: Pick<LixEngine, "executeSync" | "hooks">;
-}): boolean {
-	const { engine } = args;
-
-	if (!hookListeners.has(args.engine.hooks)) {
-		hookListeners.add(args.engine.hooks);
-		engine.hooks.onStateCommit(({ changes }) => {
-			for (const change of changes) {
-				if (
-					change.entity_id === CACHE_STALE_KEY &&
-					change.schema_key === CACHE_SCHEMA_KEY
-				) {
-					invalidateStaleStateCacheMemoV2({ engine });
-					break;
-				}
-			}
-		});
-	}
-
-	if (staleStateCache.has(args.engine.executeSync)) {
-		return staleStateCache.get(args.engine.executeSync)!;
-	}
-
-	const result = readStaleFlag(args.engine);
-	setStaleStateCacheMemoV2({ engine, value: result });
-	return result;
-}

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

@@ -1,78 +0,0 @@
-import type { LixEngine } from "../../engine/boot.js";
-import { getTimestampSync } from "../../engine/functions/timestamp.js";
-import { LixKeyValueSchema } from "../../key-value/schema-definition.js";
-import { updateUntrackedState } from "../untracked/update-untracked-state.js";
-import { setStaleStateCacheMemoV2 } from "./is-stale-state-cache.js";
-
-const CACHE_STALE_KEY = "lix_state_cache_stale";
-
-/**
- * Mark the cache v2 as stale to trigger repopulation on next read.
- *
- * @example
- * markStateCacheAsStaleV2({ engine: lix.engine! });
- */
-export function markStateCacheAsStaleV2(args: {
-	engine: Pick<
-		LixEngine,
-		"sqlite" | "hooks" | "executeSync" | "runtimeCacheRef"
-	>;
-	timestamp?: string;
-}): void {
-	const createdAt = args.timestamp ?? getTimestampSync({ engine: args.engine });
-
-	updateUntrackedState({
-		engine: args.engine,
-		changes: [
-			{
-				entity_id: CACHE_STALE_KEY,
-				schema_key: LixKeyValueSchema["x-lix-key"],
-				file_id: "lix",
-				plugin_key: "lix_sdk",
-				snapshot_content: JSON.stringify({
-					key: CACHE_STALE_KEY,
-					value: true,
-				}),
-				schema_version: LixKeyValueSchema["x-lix-version"],
-				created_at: createdAt,
-				lixcol_version_id: "global",
-			},
-		],
-	});
-
-	setStaleStateCacheMemoV2({ engine: args.engine, value: true });
-}
-
-/**
- * Mark the cache v2 as fresh after a successful repopulation.
- *
- * @example
- * markStateCacheAsFreshV2({ engine: lix.engine! });
- */
-export function markStateCacheAsFreshV2(args: {
-	engine: Pick<LixEngine, "hooks" | "executeSync" | "runtimeCacheRef">;
-	timestamp?: string;
-}): void {
-	const createdAt = args.timestamp ?? getTimestampSync({ engine: args.engine });
-
-	updateUntrackedState({
-		engine: args.engine,
-		changes: [
-			{
-				entity_id: CACHE_STALE_KEY,
-				schema_key: LixKeyValueSchema["x-lix-key"],
-				file_id: "lix",
-				plugin_key: "lix_sdk",
-				snapshot_content: JSON.stringify({
-					key: CACHE_STALE_KEY,
-					value: false,
-				}),
-				schema_version: LixKeyValueSchema["x-lix-version"],
-				created_at: createdAt,
-				lixcol_version_id: "global",
-			},
-		],
-	});
-
-	setStaleStateCacheMemoV2({ engine: args.engine, value: false });
-}

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

@@ -1,124 +0,0 @@
-import { expect, test } from "vitest";
-import { openLix } from "../../lix/open-lix.js";
-import { populateStateCacheV2 } from "./populate-state-cache.js";
-import { getTimestamp } from "../../engine/functions/timestamp.js";
-import { updateStateCache } from "../cache/update-state-cache.js";
-import { LixStoredSchemaSchema } from "../../stored-schema/schema-definition.js";
-import type { Kysely } from "kysely";
-import type { LixInternalDatabaseSchema } from "../../database/schema.js";
-import { schemaKeyToCacheTableNameV2 } from "./create-schema-cache-table.js";
-
-const cacheTable = (schemaKey: string, schemaVersion = "1.0"): string =>
-	schemaKeyToCacheTableNameV2(schemaKey, schemaVersion);
-
-function selectCacheRows(
-	sqlite: any,
-	schemaKey: string,
-	schemaVersion = "1.0"
-) {
-	return (
-		sqlite.exec({
-			sql: `SELECT * FROM ${cacheTable(schemaKey, schemaVersion)}`,
-			returnValue: "resultRows",
-			rowMode: "object",
-		}) ?? []
-	);
-}
-
-async function registerStoredSchema(
-	lix: Awaited<ReturnType<typeof openLix>>,
-	schemaKey: string
-): Promise<void> {
-	const entityId = `${schemaKey}~1.0`;
-	const timestamp = new Date().toISOString();
-
-	await updateStateCache({
-		engine: lix.engine!,
-		changes: [
-			{
-				id: `delete-${entityId}`,
-				entity_id: entityId,
-				schema_key: LixStoredSchemaSchema["x-lix-key"],
-				schema_version: LixStoredSchemaSchema["x-lix-version"],
-				file_id: "lix",
-				plugin_key: "lix_sdk",
-				snapshot_content: null,
-				created_at: timestamp,
-			},
-		],
-		commit_id: `delete-${entityId}`,
-		version_id: "global",
-	});
-
-	await updateStateCache({
-		engine: lix.engine!,
-		changes: [
-			{
-				id: `insert-${entityId}`,
-				entity_id: entityId,
-				schema_key: LixStoredSchemaSchema["x-lix-key"],
-				schema_version: LixStoredSchemaSchema["x-lix-version"],
-				file_id: "lix",
-				plugin_key: "lix_sdk",
-				snapshot_content: JSON.stringify({
-					value: {
-						$schema: "http://json-schema.org/draft-07/schema#",
-						type: "object",
-						"x-lix-key": schemaKey,
-						"x-lix-version": "1.0",
-						properties: {
-							id: { type: "string" },
-							value: { type: "string" },
-						},
-						required: [],
-						additionalProperties: false,
-					},
-				}),
-				created_at: timestamp,
-			},
-		],
-		commit_id: `insert-${entityId}`,
-		version_id: "global",
-	});
-}
-
-test("populateStateCacheV2 materializes normalized rows for global version", async () => {
-	const lix = await openLix({
-		keyValues: [{ key: "lix_deterministic_mode", value: { enabled: true } }],
-	});
-
-	await registerStoredSchema(lix, "lix_example");
-
-	const timestamp = await getTimestamp({ lix });
-	const db = lix.db as unknown as Kysely<LixInternalDatabaseSchema>;
-
-	await db
-		.insertInto("state_by_version")
-		.values({
-			entity_id: "entity-1",
-			schema_key: "lix_example",
-			file_id: "lix",
-			version_id: "global",
-			plugin_key: "test_plugin",
-			snapshot_content: JSON.stringify({
-				id: "entity-1",
-				value: "seed",
-			}) as any,
-			schema_version: "1.0",
-			created_at: timestamp,
-			updated_at: timestamp,
-			inherited_from_version_id: null,
-			change_id: "change-1",
-			commit_id: "commit-1",
-		})
-		.execute();
-
-	populateStateCacheV2({ engine: lix.engine! });
-
-	const rows = selectCacheRows(lix.engine!.sqlite, "lix_example");
-	expect(rows).toHaveLength(1);
-	const row = rows[0]!;
-	expect(row.version_id).toBe("global");
-	expect(typeof row.commit_id).toBe("string");
-	expect(row.x_value).toBe("seed");
-});