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

package/src/conversation/create-conversation.test.ts

@@ -1,194 +0,0 @@
-import { expect, test } from "vitest";
-import { createConversation } from "./create-conversation.js";
-import { openLix } from "../lix/open-lix.js";
-import { fromPlainText } from "@opral/zettel-ast";
-import { ebEntity } from "../entity/eb-entity.js";
-
-test("creates a conversation with sequential messages where only the first has null parent_id", async () => {
-	const lix = await openLix({
-		keyValues: [
-			{
-				key: "lix_deterministic_mode",
-				value: { enabled: true },
-				lixcol_version_id: "global",
-			},
-		],
-	});
-
-	const comments = [
-		{ body: fromPlainText("First message") },
-		{ body: fromPlainText("Second message") },
-		{ body: fromPlainText("Third message") },
-	];
-
-	const convWithMessages = await createConversation({ lix, comments });
-	const { comments: inserted } = convWithMessages;
-
-	expect(inserted).toHaveLength(3);
-	expect(inserted[0]!.parent_id).toBeNull();
-	expect(inserted[1]!.parent_id).toBe(inserted[0]!.id);
-	expect(inserted[2]!.parent_id).toBe(inserted[1]!.id);
-});
-
-test("defaults to global version if no versionId is provided", async () => {
-	const lix = await openLix({});
-
-	const comments = [{ body: fromPlainText("Global message") }];
-
-	const conv = await createConversation({ lix, comments });
-	expect(conv.lixcol_version_id).toBe("global");
-	expect(conv.comments[0]!.lixcol_version_id).toBe("global");
-});
-
-test("creates a conversation with entity mapping when entity is provided", async () => {
-	const lix = await openLix({});
-
-	// Create a key-value entity
-	await lix.db
-		.insertInto("key_value_by_version")
-		.values({
-			key: "test-entity-config",
-			value: { setting: "entityvalue" },
-			lixcol_version_id: "global",
-		})
-		.execute();
-
-	const keyValue = await lix.db
-		.selectFrom("key_value")
-		.where("key", "=", "test-entity-config")
-		.selectAll()
-		.executeTakeFirstOrThrow();
-
-	const comments = [{ body: fromPlainText("Comment on entity") }];
-
-	// Create conversation with entity
-	const conv = await createConversation({
-		lix,
-		comments,
-		entity: keyValue,
-	});
-
-	// Verify conversation + mapping
-	expect(conv.id).toBeDefined();
-	expect(conv.comments).toHaveLength(1);
-
-	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?.conversation_id).toBe(conv.id);
-});
-
-test("creates a conversation without entity mapping when entity is not provided", async () => {
-	const lix = await openLix({});
-
-	const comments = [{ body: fromPlainText("Standalone message") }];
-
-	const conv = await createConversation({ lix, comments });
-
-	expect(conv.id).toBeDefined();
-
-	const mappings = await lix.db
-		.selectFrom("entity_conversation")
-		.where("conversation_id", "=", conv.id)
-		.selectAll()
-		.execute();
-
-	expect(mappings).toHaveLength(0);
-});
-
-test("can query conversations for a specific entity using ebEntity", async () => {
-	const lix = await openLix({});
-
-	// Create a key-value entity
-	await lix.db
-		.insertInto("key_value_by_version")
-		.values({
-			key: "query-test-config",
-			value: { setting: "queryvalue" },
-			lixcol_version_id: "global",
-		})
-		.execute();
-
-	const keyValue = await lix.db
-		.selectFrom("key_value")
-		.where("key", "=", "query-test-config")
-		.selectAll()
-		.executeTakeFirstOrThrow();
-
-	// Create multiple conversations for the entity
-	const c1 = await createConversation({
-		lix,
-		comments: [{ body: fromPlainText("First conversation") }],
-		entity: keyValue,
-	});
-
-	const c2 = await createConversation({
-		lix,
-		comments: [{ body: fromPlainText("Second conversation") }],
-		entity: keyValue,
-	});
-
-	// Create a conversation for a different entity
-	await lix.db
-		.insertInto("key_value_by_version")
-		.values({
-			key: "other-config",
-			value: { setting: "othervalue" },
-			lixcol_version_id: "global",
-		})
-		.execute();
-
-	const other = await lix.db
-		.selectFrom("key_value")
-		.where("key", "=", "other-config")
-		.selectAll()
-		.executeTakeFirstOrThrow();
-
-	await createConversation({
-		lix,
-		comments: [{ body: fromPlainText("Other conversation") }],
-		entity: other,
-	});
-
-	// Query conversations for the specific entity using ebEntity
-	const rows = await lix.db
-		.selectFrom("conversation")
-		.innerJoin(
-			"entity_conversation",
-			"entity_conversation.conversation_id",
-			"conversation.id"
-		)
-		.where(ebEntity("entity_conversation").equals(keyValue))
-		.select(["conversation.id"])
-		.execute();
-
-	expect(rows).toHaveLength(2);
-	expect(rows.map((t) => t.id)).toContain(c1.id);
-	expect(rows.map((t) => t.id)).toContain(c2.id);
-});
-
-test("conversation_message supports metadata via createConversation", async () => {
-	const lix = await openLix({});
-
-	const conv = await createConversation({
-		lix,
-		comments: [
-			{
-				body: fromPlainText("hello"),
-				lixcol_metadata: { lix_agent_role: "user" },
-			},
-		],
-	});
-
-	expect(conv.comments).toHaveLength(1);
-	expect(conv.comments[0]!.lixcol_metadata).toEqual({
-		lix_agent_role: "user",
-	});
-});

