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

package/src/state-history/schema.ts

@@ -0,0 +1,198 @@
+import type { Selectable } from "kysely";
+import type { SqliteWasmDatabase } from "sqlite-wasm-kysely";
+
+/**
+ * State history table interface for querying historical entity states.
+ *
+ * This view provides access to entity states at specific points in change set history,
+ * with depth-based traversal for blame functionality and diff operations.
+ */
+export interface StateHistoryTable {
+	/** Unique identifier of the entity */
+	entity_id: string;
+
+	/** Schema type identifier (e.g., 'paragraph', 'comment') */
+	schema_key: string;
+
+	/** File identifier where this entity is stored */
+	file_id: string;
+
+	/** Plugin identifier that manages this entity type */
+	plugin_key: string;
+
+	/** JSON content of the entity at this point in history */
+	snapshot_content: Record<string, any>;
+
+	/** Version of the schema used for this entity */
+	schema_version: string;
+
+	/**
+	 * ID of the change that created this entity state.
+	 * Join with the `change` table to get created_at, author info, and other change metadata.
+	 * Example: `JOIN change ON state_history.change_id = change.id`
+	 */
+	change_id: string;
+
+	/**
+	 * Change set ID that serves as the root/starting point for depth calculation.
+	 * This is the change_set_id that was queried, NOT the change set where this
+	 * specific entity state was originally created.
+	 *
+	 * For example, if you query `WHERE change_set_id = 'checkpoint-123'`, then
+	 * all returned rows will have `change_set_id = 'checkpoint-123'`, even if
+	 * some entity states came from earlier change sets (at depth > 0).
+	 *
+	 * To get the actual change set where this entity state was created,
+	 * join with the change table: `JOIN change ON state_history.change_id = change.id`
+	 * and then `JOIN change_set_element ON change.id = change_set_element.change_id`.
+	 */
+	change_set_id: string;
+
+	/**
+	 * Depth of this entity state relative to the queried change_set_id.
+	 * - depth = 0: Current state at the queried change_set_id
+	 * - depth = 1: One change set back in history (parent)
+	 * - depth = 2: Two change sets back in history (grandparent)
+	 * - etc.
+	 *
+	 * Depth is calculated by traversing the change set ancestry graph backwards
+	 * from the queried change_set_id through parent change set edges.
+	 * Used for blame functionality to show how entities evolved over time.
+	 */
+	depth: number;
+
+	/**
+	 * TODO https://github.com/opral/lix-sdk/issues/320
+	 *
+	 * JSON array of change-set IDs that are the direct parents of the given change-set.
+	 * For a merge change set this array has ≥2 IDs; for the initial version it is empty.
+	 *
+	 * Use the property to display graphs in the UI by providing parent relationships.
+	 *
+	 * Example change set graph (newest to oldest):
+	 *
+	 * ```
+	 *     A (parent_change_set_ids: ["B"])      <- queried change set
+	 *     |
+	 *     B (parent_change_set_ids: ["C","D"])  <- merge change set
+	 *    / \
+	 *   C   D (parent_change_set_ids: ["E"], ["F"])
+	 *   |   |
+	 *   |   F (parent_change_set_ids: ["E"])
+	 *    \ /
+	 *     E (parent_change_set_ids: ["G"])      <- common ancestor of C & F
+	 *     |
+	 *     G (parent_change_set_ids: [])         <- initial (no parents)
+	 * ```
+	 */
+	// parent_change_set_ids: string[];
+}
+
+export type StateHistoryView = Selectable<StateHistoryTable>;
+
+export function applyStateHistoryDatabaseSchema(
+	sqlite: SqliteWasmDatabase
+): SqliteWasmDatabase {
+	sqlite.exec(STATE_HISTORY_VIEW_SQL);
+	return sqlite;
+}
+
+// Optimized to use materialized change_set_edge_all and change_set_element_all from global version
+export const STATE_HISTORY_VIEW_SQL = `
+CREATE VIEW IF NOT EXISTS state_history AS
+WITH
+	-- Get all changes with their snapshots
+	all_changes_with_snapshots AS (
+		SELECT ic.id, ic.entity_id, ic.schema_key, ic.file_id, ic.plugin_key,
+			   ic.schema_version, ic.created_at,
+			   CASE 
+			     WHEN ic.snapshot_id = 'no-content' THEN NULL
+			     ELSE json(s.content)
+			   END AS snapshot_content 
+		FROM internal_change ic
+		LEFT JOIN internal_snapshot s ON ic.snapshot_id = s.id
+	),
+	-- For state_history, we work with any change_set_id, not just version heads
+	requested_change_sets AS (
+		SELECT DISTINCT cs.id as change_set_id
+		FROM change_set_all cs
+		-- This will be filtered by the WHERE clause in queries
+	),
+	-- Find all change sets reachable from requested ones (including ancestors)
+	reachable_cs_from_requested(id, root_change_set_id, depth) AS (
+		SELECT change_set_id, change_set_id as root_change_set_id, 0 as depth 
+		FROM requested_change_sets
+		UNION
+		SELECT cse.parent_id, r.root_change_set_id, r.depth + 1
+		FROM change_set_edge_all cse 
+		JOIN reachable_cs_from_requested r ON cse.child_id = r.id
+		WHERE cse.lixcol_version_id = 'global'
+	),
+	-- Find all change set elements in reachable change sets
+	cse_in_reachable_cs AS (
+		SELECT cse.entity_id AS target_entity_id,
+			   cse.file_id AS target_file_id,
+			   cse.schema_key AS target_schema_key, 
+			   cse.change_id AS target_change_id,
+			   cse.change_set_id AS cse_origin_change_set_id,
+			   rcs.root_change_set_id,
+			   rcs.depth as changeset_depth,
+			   rcs.id as depth_change_set_id
+		FROM change_set_element_all cse
+		JOIN reachable_cs_from_requested rcs ON cse.change_set_id = rcs.id
+		WHERE cse.lixcol_version_id = 'global'
+	),
+	-- For each entity at each depth, find the latest change within that depth's change set
+	latest_change_per_entity_per_depth AS (
+		SELECT 
+			r.target_entity_id,
+			r.target_file_id,
+			r.target_schema_key,
+			r.root_change_set_id,
+			r.changeset_depth,
+			r.depth_change_set_id,
+			MAX(target_change.created_at) as latest_created_at
+		FROM cse_in_reachable_cs r 
+		INNER JOIN all_changes_with_snapshots target_change ON r.target_change_id = target_change.id
+		GROUP BY r.target_entity_id, r.target_file_id, r.target_schema_key, r.root_change_set_id, r.changeset_depth
+	),
+	-- Get the actual changes for each entity at each depth
+	entity_states_at_depths AS (
+		SELECT 
+			target_change.entity_id, 
+			target_change.schema_key, 
+			target_change.file_id,
+			target_change.plugin_key, 
+			target_change.snapshot_content,
+			target_change.schema_version,
+			r.target_change_id,
+			r.cse_origin_change_set_id,
+			r.root_change_set_id,
+			latest.changeset_depth
+		FROM latest_change_per_entity_per_depth latest
+		INNER JOIN cse_in_reachable_cs r ON (
+			latest.target_entity_id = r.target_entity_id 
+			AND latest.target_file_id = r.target_file_id
+			AND latest.target_schema_key = r.target_schema_key
+			AND latest.root_change_set_id = r.root_change_set_id
+			AND latest.changeset_depth = r.changeset_depth
+		)
+		INNER JOIN all_changes_with_snapshots target_change ON (
+			r.target_change_id = target_change.id
+			AND target_change.created_at = latest.latest_created_at
+		)
+	)
+SELECT 
+	esad.entity_id,
+	esad.schema_key,
+	esad.file_id,
+	esad.plugin_key,
+	esad.snapshot_content,
+	esad.schema_version,
+	esad.target_change_id as change_id,
+	esad.root_change_set_id as change_set_id,
+	esad.changeset_depth as depth
+FROM entity_states_at_depths esad
+WHERE esad.snapshot_content IS NOT NULL  -- Exclude deletions for now
+ORDER BY esad.entity_id, esad.changeset_depth;
+`;

