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

package/src/snapshot/schema.test.ts

@@ -1,268 +0,0 @@
-import { expect, test } from "vitest";
-import { openLix } from "../lix/open-lix.js";
-import { sql, type Kysely } from "kysely";
-import type { LixInternalDatabaseSchema } from "../database/schema.js";
-
-test("insert with default id generation", async () => {
-	const lix = await openLix({});
-
-	// Insert a snapshot without specifying an id
-	await (lix.db as unknown as Kysely<LixInternalDatabaseSchema>)
-		.insertInto("lix_internal_snapshot")
-		.values({
-			content: sql`jsonb(${JSON.stringify({ text: "Auto-generated ID test" })})`,
-		})
-		.execute();
-
-	// Find the snapshot by content to verify it was inserted with a generated ID
-	const snapshots = await (
-		lix.db as unknown as Kysely<LixInternalDatabaseSchema>
-	)
-		.selectFrom("lix_internal_snapshot")
-		.where(
-			"content",
-			"=",
-			sql`jsonb(${JSON.stringify({ text: "Auto-generated ID test" })})`
-		)
-		.select(["id", (eb) => eb.fn("json", [`content`]).as("content")])
-		.execute();
-
-	expect(snapshots).toHaveLength(1);
-	expect(snapshots[0]?.id).toBeTruthy();
-	expect(snapshots[0]?.id).not.toBe("no-content");
-	expect(snapshots[0]?.content).toEqual({ text: "Auto-generated ID test" });
-});
-
-test("handles complex JSON content", async () => {
-	const lix = await openLix({});
-
-	const complexContent = {
-		string: "test",
-		number: 123,
-		boolean: true,
-		null_value: null,
-		array: [1, 2, 3, "mixed", { nested: true }],
-		nested_object: {
-			level1: {
-				level2: {
-					deep_value: "found it",
-				},
-			},
-		},
-	};
-
-	await (lix.db as unknown as Kysely<LixInternalDatabaseSchema>)
-		.insertInto("lix_internal_snapshot")
-		.values({
-			id: "complex",
-			content: sql`jsonb(${JSON.stringify(complexContent)})`,
-		})
-		.execute();
-
-	const snapshot = await (
-		lix.db as unknown as Kysely<LixInternalDatabaseSchema>
-	)
-		.selectFrom("lix_internal_snapshot")
-		.where("id", "=", "complex")
-		.select(["id", (eb) => eb.fn("json", [`content`]).as("content")])
-		.executeTakeFirstOrThrow();
-
-	expect(snapshot.content).toEqual(complexContent);
-});
-
-test("no-content snapshot exists by default", async () => {
-	const lix = await openLix({});
-
-	// Verify the no-content snapshot exists in the internal table
-	const internalNoContent = await (
-		lix.db as unknown as Kysely<LixInternalDatabaseSchema>
-	)
-		.selectFrom("lix_internal_snapshot")
-		.where("id", "=", "no-content")
-		.selectAll()
-		.execute();
-
-	expect(internalNoContent).toHaveLength(1);
-	expect(internalNoContent[0]?.id).toBe("no-content");
-	expect(internalNoContent[0]?.content).toBeNull();
-});
-
-test("no-content snapshot is not duplicated on multiple schema applications", async () => {
-	const lix = await openLix({});
-
-	// Apply the schema again (this happens in real usage)
-	lix.engine!.sqlite.exec(`
-			INSERT OR IGNORE INTO lix_internal_snapshot (id, content)
-			VALUES ('no-content', NULL);
-		`);
-
-	// Verify there's still only one no-content snapshot
-	const noContentSnapshots = await (
-		lix.db as unknown as Kysely<LixInternalDatabaseSchema>
-	)
-		.selectFrom("lix_internal_snapshot")
-		.where("id", "=", "no-content")
-		.selectAll()
-		.execute();
-
-	expect(noContentSnapshots).toHaveLength(1);
-});
-
-test("can insert null content explicitly", async () => {
-	const lix = await openLix({});
-
-	await (lix.db as unknown as Kysely<LixInternalDatabaseSchema>)
-		.insertInto("lix_internal_snapshot")
-		.values({
-			id: "explicit-null",
-			content: null,
-		})
-		.execute();
-
-	const snapshot = await (
-		lix.db as unknown as Kysely<LixInternalDatabaseSchema>
-	)
-		.selectFrom("lix_internal_snapshot")
-		.where("id", "=", "explicit-null")
-		.selectAll()
-		.executeTakeFirstOrThrow();
-
-	expect(snapshot.content).toBeNull();
-});
-
-test("snapshot content validation - accepts JSONB", async () => {
-	const lix = await openLix({});
-
-	// This should succeed - content is properly formatted as JSONB
-	await (lix.db as unknown as Kysely<LixInternalDatabaseSchema>)
-		.insertInto("lix_internal_snapshot")
-		.values({
-			id: "valid-jsonb",
-			content: sql`jsonb(${JSON.stringify({ test: "data", value: 123 })})`,
-		})
-		.execute();
-
-	const snapshot = await (
-		lix.db as unknown as Kysely<LixInternalDatabaseSchema>
-	)
-		.selectFrom("lix_internal_snapshot")
-		.where("id", "=", "valid-jsonb")
-		.select(["id", (eb) => eb.fn("json", [`content`]).as("content")])
-		.executeTakeFirstOrThrow();
-
-	expect(snapshot.content).toEqual({ test: "data", value: 123 });
-});
-
-test("snapshot content validation - rejects text JSON", async () => {
-	const lix = await openLix({});
-
-	// This should fail - content is text JSON, not JSONB
-	// SQLite's STRICT tables enforce that BLOB columns can't store TEXT
-	await expect(
-		(lix.db as unknown as Kysely<LixInternalDatabaseSchema>)
-			.insertInto("lix_internal_snapshot")
-			.values({
-				id: "invalid-text-json",
-				content: sql`${JSON.stringify({ test: "data" })}`,
-			})
-			.execute()
-	).rejects.toThrow(
-		/SQLITE_CONSTRAINT_DATATYPE.*cannot store TEXT value in BLOB column/
-	);
-});
-
-test("snapshot content validation - rejects arbitrary binary", async () => {
-	const lix = await openLix({});
-
-	// This should fail - content is arbitrary binary data, not valid JSONB
-	// Using raw SQL to insert arbitrary binary that's not JSONB format
-	const encoder = new TextEncoder();
-	const arbitraryBytes = encoder.encode("arbitrary binary data");
-
-	await expect(async () => {
-		lix.engine!.sqlite.exec({
-			sql: `INSERT INTO lix_internal_snapshot (id, content) VALUES (?, ?)`,
-			bind: ["invalid-binary", arbitraryBytes],
-		});
-	}).rejects.toThrow(/CHECK constraint failed.*json_valid/);
-});
-
-test("snapshot content validation - prevents double-stringified JSON storage", async () => {
-	const lix = await openLix({});
-
-	// This test demonstrates the double-stringified JSON issue we were investigating
-	const originalData = { id: "test", name: "value" };
-	const onceStringified = JSON.stringify(originalData);
-	const doubleStringified = JSON.stringify(onceStringified);
-
-	// First, verify that plain text JSON is rejected by STRICT table
-	await expect(
-		(lix.db as unknown as Kysely<LixInternalDatabaseSchema>)
-			.insertInto("lix_internal_snapshot")
-			.values({
-				id: "double-stringified",
-				content: sql`${doubleStringified}`,
-			})
-			.execute()
-	).rejects.toThrow(
-		/SQLITE_CONSTRAINT_DATATYPE.*cannot store TEXT value in BLOB column/
-	);
-
-	// The real issue: jsonb() on double-stringified JSON creates valid JSONB
-	// because a JSON string is valid JSON! But with our new json_type check,
-	// this should now be rejected since it's storing a string, not an object
-	expect(() => {
-		lix.engine!.sqlite.exec({
-			sql: `INSERT INTO lix_internal_snapshot (id, content) VALUES (?, jsonb(?))`,
-			bind: ["double-stringified-jsonb", doubleStringified],
-		});
-	}).toThrow(/CHECK constraint failed/);
-
-	// Also verify that storing arrays is rejected (we only want objects)
-	expect(() => {
-		lix.engine!.sqlite.exec({
-			sql: `INSERT INTO lix_internal_snapshot (id, content) VALUES (?, jsonb(?))`,
-			bind: ["array-content", JSON.stringify([1, 2, 3])],
-		});
-	}).toThrow(/CHECK constraint failed/);
-
-	// Verify the correct way: jsonb() on properly stringified JSON
-	lix.engine!.sqlite.exec({
-		sql: `INSERT INTO lix_internal_snapshot (id, content) VALUES (?, jsonb(?))`,
-		bind: ["correct-jsonb", onceStringified],
-	});
-
-	// Verify it retrieves correctly
-	const correctResult: any = lix.engine!.sqlite.exec({
-		sql: `SELECT json(content) as json_content FROM lix_internal_snapshot WHERE id = ?`,
-		bind: ["correct-jsonb"],
-		returnValue: "resultRows",
-	});
-
-	expect(correctResult[0]?.[0]).toBe(onceStringified);
-	expect(JSON.parse(correctResult[0]![0]!)).toEqual(originalData);
-});
-
-test("snapshot ids must be unique", async () => {
-	const lix = await openLix({});
-
-	// Insert first snapshot
-	await (lix.db as unknown as Kysely<LixInternalDatabaseSchema>)
-		.insertInto("lix_internal_snapshot")
-		.values({
-			id: "duplicate",
-			content: sql`jsonb(${JSON.stringify({ first: true })})`,
-		})
-		.execute();
-
-	// Try to insert another snapshot with the same id
-	await expect(
-		(lix.db as unknown as Kysely<LixInternalDatabaseSchema>)
-			.insertInto("lix_internal_snapshot")
-			.values({
-				id: "duplicate",
-				content: sql`jsonb(${JSON.stringify({ second: true })})`,
-			})
-			.execute()
-	).rejects.toThrow(/UNIQUE constraint failed/);
-});