package/src/conversation/create-conversation.ts

@@ -1,110 +0,0 @@
-import type { Lix } from "../lix/open-lix.js";
-import type {
-	LixConversation,
-	LixConversationMessage,
-} from "./schema-definition.js";
-import type { NewState, StateByVersion } from "../engine/entity-views/types.js";
-import type { LixEntity, LixEntityCanonical } from "../entity/types.js";
-import { attachConversation } from "../entity/conversation/attach-conversation.js";
-import { nanoId } from "../engine/functions/nano-id.js";
-
-/**
- * Starts a new conversation.
- *
- * Conversations allow collaborators to attach messages to a specific
- * version or entity. Initial messages can be provided and will be
- * inserted sequentially.
- *
- * @example
- * ```ts
- * // Create a standalone conversation
- * const conv = await createConversation({ lix, comments: [{ body: "Hello" }] })
- * ```
- *
- * @example
- * ```ts
- * // Create a conversation attached to an entity
- * const conv = await createConversation({
- *   lix,
- *   entity: { entity_id: "para_123", schema_key: "markdown_paragraph", file_id: "README.md" },
- *   comments: [{ body: "This paragraph needs review" }]
- * })
- * ```
- */
-export async function createConversation(args: {
-	lix: Lix;
-	id?: string;
-	comments?: (Pick<NewState<LixConversationMessage>, "body"> &
-		Partial<Pick<NewState<LixConversationMessage>, "lixcol_metadata">>)[];
-	/** defaults to global */
-	versionId?: string;
-	/** Optional entity to attach the conversation to */
-	entity?: LixEntity | LixEntityCanonical;
-}): Promise<
-	StateByVersion<LixConversation> & {
-		comments: StateByVersion<LixConversationMessage>[];
-	}
-> {
-	const executeInTransaction = async (trx: Lix["db"]) => {
-		const conversationId =
-			args.id ?? (await nanoId({ lix: { ...args.lix, db: trx } }));
-		const versionId = args.versionId ?? "global";
-
-		await trx
-			.insertInto("conversation_by_version")
-			.values({ id: conversationId, lixcol_version_id: versionId })
-			.execute();
-
-		const conversation = await trx
-			.selectFrom("conversation_by_version")
-			.selectAll()
-			.where("id", "=", conversationId)
-			.where("lixcol_version_id", "=", versionId)
-			.executeTakeFirstOrThrow();
-
-		const insertedMessages = [] as any[];
-
-		for (const [index, message] of (args.comments ?? []).entries()) {
-			const messageId = await nanoId({ lix: { ...args.lix, db: trx } });
-
-			await trx
-				.insertInto("conversation_message_by_version")
-				.values({
-					id: messageId,
-					conversation_id: conversation.id,
-					body: message.body,
-					lixcol_metadata: message.lixcol_metadata ?? undefined,
-					parent_id: index > 0 ? insertedMessages[index - 1]!.id : null,
-					lixcol_version_id: versionId,
-				})
-				.execute();
-
-			const insertedMessage = await trx
-				.selectFrom("conversation_message_by_version")
-				.selectAll()
-				.where("id", "=", messageId)
-				.where("lixcol_version_id", "=", versionId)
-				.executeTakeFirstOrThrow();
-
-			insertedMessages.push(insertedMessage);
-		}
-
-		// If an entity is provided, create the entity-conversation mapping
-		if (args.entity) {
-			await attachConversation({
-				lix: { db: trx },
-				entity: args.entity,
-				conversation: { id: conversationId },
-				versionId: versionId,
-			});
-		}
-
-		return { ...conversation, comments: insertedMessages };
-	};
-
-	if (args.lix.db.isTransaction) {
-		return await executeInTransaction(args.lix.db);
-	} else {
-		return await args.lix.db.transaction().execute(executeInTransaction);
-	}
-}

