@lix-js/sdk 0.0.1

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@lix-js/sdk",
+  "type": "module",
+  "version": "0.0.1",
+  "license": "Apache-2.0",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "_filesComment": "Shipping src for better debugging experience",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "_comment": "Required for tree-shaking https://webpack.js.org/guides/tree-shaking/#mark-the-file-as-side-effect-free",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=21"
+  },
+  "bundleDependencies": [
+    "@lix-js/server-api-schema",
+    "sqlite-wasm-kysely"
+  ],
+  "dependencies": {
+    "dedent": "1.5.1",
+    "human-id": "^4.1.1",
+    "js-sha256": "^0.11.0",
+    "kysely": "^0.27.4",
+    "uuid": "^10.0.0",
+    "sqlite-wasm-kysely": "0.1.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.12.0",
+    "@types/uuid": "^10.0.0",
+    "@vitest/coverage-v8": "^2.0.5",
+    "eslint": "^9.12.0",
+    "json-schema-to-ts": "^3.1.1",
+    "prettier": "^3.3.3",
+    "typescript": "^5.5.4",
+    "typescript-eslint": "^8.9.0",
+    "vitest": "^2.0.5",
+    "@lix-js/server-api-schema": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsc --build",
+    "test": "tsc --noEmit && vitest run --coverage",
+    "test:watch": "vitest",
+    "bench": "vitest bench",
+    "lint": "eslint src/**/* --fix",
+    "dev": "tsc --watch",
+    "format": "prettier ./src --write"
+  }
+}

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

@@ -0,0 +1,26 @@
+import { test, expect } from "vitest";
+import { openLixInMemory } from "../lix/open-lix-in-memory.js";
+import { createAccount } from "./create-account.js";
+
+test("should create an account", async () => {
+	const lix = await openLixInMemory({});
+
+	const accountName = "test_account";
+	const account = await createAccount({ lix, name: accountName });
+
+	// Verify the account was created
+	expect(account).toMatchObject({
+		name: accountName,
+	});
+
+	// Verify the account exists in the database
+	const dbAccount = await lix.db
+		.selectFrom("account")
+		.selectAll()
+		.where("id", "=", account.id)
+		.executeTakeFirstOrThrow();
+
+	expect(dbAccount).toMatchObject({
+		name: accountName,
+	});
+});

package/src/account/create-account.ts

@@ -0,0 +1,26 @@
+import type { Lix } from "../lix/open-lix.js";
+import type { Account } from "./database-schema.js";
+
+export async function createAccount(args: {
+	lix: Lix;
+	name: string;
+}): Promise<Account> {
+	const executeInTransaction = async (trx: Lix["db"]) => {
+		const account = await trx
+			.insertInto("account")
+			.values({
+				name: args.name,
+			})
+			.returningAll()
+			.executeTakeFirstOrThrow();
+
+		return account;
+	};
+
+	// user provided an open transaction
+	if (args.lix.db.isTransaction) {
+		return executeInTransaction(args.lix.db);
+	} else {
+		return args.lix.db.transaction().execute(executeInTransaction);
+	}
+}

package/src/account/database-schema.test.ts

