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

package/src/engine/with-runtime-cache.test.ts

@@ -1,173 +0,0 @@
-import { describe, expect, test, vi } from "vitest";
-import { sql } from "kysely";
-import { internalQueryBuilder } from "./internal-query-builder.js";
-import { newLixFile } from "../lix/new-lix.js";
-import { openLix } from "../lix/open-lix.js";
-import { withRuntimeCache } from "./with-runtime-cache.js";
-
-const countCallsForSql = (
-	calls: ReadonlyArray<ReadonlyArray<unknown>>,
-	targetSql: string
-) =>
-	calls.filter(
-		([args]) => (args as { sql?: string } | undefined)?.sql === targetSql
-	).length;
-
-describe("withRuntimeCache", () => {
-	test("caches executeSync results per runtimeCacheRef", async () => {
-		const lix = await openLix({ blob: await newLixFile() });
-		const engine = lix.engine!;
-		const compiled = internalQueryBuilder
-			.selectFrom("lix_internal_state_vtable")
-			.where("entity_id", "=", "lix_deterministic_mode")
-			.where("schema_key", "=", "lix_key_value")
-			.select(
-				sql`json_extract(snapshot_content, '$.value.enabled')`.as("enabled")
-			)
-			.limit(1)
-			.compile();
-
-		const executeSpy = vi.spyOn(engine, "executeSync");
-		const countTargetCalls = () =>
-			countCallsForSql(executeSpy.mock.calls, compiled.sql);
-
-		const first = withRuntimeCache(engine, compiled);
-		const second = withRuntimeCache(engine, compiled);
-
-		expect(first.rows).toEqual(second.rows);
-		expect(countTargetCalls()).toBe(1);
-
-		executeSpy.mockRestore();
-		await lix.close();
-	});
-
-	test("invalidates cache when dependent state changes", async () => {
-		const lix = await openLix({ blob: await newLixFile() });
-		const engine = lix.engine!;
-		const compiled = internalQueryBuilder
-			.selectFrom("lix_internal_state_vtable")
-			.where("entity_id", "=", "lix_deterministic_mode")
-			.where("schema_key", "=", "lix_key_value")
-			.select(
-				sql`json_extract(snapshot_content, '$.value.enabled')`.as("enabled")
-			)
-			.limit(1)
-			.compile();
-
-		const executeSpy = vi.spyOn(engine, "executeSync");
-		const countTargetCalls = () =>
-			countCallsForSql(executeSpy.mock.calls, compiled.sql);
-
-		withRuntimeCache(engine, compiled);
-		expect(countTargetCalls()).toBe(1);
-
-		engine.hooks._emit("state_commit", {
-			changes: [
-				{
-					id: "change-1",
-					entity_id: "lix_deterministic_mode",
-					schema_key: "lix_key_value",
-					schema_version: "1",
-					file_id: "lix",
-					plugin_key: "test",
-					created_at: new Date().toISOString(),
-					snapshot_content: null,
-					version_id: "global",
-					commit_id: "commit-1",
-					writer_key: null,
-				},
-			],
-		});
-
-		withRuntimeCache(engine, compiled);
-
-		expect(countTargetCalls()).toBe(2);
-
-		executeSpy.mockRestore();
-		await lix.close();
-	});
-
-	test("ignores unrelated state changes", async () => {
-		const lix = await openLix({ blob: await newLixFile() });
-		const engine = lix.engine!;
-		const compiled = internalQueryBuilder
-			.selectFrom("lix_internal_state_vtable")
-			.where("entity_id", "=", "lix_deterministic_mode")
-			.where("schema_key", "=", "lix_key_value")
-			.select(
-				sql`json_extract(snapshot_content, '$.value.enabled')`.as("enabled")
-			)
-			.limit(1)
-			.compile();
-
-		const executeSpy = vi.spyOn(engine, "executeSync");
-		const countTargetCalls = () =>
-			countCallsForSql(executeSpy.mock.calls, compiled.sql);
-
-		withRuntimeCache(engine, compiled);
-		expect(countTargetCalls()).toBe(1);
-
-		engine.hooks._emit("state_commit", {
-			changes: [
-				{
-					id: "change-2",
-					entity_id: "some_other_config",
-					schema_key: "lix_key_value",
-					schema_version: "1",
-					file_id: "lix",
-					plugin_key: "test",
-					created_at: new Date().toISOString(),
-					snapshot_content: null,
-					version_id: "global",
-					commit_id: "commit-2",
-					writer_key: null,
-				},
-			],
-		});
-
-		withRuntimeCache(engine, compiled);
-
-		expect(countTargetCalls()).toBe(1);
-
-		executeSpy.mockRestore();
-		await lix.close();
-	});
-
-	test("scopes cache per engine instance", async () => {
-		const lixA = await openLix({ blob: await newLixFile() });
-		const lixB = await openLix({ blob: await newLixFile() });
-		const engineA = lixA.engine!;
-		const engineB = lixB.engine!;
-		const compiled = internalQueryBuilder
-			.selectFrom("lix_internal_state_vtable")
-			.where("entity_id", "=", "lix_deterministic_mode")
-			.where("schema_key", "=", "lix_key_value")
-			.select(
-				sql`json_extract(snapshot_content, '$.value.enabled')`.as("enabled")
-			)
-			.limit(1)
-			.compile();
-
-		const spyA = vi.spyOn(engineA, "executeSync");
-		const spyB = vi.spyOn(engineB, "executeSync");
-		const countTargetCalls = (calls: typeof spyA.mock.calls) =>
-			countCallsForSql(calls, compiled.sql);
-
-		withRuntimeCache(engineA, compiled);
-		withRuntimeCache(engineB, compiled);
-
-		expect(countTargetCalls(spyA.mock.calls)).toBe(1);
-		expect(countTargetCalls(spyB.mock.calls)).toBe(1);
-
-		withRuntimeCache(engineA, compiled);
-		withRuntimeCache(engineB, compiled);
-
-		expect(countTargetCalls(spyA.mock.calls)).toBe(1);
-		expect(countTargetCalls(spyB.mock.calls)).toBe(1);
-
-		spyA.mockRestore();
-		spyB.mockRestore();
-		await lixA.close();
-		await lixB.close();
-	});
-});