package/src/conversation/index.ts

@@ -1,8 +0,0 @@
-export {
-	LixConversationSchema,
-	LixConversationMessageSchema,
-	type LixConversation,
-	type LixConversationMessage,
-} from "./schema-definition.js";
-export { createConversation } from "./create-conversation.js";
-export { createConversationMessage } from "./create-conversation-message.js";

package/src/conversation/schema-definition.ts

@@ -1,74 +0,0 @@
-import type {
-	FromLixSchemaDefinition,
-	LixSchemaDefinition,
-} from "../schema-definition/definition.js";
-import { ZettelDocJsonSchema, type ZettelDoc } from "@opral/zettel-ast";
-
-export type LixConversation = FromLixSchemaDefinition<
-	typeof LixConversationSchema
->;
-
-export const LixConversationSchema = {
-	"x-lix-key": "lix_conversation",
-	"x-lix-version": "1.0",
-	"x-lix-primary-key": ["/id"],
-	"x-lix-override-lixcols": {
-		lixcol_file_id: '"lix"',
-		lixcol_plugin_key: '"lix_sdk"',
-	},
-	type: "object",
-	properties: {
-		id: {
-			type: "string",
-			"x-lix-default": "lix_uuid_v7()",
-		},
-	},
-	required: ["id"],
-	additionalProperties: false,
-} as const;
-LixConversationSchema satisfies LixSchemaDefinition;
-
-export type LixConversationMessage = FromLixSchemaDefinition<
-	typeof LixConversationMessageSchema
-> & {
-	body: ZettelDoc;
-};
-
-export const LixConversationMessageSchema = {
-	"x-lix-key": "lix_conversation_message",
-	"x-lix-version": "1.0",
-	"x-lix-primary-key": ["/id"],
-	"x-lix-override-lixcols": {
-		lixcol_file_id: '"lix"',
-		lixcol_plugin_key: '"lix_sdk"',
-	},
-	"x-lix-foreign-keys": [
-		{
-			properties: ["/conversation_id"],
-			references: {
-				schemaKey: "lix_conversation",
-				properties: ["/id"],
-			},
-		},
-		{
-			properties: ["/parent_id"],
-			references: {
-				schemaKey: "lix_conversation_message",
-				properties: ["/id"],
-			},
-		},
-	],
-	type: "object",
-	properties: {
-		id: {
-			type: "string",
-			"x-lix-default": "lix_uuid_v7()",
-		},
-		conversation_id: { type: "string" },
-		parent_id: { type: "string", nullable: true },
-		body: ZettelDocJsonSchema as any,
-	},
-	required: ["id", "conversation_id", "body"],
-	additionalProperties: false,
-} as const;
-LixConversationMessageSchema satisfies LixSchemaDefinition;