package/src/snapshot/schema.ts

@@ -1,33 +0,0 @@
-import type { SqliteWasmDatabase } from "../database/sqlite/index.js";
-import type { Generated } from "kysely";
-
-export function applySnapshotDatabaseSchema(
-	sqlite: SqliteWasmDatabase
-): SqliteWasmDatabase {
-	return sqlite.exec(`
-  CREATE TABLE IF NOT EXISTS lix_internal_snapshot (
-    id TEXT PRIMARY KEY DEFAULT (lix_uuid_v7()),
-    content BLOB -- jsonb,
-
-    -- 8 = strictly JSONB
-    -- https://www.sqlite.org/json1.html#jvalid
-    CHECK (json_valid(content, 8)),
-    
-    -- Ensure content is either NULL or a JSON object (not string, array, etc)
-    -- This prevents double-stringified JSON from being stored
-    CHECK (content IS NULL OR json_type(content) = 'object')
-  ) STRICT;
-
-  INSERT OR IGNORE INTO lix_internal_snapshot (id, content)
-  VALUES ('no-content', NULL);
-
-  -- Index on id (explicit, though PRIMARY KEY already provides one)
-  CREATE INDEX IF NOT EXISTS idx_lix_internal_snapshot_id
-    ON lix_internal_snapshot(id);
-`);
-}
-
-export type InternalSnapshotTable = {
-	id: Generated<string>;
-	content: Record<string, any> | null;
-};

