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

package/src/entity/eb-entity.ts

@@ -0,0 +1,203 @@
+import type { ExpressionBuilder, ExpressionWrapper, SqlBool } from "kysely";
+import type { LixDatabaseSchema } from "../database/schema.js";
+import type { LixEntity, LixEntityCanonical } from "./schema.js";
+
+/**
+ * List of tables that use canonical column names (entity_id, schema_key, file_id)
+ * instead of the lixcol_ prefixed versions used by entity views.
+ */
+const CANONICAL_TABLES = [
+	"state",
+	"state_all",
+	"entity_label",
+	"entity_thread",
+	"entity_thread_all",
+] as const;
+
+/**
+ * Entity Expression Builder - provides fluent API for entity operations in queries.
+ *
+ * This allows for more readable query syntax like:
+ * .where(ebEntity("file").hasLabel({ name: "important" }))
+ * .where(ebEntity("state").equals(userAccount))
+ * .where(ebEntity().in(entities)) // When context is unambiguous (no joins)
+ *
+ * @param entityType - The type of entity table being queried (e.g., "file", "account", "thread").
+ *                     Optional when the context is unambiguous (e.g., single table queries with no joins).
+ */
+export function ebEntity<
+	TB extends keyof LixDatabaseSchema = keyof LixDatabaseSchema,
+>(entityType?: TB) {
+	// When entityType is provided, determine column names based on table type
+	const isCanonicalTable = entityType
+		? CANONICAL_TABLES.includes(entityType as any)
+		: undefined;
+
+	// Helper to detect which column naming convention is used based on the entity object
+	const detectColumnType = (entity: any): boolean => {
+		// If entity has canonical columns, it's from a canonical table
+		return (
+			"entity_id" in entity && "schema_key" in entity && "file_id" in entity
+		);
+	};
+
+	// Get column names based on table type or entity structure
+	const getColumnNames = (entity?: any) => {
+		if (entityType !== undefined) {
+			// Table explicitly provided - use the appropriate columns
+			return {
+				entityIdCol: isCanonicalTable ? "entity_id" : "lixcol_entity_id",
+				schemaKeyCol: isCanonicalTable ? "schema_key" : "lixcol_schema_key",
+				fileIdCol: isCanonicalTable ? "file_id" : "lixcol_file_id",
+			};
+		}
+
+		// No table provided - detect from entity if available
+		if (entity) {
+			const useCanonical = detectColumnType(entity);
+			return {
+				entityIdCol: useCanonical ? "entity_id" : "lixcol_entity_id",
+				schemaKeyCol: useCanonical ? "schema_key" : "lixcol_schema_key",
+				fileIdCol: useCanonical ? "file_id" : "lixcol_file_id",
+			};
+		}
+
+		// Default to lixcol_ for views (most common case)
+		return {
+			entityIdCol: "lixcol_entity_id",
+			schemaKeyCol: "lixcol_schema_key",
+			fileIdCol: "lixcol_file_id",
+		};
+	};
+
+	return {
+		/**
+		 * Creates a filter that matches entities having the specified label.
+		 *
+		 * @param label - The label to filter by (either { name: "..." } or { id: "..." })
+		 * @returns Expression wrapper for use in WHERE clauses
+		 *
+		 * @example
+		 *   ```ts
+		 *   await lix.db.selectFrom("file")
+		 *      .where(ebEntity("file").hasLabel({ name: "important" }))
+		 *      .selectAll()
+		 *      .execute();
+		 *   ```
+		 */
+		hasLabel(
+			label: { id: string; name?: string } | { name: string; id?: string }
+		) {
+			return (
+				eb: ExpressionBuilder<LixDatabaseSchema, TB>
+			): ExpressionWrapper<LixDatabaseSchema, TB, SqlBool> => {
+				const { entityIdCol } = getColumnNames();
+				const columnRef = entityType
+					? `${entityType}.${entityIdCol}`
+					: entityIdCol;
+				return eb(eb.ref(columnRef as any), "in", (subquery: any) =>
+					subquery
+						.selectFrom("entity_label")
+						.innerJoin("label", "label.id", "entity_label.label_id")
+						.select("entity_label.entity_id")
+						.$if("name" in label, (qb: any) =>
+							qb.where("label.name", "=", label.name!)
+						)
+						.$if("id" in label, (qb: any) =>
+							qb.where("label.id", "=", label.id!)
+						)
+				);
+			};
+		},
+
+		/**
+		 * Creates a filter that matches entities equal to the specified entity.
+		 *
+		 * @param entity - The entity to match against (must have entity_id, schema_key, file_id)
+		 * @returns Expression wrapper for use in WHERE clauses
+		 *
+		 * @example
+		 *   ```ts
+		 *   await lix.db.selectFrom("account")
+		 *      .where(ebEntity("account").equals(targetAccount))
+		 *      .selectAll()
+		 *      .execute();
+		 *   ```
+		 */
+		equals(entity: LixEntity | LixEntityCanonical) {
+			return (
+				eb: ExpressionBuilder<LixDatabaseSchema, TB>
+			): ExpressionWrapper<LixDatabaseSchema, TB, SqlBool> => {
+				// Extract entity fields - support both canonical and lixcol_ prefixed names
+				const targetEntityId =
+					"entity_id" in entity ? entity.entity_id : entity.lixcol_entity_id;
+				const targetSchemaKey =
+					"schema_key" in entity ? entity.schema_key : entity.lixcol_schema_key;
+				const targetFileId =
+					"file_id" in entity ? entity.file_id : entity.lixcol_file_id;
+
+				const { entityIdCol, schemaKeyCol, fileIdCol } = getColumnNames(entity);
+				// Prefix with table name if provided to avoid ambiguity in joins
+				const entityIdRef = entityType
+					? `${entityType}.${entityIdCol}`
+					: entityIdCol;
+				const schemaKeyRef = entityType
+					? `${entityType}.${schemaKeyCol}`
+					: schemaKeyCol;
+				const fileIdRef = entityType ? `${entityType}.${fileIdCol}` : fileIdCol;
+
+				return eb.and([
+					eb(eb.ref(entityIdRef as any), "=", targetEntityId),
+					eb(eb.ref(schemaKeyRef as any), "=", targetSchemaKey),
+					eb(eb.ref(fileIdRef as any), "=", targetFileId),
+				]);
+			};
+		},
+
+		/**
+		 * Creates a filter that matches entities in the specified list.
+		 *
+		 * @param entities - Array of entities to match against
+		 * @returns Expression wrapper for use in WHERE clauses
+		 *
+		 * @example
+		 *   ```ts
+		 *   await lix.db.selectFrom("thread")
+		 *      .where(ebEntity("thread").in([thread1, thread2, thread3]))
+		 *      .selectAll()
+		 *      .execute();
+		 *   ```
+		 */
+		in(
+			entities: Array<
+				| { entity_id: string; schema_key: string; file_id: string }
+				| {
+						lixcol_entity_id: string;
+						lixcol_schema_key: string;
+						lixcol_file_id: string;
+				  }
+			>
+		) {
+			return (
+				eb: ExpressionBuilder<LixDatabaseSchema, TB>
+			): ExpressionWrapper<LixDatabaseSchema, TB, SqlBool> => {
+				if (entities.length === 0) {
+					// Return a condition that's always false for empty arrays
+					return eb.val(false);
+				}
+
+				// Extract entity IDs for the IN clause
+				const entityIds = entities.map((entity) =>
+					"entity_id" in entity ? entity.entity_id : entity.lixcol_entity_id
+				);
+
+				// Get column names based on first entity (assumes all entities use same convention)
+				const { entityIdCol } = getColumnNames(entities[0]);
+				const columnRef = entityType
+					? `${entityType}.${entityIdCol}`
+					: entityIdCol;
+				return eb(eb.ref(columnRef as any), "in", entityIds);
+			};
+		},
+	};
+}