package/src/engine/with-runtime-cache.ts

@@ -1,206 +0,0 @@
-import type { CompiledQuery } from "kysely";
-import type { LixEngine } from "./boot.js";
-import {
-	determineSchemaKeys,
-	extractLiteralFilters,
-} from "../observe/determine-schema-keys.js";
-import type { StateCommitChange } from "../hooks/create-hooks.js";
-
-const runtimeCaches = new WeakMap<object, Map<string, CacheEntry>>();
-
-type EngineForCache = Pick<
-	LixEngine,
-	"executeSync" | "hooks" | "runtimeCacheRef"
->;
-
-type ExecuteResult = ReturnType<EngineForCache["executeSync"]>;
-
-type CacheEntry = {
-	key: string;
-	result: ExecuteResult;
-	unsubscribe: () => void;
-	dependencies: CacheDependencies;
-};
-
-type CacheDependencies = {
-	schemaKeys: string[];
-	versionIds: string[];
-	entityIds: string[];
-};
-
-const BIGINT_SAFE_SERIALIZER = (_key: string, value: unknown) =>
-	typeof value === "bigint" ? value.toString() : value;
-
-function serialiseParameters(
-	parameters: Readonly<unknown[]> | undefined
-): string {
-	if (!parameters || parameters.length === 0) return "[]";
-	try {
-		return JSON.stringify(parameters, BIGINT_SAFE_SERIALIZER);
-	} catch {
-		// Fall back to stringifying via String() to avoid runtime crashes
-		return `[${parameters.map(String).join(",")}]`;
-	}
-}
-
-function getCacheContainer(engine: EngineForCache): Map<string, CacheEntry> {
-	let cache = runtimeCaches.get(engine.runtimeCacheRef);
-	if (!cache) {
-		cache = new Map();
-		runtimeCaches.set(engine.runtimeCacheRef, cache);
-	}
-	return cache;
-}
-
-function buildCacheKey(compiled: CompiledQuery<any>): string {
-	const paramsKey = serialiseParameters(compiled.parameters as any);
-	return `${compiled.sql}\u0000${paramsKey}`;
-}
-
-function computeDependencies(compiled: CompiledQuery<any>): CacheDependencies {
-	const schemaKeys = determineSchemaKeys(compiled) ?? [];
-	const filters = extractLiteralFilters(compiled);
-
-	return {
-		schemaKeys: Array.from(
-			new Set([...(filters.schemaKeys ?? []), ...schemaKeys])
-		),
-		versionIds: filters.versionIds ?? [],
-		entityIds: filters.entityIds ?? [],
-	};
-}
-
-function shouldInvalidate(
-	changes: StateCommitChange[] | undefined,
-	dependencies: CacheDependencies
-): boolean {
-	if (!changes || changes.length === 0) {
-		return true;
-	}
-
-	const { schemaKeys, versionIds, entityIds } = dependencies;
-
-	// No dependency information => be conservative and invalidate
-	if (
-		schemaKeys.length === 0 &&
-		versionIds.length === 0 &&
-		entityIds.length === 0
-	) {
-		return true;
-	}
-
-	for (const change of changes) {
-		const schemaKey = change.schema_key;
-		const entityId = change.entity_id;
-		const changeVersionId =
-			change.version_id ?? (change as any).lixcol_version_id;
-
-		if (schemaKeys.length > 0) {
-			if (!schemaKey) {
-				return true;
-			}
-			if (!schemaKeys.includes(schemaKey)) {
-				continue;
-			}
-		}
-
-		if (entityIds.length > 0) {
-			if (!entityId) {
-				return true;
-			}
-			if (!entityIds.includes(entityId)) {
-				continue;
-			}
-		}
-
-		if (versionIds.length > 0) {
-			if (!changeVersionId) {
-				return true;
-			}
-			if (!versionIds.includes(changeVersionId)) {
-				continue;
-			}
-		}
-
-		return true;
-	}
-
-	return false;
-}
-
-function attachInvalidation(
-	engine: EngineForCache,
-	cache: Map<string, CacheEntry>,
-	entry: CacheEntry
-): void {
-	let released = false;
-	let unsubscribeHook: () => void = () => {};
-
-	const teardown = () => {
-		if (released) return;
-		released = true;
-		unsubscribeHook();
-		cache.delete(entry.key);
-	};
-
-	unsubscribeHook = engine.hooks.onStateCommit(({ changes }) => {
-		if (shouldInvalidate(changes, entry.dependencies)) {
-			teardown();
-		}
-	});
-
-	entry.unsubscribe = teardown;
-}
-
-/**
- * Executes an internal compiled query once per engine instance and serves future callers from cache.
- *
- * Uses `engine.runtimeCacheRef` as a stable WeakMap key, subscribes to `onStateCommit`, and
- * invalidates cached results when relevant entities, schema keys, or version IDs change.
- *
- * @example
- * ```ts
- * const [config] = withRuntimeCache(
- *   engine,
- *   internalQueryBuilder
- *     .selectFrom("lix_internal_state_vtable")
- *     .where("entity_id", "=", "lix_deterministic_mode")
- *     .where("schema_key", "=", "lix_key_value")
- *     .select(sql`json_extract(snapshot_content, '$.value.enabled')`.as("enabled"))
- *     .limit(1)
- *     .compile()
- * ).rows;
- * ```
- */
-export function withRuntimeCache(
-	engine: EngineForCache,
-	compiled: CompiledQuery<any>
-): ExecuteResult {
-	const cache = getCacheContainer(engine);
-	const key = buildCacheKey(compiled);
-
-	const existing = cache.get(key);
-	if (existing) {
-		return existing.result;
-	}
-
-	const result = engine.executeSync({
-		sql: compiled.sql,
-		parameters: compiled.parameters,
-	});
-
-	const dependencies = computeDependencies(compiled);
-	const cacheEntry: CacheEntry = {
-		key,
-		result,
-		unsubscribe: () => {
-			/* replaced below */
-		},
-		dependencies,
-	};
-
-	attachInvalidation(engine, cache, cacheEntry);
-	cache.set(key, cacheEntry);
-
-	return result;
-}

