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

package/src/file/schema.ts

@@ -0,0 +1,300 @@
+import { handleFileInsert, handleFileUpdate } from "./file-handlers.js";
+import { materializeFileData } from "./materialize-file-data.js";
+import { materializeFileDataAtChangeset } from "./materialize-file-data-at-changeset.js";
+import type {
+	LixSchemaDefinition,
+	FromLixSchemaDefinition,
+} from "../schema-definition/definition.js";
+import type { Lix } from "../lix/open-lix.js";
+
+export function applyFileDatabaseSchema(
+	lix: Pick<Lix, "sqlite" | "db" | "plugin" | "hooks">
+): void {
+	lix.sqlite.createFunction({
+		name: "handle_file_insert",
+		arity: 6,
+		xFunc: (_ctx: number, ...args: any[]) => {
+			// Parse metadata if it's a JSON string (SQLite converts objects to strings)
+			let metadata = args[3];
+			if (typeof metadata === "string" && metadata !== null) {
+				try {
+					metadata = JSON.parse(metadata);
+				} catch {
+					// If parsing fails, keep as string
+				}
+			}
+
+			const result = handleFileInsert({
+				lix,
+				file: {
+					id: args[0],
+					path: args[1],
+					data: args[2],
+					metadata: metadata,
+				},
+				versionId: args[4],
+				untracked: Boolean(args[5]),
+			});
+			return result;
+		},
+		deterministic: true,
+	});
+
+	lix.sqlite.createFunction({
+		name: "handle_file_update",
+		arity: 6,
+		xFunc: (_ctx: number, ...args: any[]) => {
+			// Parse metadata if it's a JSON string (SQLite converts objects to strings)
+			let metadata = args[3];
+			if (typeof metadata === "string" && metadata !== null) {
+				try {
+					metadata = JSON.parse(metadata);
+				} catch {
+					// If parsing fails, keep as string
+				}
+			}
+
+			const result = handleFileUpdate({
+				lix,
+				file: {
+					id: args[0],
+					path: args[1],
+					data: args[2],
+					metadata: metadata,
+				},
+				versionId: args[4],
+				untracked: Boolean(args[5]),
+			});
+			return result;
+		},
+		deterministic: true,
+	});
+
+	lix.sqlite.createFunction({
+		name: "materialize_file_data",
+		arity: 4,
+		deterministic: false,
+		xFunc: (_ctx: number, ...args: any[]) => {
+			return materializeFileData({
+				lix,
+				file: {
+					id: args[0],
+					path: args[1],
+					metadata: args[3],
+				},
+				versionId: args[2],
+			});
+		},
+	});
+
+	lix.sqlite.createFunction({
+		name: "materialize_file_data_at_changeset",
+		arity: 5,
+		deterministic: false,
+		xFunc: (_ctx: number, ...args: any[]) => {
+			return materializeFileDataAtChangeset({
+				lix,
+				file: {
+					id: args[0],
+					path: args[1],
+					metadata: args[4],
+				},
+				changeSetId: args[2],
+				depth: args[3],
+			});
+		},
+	});
+
+	lix.sqlite.exec(`
+  CREATE VIEW IF NOT EXISTS file AS
+	SELECT
+		json_extract(snapshot_content, '$.id') AS id,
+		json_extract(snapshot_content, '$.path') AS path,
+		materialize_file_data(
+			json_extract(snapshot_content, '$.id'), 
+			json_extract(snapshot_content, '$.path'), 
+			version_id,
+			json_extract(snapshot_content, '$.metadata')
+		) AS data,
+		json_extract(snapshot_content, '$.metadata') AS metadata,
+		inherited_from_version_id AS lixcol_inherited_from_version_id,
+		created_at AS lixcol_created_at,
+		updated_at AS lixcol_updated_at,
+		change_id AS lixcol_change_id,
+		untracked AS lixcol_untracked
+	FROM state
+	WHERE schema_key = 'lix_file_descriptor';
+
+  CREATE VIEW IF NOT EXISTS file_all AS
+	SELECT
+		json_extract(snapshot_content, '$.id') AS id,
+		json_extract(snapshot_content, '$.path') AS path,
+		materialize_file_data(
+			json_extract(snapshot_content, '$.id'), 
+			json_extract(snapshot_content, '$.path'), 
+			version_id,
+			json_extract(snapshot_content, '$.metadata')
+		) AS data,
+		json_extract(snapshot_content, '$.metadata') AS metadata,
+		version_id AS lixcol_version_id,
+		inherited_from_version_id AS lixcol_inherited_from_version_id,
+		created_at AS lixcol_created_at,
+		updated_at AS lixcol_updated_at,
+		change_id AS lixcol_change_id,
+		untracked AS lixcol_untracked
+	FROM state_all
+	WHERE schema_key = 'lix_file_descriptor';
+
+
+  CREATE TRIGGER IF NOT EXISTS file_insert
+  INSTEAD OF INSERT ON file
+  BEGIN
+      SELECT handle_file_insert(
+        COALESCE(NEW.id, nano_id()),
+        NEW.path,
+        NEW.data,
+        NEW.metadata,
+        (SELECT version_id FROM active_version),
+        COALESCE(NEW.lixcol_untracked, 0)
+      );
+  END;
+
+  CREATE TRIGGER IF NOT EXISTS file_update
+  INSTEAD OF UPDATE ON file
+  BEGIN
+      SELECT handle_file_update(
+        NEW.id,
+        NEW.path,
+        NEW.data,
+        NEW.metadata,
+        (SELECT version_id FROM active_version),
+        COALESCE(NEW.lixcol_untracked, 0)
+      );
+  END;
+
+  CREATE TRIGGER IF NOT EXISTS file_delete
+  INSTEAD OF DELETE ON file
+  BEGIN
+      -- Delete all non-lix_file entities associated with this file first
+      DELETE FROM state_all
+      WHERE file_id = OLD.id
+        AND version_id = (SELECT version_id FROM active_version)
+        AND schema_key != 'lix_file_descriptor';
+        
+      -- Delete the file entity itself
+      DELETE FROM state_all
+      WHERE entity_id = OLD.id
+        AND schema_key = 'lix_file_descriptor'
+        AND version_id = (SELECT version_id FROM active_version);
+  END;
+
+  CREATE TRIGGER IF NOT EXISTS file_all_insert
+  INSTEAD OF INSERT ON file_all
+  BEGIN
+      SELECT handle_file_insert(
+        COALESCE(NEW.id, nano_id()),
+        NEW.path,
+        NEW.data,
+        NEW.metadata,
+        COALESCE(NEW.lixcol_version_id, (SELECT version_id FROM active_version)),
+        COALESCE(NEW.lixcol_untracked, 0)
+      );
+  END;
+
+  CREATE TRIGGER IF NOT EXISTS file_all_update
+  INSTEAD OF UPDATE ON file_all
+  BEGIN
+      SELECT handle_file_update(
+        NEW.id,
+        NEW.path,
+        NEW.data,
+        NEW.metadata,
+        COALESCE(NEW.lixcol_version_id, OLD.lixcol_version_id),
+        COALESCE(NEW.lixcol_untracked, 0)
+      );
+  END;
+
+  CREATE TRIGGER IF NOT EXISTS file_all_delete
+  INSTEAD OF DELETE ON file_all
+  BEGIN
+      -- Delete all non-lix_file entities associated with this file first
+      DELETE FROM state_all
+      WHERE file_id = OLD.id
+        AND version_id = OLD.lixcol_version_id
+        AND schema_key != 'lix_file_descriptor';
+        
+      -- Delete the file entity itself
+      DELETE FROM state_all
+      WHERE entity_id = OLD.id
+        AND schema_key = 'lix_file_descriptor'
+        AND version_id = OLD.lixcol_version_id;
+  END;
+
+  CREATE VIEW IF NOT EXISTS file_history AS
+  SELECT
+    json_extract(snapshot_content, '$.id') AS id,
+    json_extract(snapshot_content, '$.path') AS path,
+    materialize_file_data_at_changeset(
+      json_extract(snapshot_content, '$.id'),
+      json_extract(snapshot_content, '$.path'),
+      change_set_id,
+      depth,
+      json_extract(snapshot_content, '$.metadata')
+    ) AS data,
+    json_extract(snapshot_content, '$.metadata') AS metadata,
+    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 = 'lix_file_descriptor';
+`);
+}
+
+export const LixFileDescriptorSchema = {
+	"x-lix-key": "lix_file_descriptor",
+	"x-lix-version": "1.0",
+	"x-lix-primary-key": ["id"],
+	"x-lix-unique": [["path"]],
+	type: "object",
+	properties: {
+		id: { type: "string", "x-lix-generated": true },
+		path: {
+			type: "string",
+			pattern: "^/(?!.*//|.*\\\\)(?!.*/$|^/$).+",
+			description:
+				"File path must start with a slash, not contain backslashes or consecutive slashes, and not end with a slash",
+		},
+		metadata: {
+			type: "object",
+			nullable: true,
+		},
+	},
+	required: ["id", "path"],
+	additionalProperties: false,
+} as const;
+LixFileDescriptorSchema satisfies LixSchemaDefinition;
+
+/**
+ * The file descriptor type representing the stored metadata for a file.
+ *
+ * This contains the file's identity and metadata but not the actual file content.
+ * The file content (data) is materialized separately by aggregating entities from plugins.
+ */
+export type LixFileDescriptor = FromLixSchemaDefinition<
+	typeof LixFileDescriptorSchema
+>;
+
+/**
+ * Complete file type combining the descriptor with materialized data.
+ *
+ * Uses "Lix" prefix to avoid collision with JavaScript's built-in File type.
+ * This represents the full file as seen in views, combining:
+ * - LixFileDescriptor: stored metadata (id, path, metadata)
+ * - data: materialized file content from plugin entities
+ */
+export type LixFile = LixFileDescriptor & {
+	data: Uint8Array;
+};