@@ -0,0 +1,187 @@
+import { Kysely } from "kysely";
+import {
+	contentFromDatabase,
+	createDialect,
+	createInMemoryDatabase,
+	loadDatabaseInMemory,
+} from "sqlite-wasm-kysely";
+import { expect, test } from "vitest";
+import {
+	applyAccountDatabaseSchema,
+	type AccountTable,
+	type ActiveAccountTable,
+} from "./database-schema.js";
+import { openLixInMemory } from "../lix/open-lix-in-memory.js";
+
+type AccountSchema = {
+	account: AccountTable;
+	active_account: ActiveAccountTable;
+};
+
+test("account table should have no entry in the beginning and activte account should be an anonymous account", async () => {
+	const sqlite = await createInMemoryDatabase({
+		readOnly: false,
+	});
+
+	// the database has the propert definition for the uuid_v7 function
+	sqlite.createFunction("uuid_v7", {
+		arity: 0,
+		deterministic: true,
+		xFunc: () => "mock_uuid_v7",
+	});
+
+	applyAccountDatabaseSchema(sqlite);
+
+	const db = new Kysely<AccountSchema>({
+		dialect: createDialect({
+			database: sqlite,
+		}),
+	});
+
+	const account = await db
+		.selectFrom("account")
+		.selectAll()
+		.where("id", "=", "anonymous")
+		.execute();
+	expect(account?.length).toBe(0);
+
+	const active_account = await db
+		.selectFrom("active_account")
+		.selectAll()
+		.executeTakeFirst();
+
+	expect(active_account?.id).toBe("anonymous_mock_uuid_v7");
+});
+
+test("account.id should default to uuid_v7", async () => {
+	const sqlite = await createInMemoryDatabase({
+		readOnly: false,
+	});
+
+	// the database has the propert definition for the uuid_v7 function
+	sqlite.createFunction("uuid_v7", {
+		arity: 0,
+		deterministic: true,
+		xFunc: () => "mock_uuid_v7",
+	});
+
+	applyAccountDatabaseSchema(sqlite);
+
+	const db = new Kysely<AccountSchema>({
+		dialect: createDialect({
+			database: sqlite,
+		}),
+	});
+
+	const result = await db
+		.insertInto("account")
+		.values({
+			name: "test",
+		})
+		.returningAll()
+		.executeTakeFirstOrThrow();
+
+	expect(result.id).toBe("mock_uuid_v7");
+});
+
+test('it should drop the temp "current_account" table on reboot to not persist the current account', async () => {
+	const sqlite = await createInMemoryDatabase({
+		readOnly: false,
+	});
+
+	// the database has the propert definition for the uuid_v7 function
+	sqlite.createFunction("uuid_v7", {
+		arity: 0,
+		deterministic: true,
+		xFunc: () => "mock_uuid_v7",
+	});
+
+	applyAccountDatabaseSchema(sqlite);
+
+	const db = new Kysely<AccountSchema>({
+		dialect: createDialect({
+			database: sqlite,
+		}),
+	});
+
+	await db
+		.insertInto("account")
+		.values({
+			id: "test",
+			name: "test",
+		})
+		.execute();
+
+	await db.deleteFrom("active_account").execute();
+
+	await db
+		.insertInto("active_account")
+		.values({
+			id: "test",
+			name: "test",
+		})
+		.execute();
+
+	const currentAccount = await db
+		.selectFrom("active_account")
+		.selectAll()
+		.executeTakeFirst();
+
+	expect(currentAccount).toMatchObject({
+		id: "test",
+	});
+
+	const blob = contentFromDatabase(sqlite);
+
+	// re-open the database
+
+	const sqlite2 = await loadDatabaseInMemory(blob);
+
+	// the database has the propert definition for the uuid_v7 function
+	sqlite2.createFunction("uuid_v7", {
+		arity: 0,
+		deterministic: true,
+		xFunc: () => "mock_uuid_v7-2",
+	});
+
+	applyAccountDatabaseSchema(sqlite2);
+
+	const db2 = new Kysely<AccountSchema>({
+		dialect: createDialect({
+			database: sqlite2,
+		}),
+	});
+
+	const account2 = await db2
+		.selectFrom("active_account")
+		.selectAll()
+		.executeTakeFirst();
+
+	expect(account2).toMatchObject({
+		id: "anonymous_mock_uuid_v7-2",
+	});
+});
+
+test("should generate different anonymous account names", async () => {
+	const lix0 = await openLixInMemory({});
+	const lix1 = await openLixInMemory({});
+	const lix2 = await openLixInMemory({});
+
+	const account0 = await lix0.db
+		.selectFrom("active_account")
+		.selectAll()
+		.executeTakeFirst();
+
+	const account1 = await lix1.db
+		.selectFrom("active_account")
+		.selectAll()
+		.executeTakeFirst();
+
+	const account2 = await lix2.db
+		.selectFrom("active_account")
+		.selectAll()
+		.executeTakeFirst();
+
+	expect(account0?.name).not.toBe(account1?.name);
+	expect(account1?.name).not.toBe(account2?.name);
+});

package/src/account/database-schema.ts