package/src/stored-schema/index.ts

@@ -0,0 +1 @@
+export { LixStoredSchemaSchema, type StoredSchema } from "./schema.js";

package/src/stored-schema/schema.test.ts

@@ -0,0 +1,240 @@
+import { test, expect } from "vitest";
+import { openLix } from "../lix/open-lix.js";
+import type { LixSchemaDefinition } from "../schema-definition/definition.js";
+import type { NewState } from "../entity-views/types.js";
+import type { StoredSchema } from "./schema.js";
+
+test("insert and delete a stored schema", async () => {
+	const lix = await openLix({});
+
+	const schema: NewState<StoredSchema> = {
+		value: {
+			type: "object",
+			"x-lix-key": "mock",
+			"x-lix-version": "1.0",
+			properties: {
+				name: { type: "string" },
+			},
+			required: ["name"],
+			additionalProperties: false,
+		},
+	};
+
+	await lix.db.insertInto("stored_schema").values(schema).execute();
+
+	const afterInsert = await lix.db
+		.selectFrom("stored_schema")
+		.selectAll()
+		.where("key", "=", "mock")
+		.where("version", "=", "1.0")
+		.executeTakeFirst();
+
+	expect(afterInsert).toMatchObject({
+		key: "mock",
+		version: "1.0",
+		value: schema.value,
+	});
+
+	await lix.db.deleteFrom("stored_schema").where("key", "=", "mock").execute();
+
+	const afterDelete = await lix.db
+		.selectFrom("stored_schema")
+		.selectAll()
+		.where("key", "=", "mock")
+		.where("version", "=", "1.0")
+		.execute();
+
+	expect(afterDelete).toHaveLength(0);
+});
+
+test("throws if the stored schema version does not match the x-lix-version prop", async () => {
+	const lix = await openLix({});
+
+	const schema: NewState<StoredSchema> = {
+		version: "2.0",
+		key: "mock",
+		value: {
+			type: "object",
+			"x-lix-key": "mock",
+			"x-lix-version": "1.0",
+			properties: {
+				name: { type: "string" },
+			},
+			required: ["name"],
+			additionalProperties: false,
+		},
+	};
+
+	await expect(
+		lix.db.insertInto("stored_schema").values(schema).execute()
+	).rejects.toThrow(/Inserted version does not match value\.x-lix-version/);
+});
+
+test("throws if the stored schema key does not match the x-lix-key prop", async () => {
+	const lix = await openLix({});
+
+	const schema: NewState<StoredSchema> = {
+		key: "mock",
+		version: "1.0",
+		value: {
+			type: "object",
+			"x-lix-key": "mock2",
+			"x-lix-version": "1.0",
+			properties: {
+				name: { type: "string" },
+			},
+			required: ["name"],
+			additionalProperties: false,
+		},
+	};
+
+	await expect(
+		lix.db.insertInto("stored_schema").values(schema).execute()
+	).rejects.toThrow(/Inserted key does not match value\.x-lix-key/);
+});
+
+test("updating is not possible (schema is immutable, needs new version bumb)", async () => {
+	const lix = await openLix({});
+
+	const schema: NewState<StoredSchema> = {
+		value: {
+			type: "object",
+			"x-lix-key": "mock",
+			"x-lix-version": "1.0",
+			properties: {
+				name: { type: "string" },
+			},
+			required: ["name"],
+			additionalProperties: false,
+		},
+	};
+
+	await lix.db.insertInto("stored_schema").values(schema).execute();
+
+	await expect(
+		lix.db.updateTable("stored_schema").set({ version: "2.0" }).execute()
+	).rejects.toThrow(
+		/Schemas are immutable and cannot be updated for backwards compatibility. Bump the version number instead./
+	);
+});
+
+test("default fills in key and version from the schema value", async () => {
+	const lix = await openLix({});
+
+	const schema: NewState<StoredSchema> = {
+		value: {
+			"x-lix-key": "mock",
+			"x-lix-version": "1.0",
+			type: "object",
+			properties: {
+				name: { type: "string" },
+			},
+			required: ["name"],
+			additionalProperties: false,
+		},
+	};
+
+	await lix.db.insertInto("stored_schema").values(schema).execute();
+
+	const result = await lix.db
+		.selectFrom("stored_schema")
+		.selectAll()
+		.where("key", "=", "mock")
+		.executeTakeFirstOrThrow();
+
+	expect(result.key).toBe("mock");
+	expect(result.version).toBe("1.0");
+});
+
+test("validates inserted schemas", async () => {
+	const lix = await openLix({});
+
+	const schema: NewState<StoredSchema> = {
+		value: {
+			type: "object",
+			"x-lix-key": "mock",
+			"x-lix-version": 1,
+			properties: {
+				name: { type: "string" },
+			},
+			required: ["name"],
+			additionalProperties: false,
+		},
+	};
+
+	await expect(
+		lix.db.insertInto("stored_schema").values(schema).execute()
+	).rejects.toThrow(/version must be string/);
+});
+
+test("can insert into stored_schema_all with explicit key and version", async () => {
+	const lix = await openLix({});
+
+	const schema: LixSchemaDefinition = {
+		type: "object",
+		"x-lix-key": "mock_all",
+		"x-lix-version": "1.0",
+		properties: {
+			name: { type: "string" },
+		},
+		required: ["name"],
+		additionalProperties: false,
+	};
+
+	// Insert with explicit key and version
+	await lix.db
+		.insertInto("stored_schema_all")
+		.values({
+			key: "mock_all",
+			version: "1.0",
+			value: schema,
+			lixcol_version_id: "global",
+		})
+		.execute();
+
+	const result = await lix.db
+		.selectFrom("stored_schema_all")
+		.selectAll()
+		.where("key", "=", "mock_all")
+		.where("version", "=", "1.0")
+		.executeTakeFirstOrThrow();
+
+	expect(result.key).toBe("mock_all");
+	expect(result.version).toBe("1.0");
+	expect(result.value).toEqual(schema);
+});
+
+test("can insert into stored_schema_all with default key and version extraction", async () => {
+	const lix = await openLix({});
+
+	const schema: LixSchemaDefinition = {
+		type: "object",
+		"x-lix-key": "mock_extract",
+		"x-lix-version": "2.0",
+		properties: {
+			name: { type: "string" },
+		},
+		required: ["name"],
+		additionalProperties: false,
+	};
+
+	// Insert without key and version - should be extracted from value
+	await lix.db
+		.insertInto("stored_schema_all")
+		.values({
+			value: schema,
+			lixcol_version_id: "global",
+		})
+		.execute();
+
+	const result = await lix.db
+		.selectFrom("stored_schema_all")
+		.selectAll()
+		.where("key", "=", "mock_extract")
+		.where("version", "=", "2.0")
+		.executeTakeFirstOrThrow();
+
+	expect(result.key).toBe("mock_extract");
+	expect(result.version).toBe("2.0");
+	expect(result.value).toEqual(schema);
+});