package/src/database/graph-traversal-mode.ts

@@ -1,75 +0,0 @@
-/**
- * Describes how to traverse a graph structure (such as a change set graph).
- *
- * - `direct`: {@link GraphTraversalModeDirect}
- * - `recursive`: {@link GraphTraversalModeRecursive}
- *
- * This is used throughout Lix to determine how much of the graph should be included
- * during operations like applying, merging, or analyzing change sets.
- */
-export type GraphTraversalMode =
-	| GraphTraversalModeDirect
-	| GraphTraversalModeRecursive;
-
-/**
- * Direct mode: Only the specified node is included.
- *
- * No parent or child traversal is performed.
- *
- * ```mermaid
- * graph TD
- *     A[ChangeSet A]
- *     B[ChangeSet B]
- *     C[ChangeSet C]
- *     B --> A
- *     C --> B
- *     click A "Selected (direct)"
- * ```
- *
- * Selected node: A
- * Included: only A
- *
- * @example
- * ```ts
- * const mode: GraphTraversalMode = { type: "direct" };
- * ```
- */
-export type GraphTraversalModeDirect = {
-	type: "direct";
-};
-
-/**
- * Recursive mode: Includes the specified node and all transitive parents (or children).
- *
- * Optionally limits depth of traversal.
- *
- * ```mermaid
- * graph TD
- *     A[ChangeSet A]
- *     B[ChangeSet B]
- *     C[ChangeSet C]
- *     B --> A
- *     C --> B
- *     click C "Selected (recursive)"
- * ```
- *
- * @example
- * ```ts
- * const mode: GraphTraversalMode = { type: "recursive" };
- * const mode: GraphTraversalMode = { type: "recursive", depth: 1 };
- * ```
- *
- * Selected node: C
- * Included:
- * - If `depth` is undefined: C → B → A
- * - If `depth` is 1: C → B only
- */
-export type GraphTraversalModeRecursive = {
-	type: "recursive";
-	/**
-	 * Optional maximum depth to traverse.
-	 * - `depth = 0` includes direct parents/children only.
-	 * - `undefined` includes full ancestry/descendants.
-	 */
-	depth?: number;
-};

package/src/database/index.ts

@@ -1,3 +0,0 @@
-export { type LixDatabaseSchema } from "./schema.js";
-export { jsonObjectFrom, jsonArrayFrom } from "kysely/helpers/sqlite";
-export { sql } from "kysely";

package/src/database/init-db.ts