package/src/state/README.md

@@ -1,95 +0,0 @@
-# State Architecture
-
-## Overview
-
-The Lix state system manages all entity changes through a [SQLite virtual table](https://www.sqlite.org/vtab.html). This virtual table serves as the single entry point for all mutations, ensuring consistent change tracking, changeset creation, and state persistence.
-
-## State Mutation Flow
-
-All state mutations flow through a SQLite virtual table that orchestrates the three-stage lifecycle:
-
-```
-     User SQL Operations
-            │
-            v
-    ┌─────────────────────┐
-    │ State Virtual Table │  <── Entry point for ALL mutations
-    └───────┬─────────────┘
-            │
-            v
-┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
-│    MUTATION     │ --> │   TRANSACTION    │ --> │     COMMIT      │
-└─────────────────┘     └──────────────────┘     └─────────────────┘
-        │                        │                         │
-        v                        v                         v
-   Validate & Track        Group Changes           Persist to
-      Changes              in Changesets          SQLite Tables
-```
-
-The virtual table:
-
-- Intercepts INSERT, UPDATE, and DELETE operations
-- Tracks every change for audit and history
-- Groups related changes into changesets during transactions
-- Delegates to regular SQLite tables for actual storage
-
-### Stage Characteristics
-
-#### 1. MUTATION Stage
-
-- **Purpose**: Handle individual state changes
-- **Scope**: Single entity operation
-- **Storage**: None (passes through)
-- **Rollback**: Not applicable
-
-#### 2. TRANSACTION Stage
-
-- **Purpose**: Accumulate multiple mutations
-- **Scope**: Multiple entities, single version
-- **Storage**: Temporary (`lix_internal_transaction_state`)
-- **Rollback**: Automatic on error or explicit rollback
-
-#### 3. COMMIT Stage
-
-- **Purpose**: Persist changes permanently
-- **Scope**: All pending changes across versions
-- **Storage**: Permanent (`lix_internal_change`, `lix_internal_snapshot`)
-- **Rollback**: Not possible after commit
-
-## Virtual Table Architecture
-
-The virtual table acts as a facade over the actual storage mechanism:
-
-```
-┌─────────────────────────────────────────────────┐
-│              User SQL Queries                   │
-│  (SELECT, INSERT, UPDATE, DELETE on entities)   │
-└─────────────────────┬───────────────────────────┘
-                      │
-                      v
-┌─────────────────────────────────────────────────┐
-│           State Virtual Table                   │
-│                                                 │
-│  • Intercepts all operations                    │
-│  • Maintains change history                     │
-│  • Ensures transactional consistency            │
-│  • Manages cache coherency                      │
-└─────────────────────┬───────────────────────────┘
-                      │
-                      v
-┌─────────────────────────────────────────────────┐
-│         Regular SQLite Tables                   │
-│                                                 │
-│  • lix_internal_transaction_state                   │
-│  • lix_internal_state_cache                         │
-│  • lix_internal_change                              │
-│  • lix_internal_snapshot                            │
-└─────────────────────────────────────────────────┘
-```
-
-The virtual table provides:
-
-- **Transparent change tracking** - Users work with entities naturally while all changes are tracked
-- **ACID guarantees** - Leverages SQLite's transactional properties
-- **Performance optimization** - Maintains caches and indexes automatically
-- **Version isolation** - Each version sees its own consistent view of the data

package/src/state/cache/builtin-schemas.ts

@@ -1,25 +0,0 @@
-import type { LixSchemaDefinition } from "../../schema-definition/definition.js";
-import { LixSchemaViewMap } from "../../database/schema-view-map.js";
-import {
-	LixVersionDescriptorSchema,
-	LixVersionTipSchema,
-} from "../../version/schema-definition.js";
-
-const registry = new Map<string, LixSchemaDefinition>();
-
-function register(definition: LixSchemaDefinition): void {
-	const key = definition["x-lix-key"];
-	if (typeof key === "string" && key.length > 0) {
-		registry.set(key, definition);
-	}
-}
-
-for (const definition of Object.values(LixSchemaViewMap)) {
-	register(definition);
-}
-
-register(LixVersionDescriptorSchema);
-register(LixVersionTipSchema);
-
-export const BUILTIN_CACHE_SCHEMAS: Record<string, LixSchemaDefinition> =
-	Object.fromEntries(registry);

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

@@ -1,44 +0,0 @@
-import { test, expect } from "vitest";
-import { clearStateCache } from "./clear-state-cache.js";
-import { isStaleStateCache } from "./is-stale-state-cache.js";
-import { markStateCacheAsFresh } from "./mark-state-cache-as-stale.js";
-import { openLix } from "../../lix/open-lix.js";
-
-test("clearStateCache deletes all cache entries", async () => {
-	const lix = await openLix({});
-	// Insert some data to populate cache
-	await lix.db
-		.insertInto("key_value")
-		.values({
-			key: "test_key",
-			value: "test_value",
-		})
-		.execute();
-
-	const readPhysicalKeyValueCache = () => {
-		return lix.engine!.executeSync({
-			sql: `SELECT entity_id FROM lix_internal_state_cache_v1_lix_key_value`,
-		});
-	};
-
-	// Verify cache has entries in the physical schema table
-	const cacheBeforeClear = readPhysicalKeyValueCache();
-	expect(cacheBeforeClear.rows.length).toBeGreaterThan(0);
-
-	// Ensure the stale flag is false and cached before we clear it
-	markStateCacheAsFresh({ engine: lix.engine! });
-	expect(isStaleStateCache({ engine: lix.engine! })).toBe(false);
-
-	// Clear the cache
-	clearStateCache({ engine: lix.engine! });
-
-	// Verify cache is empty
-	const cacheAfterClear = readPhysicalKeyValueCache();
-	expect(cacheAfterClear.rows.length).toBe(0);
-
-	// Verify the cache is marked as stale
-	const isStale = isStaleStateCache({
-		engine: lix.engine!,
-	});
-	expect(isStale).toBe(true);
-});

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

@@ -1,52 +0,0 @@
-import type { LixEngine } from "../../engine/boot.js";
-import { markStateCacheAsStale } from "./mark-state-cache-as-stale.js";
-
-/**
- * Clears all state cache tables.
- *
- * This function:
- * 1. Marks the cache as stale to prevent repopulation during delete
- * 2. Finds ALL per-schema physical tables (not just cached ones)
- * 3. Deletes all entries from each table
- *
- * @example
- * clearStateCache({ engine: lix.engine! });
- */
-export function clearStateCache(args: {
-	engine: Pick<
-		LixEngine,
-		"sqlite" | "hooks" | "executeSync" | "runtimeCacheRef"
-	>;
-	timestamp?: string;
-}): void {
-	// Mark the cache as stale first to prevent repopulation during delete
-	markStateCacheAsStale({
-		engine: args.engine,
-		timestamp: args.timestamp,
-	});
-
-	// Find ALL physical cache tables in the database (not just cached ones)
-	// This ensures we clear tables even if they weren't in our cache
-	// Exclude the v2 virtual table itself
-	const existingTables = args.engine.sqlite.exec({
-		sql: `SELECT name FROM sqlite_schema 
-		      WHERE type='table' 
-		      AND name LIKE 'lix_internal_state_cache_v1_%' 
-		      AND name != 'lix_internal_state_cache'`,
-		returnValue: "resultRows",
-	}) as any[];
-
-	// Delete all entries from each physical table
-	if (existingTables) {
-		for (const row of existingTables) {
-			const tableName = row[0] as string;
-			// Skip virtual tables (shouldn't happen with our query, but be safe)
-			if (tableName === "lix_internal_state_cache") continue;
-
-			args.engine.sqlite.exec({
-				sql: `DELETE FROM ${tableName}`,
-				returnValue: "resultRows",
-			});
-		}
-	}
-}

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

@@ -1,67 +0,0 @@
-import { test, expect } from "vitest";
-import { openLix } from "../../lix/open-lix.js";
-import {
-	createSchemaCacheTable,
-	schemaKeyToCacheTableName,
-} from "./create-schema-cache-table.js";
-import type { LixSchemaDefinition } from "../../schema-definition/definition.js";
-
-const TEST_CACHE_SCHEMA = {
-	"x-lix-key": "lix_test_create",
-	"x-lix-version": "1.0",
-	type: "object",
-	additionalProperties: false,
-	properties: {},
-} as const satisfies LixSchemaDefinition;
-
-test("createSchemaCacheTable creates table with core indexes and is idempotent", async () => {
-	const lix = await openLix({});
-
-	const tableName = schemaKeyToCacheTableName(TEST_CACHE_SCHEMA["x-lix-key"]);
-
-	// First call should create the table and indexes
-	createSchemaCacheTable({ engine: lix.engine!, schema: TEST_CACHE_SCHEMA });
-
-	// 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)
-	createSchemaCacheTable({ engine: lix.engine!, schema: TEST_CACHE_SCHEMA });
-
-	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);
-});