package/src/stored-schema/schema.ts

@@ -0,0 +1,67 @@
+import type { SqliteWasmDatabase } from "sqlite-wasm-kysely";
+import type {
+	LixSchemaDefinition,
+	FromLixSchemaDefinition,
+} from "../schema-definition/definition.js";
+import { JSONTypeSchema } from "../schema-definition/json-type.js";
+import { createEntityViewsIfNotExists } from "../entity-views/entity-view-builder.js";
+
+export function applyStoredSchemaDatabaseSchema(
+	sqlite: SqliteWasmDatabase
+): void {
+	// Create both primary and _all views for stored_schema with validation
+	createEntityViewsIfNotExists({
+		lix: { sqlite },
+		schema: LixStoredSchemaSchema,
+		overrideName: "stored_schema",
+		pluginKey: "lix_own_entity",
+		hardcodedFileId: "lix",
+		defaultValues: {
+			key: (row) => row.value?.["x-lix-key"] || "",
+			version: (row) => row.value?.["x-lix-version"] || "",
+		},
+		validation: {
+			onInsert: [
+				{
+					condition:
+						"NEW.key IS NULL OR NEW.key = json_extract(NEW.value, '$.x-lix-key')",
+					errorMessage: `Inserted key does not match value.x-lix-key: key=" || NEW.key || " x-lix-key=" || json_extract(NEW.value, '$.x-lix-key')`,
+				},
+				{
+					condition:
+						"NEW.version IS NULL OR NEW.version = json_extract(NEW.value, '$.x-lix-version')",
+					errorMessage: `Inserted version does not match value.x-lix-version: version=" || NEW.version || " x-lix-version=" || json_extract(NEW.value, '$.x-lix-version')`,
+				},
+			],
+			onUpdate: [
+				{
+					condition: "0", // Always fail
+					errorMessage:
+						"Schemas are immutable and cannot be updated for backwards compatibility. Bump the version number instead.",
+				},
+			],
+		},
+	});
+}
+
+export const LixStoredSchemaSchema = {
+	"x-lix-key": "lix_stored_schema",
+	"x-lix-version": "1.0",
+	"x-lix-primary-key": ["key", "version"],
+	type: "object",
+	properties: {
+		key: { type: "string", "x-lix-generated": true },
+		version: { type: "string", "x-lix-generated": true },
+		value: JSONTypeSchema as any,
+	},
+	additionalProperties: false,
+} as const;
+
+LixStoredSchemaSchema satisfies LixSchemaDefinition;
+
+export type StoredSchema = FromLixSchemaDefinition<
+	typeof LixStoredSchemaSchema
+> & {
+	// override the value to any to allow any JSON type (instead of unknown which is annoying)
+	value: any;
+};

package/src/sync/get-diffing-rows.ts

@@ -1,6 +1,22 @@
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-nocheck
+
 import type { Lix } from "../lix/open-lix.js";
 import type { VectorClock } from "./merge-state.js";
 
+/**
+ * Collects all database rows that differ from a target state.
+ *
+ * The returned rows can be upserted on the target to synchronise two
+ * Lix instances. The current vector clock of this Lix file is also
+ * returned to let the remote side calculate its own diff.
+ *
+ * @example
+ * ```ts
+ * const { upsertedRows } = await getDiffingRows({ lix, targetVectorClock })
+ * ```
+ */
+
 export async function getDiffingRows(args: {
 	/**
 	 * the lix to merge their state into

package/src/sync/merge-state.ts

@@ -1,7 +1,10 @@
-import {
-	tableIdColumns,
-	tablesByDepencies,
-} from "../database/mutation-log/database-schema.js";
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-nocheck
+
+// import {
+// 	tableIdColumns,
+// 	tablesByDepencies,
+// } from "../database/mutation-log/database-schema.js";
 import type { Lix } from "../lix/open-lix.js";
 
 export type VectorClock = {