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

package/src/state-history/schema.ts

@@ -1,288 +0,0 @@
-import type { Selectable } from "kysely";
-import type { LixEngine } from "../engine/boot.js";
-
-/**
- * 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>;
-
-	/** Optional change metadata associated with this historical state. */
-	metadata: Record<string, any> | null;
-
-	/** 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;
-
-	/**
-	 * The actual commit ID where this entity state was originally created.
-	 *
-	 * This represents the true origin commit for each historical state, making it easy
-	 * to understand the provenance of each entity state without additional joins.
-	 *
-	 * For example, when viewing history you might see:
-	 * - depth 0: commit_id = 'commit-123' (current state created in commit-123)
-	 * - depth 2: commit_id = 'commit-100' (historical state created in commit-100)
-	 *
-	 * This tells you exactly where each state was created in the commit graph.
-	 */
-	commit_id: string;
-
-	/**
-	 * The root commit ID used as the starting point for traversing history.
-	 *
-	 * When querying history from a specific commit, this field contains that
-	 * commit ID for all returned rows. Used with `depth` to understand how
-	 * far back in history each entity state is from this root.
-	 *
-	 * For example, if you query `WHERE root_commit_id = 'commit-123'`,
-	 * all returned rows will have `root_commit_id = 'commit-123'`.
-	 */
-	root_commit_id: string;
-
-	/**
-	 * Depth of this entity state relative to the root_commit_id.
-	 * - depth = 0: Current state at the queried commit_id
-	 * - depth = 1: One commit back in history (parent)
-	 * - depth = 2: Two commits back in history (grandparent)
-	 * - etc.
-	 *
-	 * Depth is calculated by traversing the commit ancestry graph backwards
-	 * from the queried commit_id through parent commit 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(args: {
-	engine: Pick<LixEngine, "sqlite">;
-}): void {
-	args.engine.sqlite.exec(STATE_HISTORY_VIEW_SQL);
-}
-
-// Optimized to keep the generic history view, but add a fast path for depth=0
-// to avoid whole-graph recursion for common queries like "WHERE depth = 0".
-export const STATE_HISTORY_VIEW_SQL = `
-CREATE VIEW IF NOT EXISTS state_history AS
-WITH
-	-- Inline entity views to avoid preprocessor dependencies
-	_commit_by_version AS (
-		SELECT 
-			json_extract(s.snapshot_content, '$.id') AS id,
-			json_extract(s.snapshot_content, '$.change_set_id') AS change_set_id,
-			s.version_id AS lixcol_version_id
-		FROM state_by_version AS s
-		WHERE s.schema_key = 'lix_commit'
-			AND s.snapshot_content IS NOT NULL
-	),
-	_change_set_element_by_version AS (
-		SELECT
-			json_extract(s.snapshot_content, '$.change_set_id') AS change_set_id,
-			json_extract(s.snapshot_content, '$.change_id') AS change_id,
-			json_extract(s.snapshot_content, '$.entity_id') AS entity_id,
-			json_extract(s.snapshot_content, '$.schema_key') AS schema_key,
-			json_extract(s.snapshot_content, '$.file_id') AS file_id,
-			s.version_id AS lixcol_version_id
-		FROM state_by_version AS s
-		WHERE s.schema_key = 'lix_change_set_element'
-			AND s.snapshot_content IS NOT NULL
-	),
-	_commit_edge_by_version AS (
-		SELECT
-			json_extract(s.snapshot_content, '$.parent_id') AS parent_id,
-			json_extract(s.snapshot_content, '$.child_id') AS child_id,
-			s.version_id AS lixcol_version_id
-		FROM state_by_version AS s
-		WHERE s.schema_key = 'lix_commit_edge'
-			AND s.snapshot_content IS NOT NULL
-	),
-
-	-- 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,
-			   CASE
-			     WHEN ic.metadata IS NULL THEN NULL
-			     ELSE json(ic.metadata)
-			   END AS metadata
-		FROM lix_internal_change ic
-		LEFT JOIN lix_internal_snapshot s ON ic.snapshot_id = s.id
-	),
-
-	-- Fast path for depth = 0 (no recursion, direct commit join)
-	depth0_entity_states AS (
-		SELECT 
-			chg.entity_id,
-			chg.schema_key,
-			chg.file_id,
-			chg.plugin_key,
-			chg.snapshot_content,
-			chg.metadata,
-			chg.schema_version,
-			cse.change_id AS target_change_id,
-			c.id AS origin_commit_id,
-			c.id AS root_commit_id,
-			0 AS commit_depth
-		FROM _change_set_element_by_version cse
-		JOIN _commit_by_version c 
-			ON cse.change_set_id = c.change_set_id 
-			AND c.lixcol_version_id = 'global'
-		JOIN all_changes_with_snapshots chg 
-			ON chg.id = cse.change_id
-		WHERE cse.lixcol_version_id = 'global'
-	),
-
-	-- General path for depth > 0 (recursive, ancestors of requested commits)
-	requested_commits AS (
-		SELECT DISTINCT c.id as commit_id
-		FROM _commit_by_version c
-	),
-	reachable_commits_from_requested(id, root_commit_id, depth) AS (
-		SELECT commit_id, commit_id as root_commit_id, 0 as depth 
-		FROM requested_commits
-		UNION
-		SELECT ce.parent_id, r.root_commit_id, r.depth + 1
-		FROM _commit_edge_by_version ce 
-		JOIN reachable_commits_from_requested r ON ce.child_id = r.id
-		WHERE ce.lixcol_version_id = 'global'
-	),
-	commit_changesets AS (
-		SELECT 
-			c.id as commit_id,
-			c.change_set_id as change_set_id,
-			rc.root_commit_id,
-			rc.depth as commit_depth
-		FROM _commit_by_version c
-		JOIN reachable_commits_from_requested rc ON c.id = rc.id
-		WHERE c.lixcol_version_id = 'global'
-	),
-	cse_in_reachable_commits 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,
-			   cc.commit_id AS origin_commit_id,
-			   cc.root_commit_id,
-			   cc.commit_depth,
-			   cc.commit_id as depth_commit_id
-		FROM _change_set_element_by_version cse
-		JOIN commit_changesets cc ON cse.change_set_id = cc.change_set_id
-		WHERE cse.lixcol_version_id = 'global'
-	),
-	latest_change_per_entity_per_depth AS (
-		SELECT 
-			r.target_entity_id,
-			r.target_file_id,
-			r.target_schema_key,
-			r.root_commit_id,
-			r.commit_depth,
-			r.depth_commit_id,
-			MAX(target_change.created_at) as latest_created_at
-		FROM cse_in_reachable_commits 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_commit_id, r.commit_depth
-	),
-	depthN_entity_states AS (
-		SELECT 
-			target_change.entity_id, 
-			target_change.schema_key, 
-			target_change.file_id,
-			target_change.plugin_key, 
-			target_change.snapshot_content,
-			target_change.metadata,
-			target_change.schema_version,
-			r.target_change_id,
-			r.origin_commit_id,
-			r.root_commit_id,
-			latest.commit_depth
-		FROM latest_change_per_entity_per_depth latest
-		INNER JOIN cse_in_reachable_commits 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_commit_id = r.root_commit_id
-			AND latest.commit_depth = r.commit_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
-		)
-		WHERE latest.commit_depth > 0
-	)
-
-SELECT 
-	es.entity_id,
-	es.schema_key,
-	es.file_id,
-	es.plugin_key,
-	es.snapshot_content,
-	es.metadata,
-	es.schema_version,
-	es.target_change_id as change_id,
-	es.origin_commit_id as commit_id,
-	es.root_commit_id as root_commit_id,
-	es.commit_depth as depth,
-	'global' as version_id
-FROM (
-	SELECT * FROM depth0_entity_states
-	UNION ALL
-	SELECT * FROM depthN_entity_states
-) AS es
-WHERE es.snapshot_content IS NOT NULL  -- Exclude deletions for now
-ORDER BY es.entity_id, es.commit_depth;
-`;

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

@@ -1,352 +0,0 @@
-import { test, expect, vi } from "vitest";
-import { sql } from "kysely";
-import { openLix } from "../lix/open-lix.js";
-import type { LixSchemaDefinition } from "../schema-definition/definition.js";
-import { getStoredSchema, getAllStoredSchemas } from "./get-stored-schema.js";
-import { createVersion } from "../version/create-version.js";
-import { LixStoredSchemaSchema } from "./schema-definition.js";
-import { internalQueryBuilder } from "../engine/internal-query-builder.js";
-import type { StateCommitChange } from "../hooks/create-hooks.js";
-
-const ALL_STORED_SCHEMAS_SQL = internalQueryBuilder
-	.selectFrom("lix_internal_state_vtable")
-	.select(["snapshot_content", "updated_at"])
-	.where("schema_key", "=", LixStoredSchemaSchema["x-lix-key"])
-	.where("snapshot_content", "is not", null)
-	.compile().sql;
-
-const SINGLE_STORED_SCHEMA_SQL = internalQueryBuilder
-	.selectFrom("lix_internal_state_vtable")
-	.select(sql`json_extract(snapshot_content, '$.value')`.as("value"))
-	.where("schema_key", "=", LixStoredSchemaSchema["x-lix-key"])
-	.where(sql`json_extract(snapshot_content, '$.value."x-lix-key"')`, "=", "")
-	.where("version_id", "=", "global")
-	.where("snapshot_content", "is not", null)
-	.orderBy(
-		sql`json_extract(snapshot_content, '$.value."x-lix-version"')`,
-		"desc"
-	)
-	.limit(1)
-	.compile().sql;
-
-const countCallsForSql = (
-	calls: ReadonlyArray<ReadonlyArray<unknown>>,
-	targetSql: string
-) =>
-	calls.filter(
-		([args]) => (args as { sql?: string } | undefined)?.sql === targetSql
-	).length;
-
-const createStoredSchemaHookChange = (): StateCommitChange => ({
-	id: "hook-change",
-	entity_id: "stored-schema",
-	schema_key: "lix_stored_schema",
-	schema_version: "1.0",
-	file_id: "lix",
-	plugin_key: "lix_own_entity",
-	created_at: "1970-01-01T00:00:00.000Z",
-	snapshot_content: null,
-	version_id: "global",
-	commit_id: "stored-schema-commit",
-	untracked: 0,
-	metadata: null,
-	writer_key: null,
-});
-
-test("returns null when no stored schema is found", async () => {
-	const lix = await openLix({});
-
-	const schema = getStoredSchema({ engine: lix.engine!, key: "missing" });
-	expect(schema).toBeNull();
-});
-
-test("returns the latest stored schema version for a key", async () => {
-	const lix = await openLix({});
-
-	const base: LixSchemaDefinition = {
-		type: "object",
-		"x-lix-key": "test_schema",
-		"x-lix-version": "1.0",
-		properties: { id: { type: "string" } },
-		required: ["id"],
-		additionalProperties: false,
-	};
-
-	await lix.db
-		.insertInto("stored_schema_by_version")
-		.values({ value: base, lixcol_version_id: "global" })
-		.execute();
-
-	await lix.db
-		.insertInto("stored_schema_by_version")
-		.values({
-			value: { ...base, "x-lix-version": "2.0" },
-			lixcol_version_id: "global",
-		})
-		.execute();
-
-	const schema = getStoredSchema({
-		engine: lix.engine!,
-		key: "test_schema",
-	});
-
-	expect(schema).not.toBeNull();
-	expect(schema?.["x-lix-version"]).toBe("2.0");
-});
-
-test("ignores schemas outside the global version", async () => {
-	const lix = await openLix({});
-
-	const featureVersion = await createVersion({
-		lix,
-		id: "feature",
-		name: "Feature",
-	});
-
-	const base: LixSchemaDefinition = {
-		type: "object",
-		"x-lix-key": "global_only_schema",
-		"x-lix-version": "1.0",
-		properties: { id: { type: "string" } },
-		required: ["id"],
-		additionalProperties: false,
-	};
-
-	await lix.db
-		.insertInto("stored_schema_by_version")
-		.values({ value: base, lixcol_version_id: "global" })
-		.execute();
-
-	await lix.db
-		.insertInto("stored_schema_by_version")
-		.values({
-			value: { ...base, "x-lix-version": "3.0" },
-			lixcol_version_id: featureVersion.id,
-		})
-		.execute();
-
-	const schema = getStoredSchema({
-		engine: lix.engine!,
-		key: "global_only_schema",
-	});
-
-	expect(schema).not.toBeNull();
-	expect(schema?.["x-lix-version"]).toBe("1.0");
-});
-
-test("getAllStoredSchemas returns all definitions and caches the result", async () => {
-	const lix = await openLix({});
-
-	const schemas: LixSchemaDefinition[] = [
-		{
-			type: "object",
-			"x-lix-key": "schema_one",
-			"x-lix-version": "1.0",
-			properties: { id: { type: "string" } },
-			required: ["id"],
-			additionalProperties: false,
-		},
-		{
-			type: "object",
-			"x-lix-key": "schema_two",
-			"x-lix-version": "1.0",
-			properties: { id: { type: "string" } },
-			required: ["id"],
-			additionalProperties: false,
-		},
-	];
-
-	for (const schema of schemas) {
-		await lix.db
-			.insertInto("stored_schema_by_version")
-			.values({ value: schema, lixcol_version_id: "global" })
-			.execute();
-	}
-
-	const spy = vi.spyOn(lix.engine!, "executeSync");
-
-	const first = getAllStoredSchemas({ engine: lix.engine! });
-	expect(first.definitions.has("schema_one")).toBe(true);
-	expect(first.definitions.has("schema_two")).toBe(true);
-
-	const afterFirst = countCallsForSql(spy.mock.calls, ALL_STORED_SCHEMAS_SQL);
-
-	const second = getAllStoredSchemas({ engine: lix.engine! });
-	expect(second.definitions.has("schema_one")).toBe(true);
-	expect(second.definitions.has("schema_two")).toBe(true);
-	expect(countCallsForSql(spy.mock.calls, ALL_STORED_SCHEMAS_SQL)).toBe(
-		afterFirst
-	);
-
-	spy.mockRestore();
-});
-
-test("getAllStoredSchemas invalidates cache on state commit", async () => {
-	const lix = await openLix({});
-
-	const schema: LixSchemaDefinition = {
-		type: "object",
-		"x-lix-key": "invalidate_all_schema",
-		"x-lix-version": "1.0",
-		properties: { id: { type: "string" } },
-		required: ["id"],
-		additionalProperties: false,
-	};
-
-	await lix.db
-		.insertInto("stored_schema_by_version")
-		.values({ value: schema, lixcol_version_id: "global" })
-		.execute();
-
-	const spy = vi.spyOn(lix.engine!, "executeSync");
-
-	const initial = getAllStoredSchemas({ engine: lix.engine! });
-	expect(initial.definitions.has("invalidate_all_schema")).toBe(true);
-
-	const expectedPerFetch = countCallsForSql(
-		spy.mock.calls,
-		ALL_STORED_SCHEMAS_SQL
-	);
-
-	spy.mockClear();
-
-	lix.engine!.hooks._emit("state_commit", {
-		changes: [createStoredSchemaHookChange()],
-	});
-
-	const afterInvalidate = getAllStoredSchemas({ engine: lix.engine! });
-	expect(afterInvalidate.definitions.has("invalidate_all_schema")).toBe(true);
-	expect(countCallsForSql(spy.mock.calls, ALL_STORED_SCHEMAS_SQL)).toBe(
-		expectedPerFetch
-	);
-
-	spy.mockRestore();
-});
-
-test("getAllStoredSchemas primes getStoredSchema cache", async () => {
-	const lix = await openLix({});
-
-	const schema: LixSchemaDefinition = {
-		type: "object",
-		"x-lix-key": "primed_schema",
-		"x-lix-version": "1.0",
-		properties: { id: { type: "string" } },
-		required: ["id"],
-		additionalProperties: false,
-	};
-
-	await lix.db
-		.insertInto("stored_schema_by_version")
-		.values({ value: schema, lixcol_version_id: "global" })
-		.execute();
-
-	const spy = vi.spyOn(lix.engine!, "executeSync");
-
-	getAllStoredSchemas({ engine: lix.engine! });
-	const callsAfterAllAll = countCallsForSql(
-		spy.mock.calls,
-		ALL_STORED_SCHEMAS_SQL
-	);
-	const callsAfterAllSingle = countCallsForSql(
-		spy.mock.calls,
-		SINGLE_STORED_SCHEMA_SQL
-	);
-
-	const single = getStoredSchema({
-		engine: lix.engine!,
-		key: "primed_schema",
-	});
-	expect(single?.["x-lix-key"]).toBe("primed_schema");
-	expect(countCallsForSql(spy.mock.calls, ALL_STORED_SCHEMAS_SQL)).toBe(
-		callsAfterAllAll
-	);
-	expect(countCallsForSql(spy.mock.calls, SINGLE_STORED_SCHEMA_SQL)).toBe(
-		callsAfterAllSingle
-	);
-
-	spy.mockRestore();
-});
-
-test("caches lookups for identical keys", async () => {
-	const lix = await openLix({});
-
-	const schema: LixSchemaDefinition = {
-		type: "object",
-		"x-lix-key": "cached_schema",
-		"x-lix-version": "1.0",
-		properties: { id: { type: "string" } },
-		required: ["id"],
-		additionalProperties: false,
-	};
-
-	await lix.db
-		.insertInto("stored_schema_by_version")
-		.values({ value: schema, lixcol_version_id: "global" })
-		.execute();
-
-	const spy = vi.spyOn(lix.engine!, "executeSync");
-
-	const first = getStoredSchema({
-		engine: lix.engine!,
-		key: "cached_schema",
-	});
-	expect(first?.["x-lix-version"]).toBe("1.0");
-
-	const afterFirst = countCallsForSql(spy.mock.calls, SINGLE_STORED_SCHEMA_SQL);
-
-	const second = getStoredSchema({
-		engine: lix.engine!,
-		key: "cached_schema",
-	});
-	expect(second?.["x-lix-version"]).toBe("1.0");
-	expect(countCallsForSql(spy.mock.calls, SINGLE_STORED_SCHEMA_SQL)).toBe(
-		afterFirst
-	);
-
-	spy.mockRestore();
-});
-
-test("invalidates the cache when stored schemas change", async () => {
-	const lix = await openLix({});
-
-	const schema: LixSchemaDefinition = {
-		type: "object",
-		"x-lix-key": "cache_invalidate_schema",
-		"x-lix-version": "1.0",
-		properties: { id: { type: "string" } },
-		required: ["id"],
-		additionalProperties: false,
-	};
-
-	await lix.db
-		.insertInto("stored_schema_by_version")
-		.values({ value: schema, lixcol_version_id: "global" })
-		.execute();
-
-	const spy = vi.spyOn(lix.engine!, "executeSync");
-
-	const initial = getStoredSchema({
-		engine: lix.engine!,
-		key: "cache_invalidate_schema",
-	});
-	expect(initial?.["x-lix-version"]).toBe("1.0");
-
-	const perFetch = countCallsForSql(spy.mock.calls, SINGLE_STORED_SCHEMA_SQL);
-
-	spy.mockClear();
-
-	lix.engine!.hooks._emit("state_commit", {
-		changes: [createStoredSchemaHookChange()],
-	});
-
-	const afterInvalidate = getStoredSchema({
-		engine: lix.engine!,
-		key: "cache_invalidate_schema",
-	});
-	expect(afterInvalidate?.["x-lix-version"]).toBe("1.0");
-	expect(countCallsForSql(spy.mock.calls, SINGLE_STORED_SCHEMA_SQL)).toBe(
-		perFetch
-	);
-
-	spy.mockRestore();
-});