@@ -1,158 +0,0 @@
-import { Kysely } from "kysely";
-import type { SqliteWasmDatabase } from "./sqlite/create-in-memory-database.js";
-import type { LixDatabaseSchema } from "./schema.js";
-import { createLixDialect } from "./sqlite/lix-dialect.js";
-import { createDefaultPlugins } from "./kysely/plugins.js";
-// Schema imports
-import { applyChangeDatabaseSchema } from "../change/schema.js";
-import { applyVersionDatabaseSchema } from "../version/schema.js";
-import { applySnapshotDatabaseSchema } from "../snapshot/schema.js";
-import { applyStateDatabaseSchema } from "../state/schema.js";
-// import { applyAccountDatabaseSchema } from "../account/schema.js";
-import { applyStateHistoryDatabaseSchema } from "../state-history/schema.js";
-import type { LixHooks } from "../hooks/create-hooks.js";
-import type { LixEngine } from "../engine/boot.js";
-import { nanoIdSync } from "../engine/functions/nano-id.js";
-import { applyFileLixcolCacheSchema } from "../filesystem/file/cache/lixcol-schema.js";
-import { applyFileDataCacheSchema } from "../filesystem/file/cache/schema.js";
-import { applyFilePathCacheSchema } from "../filesystem/file/cache/path-cache-schema.js";
-import { applyTransactionStateSchema } from "../state/transaction/schema.js";
-import { uuidV7Sync } from "../engine/functions/uuid-v7.js";
-import { humanIdSync } from "../engine/functions/generate-human-id.js";
-import { getTimestampSync } from "../engine/functions/timestamp.js";
-// import { applyKeyValueDatabaseSchema } from "../key-value/schema.js";
-
-/**
- * Configuration for JSON columns in database views.
- *
- * Specifies which columns contain JSON data and what types of JSON values they accept.
- * This is used by the JSONColumnPlugin to properly serialize/deserialize JSON data.
- *
- * Column types:
- * - `type: 'object'` - Column only accepts JSON objects. String values are assumed to be
- *   pre-serialized JSON to prevent double serialization when data flows between views.
- * - `type: ['string', 'number', 'boolean', 'object', 'array', 'null']` - Column accepts
- *   any valid JSON value. All values are properly serialized.
- *
- * @example
- * ```typescript
- * {
- *   change: {
- *     snapshot_content: { type: 'object' } // Only objects, prevents double serialization
- *   },
- *   key_value: {
- *     value: { type: ['string', 'number', 'boolean', 'object', 'array', 'null'] } // Any JSON
- *   }
- * }
- * ```
- */
-export function prepareEngineDatabase(args: {
-	engine: Pick<
-		LixEngine,
-		"sqlite" | "hooks" | "executeSync" | "runtimeCacheRef" | "preprocessQuery"
-	>;
-}): void {
-	// Lower fsync frequency for better write throughput; NORMAL still syncs at txn boundaries.
-	args.engine.sqlite.exec({ sql: "PRAGMA synchronous = NORMAL;" });
-	// Enlarge the page cache to keep more hot pages in memory (approximately 40 MiB at 4 KiB pages).
-	args.engine.sqlite.exec({ sql: "PRAGMA cache_size = 10000;" });
-
-	initFunctions(args.engine);
-
-	// Apply all database schemas first (tables, views, triggers)
-	applyTransactionStateSchema({ engine: args.engine });
-	applySnapshotDatabaseSchema(args.engine.sqlite);
-	applyChangeDatabaseSchema(args.engine.sqlite);
-	applyFileLixcolCacheSchema({ engine: args.engine });
-	applyFileDataCacheSchema({ engine: args.engine });
-	applyFilePathCacheSchema({ engine: args.engine });
-	applyStateDatabaseSchema({ engine: args.engine });
-	// applyEntityDatabaseSchema({ engine: args.engine });
-	// applyChangeSetDatabaseSchema({ engine: args.engine });
-	// applyCommitDatabaseSchema({ engine: args.engine });
-	// applyStoredSchemaDatabaseSchema({ engine: args.engine });
-	applyVersionDatabaseSchema({ engine: args.engine });
-	// applyAccountDatabaseSchema({ engine: args.engine });
-	// applyKeyValueDatabaseSchema({ engine: args.engine });
-	// applyChangeAuthorDatabaseSchema({ engine: args.engine });
-	// applyLabelDatabaseSchema({ engine: args.engine });
-	applyStateHistoryDatabaseSchema({ engine: args.engine });
-	// applyConversationDatabaseSchema({ engine: args.engine });
-	// applyEntityConversationDatabaseSchema({ engine: args.engine });
-	// applyChangeProposalDatabaseSchema({ engine: args.engine });
-	// applyFileDatabaseSchema will be called later when lix is fully constructed
-	// applyLogDatabaseSchema({ engine: args.engine });
-}
-
-export function initKysely(args: {
-	sqlite: SqliteWasmDatabase;
-}): Kysely<LixDatabaseSchema> {
-	const db = new Kysely<LixDatabaseSchema>({
-		dialect: createLixDialect({ sqlite: args.sqlite }),
-		plugins: [...createDefaultPlugins()],
-	});
-
-	return db;
-}
-
-function initFunctions(args: {
-	sqlite: SqliteWasmDatabase;
-	executeSync: LixEngine["executeSync"];
-	runtimeCacheRef: LixEngine["runtimeCacheRef"];
-	hooks: LixHooks;
-}) {
-	const engine = {
-		sqlite: args.sqlite,
-		hooks: args.hooks,
-		executeSync: args.executeSync,
-		runtimeCacheRef: args.runtimeCacheRef,
-	} as const satisfies Pick<
-		LixEngine,
-		"sqlite" | "hooks" | "executeSync" | "runtimeCacheRef"
-	>;
-
-	// TODO function registration is in the engine's boot itself.
-	args.sqlite.createFunction({
-		name: "lix_uuid_v7",
-		arity: 0,
-		xFunc: () => uuidV7Sync({ engine: engine }),
-	});
-
-	args.sqlite.createFunction({
-		name: "human_id",
-		arity: 0,
-		xFunc: () =>
-			humanIdSync({ engine: engine, separator: "-", capitalize: false }),
-	});
-
-	args.sqlite.createFunction({
-		name: "lix_timestamp",
-		arity: 0,
-		xFunc: () => getTimestampSync({ engine: engine }),
-	});
-
-	args.sqlite.createFunction({
-		name: "lix_nano_id",
-		arity: -1,
-		// @ts-expect-error - not sure why this is not working
-		xFunc: (_ctx: number, length?: number) => {
-			return nanoIdSync({ engine, length });
-		},
-	});
-
-	args.sqlite.createFunction({
-		name: "lix_trigger_raise",
-		arity: -1,
-		xFunc: (_ctx: number, kind?: unknown, message?: unknown) => {
-			const action = typeof kind === "string" ? kind.toUpperCase() : "FAIL";
-			if (action === "IGNORE") {
-				return null;
-			}
-			const text =
-				typeof message === "string" && message.length > 0
-					? message
-					: `Trigger ${action}`;
-			throw new Error(text);
-		},
-	});
-}

