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

package/src/entity/label/schema.ts

@@ -0,0 +1,55 @@
+import type {
+	LixSchemaDefinition,
+	FromLixSchemaDefinition,
+} from "../../schema-definition/definition.js";
+import { createEntityViewsIfNotExists } from "../../entity-views/entity-view-builder.js";
+import type { Lix } from "../../lix/open-lix.js";
+
+export function applyEntityLabelDatabaseSchema(
+	lix: Pick<Lix, "sqlite" | "db">
+): void {
+	createEntityViewsIfNotExists({
+		lix,
+		schema: LixEntityLabelSchema,
+		overrideName: "entity_label",
+		pluginKey: "lix_own_entity",
+		hardcodedFileId: "lix",
+	});
+}
+
+export const LixEntityLabelSchema = {
+	"x-lix-key": "lix_entity_label",
+	"x-lix-version": "1.0",
+	"x-lix-primary-key": ["entity_id", "schema_key", "file_id", "label_id"],
+	"x-lix-foreign-keys": [
+		{
+			properties: ["entity_id", "schema_key", "file_id"],
+			references: {
+				schemaKey: "state",
+				properties: ["entity_id", "schema_key", "file_id"],
+			},
+		},
+		{
+			properties: ["label_id"],
+			references: {
+				schemaKey: "lix_label",
+				properties: ["id"],
+			},
+		},
+	],
+	type: "object",
+	properties: {
+		entity_id: { type: "string" },
+		schema_key: { type: "string" },
+		file_id: { type: "string" },
+		label_id: { type: "string" },
+	},
+	required: ["entity_id", "schema_key", "file_id", "label_id"],
+	additionalProperties: false,
+} as const;
+LixEntityLabelSchema satisfies LixSchemaDefinition;
+
+// Pure business logic type (inferred from schema)
+export type LixEntityLabel = FromLixSchemaDefinition<
+	typeof LixEntityLabelSchema
+>;

package/src/entity/schema.ts

@@ -0,0 +1,22 @@
+import type { Lix } from "../lix/open-lix.js";
+import { applyEntityLabelDatabaseSchema } from "./label/schema.js";
+
+export function applyEntityDatabaseSchema(
+	lix: Pick<Lix, "sqlite" | "db">
+): void {
+	applyEntityLabelDatabaseSchema(lix);
+}
+
+// Entity type with canonical column names (used in regular tables like state, entity_label)
+export type LixEntityCanonical = {
+	schema_key: string;
+	file_id: string;
+	entity_id: string;
+};
+
+// Entity type with lixcol_ prefixed columns (used in entity views)
+export type LixEntity = {
+	lixcol_schema_key: string;
+	lixcol_file_id: string;
+	lixcol_entity_id: string;
+};

package/src/entity/thread/create-entity-thread.test.ts