package/src/file/store-detected-change-schema.test.ts

@@ -0,0 +1,248 @@
+import { test, expect } from "vitest";
+import { openLix } from "../lix/open-lix.js";
+import { storeDetectedChangeSchema } from "./store-detected-change-schema.js";
+import type { LixPlugin } from "../plugin/lix-plugin.js";
+
+test("storeDetectedChangeSchema stores new schema on first use", async () => {
+	const lix = await openLix({});
+
+	const testSchema = {
+		"x-lix-key": "test_schema",
+		"x-lix-version": "1.0",
+		type: "object",
+		properties: {
+			value: { type: "string" },
+		},
+	} as const;
+
+	// Store schema for the first time
+	storeDetectedChangeSchema({
+		lix,
+		schema: testSchema,
+	});
+
+	// Check that schema was stored
+	const storedSchema = await lix.db
+		.selectFrom("stored_schema")
+		.where("key", "=", "test_schema")
+		.where("version", "=", "1.0")
+		.selectAll()
+		.execute();
+
+	expect(storedSchema).toHaveLength(1);
+	expect(storedSchema[0]?.value).toEqual(testSchema);
+});
+
+test("storeDetectedChangeSchema allows identical schema to be used again", async () => {
+	const lix = await openLix({});
+
+	const testSchema = {
+		"x-lix-key": "test_schema_2",
+		"x-lix-version": "1.0",
+		type: "object",
+		properties: {
+			value: { type: "string" },
+		},
+	} as const;
+
+	// Store schema first time
+	storeDetectedChangeSchema({
+		lix,
+		schema: testSchema,
+	});
+
+	// Store same schema again - should not throw
+	expect(() => {
+		storeDetectedChangeSchema({
+			lix,
+			schema: testSchema,
+		});
+	}).not.toThrow();
+
+	// Should only have one schema stored
+	const storedSchemas = await lix.db
+		.selectFrom("stored_schema")
+		.where("key", "=", "test_schema_2")
+		.selectAll()
+		.execute();
+
+	expect(storedSchemas).toHaveLength(1);
+});
+
+test("storeDetectedChangeSchema throws error when schema differs for same version", async () => {
+	const lix = await openLix({});
+
+	const originalSchema = {
+		"x-lix-key": "test_schema_3",
+		"x-lix-version": "1.0",
+		type: "object",
+		properties: {
+			value: { type: "string" },
+		},
+	} as const;
+
+	const differentSchema = {
+		"x-lix-key": "test_schema_3",
+		"x-lix-version": "1.0", // Same version
+		type: "object",
+		properties: {
+			value: { type: "number" }, // Different property type!
+		},
+	} as const;
+
+	// Store original schema
+	storeDetectedChangeSchema({
+		lix,
+		schema: originalSchema,
+	});
+
+	// Try to store different schema with same version - should throw
+	expect(() => {
+		storeDetectedChangeSchema({
+			lix,
+			schema: differentSchema,
+		});
+	}).toThrow(
+		"Schema differs from stored version for key 'test_schema_3' version '1.0'. Please bump the schema version (x-lix-version) to use a different schema."
+	);
+});
+
+test("storeDetectedChangeSchema allows different schemas with different versions", async () => {
+	const lix = await openLix({});
+
+	const schemaV1 = {
+		"x-lix-key": "test_schema_4",
+		"x-lix-version": "1.0",
+		type: "object",
+		properties: {
+			value: { type: "string" },
+		},
+	} as const;
+
+	const schemaV2 = {
+		"x-lix-key": "test_schema_4",
+		"x-lix-version": "2.0", // Different version
+		type: "object",
+		properties: {
+			value: { type: "number" }, // Different property type is OK with different version
+		},
+	} as const;
+
+	// Store v1 schema
+	storeDetectedChangeSchema({
+		lix,
+		schema: schemaV1,
+	});
+
+	// Store v2 schema - should not throw
+	expect(() => {
+		storeDetectedChangeSchema({
+			lix,
+			schema: schemaV2,
+		});
+	}).not.toThrow();
+
+	// Should have both schemas stored
+	const storedSchemas = await lix.db
+		.selectFrom("stored_schema")
+		.where("key", "=", "test_schema_4")
+		.selectAll()
+		.execute();
+
+	expect(storedSchemas).toHaveLength(2);
+	expect(storedSchemas.map((s) => s.version).sort()).toEqual(["1.0", "2.0"]);
+});
+
+test("storeDetectedChangeSchema enforces strict JSON determinism", async () => {
+	const lix = await openLix({});
+
+	const originalSchema = {
+		"x-lix-key": "test_schema_5",
+		"x-lix-version": "1.0",
+		type: "object",
+		properties: {
+			a: { type: "string" },
+			b: { type: "number" },
+		},
+	} as const;
+
+	// Same schema but different property order
+	const reorderedSchema = {
+		"x-lix-key": "test_schema_5",
+		"x-lix-version": "1.0",
+		type: "object",
+		properties: {
+			b: { type: "number" }, // Reordered properties
+			a: { type: "string" },
+		},
+	} as const;
+
+	// Store original schema
+	storeDetectedChangeSchema({
+		lix,
+		schema: originalSchema,
+	});
+
+	// Try to store reordered schema - should throw because JSON.stringify will be different
+	expect(() => {
+		storeDetectedChangeSchema({
+			lix,
+			schema: reorderedSchema,
+		});
+	}).toThrow(
+		"Schema differs from stored version for key 'test_schema_5' version '1.0'. Please bump the schema version (x-lix-version) to use a different schema."
+	);
+});
+
+test("integration with plugin detectChanges", async () => {
+	const mockPlugin: LixPlugin = {
+		key: "test-plugin",
+		detectChangesGlob: "*.txt",
+		detectChanges: () => [
+			{
+				entity_id: "entity1",
+				schema: {
+					"x-lix-key": "integration_test_schema",
+					"x-lix-version": "1.0",
+					type: "object",
+					properties: {
+						value: { type: "string" },
+					},
+				},
+				snapshot_content: { value: "test" },
+			},
+		],
+	};
+
+	const lix = await openLix({
+		providePlugins: [mockPlugin],
+	});
+
+	// Insert a file - should automatically store the schema via file handlers
+	await lix.db
+		.insertInto("file")
+		.values({
+			id: "test-file",
+			data: new TextEncoder().encode("test content"),
+			path: "/test.txt",
+		})
+		.execute();
+
+	// Check that schema was automatically stored
+	const storedSchema = await lix.db
+		.selectFrom("stored_schema")
+		.where("key", "=", "integration_test_schema")
+		.where("version", "=", "1.0")
+		.selectAll()
+		.execute();
+
+	expect(storedSchema).toHaveLength(1);
+	expect(storedSchema[0]?.value).toEqual({
+		"x-lix-key": "integration_test_schema",
+		"x-lix-version": "1.0",
+		type: "object",
+		properties: {
+			value: { type: "string" },
+		},
+	});
+});