package/src/entity/index.ts

@@ -0,0 +1,12 @@
+export type { LixEntity, LixEntityCanonical } from "./schema.js";
+export type { LixEntityLabel } from "./label/schema.js";
+export type { LixEntityThread } from "./thread/schema.js";
+export {
+	createEntityLabel,
+	deleteEntityLabel,
+} from "./label/create-entity-label.js";
+export {
+	createEntityThread,
+	deleteEntityThread,
+} from "./thread/create-entity-thread.js";
+export { ebEntity } from "./eb-entity.js";

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

@@ -0,0 +1,316 @@
+import { expect, test } from "vitest";
+import { openLix } from "../../lix/open-lix.js";
+import { createLabel } from "../../label/create-label.js";
+import { createEntityLabel, deleteEntityLabel } from "./create-entity-label.js";
+import { mockJsonPlugin } from "../../plugin/mock-json-plugin.js";
+
+test("createEntityLabel creates a mapping between entity and label", async () => {
+	const lix = await openLix({});
+
+	// Create a label
+	const label = await createLabel({ lix, name: "important" });
+
+	// Create an entity in state
+	await lix.db
+		.insertInto("state")
+		.values({
+			entity_id: "doc123",
+			schema_key: "document",
+			file_id: "docs.json",
+			plugin_key: "test_plugin",
+			schema_version: "1.0",
+			snapshot_content: { id: "doc123", title: "User Guide" },
+		})
+		.execute();
+
+	// Create entity-label mapping
+	await createEntityLabel({
+		lix,
+		entity: {
+			entity_id: "doc123",
+			schema_key: "document",
+			file_id: "docs.json",
+		},
+		label: { id: label.id },
+	});
+
+	// Verify mapping was created
+	const mapping = await lix.db
+		.selectFrom("entity_label")
+		.where("entity_id", "=", "doc123")
+		.where("label_id", "=", label.id)
+		.selectAll()
+		.executeTakeFirst();
+
+	expect(mapping).toMatchObject({
+		entity_id: "doc123",
+		schema_key: "document",
+		file_id: "docs.json",
+		label_id: label.id,
+	});
+});
+
+test("createEntityLabel throws error if entity doesn't exist", async () => {
+	const lix = await openLix({});
+
+	const label = await createLabel({ lix, name: "test-label" });
+
+	// Try to create mapping for non-existent entity
+	// Should throw foreign key constraint error
+	await expect(
+		createEntityLabel({
+			lix,
+			entity: {
+				entity_id: "non-existent",
+				schema_key: "document",
+				file_id: "docs.json",
+			},
+			label: { id: label.id },
+		})
+	).rejects.toThrow(
+		/Foreign key constraint violation.*lix_entity_label.*\(entity_id, schema_key, file_id\).*state\.\(entity_id, schema_key, file_id\)/
+	);
+});
+
+test("createEntityLabel throws error if label doesn't exist", async () => {
+	const lix = await openLix({});
+
+	// Create an entity in state
+	await lix.db
+		.insertInto("state")
+		.values({
+			entity_id: "doc123",
+			schema_key: "document",
+			file_id: "docs.json",
+			plugin_key: "test_plugin",
+			schema_version: "1.0",
+			snapshot_content: { id: "doc123" },
+		})
+		.execute();
+
+	// Try to create mapping with non-existent label
+	// Should throw foreign key constraint error
+	await expect(
+		createEntityLabel({
+			lix,
+			entity: {
+				entity_id: "doc123",
+				schema_key: "document",
+				file_id: "docs.json",
+			},
+			label: { id: "non-existent-label" },
+		})
+	).rejects.toThrow(
+		/Foreign key constraint violation.*lix_entity_label.*\(label_id\).*lix_label\.\(id\)/
+	);
+});
+
+test("createEntityLabel is idempotent - doesn't fail if mapping already exists", async () => {
+	const lix = await openLix({});
+
+	const label = await createLabel({ lix, name: "idempotent-test" });
+
+	// Create entity
+	await lix.db
+		.insertInto("state")
+		.values({
+			entity_id: "doc456",
+			schema_key: "document",
+			file_id: "docs.json",
+			plugin_key: "test_plugin",
+			schema_version: "1.0",
+			snapshot_content: { id: "doc456" },
+		})
+		.execute();
+
+	// Create mapping first time
+	await createEntityLabel({
+		lix,
+		entity: {
+			entity_id: "doc456",
+			schema_key: "document",
+			file_id: "docs.json",
+		},
+		label: { id: label.id },
+	});
+
+	// Create same mapping again - should not throw
+	await expect(
+		createEntityLabel({
+			lix,
+			entity: {
+				entity_id: "doc456",
+				schema_key: "document",
+				file_id: "docs.json",
+			},
+			label: { id: label.id },
+		})
+	).resolves.toBeUndefined();
+
+	// Verify only one mapping exists
+	const mappings = await lix.db
+		.selectFrom("entity_label")
+		.where("entity_id", "=", "doc456")
+		.where("label_id", "=", label.id)
+		.selectAll()
+		.execute();
+
+	expect(mappings).toHaveLength(1);
+});
+
+test("deleteEntityLabel removes the mapping", async () => {
+	const lix = await openLix({});
+
+	const label = await createLabel({ lix, name: "removable" });
+
+	// Create entity
+	await lix.db
+		.insertInto("state")
+		.values({
+			entity_id: "doc789",
+			schema_key: "document",
+			file_id: "docs.json",
+			plugin_key: "test_plugin",
+			schema_version: "1.0",
+			snapshot_content: { id: "doc789" },
+		})
+		.execute();
+
+	// Create mapping
+	await createEntityLabel({
+		lix,
+		entity: {
+			entity_id: "doc789",
+			schema_key: "document",
+			file_id: "docs.json",
+		},
+		label: { id: label.id },
+	});
+
+	// Verify mapping exists
+	const beforeRemove = await lix.db
+		.selectFrom("entity_label")
+		.where("entity_id", "=", "doc789")
+		.selectAll()
+		.execute();
+
+	expect(beforeRemove).toHaveLength(1);
+
+	// Remove mapping
+	await deleteEntityLabel({
+		lix,
+		entity: {
+			entity_id: "doc789",
+			schema_key: "document",
+			file_id: "docs.json",
+		},
+		label: { id: label.id },
+	});
+
+	// Verify mapping is gone
+	const afterRemove = await lix.db
+		.selectFrom("entity_label")
+		.where("entity_id", "=", "doc789")
+		.selectAll()
+		.execute();
+
+	expect(afterRemove).toHaveLength(0);
+});
+
+test("createEntityLabel works with change_set entities", async () => {
+	const lix = await openLix({});
+
+	const reviewedLabel = await createLabel({ lix, name: "reviewed" });
+
+	// Create a change set
+	await lix.db
+		.insertInto("change_set")
+		.values({
+			id: "cs789",
+		})
+		.execute();
+
+	// Label the change set
+	await createEntityLabel({
+		lix,
+		entity: {
+			entity_id: "cs789",
+			schema_key: "lix_change_set",
+			file_id: "lix",
+		},
+		label: { id: reviewedLabel.id },
+	});
+
+	// Verify the label was applied by checking entity_label table directly
+	const mapping = await lix.db
+		.selectFrom("entity_label")
+		.where("entity_id", "=", "cs789")
+		.where("schema_key", "=", "lix_change_set")
+		.where("file_id", "=", "lix")
+		.selectAll()
+		.executeTakeFirst();
+
+	expect(mapping).toBeDefined();
+	expect(mapping?.label_id).toBe(reviewedLabel.id);
+});
+
+test("createEntityLabel works with files", async () => {
+	const lix = await openLix({
+		providePlugins: [mockJsonPlugin],
+	});
+
+	const importantLabel = await createLabel({ lix, name: "important-file" });
+
+	// Create a file
+	await lix.db
+		.insertInto("file")
+		.values({
+			id: "test-file-123",
+			path: "/important-data.json",
+			data: new TextEncoder().encode(
+				JSON.stringify({
+					title: "Important Data",
+					content: "This file contains critical information",
+				})
+			),
+		})
+		.execute();
+
+	// Get the file to retrieve its lixcol_* columns
+	const file = await lix.db
+		.selectFrom("file")
+		.where("id", "=", "test-file-123")
+		.selectAll()
+		.executeTakeFirstOrThrow();
+
+	// Label the file using its lixcol_* columns
+	await createEntityLabel({
+		lix,
+		entity: file,
+		label: importantLabel,
+	});
+
+	// Verify the label was applied
+	const mapping = await lix.db
+		.selectFrom("entity_label")
+		.where("entity_id", "=", file.lixcol_entity_id)
+		.where("schema_key", "=", "lix_file_descriptor")
+		.where("file_id", "=", file.lixcol_file_id)
+		.selectAll()
+		.executeTakeFirst();
+
+	expect(mapping).toBeDefined();
+	expect(mapping?.label_id).toBe(importantLabel.id);
+
+	// Also verify we can query files by label using entityEb
+	const { ebEntity: entityEb } = await import("../eb-entity.js");
+
+	const importantFiles = await lix.db
+		.selectFrom("file")
+		.where(entityEb("file").hasLabel(importantLabel))
+		.selectAll()
+		.execute();
+
+	expect(importantFiles).toHaveLength(1);
+	expect(importantFiles[0]?.id).toBe("test-file-123");
+});

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

