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

package/src/entity/eb-entity.ts

@@ -1,203 +0,0 @@
-import type { ExpressionBuilder, ExpressionWrapper, SqlBool } from "kysely";
-import type { LixDatabaseSchema } from "../database/schema.js";
-import type { LixEntity, LixEntityCanonical } from "./types.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_by_version",
-	"entity_label",
-	"entity_conversation",
-	"entity_conversation_by_version",
-] 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", "conversation").
- *                     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("conversation")
-		 *      .where(ebEntity("conversation").in([c1, c2, c3]))
-		 *      .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

@@ -1,9 +0,0 @@
-export type { LixEntity, LixEntityCanonical } from "./types.js";
-export type { LixEntityLabel } from "./label/schema-definition.js";
-export type { LixEntityConversation } from "./conversation/schema-definition.js";
-export { attachLabel, detachLabel } from "./label/attach-label.js";
-export {
-	attachConversation,
-	detachConversation,
-} from "./conversation/attach-conversation.js";
-export { ebEntity } from "./eb-entity.js";

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

@@ -1,356 +0,0 @@
-import { expect, test } from "vitest";
-import { openLix } from "../../lix/open-lix.js";
-import { createLabel } from "../../label/create-label.js";
-import { attachLabel, detachLabel } from "./attach-label.js";
-import { mockJsonPlugin } from "../../plugin/mock-json-plugin.js";
-import type { LixSchemaDefinition } from "../../schema-definition/definition.js";
-
-const documentSchema: LixSchemaDefinition = {
-	"x-lix-key": "test_document",
-	"x-lix-version": "1.0",
-	"x-lix-primary-key": ["/id"],
-	type: "object",
-	additionalProperties: false,
-	properties: {
-		id: { type: "string" },
-		title: { type: "string" },
-	},
-	required: ["id"],
-} as const;
-
-test("attachLabel creates a mapping between entity and label", async () => {
-	const lix = await openLix({});
-
-	// Create a label
-	const label = await createLabel({ lix, name: "important" });
-
-	await lix.db
-		.insertInto("stored_schema")
-		.values({ value: documentSchema })
-		.execute();
-
-	// Create an entity in state
-	await lix.db
-		.insertInto("state")
-		.values({
-			entity_id: "doc123",
-			schema_key: "test_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 attachLabel({
-		lix,
-		entity: {
-			entity_id: "doc123",
-			schema_key: "test_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: "test_document",
-		file_id: "docs.json",
-		label_id: label.id,
-	});
-});
-
-test("attachLabel 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(
-		attachLabel({
-			lix,
-			entity: {
-				entity_id: "non-existent",
-				schema_key: "test_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("attachLabel throws error if label doesn't exist", async () => {
-	const lix = await openLix({});
-
-	await lix.db
-		.insertInto("stored_schema")
-		.values({ value: documentSchema })
-		.execute();
-
-	// Create an entity in state
-	await lix.db
-		.insertInto("state")
-		.values({
-			entity_id: "doc123",
-			schema_key: "test_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(
-		attachLabel({
-			lix,
-			entity: {
-				entity_id: "doc123",
-				schema_key: "test_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("attachLabel is idempotent - doesn't fail if mapping already exists", async () => {
-	const lix = await openLix({});
-
-	const label = await createLabel({ lix, name: "idempotent-test" });
-
-	await lix.db
-		.insertInto("stored_schema")
-		.values({ value: documentSchema })
-		.execute();
-
-	// Create entity
-	await lix.db
-		.insertInto("state")
-		.values({
-			entity_id: "doc456",
-			schema_key: "test_document",
-			file_id: "docs.json",
-			plugin_key: "test_plugin",
-			schema_version: "1.0",
-			snapshot_content: { id: "doc456" },
-		})
-		.execute();
-
-	// Create mapping first time
-	await attachLabel({
-		lix,
-		entity: {
-			entity_id: "doc456",
-			schema_key: "test_document",
-			file_id: "docs.json",
-		},
-		label: { id: label.id },
-	});
-
-	// Create same mapping again - should not throw
-	await expect(
-		attachLabel({
-			lix,
-			entity: {
-				entity_id: "doc456",
-				schema_key: "test_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("detachLabel removes the mapping", async () => {
-	const lix = await openLix({});
-
-	const label = await createLabel({ lix, name: "removable" });
-
-	await lix.db
-		.insertInto("stored_schema")
-		.values({ value: documentSchema })
-		.execute();
-
-	// Create entity
-	await lix.db
-		.insertInto("state")
-		.values({
-			entity_id: "doc789",
-			schema_key: "test_document",
-			file_id: "docs.json",
-			plugin_key: "test_plugin",
-			schema_version: "1.0",
-			snapshot_content: { id: "doc789" },
-		})
-		.execute();
-
-	// Create mapping
-	await attachLabel({
-		lix,
-		entity: {
-			entity_id: "doc789",
-			schema_key: "test_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 detachLabel({
-		lix,
-		entity: {
-			entity_id: "doc789",
-			schema_key: "test_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("attachLabel works with change_set entities", async () => {
-	const lix = await openLix({});
-
-	const reviewedLabel = await createLabel({
-		lix,
-		name: "reviewed",
-		lixcol_version_id: "global",
-	});
-
-	// Create a change set
-	await lix.db
-		.insertInto("change_set")
-		.values({
-			id: "cs789",
-		})
-		.execute();
-
-	// Label the change set
-	await attachLabel({
-		lix,
-		entity: {
-			entity_id: "cs789",
-			schema_key: "lix_change_set",
-			file_id: "lix",
-		},
-		label: { id: reviewedLabel.id },
-		versionId: "global",
-	});
-
-	// Verify the label was applied by checking entity_label table directly
-	const mapping = await lix.db
-		.selectFrom("entity_label_by_version")
-		.where("entity_id", "=", "cs789")
-		.where("schema_key", "=", "lix_change_set")
-		.where("file_id", "=", "lix")
-		.where("lixcol_version_id", "=", "global")
-		.selectAll()
-		.executeTakeFirst();
-
-	expect(mapping).toBeDefined();
-	expect(mapping?.label_id).toBe(reviewedLabel.id);
-});
-
-test("attachLabel 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 attachLabel({
-		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");
-});