@@ -0,0 +1,282 @@
+import { test, expect } from "vitest";
+import { openLix } from "../../lix/open-lix.js";
+import {
+	createEntityThread,
+	deleteEntityThread,
+} from "./create-entity-thread.js";
+import { createThread } from "../../thread/create-thread.js";
+import { fromPlainText } from "@opral/zettel-ast";
+
+test("createEntityThread should create a mapping between entity and thread", async () => {
+	const lix = await openLix({});
+
+	// Create a key-value entity
+	await lix.db
+		.insertInto("key_value_all")
+		.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();
+
+	// Create a thread
+	const thread = await createThread({
+		lix,
+		comments: [{ body: fromPlainText("Test comment") }],
+	});
+
+	// Create entity-thread mapping
+	await createEntityThread({
+		lix,
+		entity: keyValue,
+		thread: { id: thread.id },
+	});
+
+	// Verify mapping exists
+	const mapping = await lix.db
+		.selectFrom("entity_thread")
+		.where("entity_id", "=", keyValue.key)
+		.where("schema_key", "=", "lix_key_value")
+		.where("file_id", "=", "lix")
+		.where("thread_id", "=", thread.id)
+		.selectAll()
+		.executeTakeFirst();
+
+	expect(mapping).toBeDefined();
+	expect(mapping?.entity_id).toBe(keyValue.key);
+	expect(mapping?.thread_id).toBe(thread.id);
+});
+
+test("createEntityThread should handle lixcol_ prefixed entity fields", async () => {
+	const lix = await openLix({});
+
+	// Create a key-value entity
+	await lix.db
+		.insertInto("key_value_all")
+		.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();
+
+	// Create a thread
+	const thread = await createThread({
+		lix,
+		comments: [{ body: fromPlainText("Test comment 2") }],
+	});
+
+	// Create entity-thread mapping using entity object
+	await createEntityThread({
+		lix,
+		entity: keyValue,
+		thread: { id: thread.id },
+	});
+
+	// Verify mapping exists
+	const mapping = await lix.db
+		.selectFrom("entity_thread")
+		.where("entity_id", "=", keyValue.key)
+		.where("schema_key", "=", "lix_key_value")
+		.where("file_id", "=", "lix")
+		.where("thread_id", "=", thread.id)
+		.selectAll()
+		.executeTakeFirst();
+
+	expect(mapping).toBeDefined();
+	expect(mapping?.entity_id).toBe(keyValue.key);
+	expect(mapping?.thread_id).toBe(thread.id);
+});
+
+test("createEntityThread should be idempotent for same entity-thread pair", async () => {
+	const lix = await openLix({});
+
+	// Create a key-value entity and thread
+	await lix.db
+		.insertInto("key_value_all")
+		.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 thread = await createThread({
+		lix,
+		comments: [{ body: fromPlainText("Test comment 3") }],
+	});
+
+	// Create entity-thread mapping twice
+	await createEntityThread({
+		lix,
+		entity: keyValue,
+		thread: { id: thread.id },
+	});
+
+	await createEntityThread({
+		lix,
+		entity: keyValue,
+		thread: { id: thread.id },
+	});
+
+	// Verify only one mapping exists
+	const mappings = await lix.db
+		.selectFrom("entity_thread")
+		.where("entity_id", "=", keyValue.key)
+		.where("schema_key", "=", "lix_key_value")
+		.where("file_id", "=", "lix")
+		.where("thread_id", "=", thread.id)
+		.selectAll()
+		.execute();
+
+	expect(mappings).toHaveLength(1);
+});
+
+test("deleteEntityThread should remove the mapping", async () => {
+	const lix = await openLix({});
+
+	// Create a key-value entity and thread
+	await lix.db
+		.insertInto("key_value_all")
+		.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 thread = await createThread({
+		lix,
+		comments: [{ body: fromPlainText("Test comment 4") }],
+	});
+
+	// Create entity-thread mapping
+	await createEntityThread({
+		lix,
+		entity: keyValue,
+		thread: { id: thread.id },
+	});
+
+	// Verify mapping exists
+	const mappingBefore = await lix.db
+		.selectFrom("entity_thread")
+		.where("entity_id", "=", keyValue.key)
+		.where("schema_key", "=", "lix_key_value")
+		.where("file_id", "=", "lix")
+		.where("thread_id", "=", thread.id)
+		.selectAll()
+		.executeTakeFirst();
+
+	expect(mappingBefore).toBeDefined();
+
+	// Delete the mapping
+	await deleteEntityThread({
+		lix,
+		entity: keyValue,
+		thread: { id: thread.id },
+	});
+
+	// Verify mapping is gone
+	const mappingAfter = await lix.db
+		.selectFrom("entity_thread")
+		.where("entity_id", "=", keyValue.key)
+		.where("schema_key", "=", "lix_key_value")
+		.where("file_id", "=", "lix")
+		.where("thread_id", "=", thread.id)
+		.selectAll()
+		.executeTakeFirst();
+
+	expect(mappingAfter).toBeUndefined();
+});
+
+test("entity can have multiple threads", async () => {
+	const lix = await openLix({});
+
+	// Create a key-value entity
+	await lix.db
+		.insertInto("key_value_all")
+		.values({
+			key: "multi-thread-config",
+			value: { setting: "multivalue" },
+			lixcol_version_id: "global",
+		})
+		.execute();
+
+	const keyValue = await lix.db
+		.selectFrom("key_value")
+		.where("key", "=", "multi-thread-config")
+		.selectAll()
+		.executeTakeFirstOrThrow();
+
+	// Create multiple threads
+	const thread1 = await createThread({
+		lix,
+		comments: [{ body: fromPlainText("Thread 1") }],
+	});
+	const thread2 = await createThread({
+		lix,
+		comments: [{ body: fromPlainText("Thread 2") }],
+	});
+	const thread3 = await createThread({
+		lix,
+		comments: [{ body: fromPlainText("Thread 3") }],
+	});
+
+	// Create mappings
+	await createEntityThread({
+		lix,
+		entity: keyValue,
+		thread: { id: thread1.id },
+	});
+
+	await createEntityThread({
+		lix,
+		entity: keyValue,
+		thread: { id: thread2.id },
+	});
+
+	await createEntityThread({
+		lix,
+		entity: keyValue,
+		thread: { id: thread3.id },
+	});
+
+	// Query all threads for this entity
+	const threads = await lix.db
+		.selectFrom("thread")
+		.innerJoin("entity_thread", "entity_thread.thread_id", "thread.id")
+		.where("entity_thread.entity_id", "=", keyValue.key)
+		.where("entity_thread.schema_key", "=", "lix_key_value")
+		.where("entity_thread.file_id", "=", "lix")
+		.select(["thread.id", "thread.metadata"])
+		.execute();
+
+	expect(threads).toHaveLength(3);
+	expect(threads.map((t) => t.id)).toContain(thread1.id);
+	expect(threads.map((t) => t.id)).toContain(thread2.id);
+	expect(threads.map((t) => t.id)).toContain(thread3.id);
+});