@@ -0,0 +1,113 @@
+import type { Lix } from "../../lix/open-lix.js";
+import type { LixEntity, LixEntityCanonical } from "../schema.js";
+
+/**
+ * Creates a mapping between an entity and a label.
+ *
+ * This function allows any entity in the system to be labeled,
+ * enabling universal labeling across all entity types.
+ *
+ * @example
+ * // Label a bundle entity
+ * await createEntityLabel({
+ *   lix,
+ *   entity: {
+ *     entity_id: "bundle123",
+ *     schema_key: "inlang_bundle",
+ *     file_id: "messages.json"
+ *   },
+ *   label: { id: "needs-translation-label-id" }
+ * });
+ *
+ * @example
+ * // Label a change set
+ * await createEntityLabel({
+ *   lix,
+ *   entity: {
+ *     entity_id: "cs123",
+ *     schema_key: "lix_change_set",
+ *     file_id: "lix"
+ *   },
+ *   label: { id: "reviewed-label-id" }
+ * });
+ */
+export async function createEntityLabel(args: {
+	lix: Pick<Lix, "db">;
+	entity: LixEntity | LixEntityCanonical;
+	label: { id: string };
+}): Promise<void> {
+	const { lix, entity, label } = 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;
+
+	// Check if the mapping already exists
+	const existingMapping = await lix.db
+		.selectFrom("entity_label")
+		.where("entity_id", "=", entity_id)
+		.where("schema_key", "=", schema_key)
+		.where("file_id", "=", file_id)
+		.where("label_id", "=", label.id)
+		.select(["entity_id"])
+		.executeTakeFirst();
+
+	if (existingMapping) {
+		// Mapping already exists, nothing to do
+		return;
+	}
+
+	// Create the entity-label mapping
+	// Foreign key constraints will automatically validate that:
+	// - The entity exists in state
+	// - The label exists
+	await lix.db
+		.insertInto("entity_label")
+		.values({
+			entity_id: entity_id,
+			schema_key: schema_key,
+			file_id: file_id,
+			label_id: label.id,
+		})
+		.execute();
+}
+
+/**
+ * Deletes a mapping between an entity and a label.
+ *
+ * @example
+ * await deleteEntityLabel({
+ *   lix,
+ *   entity: {
+ *     entity_id: "bundle123",
+ *     schema_key: "inlang_bundle",
+ *     file_id: "messages.json"
+ *   },
+ *   label: { id: "needs-translation-label-id" }
+ * });
+ */
+export async function deleteEntityLabel(args: {
+	lix: Pick<Lix, "db">;
+	entity: LixEntity | LixEntityCanonical;
+	label: { id: string };
+}): Promise<void> {
+	const { lix, entity, label } = 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;
+
+	await lix.db
+		.deleteFrom("entity_label")
+		.where("entity_id", "=", entity_id)
+		.where("schema_key", "=", schema_key)
+		.where("file_id", "=", file_id)
+		.where("label_id", "=", label.id)
+		.execute();
+}