@@ -0,0 +1,58 @@
+import type { Generated, Insertable, Selectable, Updateable } from "kysely";
+import type { SqliteDatabase } from "sqlite-wasm-kysely";
+import { humanId } from "human-id";
+
+export function applyAccountDatabaseSchema(
+	sqlite: SqliteDatabase
+): SqliteDatabase {
+	const anonymousAccountName = `Anonymous ${humanId({
+		capitalize: true,
+		adjectiveCount: 0,
+		separator: "_",
+	})
+		// Human ID has two words, remove the last one
+		.split("_")[0]!
+		// Human ID uses plural, remove the last character to make it singular
+		.slice(0, -1)}`;
+
+	const sql = `
+  CREATE TABLE IF NOT EXISTS account (
+    id TEXT PRIMARY KEY DEFAULT (uuid_v7()),
+    name TEXT NOT NULL
+  ) STRICT;
+
+  -- default anonymous account
+  -- INSERT OR IGNORE INTO account (id, name) 
+  -- VALUES ('anonymous', 'anonymous');
+
+  -- current account(s)
+  -- temp table because current accounts are session
+  -- specific and should not be persisted
+  CREATE TEMP TABLE IF NOT EXISTS active_account (
+    id TEXT PRIMARY KEY,
+    name TEXT NOT NULL
+    -- can't use foreign keys in temp tables... :(
+  ) STRICT;
+
+  -- default to the anonymous account
+  INSERT INTO active_account (id, name) values ('anonymous_' || uuid_v7(), '${anonymousAccountName}');
+`;
+
+	return sqlite.exec(sql);
+}
+
+export type Account = Selectable<AccountTable>;
+export type NewAccount = Insertable<AccountTable>;
+export type AccountUpdate = Updateable<AccountTable>;
+export type AccountTable = {
+	id: Generated<string>;
+	name: string;
+};
+
+export type ActiveAccount = Selectable<ActiveAccountTable>;
+export type NewActiveAccount = Insertable<ActiveAccountTable>;
+export type ActiveAccountUpdate = Updateable<ActiveAccountTable>;
+export type ActiveAccountTable = {
+	id: string;
+	name: string;
+};

package/src/account/index.ts

@@ -0,0 +1,3 @@
+export * from "./database-schema.js";
+export { createAccount } from "./create-account.js";
+export { switchAccount } from "./switch-account.js";

package/src/account/switch-account.test.ts

@@ -0,0 +1,63 @@
+import { test, expect } from "vitest";
+import { openLixInMemory } from "../lix/open-lix-in-memory.js";
+import { createAccount } from "./create-account.js";
+import { switchAccount } from "./switch-account.js";
+
+test("should switch the current account", async () => {
+	const lix = await openLixInMemory({});
+
+	// Create two accounts
+	const account1 = await createAccount({ lix, name: "account1" });
+	const account2 = await createAccount({ lix, name: "account2" });
+
+	// Switch to account1
+	await switchAccount({ lix, to: [account1] });
+
+	// Verify the current account is account1
+	let activeAccount = await lix.db
+		.selectFrom("active_account")
+		.selectAll()
+		.executeTakeFirstOrThrow();
+
+	expect(activeAccount.id).toBe(account1.id);
+
+	// Switch to account2
+	await switchAccount({ lix, to: [account2] });
+
+	// Verify the current account is account2
+	activeAccount = await lix.db
+		.selectFrom("active_account")
+		.selectAll()
+		.executeTakeFirstOrThrow();
+
+	expect(activeAccount.id).toBe(account2.id);
+});
+
+test("should handle switching to the same account", async () => {
+	const lix = await openLixInMemory({});
+
+	// Create an account
+	const account = await createAccount({ lix, name: "account" });
+
+	// Switch to the account
+	await switchAccount({ lix, to: [account] });
+
+	// Verify the current account is the created account
+	let activeAccount = await lix.db
+		.selectFrom("active_account")
+		.selectAll()
+		.executeTakeFirstOrThrow();
+
+	expect(activeAccount.id).toBe(account.id);
+
+	// Switch to the same account again
+	await switchAccount({ lix, to: [account] });
+
+	// Verify the current account is still the same account
+	activeAccount = await lix.db
+		.selectFrom("active_account")
+		.selectAll()
+		.executeTakeFirstOrThrow();
+
+	expect(activeAccount.id).toBe(account.id);
+});

package/src/account/switch-account.ts

@@ -0,0 +1,39 @@
+import type { Lix } from "../lix/open-lix.js";
+import type { Account } from "./database-schema.js";
+
+/**
+ * Switch the current account to the provided account.
+ *
+ * @example
+ *
+ *   One active account
+ *
+ *   ```ts
+ *   await switchAccount({ lix, to: [otherAccount] });
+ *   ```
+ *
+ * @example
+ *
+ *   Multiple active accounts
+ *
+ *   ```ts
+ *   await switchAccount({ lix, to: [account1, account2] });
+ *   ```
+ */
+export async function switchAccount(args: {
+	lix: Pick<Lix, "db">;
+	to: Account[];
+}): Promise<void> {
+	const executeInTransaction = async (trx: Lix["db"]) => {
+		// delete all rows from the current_account table
+		await trx.deleteFrom("active_account").execute();
+		// insert the new account id into the current_account table
+		await trx.insertInto("active_account").values(args.to).execute();
+	};
+
+	if (args.lix.db.isTransaction) {
+		return executeInTransaction(args.lix.db);
+	} else {
+		return args.lix.db.transaction().execute(executeInTransaction);
+	}
+}