package/src/entity/thread/create-entity-thread.ts

@@ -0,0 +1,134 @@
+import type { Lix } from "../../lix/open-lix.js";
+import type { LixEntity, LixEntityCanonical } from "../schema.js";
+
+/**
+ * Creates a mapping between an entity and a thread.
+ *
+ * This function allows any entity in the system to have discussion threads,
+ * enabling universal commenting across all entity types.
+ *
+ * @example
+ * // Add thread to a markdown paragraph
+ * await createEntityThread({
+ *   lix,
+ *   entity: {
+ *     entity_id: "para_123",
+ *     schema_key: "markdown_paragraph",
+ *     file_id: "README.md"
+ *   },
+ *   thread: { id: "thread_001" }
+ * });
+ *
+ * @example
+ * // Add thread to a CSV cell
+ * await createEntityThread({
+ *   lix,
+ *   entity: {
+ *     entity_id: "row_789::column_2",
+ *     schema_key: "csv_cell",
+ *     file_id: "data.csv"
+ *   },
+ *   thread: { id: "thread_002" }
+ * });
+ *
+ * @example
+ * // Add thread to a change set
+ * await createEntityThread({
+ *   lix,
+ *   entity: {
+ *     entity_id: "cs123",
+ *     schema_key: "lix_change_set",
+ *     file_id: "lix"
+ *   },
+ *   thread: { id: "thread_003" }
+ * });
+ */
+export async function createEntityThread(args: {
+	lix: Pick<Lix, "db">;
+	entity: LixEntity | LixEntityCanonical;
+	thread: { id: string };
+	versionId?: string;
+}): Promise<void> {
+	const { lix, entity, thread } = args;
+
+	// Extract entity fields - support both canonical and lixcol_ prefixed names
+	const entity_id =
+		"entity_id" in entity ? entity.entity_id : entity.lixcol_entity_id;
+	const schema_key =
+		"schema_key" in entity ? entity.schema_key : entity.lixcol_schema_key;
+	const file_id = "file_id" in entity ? entity.file_id : entity.lixcol_file_id;
+
+	const versionId = args.versionId ?? "global";
+
+	// Check if the mapping already exists
+	const existingMapping = await lix.db
+		.selectFrom("entity_thread_all")
+		.where("entity_id", "=", entity_id)
+		.where("schema_key", "=", schema_key)
+		.where("file_id", "=", file_id)
+		.where("thread_id", "=", thread.id)
+		.where("lixcol_version_id", "=", versionId)
+		.select(["entity_id"])
+		.executeTakeFirst();
+
+	if (existingMapping) {
+		// Mapping already exists, nothing to do
+		return;
+	}
+
+	// Create the entity-thread mapping
+	// Foreign key constraints will automatically validate that:
+	// - The entity exists in state
+	// - The thread exists
+	await lix.db
+		.insertInto("entity_thread_all")
+		.values({
+			entity_id: entity_id,
+			schema_key: schema_key,
+			file_id: file_id,
+			thread_id: thread.id,
+			lixcol_version_id: versionId,
+		})
+		.execute();
+}
+
+/**
+ * Deletes a mapping between an entity and a thread.
+ *
+ * @example
+ * await deleteEntityThread({
+ *   lix,
+ *   entity: {
+ *     entity_id: "para_123",
+ *     schema_key: "markdown_paragraph",
+ *     file_id: "README.md"
+ *   },
+ *   thread: { id: "thread_001" }
+ * });
+ */
+export async function deleteEntityThread(args: {
+	lix: Pick<Lix, "db">;
+	entity: LixEntity | LixEntityCanonical;
+	thread: { id: string };
+	versionId?: string;
+}): Promise<void> {
+	const { lix, entity, thread } = args;
+
+	// Extract entity fields - support both canonical and lixcol_ prefixed names
+	const entity_id =
+		"entity_id" in entity ? entity.entity_id : entity.lixcol_entity_id;
+	const schema_key =
+		"schema_key" in entity ? entity.schema_key : entity.lixcol_schema_key;
+	const file_id = "file_id" in entity ? entity.file_id : entity.lixcol_file_id;
+
+	const versionId = args.versionId ?? "global";
+
+	await lix.db
+		.deleteFrom("entity_thread_all")
+		.where("entity_id", "=", entity_id)
+		.where("schema_key", "=", schema_key)
+		.where("file_id", "=", file_id)
+		.where("thread_id", "=", thread.id)
+		.where("lixcol_version_id", "=", versionId)
+		.execute();
+}