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

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

@@ -19,6 +19,20 @@ import type {
  * ```
  */
 export type StateEntityView = {
+	/**
+	 * The unique identifier for this entity within its schema and file.
+	 *
+	 * This is the primary identifier used to reference this specific entity.
+	 */
+	lixcol_entity_id: Generated<string>;
+
+	/**
+	 * The schema key that defines the structure and type of this entity.
+	 *
+	 * This references the schema definition that validates and types this entity.
+	 */
+	lixcol_schema_key: Generated<string>;
+
 	/**
 	 * File identifier where this entity is stored.
 	 *
@@ -27,6 +41,13 @@ export type StateEntityView = {
 	 */
 	lixcol_file_id: Generated<string>;
 
+	/**
+	 * The plugin key that manages this entity type.
+	 *
+	 * This identifies which plugin is responsible for handling this entity.
+	 */
+	lixcol_plugin_key: Generated<string>;
+
 	/**
 	 * Version identifier this entity was inherited from during branching.
 	 *
@@ -78,6 +99,15 @@ export type StateEntityView = {
 	 * in the state resolution order: untracked > tracked > inherited.
 	 */
 	lixcol_untracked: Generated<boolean>;
+
+	/**
+	 * Commit identifier that contains this entity's last change.
+	 *
+	 * This references the commit.id that contains the last change to this entity.
+	 * Useful for understanding which commit a particular entity state belongs to,
+	 * enabling history queries and version comparison.
+	 */
+	lixcol_commit_id: Generated<string>;
 };
 
 /**
@@ -97,6 +127,20 @@ export type StateEntityView = {
  * ```
  */
 export type EntityStateColumns = {
+	/**
+	 * The unique identifier for this entity within its schema and file.
+	 *
+	 * This is the primary identifier used to reference this specific entity.
+	 */
+	lixcol_entity_id: LixGenerated<string>;
+
+	/**
+	 * The schema key that defines the structure and type of this entity.
+	 *
+	 * This references the schema definition that validates and types this entity.
+	 */
+	lixcol_schema_key: LixGenerated<string>;
+
 	/**
 	 * File identifier where this entity is stored.
 	 *
@@ -105,6 +149,13 @@ export type EntityStateColumns = {
 	 */
 	lixcol_file_id: LixGenerated<string>;
 
+	/**
+	 * The plugin key that manages this entity type.
+	 *
+	 * This identifies which plugin is responsible for handling this entity.
+	 */
+	lixcol_plugin_key: LixGenerated<string>;
+
 	/**
 	 * Version identifier this entity was inherited from during branching.
 	 *
@@ -156,6 +207,15 @@ export type EntityStateColumns = {
 	 * in the state resolution order: untracked > tracked > inherited.
 	 */
 	lixcol_untracked: LixGenerated<boolean>;
+
+	/**
+	 * Commit identifier that contains this entity's last change.
+	 *
+	 * This references the commit.id that contains the last change to this entity.
+	 * Useful for understanding which commit a particular entity state belongs to,
+	 * enabling history queries and version comparison.
+	 */
+	lixcol_commit_id: LixGenerated<string>;
 };
 
 /**
@@ -236,10 +296,13 @@ export function createEntityStateView(args: {
 	validation?: ValidationCallbacks;
 }): void {
 	const view_name = args.overrideName ?? args.schema["x-lix-key"];
+	// Quote the view name to handle SQL reserved keywords
+	const quoted_view_name = `"${view_name}"`;
 
 	createSingleEntityView({
 		...args,
 		viewName: view_name,
+		quotedViewName: quoted_view_name,
 		stateTable: "state",
 	});
 }
@@ -248,6 +311,7 @@ function createSingleEntityView(args: {
 	lix: Pick<Lix, "sqlite">;
 	schema: LixSchemaDefinition;
 	viewName: string;
+	quotedViewName?: string;
 	stateTable: "state";
 	/** Plugin identifier for the entity */
 	pluginKey: string;
@@ -270,6 +334,7 @@ function createSingleEntityView(args: {
 	}
 
 	const view_name = args.viewName;
+	const quoted_view_name = args.quotedViewName || `"${view_name}"`;
 	const schema_key = args.schema["x-lix-key"];
 	const properties = Object.keys((args.schema as any).properties);
 	const primaryKeys = args.schema["x-lix-primary-key"];
@@ -280,11 +345,11 @@ function createSingleEntityView(args: {
 	const entityIdNew =
 		primaryKeys.length === 1
 			? `NEW.${primaryKeys[0]}`
-			: `(${primaryKeys.map((key) => `NEW.${key}`).join(" || '::' || ")})`;
+			: `(${primaryKeys.map((key) => `NEW.${key}`).join(" || '~' || ")})`;
 	const entityIdOld =
 		primaryKeys.length === 1
 			? `OLD.${primaryKeys[0]}`
-			: `(${primaryKeys.map((key) => `OLD.${key}`).join(" || '::' || ")})`;
+			: `(${primaryKeys.map((key) => `OLD.${key}`).join(" || '~' || ")})`;
 
 	// Create UDFs for default values
 	if (args.defaultValues) {
@@ -366,12 +431,16 @@ function createSingleEntityView(args: {
 
 	// Operational columns for active view (no version_id exposed)
 	const operationalColumns = [
+		"entity_id AS lixcol_entity_id",
+		"schema_key AS lixcol_schema_key",
+		"file_id AS lixcol_file_id",
+		"plugin_key AS lixcol_plugin_key",
 		"inherited_from_version_id AS lixcol_inherited_from_version_id",
 		"created_at AS lixcol_created_at",
 		"updated_at AS lixcol_updated_at",
-		"file_id AS lixcol_file_id",
 		"change_id AS lixcol_change_id",
 		"untracked AS lixcol_untracked",
+		"commit_id AS lixcol_commit_id",
 	];
 
 	// Handle version_id for active view
@@ -410,7 +479,7 @@ function createSingleEntityView(args: {
 
 	// Generated SQL query - set breakpoint here to inspect the generated SQL during debugging
 	const sqlQuery = `
-    CREATE VIEW IF NOT EXISTS ${view_name} AS
+    CREATE VIEW IF NOT EXISTS ${quoted_view_name} AS
       SELECT
         ${Object.keys((args.schema as any).properties)
 					.map(
@@ -422,7 +491,7 @@ function createSingleEntityView(args: {
       WHERE schema_key = '${schema_key}';
 
       CREATE TRIGGER IF NOT EXISTS ${view_name}_insert
-      INSTEAD OF INSERT ON ${view_name}
+      INSTEAD OF INSERT ON ${quoted_view_name}
       BEGIN      
         ${insertValidationSQL}
         INSERT INTO state_all (
@@ -445,12 +514,12 @@ function createSingleEntityView(args: {
           json_object(${properties.map((prop) => `'${prop}', with_default_values.${prop}`).join(", ")}),
           '${args.schema["x-lix-version"]}',
           ${versionIdReference.replace(/NEW\./g, "with_default_values.")},
-          with_default_values.lixcol_untracked
+          COALESCE(with_default_values.lixcol_untracked, 0)
         FROM (
           SELECT
             ${defaultsSubquery},
             NEW.lixcol_file_id AS lixcol_file_id,
-            NEW.lixcol_untracked AS lixcol_untracked
+            COALESCE(NEW.lixcol_untracked, 0) AS lixcol_untracked
         ) AS with_default_values`
 						: `
         VALUES (
@@ -461,13 +530,13 @@ function createSingleEntityView(args: {
           json_object(${properties.map((prop) => `'${prop}', NEW.${prop}`).join(", ")}),
           '${args.schema["x-lix-version"]}',
           ${versionIdReference},
-          NEW.lixcol_untracked
+          COALESCE(NEW.lixcol_untracked, 0)
         )`
 				};
       END;
 
       CREATE TRIGGER IF NOT EXISTS ${view_name}_update
-      INSTEAD OF UPDATE ON ${view_name}
+      INSTEAD OF UPDATE ON ${quoted_view_name}
       BEGIN
         ${updateValidationSQL}
         UPDATE state_all
@@ -487,7 +556,7 @@ function createSingleEntityView(args: {
       END;
 
       CREATE TRIGGER IF NOT EXISTS ${view_name}_delete
-      INSTEAD OF DELETE ON ${view_name}
+      INSTEAD OF DELETE ON ${quoted_view_name}
       BEGIN
         ${deleteValidationSQL}
         DELETE FROM state_all

package/src/entity-views/entity-view-builder.test.ts

@@ -66,12 +66,12 @@ describe("createEntityViewsIfNotExists (Integration)", () => {
 		const activeVersion = await lix.db
 			.selectFrom("active_version")
 			.innerJoin("version", "active_version.version_id", "version.id")
-			.select("version.change_set_id")
+			.select("version.commit_id")
 			.executeTakeFirstOrThrow();
 
 		const historyResult = await lix.db
 			.selectFrom("triple_test_history" as any)
-			.where("lixcol_change_set_id", "=", activeVersion.change_set_id)
+			.where("lixcol_commit_id", "=", activeVersion.commit_id)
 			.selectAll()
 			.execute();
 
@@ -100,7 +100,7 @@ describe("createEntityViewsIfNotExists (Integration)", () => {
 		// Verify column differences between views
 		expect(activeResult[0]).not.toHaveProperty("lixcol_version_id"); // Primary view hides version_id
 		expect(allResult[0]).toHaveProperty("lixcol_version_id"); // _all view exposes version_id
-		expect(historyResult[0]).toHaveProperty("lixcol_change_set_id"); // _history view has history columns
+		expect(historyResult[0]).toHaveProperty("lixcol_commit_id"); // _history view has history columns
 		expect(historyResult[0]).toHaveProperty("lixcol_depth", 0); // Current state is at depth 0
 	});
 
@@ -177,13 +177,13 @@ describe("createEntityViewsIfNotExists (Integration)", () => {
 		const activeVersion = await lix.db
 			.selectFrom("active_version")
 			.innerJoin("version", "active_version.version_id", "version.id")
-			.select("version.change_set_id")
+			.select("version.commit_id")
 			.executeTakeFirstOrThrow();
 
 		const historyResult = await lix.db
 			.selectFrom("cross_test_history" as any)
-			.where("entity_id", "=", "test_id")
-			.where("lixcol_change_set_id", "=", activeVersion.change_set_id)
+			.where("lixcol_entity_id", "=", "test_id")
+			.where("lixcol_root_commit_id", "=", activeVersion.commit_id)
 			.orderBy("lixcol_depth", "asc")
 			.selectAll()
 			.execute();

package/src/entity-views/types.ts

@@ -97,10 +97,10 @@ export type EntityStateAllView<T> = T & EntityStateAllColumns;
  * // Define a history view type for key-value entities
  * type KeyValueHistoryView = EntityStateHistoryView<KeyValue>;
  *
- * // Query entity state at a specific change set
+ * // Query entity state at a specific commit
  * await lix.db
  *   .selectFrom("key_value_history")
- *   .where("lixcol_change_set_id", "=", changeSetId)
+ *   .where("lixcol_commit_id", "=", commitId)
  *   .where("lixcol_depth", "=", 0)
  *   .selectAll()
  *   .execute();

package/src/file/file-handlers.test.ts

@@ -2,8 +2,8 @@ import { describe, it, expect } from "vitest";
 import { openLix } from "../lix/open-lix.js";
 import { createVersion } from "../version/create-version.js";
 import { handleFileInsert, handleFileUpdate } from "./file-handlers.js";
-import { nanoid } from "../database/nano-id.js";
 import { mockJsonPlugin } from "../plugin/mock-json-plugin.js";
+import { randomNanoId } from "../database/nano-id.js";
 
 describe("file insert", () => {
 	it("should handle unknown file types with fallback plugin", async () => {
@@ -21,7 +21,7 @@ describe("file insert", () => {
 		handleFileInsert({
 			lix,
 			file: {
-				id: nanoid(),
+				id: randomNanoId(),
 				path: "/test.unknown",
 				data: new TextEncoder().encode("some content"),
 				metadata: null,
@@ -52,7 +52,7 @@ describe("file update", () => {
 			],
 		});
 		const version = await createVersion({ lix });
-		const fileId = nanoid();
+		const fileId = randomNanoId();
 
 		// Manually insert the file into the file table first
 		await lix.db
@@ -94,7 +94,7 @@ describe("file update", () => {
 			providePlugins: [mockJsonPlugin],
 		});
 		const version = await createVersion({ lix });
-		const fileId = nanoid();
+		const fileId = randomNanoId();
 
 		// Initial JSON data with two users
 		const initialJsonData = {

package/src/file/file-handlers.ts

@@ -28,6 +28,25 @@ export function handleFileInsert(args: {
 	versionId: string;
 	untracked?: boolean;
 }): 0 | 1 {
+	const [shouldSkip] = executeSync({
+		lix: args.lix,
+		query: args.lix.db
+			.selectFrom("key_value")
+			.where("key", "=", "lix_skip_file_handlers")
+			.select("value"),
+	});
+
+	if (shouldSkip) {
+		// If skip flag is set, do not process the file
+		createLixOwnLogSync({
+			lix: args.lix,
+			key: "lix_file_skipped_insert_handler",
+			level: "debug",
+			message: `Skipping file insert for ${args.file.path} due to lix_skip_file_handlers flag`,
+		});
+		return 1; // Indicate no changes were made
+	}
+
 	// Insert the file metadata into state table
 	executeSync({
 		lix: args.lix,
@@ -40,6 +59,7 @@ export function handleFileInsert(args: {
 				id: args.file.id,
 				path: args.file.path,
 				metadata: args.file.metadata || null,
+				hidden: args.file.hidden ?? false,
 			},
 			schema_version: LixFileDescriptorSchema["x-lix-version"],
 			version_id: args.versionId,
@@ -179,6 +199,25 @@ export function handleFileUpdate(args: {
 	versionId: string;
 	untracked?: boolean;
 }): 0 | 1 {
+	const [shouldSkip] = executeSync({
+		lix: args.lix,
+		query: args.lix.db
+			.selectFrom("key_value")
+			.where("key", "=", "lix_skip_file_handlers")
+			.select("value"),
+	});
+
+	if (shouldSkip) {
+		// If skip flag is set, do not process the file
+		createLixOwnLogSync({
+			lix: args.lix,
+			key: "lix_file_skipped_update_handler",
+			level: "debug",
+			message: `Skipping file update for ${args.file.path} due to lix_skip_file_handlers flag`,
+		});
+		return 1; // Indicate no changes were made
+	}
+
 	// Update the file metadata in state table
 	executeSync({
 		lix: args.lix,
@@ -189,6 +228,7 @@ export function handleFileUpdate(args: {
 					id: args.file.id,
 					path: args.file.path,
 					metadata: args.file.metadata || null,
+					hidden: args.file.hidden ?? false,
 				},
 				untracked: args.untracked || false,
 			})

package/src/file/materialize-file-data-at-commit.ts

@@ -0,0 +1,157 @@
+import { executeSync } from "../database/execute-sync.js";
+import type { Lix } from "../lix/open-lix.js";
+import type { LixFile } from "./schema.js";
+import { lixUnknownFileFallbackPlugin } from "./unknown-file-fallback-plugin.js";
+
+function globSync(args: {
+	lix: Pick<Lix, "sqlite">;
+	glob: string;
+	path: string;
+}): boolean {
+	const columnNames: string[] = [];
+	const result = args.lix.sqlite.exec({
+		sql: `SELECT CASE WHEN ? GLOB ? THEN 1 ELSE 0 END AS matches`,
+		bind: [args.path, args.glob],
+		returnValue: "resultRows",
+		columnNames,
+	});
+
+	return (result[0]?.[0] as any) === 1;
+}
+
+export function materializeFileDataAtCommit(args: {
+	lix: Pick<Lix, "sqlite" | "plugin" | "db">;
+	file: Omit<LixFile, "data">;
+	rootCommitId: string;
+	depth: number;
+}): Uint8Array {
+	const plugins = args.lix.plugin.getAllSync();
+
+	// First, try to find a specific plugin that can handle this file (excluding fallback)
+	for (const plugin of plugins) {
+		if (
+			!plugin.detectChangesGlob ||
+			!globSync({
+				lix: args.lix,
+				path: args.file.path,
+				glob: plugin.detectChangesGlob,
+			})
+		) {
+			continue;
+		}
+
+		if (!plugin.applyChanges) {
+			continue;
+		}
+
+		// Get plugin changes from state_history table
+		const changes = executeSync({
+			lix: args.lix,
+			query: selectFileChanges({
+				lix: args.lix,
+				pluginKey: plugin.key,
+				fileId: args.file.id,
+				rootCommitId: args.rootCommitId,
+				depth: args.depth,
+			}),
+		});
+
+		// Format changes for plugin
+		const formattedChanges = changes.map((change) => ({
+			...change,
+			snapshot_content:
+				typeof change.snapshot_content === "string"
+					? JSON.parse(change.snapshot_content)
+					: change.snapshot_content,
+		}));
+
+		const file = plugin.applyChanges({
+			file: args.file,
+			changes: formattedChanges,
+		});
+
+		return file.fileData;
+	}
+
+	// If no specific plugin matched, use the fallback plugin
+	const changes = executeSync({
+		lix: args.lix,
+		query: selectFileChanges({
+			lix: args.lix,
+			pluginKey: lixUnknownFileFallbackPlugin.key,
+			fileId: args.file.id,
+			rootCommitId: args.rootCommitId,
+			depth: args.depth,
+		}),
+	});
+
+	// Format changes for plugin
+	const formattedChanges = changes.map((change) => ({
+		...change,
+		snapshot_content:
+			typeof change.snapshot_content === "string"
+				? JSON.parse(change.snapshot_content)
+				: change.snapshot_content,
+	}));
+
+	if (formattedChanges.length === 0) {
+		throw new Error(
+			`[materializeFileDataAtCommit] No changes found for file ${args.file.id} with plugin ${lixUnknownFileFallbackPlugin.key} at root commit ${args.rootCommitId} depth ${args.depth}. Cannot materialize file data.`
+		);
+	}
+
+	const file = lixUnknownFileFallbackPlugin.applyChanges!({
+		file: args.file,
+		changes: formattedChanges,
+	});
+
+	return file.fileData;
+}
+
+function selectFileChanges(args: {
+	lix: Pick<Lix, "db">;
+	pluginKey: string;
+	fileId: string;
+	rootCommitId: string;
+	depth: number;
+}) {
+	return args.lix.db
+		.selectFrom("state_history as sh1")
+		.where("sh1.plugin_key", "=", args.pluginKey)
+		.where("sh1.file_id", "=", args.fileId)
+		.where("sh1.root_commit_id", "=", args.rootCommitId)
+		.where("sh1.depth", ">=", args.depth)
+		.where("sh1.depth", "=", (eb) =>
+			// This subquery finds the "leaf state" for each entity at the requested depth in history.
+			//
+			// What this does: "For each entity in the file, find its most recent state that existed
+			// at or before the requested depth. Some entities might have changed at depth 0, others
+			// might be unchanged since depth 5 - we need all of them to reconstruct the complete file."
+			//
+			// Example: Requesting depth=1 for a JSON file
+			// - "name" entity: last changed at depth=3 (unchanged for 3 changesets)
+			// - "value" entity: last changed at depth=1 (changed 1 changeset ago)
+			// - "description" entity: last changed at depth=0 (just changed)
+			//
+			// Result: We get "name" from depth=3 and "value" from depth=1 (ignoring "description" at depth=0)
+			//
+			// args.depth: The depth we want to reconstruct the file at (0=current, higher=further back in history)
+			// >= args.depth: Go backwards in history to find all entities that existed at or before this point
+			// min(depth): For each entity, get its most recent state (leaf) at or after the requested depth
+			eb
+				.selectFrom("state_history as sh2")
+				.select((eb) => eb.fn.min("sh2.depth").as("min_depth"))
+				.whereRef("sh2.entity_id", "=", "sh1.entity_id")
+				.whereRef("sh2.file_id", "=", "sh1.file_id")
+				.whereRef("sh2.plugin_key", "=", "sh1.plugin_key")
+				.whereRef("sh2.root_commit_id", "=", "sh1.root_commit_id")
+				.where("sh2.depth", ">=", args.depth)
+		)
+		.select([
+			"sh1.entity_id",
+			"sh1.schema_key",
+			"sh1.file_id",
+			"sh1.plugin_key",
+			"sh1.snapshot_content",
+		]);
+}