package/src/entity/conversation/attach-conversation.test.ts

@@ -1,251 +0,0 @@
-import { test, expect } from "vitest";
-import { openLix } from "../../lix/open-lix.js";
-import {
-	attachConversation,
-	detachConversation,
-} from "./attach-conversation.js";
-import { createConversation } from "../../conversation/create-conversation.js";
-import { fromPlainText } from "@opral/zettel-ast";
-
-test("attachConversation should create a mapping between entity and conversation", async () => {
-	const lix = await openLix({});
-
-	await lix.db
-		.insertInto("key_value_by_version")
-		.values({
-			key: "test-config",
-			value: { setting: "value1" },
-			lixcol_version_id: "global",
-		})
-		.execute();
-	const keyValue = await lix.db
-		.selectFrom("key_value")
-		.where("key", "=", "test-config")
-		.selectAll()
-		.executeTakeFirstOrThrow();
-
-	const conv = await createConversation({
-		lix,
-		comments: [{ body: fromPlainText("Test msg") }],
-	});
-
-	await attachConversation({
-		lix,
-		entity: keyValue,
-		conversation: { id: conv.id },
-	});
-
-	const mapping = await lix.db
-		.selectFrom("entity_conversation")
-		.where("entity_id", "=", keyValue.key)
-		.where("schema_key", "=", "lix_key_value")
-		.where("file_id", "=", "lix")
-		.where("conversation_id", "=", conv.id)
-		.selectAll()
-		.executeTakeFirst();
-
-	expect(mapping).toBeDefined();
-	expect(mapping?.entity_id).toBe(keyValue.key);
-	expect(mapping?.conversation_id).toBe(conv.id);
-});
-
-test("attachConversation should handle lixcol_ prefixed entity fields", async () => {
-	const lix = await openLix({});
-	await lix.db
-		.insertInto("key_value_by_version")
-		.values({
-			key: "test-config-2",
-			value: { setting: "value2" },
-			lixcol_version_id: "global",
-		})
-		.execute();
-	const keyValue = await lix.db
-		.selectFrom("key_value")
-		.where("key", "=", "test-config-2")
-		.selectAll()
-		.executeTakeFirstOrThrow();
-
-	const conv = await createConversation({
-		lix,
-		comments: [{ body: fromPlainText("Test msg 2") }],
-	});
-
-	await attachConversation({
-		lix,
-		entity: keyValue,
-		conversation: { id: conv.id },
-	});
-
-	const mapping = await lix.db
-		.selectFrom("entity_conversation")
-		.where("entity_id", "=", keyValue.key)
-		.where("schema_key", "=", "lix_key_value")
-		.where("file_id", "=", "lix")
-		.where("conversation_id", "=", conv.id)
-		.selectAll()
-		.executeTakeFirst();
-
-	expect(mapping).toBeDefined();
-	expect(mapping?.entity_id).toBe(keyValue.key);
-	expect(mapping?.conversation_id).toBe(conv.id);
-});
-
-test("attachConversation should be idempotent for same entity-conversation pair", async () => {
-	const lix = await openLix({});
-	await lix.db
-		.insertInto("key_value_by_version")
-		.values({
-			key: "test-config-3",
-			value: { setting: "value3" },
-			lixcol_version_id: "global",
-		})
-		.execute();
-	const keyValue = await lix.db
-		.selectFrom("key_value")
-		.where("key", "=", "test-config-3")
-		.selectAll()
-		.executeTakeFirstOrThrow();
-	const conv = await createConversation({
-		lix,
-		comments: [{ body: fromPlainText("Test msg 3") }],
-	});
-
-	await attachConversation({
-		lix,
-		entity: keyValue,
-		conversation: { id: conv.id },
-	});
-	await attachConversation({
-		lix,
-		entity: keyValue,
-		conversation: { id: conv.id },
-	});
-
-	const mappings = await lix.db
-		.selectFrom("entity_conversation")
-		.where("entity_id", "=", keyValue.key)
-		.where("schema_key", "=", "lix_key_value")
-		.where("file_id", "=", "lix")
-		.where("conversation_id", "=", conv.id)
-		.selectAll()
-		.execute();
-
-	expect(mappings).toHaveLength(1);
-});
-
-test("detachConversation should remove the mapping", async () => {
-	const lix = await openLix({});
-	await lix.db
-		.insertInto("key_value_by_version")
-		.values({
-			key: "test-config-4",
-			value: { setting: "value4" },
-			lixcol_version_id: "global",
-		})
-		.execute();
-	const keyValue = await lix.db
-		.selectFrom("key_value")
-		.where("key", "=", "test-config-4")
-		.selectAll()
-		.executeTakeFirstOrThrow();
-	const conv = await createConversation({
-		lix,
-		comments: [{ body: fromPlainText("Test msg 4") }],
-	});
-
-	await attachConversation({
-		lix,
-		entity: keyValue,
-		conversation: { id: conv.id },
-	});
-
-	const before = await lix.db
-		.selectFrom("entity_conversation")
-		.where("entity_id", "=", keyValue.key)
-		.where("schema_key", "=", "lix_key_value")
-		.where("file_id", "=", "lix")
-		.where("conversation_id", "=", conv.id)
-		.selectAll()
-		.executeTakeFirst();
-	expect(before).toBeDefined();
-
-	await detachConversation({
-		lix,
-		entity: keyValue,
-		conversation: { id: conv.id },
-	});
-
-	const after = await lix.db
-		.selectFrom("entity_conversation")
-		.where("entity_id", "=", keyValue.key)
-		.where("schema_key", "=", "lix_key_value")
-		.where("file_id", "=", "lix")
-		.where("conversation_id", "=", conv.id)
-		.selectAll()
-		.executeTakeFirst();
-	expect(after).toBeUndefined();
-});
-
-test("entity can have multiple conversations", async () => {
-	const lix = await openLix({});
-	await lix.db
-		.insertInto("key_value_by_version")
-		.values({
-			key: "multi-conv-config",
-			value: { setting: "multivalue" },
-			lixcol_version_id: "global",
-		})
-		.execute();
-	const keyValue = await lix.db
-		.selectFrom("key_value")
-		.where("key", "=", "multi-conv-config")
-		.selectAll()
-		.executeTakeFirstOrThrow();
-
-	const c1 = await createConversation({
-		lix,
-		comments: [{ body: fromPlainText("C1") }],
-	});
-	const c2 = await createConversation({
-		lix,
-		comments: [{ body: fromPlainText("C2") }],
-	});
-	const c3 = await createConversation({
-		lix,
-		comments: [{ body: fromPlainText("C3") }],
-	});
-
-	await attachConversation({
-		lix,
-		entity: keyValue,
-		conversation: { id: c1.id },
-	});
-	await attachConversation({
-		lix,
-		entity: keyValue,
-		conversation: { id: c2.id },
-	});
-	await attachConversation({
-		lix,
-		entity: keyValue,
-		conversation: { id: c3.id },
-	});
-
-	const rows = await lix.db
-		.selectFrom("conversation")
-		.innerJoin(
-			"entity_conversation",
-			"entity_conversation.conversation_id",
-			"conversation.id"
-		)
-		.where("entity_conversation.entity_id", "=", keyValue.key)
-		.where("entity_conversation.schema_key", "=", "lix_key_value")
-		.where("entity_conversation.file_id", "=", "lix")
-		.select(["conversation.id"])
-		.execute();
-
-	expect(rows).toHaveLength(3);
-	expect(rows.map((t) => t.id)).toContain(c1.id);
-	expect(rows.map((t) => t.id)).toContain(c2.id);
-	expect(rows.map((t) => t.id)).toContain(c3.id);
-});