package/src/file/store-detected-change-schema.ts

@@ -0,0 +1,52 @@
+import { executeSync } from "../database/execute-sync.js";
+import type { Lix } from "../lix/open-lix.js";
+import type { LixSchemaDefinition } from "../schema-definition/definition.js";
+
+export function storeDetectedChangeSchema(args: {
+	lix: Pick<Lix, "sqlite" | "db">;
+	schema: LixSchemaDefinition;
+	untracked?: boolean;
+}): void {
+	const schemaKey = args.schema["x-lix-key"];
+	const schemaVersion = args.schema["x-lix-version"];
+
+	// Check if schema already exists
+	const existingSchema = executeSync({
+		lix: args.lix,
+		query: args.lix.db
+			.selectFrom("stored_schema")
+			.where("key", "=", schemaKey)
+			.where("version", "=", schemaVersion)
+			.select(["key", "version", "value"])
+			.limit(1),
+	})[0];
+
+	if (existingSchema) {
+		// Compare schemas using JSON.stringify for strict determinism
+		// Handle case where stored value might already be stringified
+		const existingSchemaJson =
+			typeof existingSchema.value === "string"
+				? existingSchema.value
+				: JSON.stringify(existingSchema.value);
+		const newSchemaJson = JSON.stringify(args.schema);
+
+		if (existingSchemaJson !== newSchemaJson) {
+			throw new Error(
+				`Schema differs from stored version for key '${schemaKey}' version '${schemaVersion}'. ` +
+					`Please bump the schema version (x-lix-version) to use a different schema.`
+			);
+		}
+		// Schemas match, continue
+	} else {
+		// Store new schema
+		executeSync({
+			lix: args.lix,
+			query: args.lix.db.insertInto("stored_schema").values({
+				key: schemaKey,
+				version: schemaVersion,
+				value: args.schema as any,
+				lixcol_untracked: args.untracked || false,
+			}),
+		});
+	}
+}