package/src/database/kysely/index.ts

@@ -1 +0,0 @@
-export { createDefaultPlugins } from "./plugins.js";

package/src/database/kysely/json-column-config.ts

@@ -1,63 +0,0 @@
-import { LixSchemaViewMap } from "../schema-view-map.js";
-import { isJsonType } from "../../schema-definition/json-type.js";
-
-export function buildJsonColumnConfig(args?: {
-	includeChangeView?: boolean;
-}): Record<string, Record<string, { type: any }>> {
-	const includeChangeView = args?.includeChangeView ?? true;
-	const result: Record<string, Record<string, { type: any }>> = {};
-
-	const fileJsonColumns = {
-		metadata: { type: "object" },
-	} as const;
-
-	const hardcoded: Record<string, Record<string, { type: any }>> = {
-		state: {
-			snapshot_content: { type: "object" },
-			metadata: { type: "object" },
-		},
-		state_by_version: {
-			snapshot_content: { type: "object" },
-			metadata: { type: "object" },
-		},
-		state_history: {
-			snapshot_content: { type: "object" },
-			metadata: { type: "object" },
-		},
-		// hardcoded special handling for file views
-		file: fileJsonColumns,
-		file_by_version: fileJsonColumns,
-		file_history: fileJsonColumns,
-	};
-
-	if (includeChangeView) {
-		hardcoded.change = {
-			snapshot_content: { type: "object" },
-			metadata: { type: "object" },
-		};
-	}
-
-	Object.assign(result, hardcoded);
-
-	for (const [viewName, schema] of Object.entries(LixSchemaViewMap)) {
-		if (typeof schema === "boolean" || !schema.properties) continue;
-		const jsonColumns: Record<string, { type: any }> = {};
-		for (const [key, def] of Object.entries(schema.properties)) {
-			if (isJsonType(def)) {
-				jsonColumns[key] = {
-					type: ["string", "number", "boolean", "object", "array", "null"],
-				};
-			}
-		}
-
-		// All entity views expose lixcol_metadata as a JSON column sourced from change metadata.
-		jsonColumns.lixcol_metadata = { type: "object" };
-		if (Object.keys(jsonColumns).length > 0) {
-			result[viewName] = jsonColumns;
-			result[viewName + "_by_version"] = jsonColumns;
-			result[viewName + "_history"] = jsonColumns;
-		}
-	}
-
-	return result;
-}