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

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

@@ -1,6 +1,7 @@
 import { expect, test } from "vitest";
 import { InMemoryStorage } from "./in-memory.js";
 import { openLix } from "../open-lix.js";
+import { newLixFile } from "../new-lix.js";
 
 test("should open a database with new lix on first call", async () => {
 	const storage = new InMemoryStorage();
@@ -18,54 +19,12 @@ test("should open a database with new lix on first call", async () => {
 
 test("should return same database instance on subsequent calls", async () => {
 	const storage = new InMemoryStorage();
-	const database1 = await storage.open();
-	const database2 = await storage.open();
+	const database1 = await storage.open({ createBlob: newLixFile });
+	const database2 = await storage.open({ createBlob: newLixFile });
 
 	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 });
@@ -98,55 +57,22 @@ test("should export current database state as blob", async () => {
 
 test("should close database connection", async () => {
 	const storage = new InMemoryStorage();
-	const database1 = await storage.open();
+	const database1 = await storage.open({ createBlob: newLixFile });
 
 	await storage.close();
 
 	// Opening again should create a new database
-	const database2 = await storage.open();
+	const database2 = await storage.open({ createBlob: newLixFile });
 	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);
+	// Export should throw an error if we haven't opened yet
+	await expect(storage.export()).rejects.toThrow(
+		"Database has not been opened yet"
+	);
 });
 
 test("multiple storage instances should be independent", async () => {

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

@@ -4,7 +4,6 @@ import {
 	importDatabase,
 	contentFromDatabase,
 } from "sqlite-wasm-kysely";
-import { newLixFile } from "../new-lix.js";
 import type { LixStorageAdapter } from "./lix-storage-adapter.js";
 
 /**
@@ -19,15 +18,18 @@ export class InMemoryStorage implements LixStorageAdapter {
 	/**
 	 * Opens an in-memory SQLite database.
 	 *
-	 * Creates a new empty lix if this is the first time opening.
+	 * Creates a new database and optionally initializes it with the provided blob.
 	 * Returns the same database instance on subsequent calls.
 	 */
-	async open(): Promise<SqliteWasmDatabase> {
+	async open(args: {
+		blob?: Blob;
+		createBlob: () => Promise<Blob>;
+	}): Promise<SqliteWasmDatabase> {
 		if (!this.database) {
 			this.database = await createInMemoryDatabase({ readOnly: false });
 
-			// Initialize with new empty lix
-			const blob = await newLixFile();
+			// Initialize with provided blob or create new one
+			const blob = args.blob ?? (await args.createBlob());
 			importDatabase({
 				db: this.database,
 				content: new Uint8Array(await blob.arrayBuffer()),
@@ -47,23 +49,16 @@ export class InMemoryStorage implements LixStorageAdapter {
 		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.
+	 *
+	 * @throws Error if the database has not been opened yet
 	 */
 	async export(): Promise<Blob> {
-		const database = await this.open();
-		const content = contentFromDatabase(database);
+		if (!this.database) {
+			throw new Error("Database has not been opened yet");
+		}
+		const content = contentFromDatabase(this.database);
 		return new Blob([content]);
 	}
 }

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

@@ -2,15 +2,51 @@
  * Storage adapter interface for Lix.
  */
 import type { SqliteWasmDatabase } from "sqlite-wasm-kysely";
+import type { LixAccount } from "../../account/schema.js";
+import type { Lix } from "../open-lix.js";
 
 export interface LixStorageAdapter {
-	open(): Promise<SqliteWasmDatabase>;
+	/**
+	 * Opens and returns the database instance.
+	 *
+	 * @param args - Arguments for opening the storage
+	 * @param args.blob - Optional blob to initialize the storage with (takes precedence over existing data)
+	 * @param args.createBlob - Callback to create a new blob if no existing data is found
+	 */
+	open(args: {
+		blob?: Blob;
+		createBlob: () => Promise<Blob>;
+	}): Promise<SqliteWasmDatabase>;
+
+	/**
+	 * Closes the database and cleans up resources.
+	 */
 	close(): Promise<void>;
-	import(blob: Blob): Promise<void>;
+
+	/**
+	 * Exports the current storage state as a blob.
+	 */
 	export(): Promise<Blob>;
+
+	/**
+	 * Called after the Lix instance is fully initialized.
+	 * Allows storage adapters to set up observers, hooks, etc.
+	 *
+	 * @param args - Object containing the Lix instance and future options
+	 */
+	connect?(args: { lix: Lix }): void;
+
 	/**
-	 * Called when state commits happen.
-	 * Optional method for storage adapters that want to persist on state changes.
+	 * Returns any persisted state that should be restored.
+	 * Called during Lix initialization to restore saved state.
+	 *
+	 * @returns Promise resolving to persisted state, or undefined if none
 	 */
-	onStateCommit?(): void;
+	getPersistedState?(): Promise<
+		| {
+				activeAccounts?: Pick<LixAccount, "id" | "name">[];
+				// Future: Add more persisted state here
+		  }
+		| undefined
+	>;
 }

package/src/lix/storage/opfs.test.ts

@@ -1,11 +1,11 @@
 import { test, expect, describe, beforeEach, vi } from "vitest";
 import { OpfsStorage } from "./opfs.js";
 import { openLix } from "../open-lix.js";
-import { InMemoryStorage } from "./in-memory.js";
+import { newLixFile } from "../new-lix.js";
 
 // Create a realistic in-memory OPFS mock
 class MockOPFS {
-	private files = new Map<string, Uint8Array>();
+	private files = new Map<string, Uint8Array | string>();
 
 	createMockOpfsRoot() {
 		return {
@@ -25,10 +25,21 @@ class MockOPFS {
 	private createMockFileHandle(filename: string) {
 		return {
 			getFile: vi.fn().mockImplementation(() => {
-				const data = this.files.get(filename) || new Uint8Array(0);
-				return Promise.resolve({
-					arrayBuffer: vi.fn().mockResolvedValue(data.buffer),
-				});
+				const data = this.files.get(filename);
+				if (typeof data === "string") {
+					return Promise.resolve({
+						text: vi.fn().mockResolvedValue(data),
+						arrayBuffer: vi
+							.fn()
+							.mockResolvedValue(new TextEncoder().encode(data).buffer),
+					});
+				} else {
+					const bytes = data || new Uint8Array(0);
+					return Promise.resolve({
+						text: vi.fn().mockResolvedValue(new TextDecoder().decode(bytes)),
+						arrayBuffer: vi.fn().mockResolvedValue(bytes.buffer),
+					});
+				}
 			}),
 			createWritable: vi.fn().mockImplementation(() => {
 				return Promise.resolve(this.createMockWritable(filename));
@@ -37,11 +48,15 @@ class MockOPFS {
 	}
 
 	private createMockWritable(filename: string) {
-		let buffer = new Uint8Array(0);
+		let buffer: Uint8Array | string;
 
 		return {
-			write: vi.fn().mockImplementation((data: Uint8Array) => {
-				buffer = new Uint8Array(data);
+			write: vi.fn().mockImplementation((data: Uint8Array | string) => {
+				if (typeof data === "string") {
+					buffer = data;
+				} else {
+					buffer = new Uint8Array(data);
+				}
 				return Promise.resolve();
 			}),
 			close: vi.fn().mockImplementation(() => {
@@ -57,6 +72,7 @@ describe("OpfsStorage", () => {
 
 	beforeEach(() => {
 		vi.clearAllMocks();
+		// Create a fresh MockOPFS instance for each test to prevent cross-test pollution
 		mockOpfs = new MockOPFS();
 
 		// Setup OPFS mock
@@ -69,6 +85,7 @@ describe("OpfsStorage", () => {
 				},
 			},
 			writable: true,
+			configurable: true,
 		});
 	});
 
@@ -99,8 +116,8 @@ describe("OpfsStorage", () => {
 
 	test("returns same database instance on multiple open calls", async () => {
 		const storage = new OpfsStorage({ path: "test.db" });
-		const db1 = await storage.open();
-		const db2 = await storage.open();
+		const db1 = await storage.open({ createBlob: () => newLixFile() });
+		const db2 = await storage.open({ createBlob: () => newLixFile() });
 
 		expect(db1).toBe(db2);
 	});
@@ -113,26 +130,6 @@ describe("OpfsStorage", () => {
 		await expect(storage.close()).resolves.not.toThrow();
 	});
 
-	test("imports lix file blob and saves to OPFS", async () => {
-		const storage = new OpfsStorage({ path: "test.db" });
-
-		const sourceLix = await openLix({ storage: new InMemoryStorage() });
-
-		// Add some data to the source
-		await sourceLix.db
-			.insertInto("key_value")
-			.values({
-				key: "imported-key",
-				value: "imported-value",
-			})
-			.execute();
-
-		const lixBlob = await sourceLix.toBlob();
-
-		// This should not throw
-		await expect(storage.import(lixBlob)).resolves.not.toThrow();
-	});
-
 	test("integrates with openLix", async () => {
 		const storage = new OpfsStorage({ path: "integration.db" });
 		const lix = await openLix({ storage });
@@ -180,6 +177,9 @@ describe("OpfsStorage", () => {
 		expect(result[0]?.value).toBe("e2e-test-value");
 	});
 
+	// TODO occasional test failures due to timing issues
+	// faulty state materialization might be the cause.
+	// fix after https://github.com/opral/lix-sdk/issues/308
 	test("can save and load data persistence", async () => {
 		const path = "persistence-test.db";
 
@@ -198,6 +198,9 @@ describe("OpfsStorage", () => {
 		// Wait for auto-save to complete
 		await new Promise((resolve) => setTimeout(resolve, 150));
 
+		// Close the first lix to ensure data is saved
+		await lix1.close();
+
 		// Open new storage instance with same path
 		const storage2 = new OpfsStorage({ path });
 		const lix2 = await openLix({ storage: storage2 });
@@ -212,4 +215,224 @@ describe("OpfsStorage", () => {
 		expect(result).toHaveLength(1);
 		expect(result[0]?.value).toBe("test-value");
 	});
+
+	test("persists active account", async () => {
+		const path = "example.lix";
+		const storage = new OpfsStorage({ path });
+
+		const account = { id: "test-account", name: "Test User" };
+
+		// provide lix on initial load with an account
+		const lix = await openLix({
+			storage,
+			account,
+		});
+
+		// Verify current active account with details
+		const activeAccount = await lix.db
+			.selectFrom("active_account as aa")
+			.innerJoin("account_all as a", "a.id", "aa.account_id")
+			.where("a.lixcol_version_id", "=", "global")
+			.select(["aa.account_id", "a.id", "a.name"])
+			.executeTakeFirstOrThrow();
+
+		expect(activeAccount.account_id).toBe(account.id);
+		expect(activeAccount.name).toBe(account.name);
+
+		await lix.close();
+
+		// Reopen the lix
+		const lix2 = await openLix({ storage });
+
+		// Verify active account persisted with details
+		const activeAccount2 = await lix2.db
+			.selectFrom("active_account as aa")
+			.innerJoin("account_all as a", "a.id", "aa.account_id")
+			.where("a.lixcol_version_id", "=", "global")
+			.select(["aa.account_id", "a.id", "a.name"])
+			.executeTakeFirstOrThrow();
+
+		expect(activeAccount2.account_id).toBe(account.id);
+		expect(activeAccount2.name).toBe(account.name);
+	});
+
+	test("active account persistence across multiple storage instances", async () => {
+		const path = "example.lix";
+		const storage1 = new OpfsStorage({ path });
+
+		const account = { id: "test-account", name: "Test User" };
+
+		const lix1 = await openLix({
+			storage: storage1,
+			account,
+		});
+
+		// Verify current active account with details
+		const activeAccount = await lix1.db
+			.selectFrom("active_account as aa")
+			.innerJoin("account_all as a", "a.id", "aa.account_id")
+			.where("a.lixcol_version_id", "=", "global")
+			.select(["aa.account_id", "a.id", "a.name"])
+			.executeTakeFirstOrThrow();
+
+		expect(activeAccount.account_id).toBe(account.id);
+		expect(activeAccount.name).toBe(account.name);
+
+		await lix1.close();
+
+		const storage2 = new OpfsStorage({ path });
+		// Reopen the lix instance
+		const lix2 = await openLix({ storage: storage2 });
+
+		// Verify active account persisted with details
+		const activeAccount2 = await lix2.db
+			.selectFrom("active_account as aa")
+			.innerJoin("account_all as a", "a.id", "aa.account_id")
+			.where("a.lixcol_version_id", "=", "global")
+			.select(["aa.account_id", "a.id", "a.name"])
+			.executeTakeFirstOrThrow();
+
+		expect(activeAccount2.account_id).toBe(account.id);
+		expect(activeAccount2.name).toBe(account.name);
+	});
+
+	// TODO occasional test failures due to timing issues
+	// faulty state materialization might be the cause.
+	// fix after https://github.com/opral/lix-sdk/issues/308
+	test("only saves active accounts when they change", async () => {
+		const path = "observer-test.lix";
+		const storage = new OpfsStorage({ path });
+
+		const account = { id: "observer-account", name: "Observer Test" };
+		const lix = await openLix({ storage, account });
+
+		// Spy on the saveActiveAccounts method
+		const saveActiveAccountsSpy = vi.spyOn(
+			storage as any,
+			"saveActiveAccounts"
+		);
+
+		// Wait a bit for the initial save from the observer
+		await new Promise((resolve) => setTimeout(resolve, 50));
+
+		// Clear the spy to ignore the initial save
+		saveActiveAccountsSpy.mockClear();
+
+		// Ensure active version exists before proceeding
+		const activeVersion = await lix.db
+			.selectFrom("active_version")
+			.select("version_id")
+			.executeTakeFirst();
+
+		expect(activeVersion).toBeDefined();
+		expect(activeVersion?.version_id).toBeDefined();
+
+		// Make a change that doesn't affect active_account
+		await lix.db
+			.insertInto("key_value")
+			.values({ key: "test-key", value: "test-value" })
+			.execute();
+
+		// Wait for potential save
+		await new Promise((resolve) => setTimeout(resolve, 50));
+
+		// Should not have saved active accounts
+		expect(saveActiveAccountsSpy).not.toHaveBeenCalled();
+
+		// Now update the active account by deleting and re-inserting
+		// First create the new account in account_all
+		await lix.db
+			.insertInto("account_all")
+			.values({
+				id: "new-account",
+				name: "New Account",
+				lixcol_version_id: "global",
+			})
+			.execute();
+
+		await lix.db
+			.deleteFrom("active_account")
+			.where("account_id", "=", account.id)
+			.execute();
+
+		await lix.db
+			.insertInto("active_account")
+			.values({ account_id: "new-account" })
+			.execute();
+
+		// Wait for save
+		await new Promise((resolve) => setTimeout(resolve, 150));
+
+		// Should have saved active accounts now (twice: once for delete, once for insert)
+		expect(saveActiveAccountsSpy).toHaveBeenCalledTimes(2);
+
+		await lix.close();
+	});
+
+	test("clean() removes all files from OPFS", async () => {
+		// Create some files in OPFS
+		const storage1 = new OpfsStorage({ path: "file1.lix" });
+		const storage2 = new OpfsStorage({ path: "file2.lix" });
+
+		// Open and create files
+		await openLix({ storage: storage1 });
+		await openLix({ storage: storage2 });
+
+		// Also create an active accounts file
+		const lix3 = await openLix({
+			storage: new OpfsStorage({ path: "file3.lix" }),
+			account: { id: "test-clean", name: "Clean Test" },
+		});
+		await lix3.close();
+
+		// Mock the OPFS directory structure for clean()
+		const mockFiles = new Map([
+			["file1.lix", { kind: "file", name: "file1.lix" }],
+			["file2.lix", { kind: "file", name: "file2.lix" }],
+			["file3.lix", { kind: "file", name: "file3.lix" }],
+			[
+				"lix_active_accounts.json",
+				{ kind: "file", name: "lix_active_accounts.json" },
+			],
+			["some-dir", { kind: "directory", name: "some-dir" }],
+		]);
+
+		const removeEntrySpy = vi.fn();
+
+		// Override getDirectory for clean() to return our mock structure
+		vi.mocked(navigator.storage.getDirectory).mockResolvedValueOnce({
+			values: vi.fn().mockImplementation(function* () {
+				for (const entry of mockFiles.values()) {
+					yield entry;
+				}
+			}),
+			removeEntry: removeEntrySpy,
+		} as any);
+
+		// Call clean()
+		await OpfsStorage.clean();
+
+		// Verify all files and directories were removed
+		expect(removeEntrySpy).toHaveBeenCalledTimes(5);
+		expect(removeEntrySpy).toHaveBeenCalledWith("file1.lix");
+		expect(removeEntrySpy).toHaveBeenCalledWith("file2.lix");
+		expect(removeEntrySpy).toHaveBeenCalledWith("file3.lix");
+		expect(removeEntrySpy).toHaveBeenCalledWith("lix_active_accounts.json");
+		expect(removeEntrySpy).toHaveBeenCalledWith("some-dir", {
+			recursive: true,
+		});
+	});
+
+	test("clean() throws error if OPFS is not supported", async () => {
+		// Remove navigator to simulate unsupported environment
+		const originalNavigator = globalThis.navigator;
+		delete (globalThis as any).navigator;
+
+		await expect(OpfsStorage.clean()).rejects.toThrow(
+			"OPFS is not supported in this environment"
+		);
+
+		// Restore navigator
+		globalThis.navigator = originalNavigator;
+	});
 });