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

package/src/lix/open-lix.test.ts

@@ -1,15 +1,14 @@
 import { expect, test } from "vitest";
-import { openLixInMemory } from "./open-lix-in-memory.js";
 import { newLixFile } from "./new-lix.js";
 import type { LixPlugin } from "../plugin/lix-plugin.js";
-import { toBlob } from "./to-blob.js";
-import { usedFileExtensions } from "./open-lix.js";
+import { openLix, usedFileExtensions } from "./open-lix.js";
+import type { Account } from "../account/schema.js";
 
 test("providing plugins should be possible", async () => {
 	const mockPlugin: LixPlugin = {
 		key: "mock-plugin",
 	};
-	const lix = await openLixInMemory({
+	const lix = await openLix({
 		blob: await newLixFile(),
 		providePlugins: [mockPlugin],
 	});
@@ -17,7 +16,7 @@ test("providing plugins should be possible", async () => {
 });
 
 test("providing key values should be possible", async () => {
-	const lix = await openLixInMemory({
+	const lix = await openLix({
 		blob: await newLixFile(),
 		keyValues: [{ key: "mock_key", value: "value" }],
 	});
@@ -31,8 +30,8 @@ test("providing key values should be possible", async () => {
 	expect(value).toMatchObject({ key: "mock_key", value: "value" });
 
 	// testing overwriting key values
-	const lix1 = await openLixInMemory({
-		blob: await toBlob({ lix }),
+	const lix1 = await openLix({
+		blob: await lix.toBlob(),
 		keyValues: [{ key: "mock_key", value: "value2" }],
 	});
 
@@ -46,12 +45,12 @@ test("providing key values should be possible", async () => {
 });
 
 test("providing an account should be possible", async () => {
-	const mockAccount = {
+	const mockAccount: Account = {
 		id: "mock-account",
 		name: "peter",
 	};
 
-	const lix = await openLixInMemory({
+	const lix = await openLix({
 		account: mockAccount,
 		blob: await newLixFile(),
 	});
@@ -63,26 +62,10 @@ test("providing an account should be possible", async () => {
 
 	expect(accounts, "to be the provided account").toContainEqual(mockAccount);
 	expect(accounts, "no other active account is inserted").lengthOf(1);
-
-	await lix.db
-		.insertInto("key_value")
-		.values([{ key: "mock_key", value: "something" }])
-		.execute();
-
-	// lix automatically handles inserting the active account into the account table
-	const change = await lix.db
-		.selectFrom("change")
-		.innerJoin("change_author", "change_author.change_id", "change.id")
-		.where("schema_key", "=", "lix_key_value_table")
-		.where("entity_id", "=", "mock_key")
-		.select("change_author.account_id")
-		.executeTakeFirstOrThrow();
-
-	expect(change.account_id).toBe(mockAccount.id);
 });
 
 test("usedFileExtensions", async () => {
-	const lix = await openLixInMemory({
+	const lix = await openLix({
 		blob: await newLixFile(),
 	});
 	await lix.db
@@ -106,3 +89,59 @@ test("usedFileExtensions", async () => {
 	const extensions = await usedFileExtensions(lix.db);
 	expect(new Set(extensions)).toEqual(new Set(["txt", "pdf"]));
 });
+
+test("it should open a lix in memory from a blob", async () => {
+	const lix1 = await openLix({});
+
+	await lix1.db
+		.insertInto("file")
+		.values({
+			id: "1",
+			path: "/a.txt",
+			data: new TextEncoder().encode("hello"),
+		})
+		.execute();
+
+	const lix2 = await openLix({ blob: await lix1.toBlob() });
+	const files = await lix2.db.selectFrom("file").selectAll().execute();
+
+	expect(files).toEqual([
+		expect.objectContaining({
+			id: "1",
+			path: "/a.txt",
+			data: new TextEncoder().encode("hello"),
+		}),
+	]);
+});
+
+test("should default to InMemoryStorage when no storage is provided", async () => {
+	const lix = await openLix({});
+
+	// Should create a valid lix with new data
+	const lixId = await lix.db
+		.selectFrom("key_value")
+		.select("value")
+		.where("key", "=", "lix_id")
+		.executeTakeFirstOrThrow();
+
+	expect(lixId.value).toBeDefined();
+	expect(typeof lixId.value).toBe("string");
+
+	// Should be able to add and query data
+	await lix.db
+		.insertInto("file")
+		.values({
+			id: "test-file",
+			path: "/test.txt",
+			data: new TextEncoder().encode("test content"),
+		})
+		.execute();
+
+	const files = await lix.db.selectFrom("file").selectAll().execute();
+	expect(files).toHaveLength(1);
+	expect(files[0]).toMatchObject({
+		id: "test-file",
+		path: "/test.txt",
+		data: new TextEncoder().encode("test content"),
+	});
+});

package/src/lix/open-lix.ts

@@ -1,14 +1,18 @@
 import type { LixPlugin } from "../plugin/lix-plugin.js";
 import { type SqliteWasmDatabase } from "sqlite-wasm-kysely";
 import { initDb } from "../database/init-db.js";
-import { initFileQueueProcess } from "../file-queue/file-queue-process.js";
 import { sql, type Kysely } from "kysely";
 import type { LixDatabaseSchema } from "../database/schema.js";
-import { initSyncProcess } from "../sync/sync-process.js";
-import type { NewKeyValue } from "../key-value/database-schema.js";
+import type { KeyValue } from "../key-value/schema.js";
 import { capture } from "../services/telemetry/capture.js";
 import { ENV_VARIABLES } from "../services/env-variables/index.js";
-import type { Account } from "../account/database-schema.js";
+import { applyFileDatabaseSchema } from "../file/schema.js";
+import type { NewState } from "../entity-views/types.js";
+import type { Account } from "../account/schema.js";
+import { InMemoryStorage } from "./storage/in-memory.js";
+import type { LixStorageAdapter } from "./storage/lix-storage-adapter.js";
+import { createHooks, type LixHooks } from "../hooks/create-hooks.js";
+import { createObserve } from "../observe/create-observe.js";
 
 export type Lix = {
 	/**
@@ -25,11 +29,60 @@ export type Lix = {
 	db: Kysely<LixDatabaseSchema>;
 	plugin: {
 		getAll: () => Promise<LixPlugin[]>;
+		getAllSync: () => LixPlugin[];
 	};
+	/**
+	 * Hooks for listening to database lifecycle events.
+	 *
+	 * Allows registering callbacks that fire at specific points
+	 * in Lix's execution, such as when state changes are committed.
+	 */
+	hooks: LixHooks;
+	/**
+	 * Closes the lix instance and its storage.
+	 */
+	close: () => Promise<void>;
+	observe: ReturnType<typeof createObserve>;
+	/**
+	 * Serialises the Lix into a {@link Blob}.
+	 *
+	 * Use this helper to persist the current state to disk or send it to a
+	 * server. The blob contains the raw SQLite file representing the Lix
+	 * project.
+	 *
+	 * @example
+	 * ```ts
+	 * const blob = await lix.toBlob()
+	 * download(blob)
+	 * ```
+	 */
+	toBlob: () => Promise<Blob>;
 };
 
 /**
- * Common setup between different lix environments.
+ * Opens a Lix instance.
+ *
+ * Creates an in-memory database by default. If a blob is provided,
+ * the database is initialized with that data. If a database is provided,
+ * uses that database directly.
+ *
+ * TODO: Add storage abstraction to support:
+ *   - OPFS storage (persistent in browser)
+ *   - Node.js filesystem storage
+ *   - Custom storage adapters
+ *
+ * @example
+ * ```ts
+ * // In-memory (default)
+ * const lix = await openLix({})
+ *
+ * // From existing data
+ * const lix = await openLix({ blob: existingLixFile })
+ *
+ * // With custom database (current approach)
+ * const db = await createInMemoryDatabase({ readOnly: false })
+ * const lix = await openLix({ database: db })
+ * ```
  */
 export async function openLix(args: {
 	/**
@@ -42,7 +95,16 @@ export async function openLix(args: {
 	 *   const lix = await openLix({ account })
 	 */
 	account?: Account;
-	database: SqliteWasmDatabase;
+	/**
+	 * Lix file data to initialize the database with.
+	 */
+	blob?: Blob;
+	/**
+	 * Storage adapter for persisting lix data.
+	 *
+	 * @default InMemoryStorage
+	 */
+	storage?: LixStorageAdapter;
 	/**
 	 * Usecase are lix apps that define their own file format,
 	 * like inlang (unlike a markdown, csv, or json plugin).
@@ -54,7 +116,7 @@ export async function openLix(args: {
 	 *     file format sdk. the file is not portable
 	 *
 	 * @example
-	 *   const lix = await openLixInMemory({ providePlugins: [myPlugin] })
+	 *   const lix = await openLix({ providePlugins: [myPlugin] })
 	 */
 	providePlugins?: LixPlugin[];
 	/**
@@ -63,18 +125,49 @@ export async function openLix(args: {
 	 * @example
 	 *   const lix = await openLix({ keyValues: [{ key: "lix_sync", value: "false" }] })
 	 */
-	keyValues?: NewKeyValue[];
+	keyValues?: NewState<KeyValue>[];
 }): Promise<Lix> {
-	const db = initDb({ sqlite: args.database });
+	const storage = args.storage ?? new InMemoryStorage();
+	const database = await storage.open();
+
+	// Import blob data if provided
+	if (args.blob) {
+		await storage.import(args.blob);
+	}
+
+	// Create hooks before initializing database so they can be used in schema setup
+	const hooks = createHooks();
+
+	const db = initDb({ sqlite: database, hooks });
+
+	// Connect storage to state commit hooks if it supports it
+	if ("onStateCommit" in storage && storage.onStateCommit) {
+		hooks.onStateCommit(() => {
+			storage.onStateCommit!();
+		});
+	}
 
 	if (args.keyValues && args.keyValues.length > 0) {
-		await db
-			.insertInto("key_value")
-			.values(args.keyValues)
-			.onConflict((oc) =>
-				oc.doUpdateSet((eb) => ({ value: eb.ref("excluded.value") }))
-			)
-			.execute();
+		for (const keyValue of args.keyValues) {
+			// Check if the key already exists
+			const existing = await db
+				.selectFrom("key_value")
+				.select("key")
+				.where("key", "=", keyValue.key)
+				.executeTakeFirst();
+
+			if (existing) {
+				// Update existing key
+				await db
+					.updateTable("key_value")
+					.set({ value: keyValue.value })
+					.where("key", "=", keyValue.key)
+					.execute();
+			} else {
+				// Insert new key
+				await db.insertInto("key_value").values(keyValue).execute();
+			}
+		}
 	}
 
 	if (args.account) {
@@ -96,19 +189,35 @@ export async function openLix(args: {
 
 	const plugin = {
 		getAll: async () => plugins,
+		getAllSync: () => plugins,
 	};
 
-	await initFileQueueProcess({ lix: { db, plugin, sqlite: args.database } });
+	// await initFileQueueProcess({ lix: { db, plugin, sqlite: args.database } });
 
-	await initSyncProcess({ lix: { db, plugin, sqlite: args.database } });
+	// await initSyncProcess({ lix: { db, plugin, sqlite: args.database } });
 
 	captureOpened({ db });
 
-	return {
+	const observe = createObserve({ hooks });
+
+	const lix = {
 		db,
-		sqlite: args.database,
+		sqlite: database,
 		plugin,
+		hooks,
+		observe,
+		close: async () => {
+			await storage.close();
+		},
+		toBlob: async () => {
+			return storage.export();
+		},
 	};
+
+	// Apply file and account schemas now that we have the full lix object with plugins
+	applyFileDatabaseSchema(lix);
+
+	return lix;
 }
 
 async function captureOpened(args: { db: Kysely<LixDatabaseSchema> }) {
@@ -138,8 +247,8 @@ async function captureOpened(args: { db: Kysely<LixDatabaseSchema> }) {
 		if (Math.random() > 0.1) {
 			await capture("LIX-SDK lix opened", {
 				accountId: activeAccount.id,
-				lixId: lixId.value,
-				telemetryKeyValue: telemetry?.value ?? "on",
+				lixId: lixId.value as string,
+				telemetryKeyValue: (telemetry?.value ?? "on") as string,
 				properties: {
 					lix_sdk_version: ENV_VARIABLES.LIX_SDK_VERSION,
 					stored_file_extensions: fileExtensions,

package/src/lix/storage/in-memory.test.ts

@@ -0,0 +1,180 @@
+import { expect, test } from "vitest";
+import { InMemoryStorage } from "./in-memory.js";
+import { openLix } from "../open-lix.js";
+
+test("should open a database with new lix on first call", async () => {
+	const storage = new InMemoryStorage();
+	const lix = await openLix({ storage });
+
+	const lixId = await lix.db
+		.selectFrom("key_value")
+		.select("value")
+		.where("key", "=", "lix_id")
+		.executeTakeFirstOrThrow();
+
+	expect(lixId.value).toBeDefined();
+	expect(typeof lixId.value).toBe("string");
+});
+
+test("should return same database instance on subsequent calls", async () => {
+	const storage = new InMemoryStorage();
+	const database1 = await storage.open();
+	const database2 = await storage.open();
+
+	expect(database1).toBe(database2);
+});
+
+test("should import blob data, replacing existing content", async () => {
+	const storage = new InMemoryStorage();
+	const lix = await openLix({ storage });
+
+	// Add some initial data
+	await lix.db
+		.insertInto("file")
+		.values({
+			id: "initial-file",
+			path: "/initial.txt",
+			data: new TextEncoder().encode("initial content"),
+		})
+		.execute();
+
+	// Create a new lix with different data
+	const originalStorage = new InMemoryStorage();
+	const originalLix = await openLix({ storage: originalStorage });
+
+	await originalLix.db
+		.insertInto("file")
+		.values({
+			id: "imported-file",
+			path: "/imported.txt",
+			data: new TextEncoder().encode("imported content"),
+		})
+		.execute();
+
+	const blob = await originalStorage.export();
+
+	// Import the blob
+	await storage.import(blob);
+
+	// Check that old data is gone and new data is present
+	const files = await lix.db.selectFrom("file").selectAll().execute();
+	expect(files).toHaveLength(1);
+	expect(files[0]).toMatchObject({
+		id: "imported-file",
+		path: "/imported.txt",
+		data: new TextEncoder().encode("imported content"),
+	});
+});
+
+test("should export current database state as blob", async () => {
+	const storage = new InMemoryStorage();
+	const lix = await openLix({ storage });
+
+	// Add some test data
+	await lix.db
+		.insertInto("file")
+		.values({
+			id: "test-file",
+			path: "/test.txt",
+			data: new TextEncoder().encode("test content"),
+		})
+		.execute();
+
+	const blob = await storage.export();
+
+	// Create new storage and import the blob
+	const newStorage = new InMemoryStorage();
+	const newLix = await openLix({ storage: newStorage, blob });
+
+	// Verify the data was exported and imported correctly
+	const files = await newLix.db.selectFrom("file").selectAll().execute();
+	expect(files).toHaveLength(1);
+	expect(files[0]).toMatchObject({
+		id: "test-file",
+		path: "/test.txt",
+		data: new TextEncoder().encode("test content"),
+	});
+});
+
+test("should close database connection", async () => {
+	const storage = new InMemoryStorage();
+	const database1 = await storage.open();
+
+	await storage.close();
+
+	// Opening again should create a new database
+	const database2 = await storage.open();
+	expect(database1).not.toBe(database2);
+});
+
+test("should handle import before open", async () => {
+	const storage = new InMemoryStorage();
+
+	// Create a blob with test data
+	const sourceStorage = new InMemoryStorage();
+	const sourceLix = await openLix({ storage: sourceStorage });
+
+	await sourceLix.db
+		.insertInto("file")
+		.values({
+			id: "test-file",
+			path: "/test.txt",
+			data: new TextEncoder().encode("test content"),
+		})
+		.execute();
+
+	const blob = await sourceStorage.export();
+
+	// Import before opening
+	await storage.import(blob);
+
+	// Now open and verify
+	const lix = await openLix({ storage });
+	const files = await lix.db.selectFrom("file").selectAll().execute();
+
+	expect(files).toHaveLength(1);
+	expect(files[0]).toMatchObject({
+		id: "test-file",
+		path: "/test.txt",
+	});
+});
+
+test("should handle export before open", async () => {
+	const storage = new InMemoryStorage();
+
+	// Export should work even if we haven't opened yet
+	const blob = await storage.export();
+
+	expect(blob).toBeInstanceOf(Blob);
+	expect(blob.size).toBeGreaterThan(0);
+});
+
+test("multiple storage instances should be independent", async () => {
+	const storage1 = new InMemoryStorage();
+	const storage2 = new InMemoryStorage();
+
+	const lix1 = await openLix({ storage: storage1 });
+	const lix2 = await openLix({ storage: storage2 });
+
+	// Add data to first instance
+	await lix1.db
+		.insertInto("file")
+		.values({
+			id: "file1",
+			path: "/test1.txt",
+			data: new TextEncoder().encode("data1"),
+		})
+		.execute();
+
+	// Second instance should not have the data
+	const files2 = await lix2.db.selectFrom("file").selectAll().execute();
+	expect(files2).toHaveLength(0);
+
+	// First instance should still have the data
+	const files1 = await lix1.db.selectFrom("file").selectAll().execute();
+	expect(files1).toHaveLength(1);
+	expect(files1[0]).toMatchObject({
+		id: "file1",
+		path: "/test1.txt",
+	});
+});

package/src/lix/storage/in-memory.ts

@@ -0,0 +1,69 @@
+import {
+	type SqliteWasmDatabase,
+	createInMemoryDatabase,
+	importDatabase,
+	contentFromDatabase,
+} from "sqlite-wasm-kysely";
+import { newLixFile } from "../new-lix.js";
+import type { LixStorageAdapter } from "./lix-storage-adapter.js";
+
+/**
+ * In-memory storage adapter for Lix.
+ *
+ * Data is stored only for the lifetime of the JavaScript context.
+ * When the page is refreshed or the application is closed, all data is lost.
+ */
+export class InMemoryStorage implements LixStorageAdapter {
+	private database?: SqliteWasmDatabase;
+
+	/**
+	 * Opens an in-memory SQLite database.
+	 *
+	 * Creates a new empty lix if this is the first time opening.
+	 * Returns the same database instance on subsequent calls.
+	 */
+	async open(): Promise<SqliteWasmDatabase> {
+		if (!this.database) {
+			this.database = await createInMemoryDatabase({ readOnly: false });
+
+			// Initialize with new empty lix
+			const blob = await newLixFile();
+			importDatabase({
+				db: this.database,
+				content: new Uint8Array(await blob.arrayBuffer()),
+			});
+		}
+
+		return this.database;
+	}
+
+	/**
+	 * Closes the database connection.
+	 *
+	 * Note: For in-memory databases, this just clears the reference.
+	 * The data is lost when the database is no longer referenced.
+	 */
+	async close(): Promise<void> {
+		this.database = undefined;
+	}
+
+	/**
+	 * Imports data from a blob, replacing the current database content.
+	 */
+	async import(blob: Blob): Promise<void> {
+		const database = await this.open();
+		importDatabase({
+			db: database,
+			content: new Uint8Array(await blob.arrayBuffer()),
+		});
+	}
+
+	/**
+	 * Exports the current database state as a blob.
+	 */
+	async export(): Promise<Blob> {
+		const database = await this.open();
+		const content = contentFromDatabase(database);
+		return new Blob([content]);
+	}
+}

package/src/lix/storage/lix-storage-adapter.ts

@@ -0,0 +1,16 @@
+/**
+ * Storage adapter interface for Lix.
+ */
+import type { SqliteWasmDatabase } from "sqlite-wasm-kysely";
+
+export interface LixStorageAdapter {
+	open(): Promise<SqliteWasmDatabase>;
+	close(): Promise<void>;
+	import(blob: Blob): Promise<void>;
+	export(): Promise<Blob>;
+	/**
+	 * Called when state commits happen.
+	 * Optional method for storage adapters that want to persist on state changes.
+	 */
+	onStateCommit?(): void;
+}