@statewalker/db-sqlite-browser 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mikhail Kotelnikov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,31 @@
+# @statewalker/db-sqlite-browser
+
+libSQL/SQLite WASM driver implementing `@statewalker/db-api` for browser environments,
+backed by `@libsql/libsql-wasm-experimental` (FTS5 + vector search compiled to WebAssembly).
+
+## Installation
+
+```sh
+pnpm add @statewalker/db-sqlite-browser
+```
+
+## Usage
+
+```ts
+import { newBrowserSqliteDb } from "@statewalker/db-sqlite-browser";
+
+// In-memory (omit `path`) or file-backed; `wasmUrl` locates sqlite3.wasm (default "/sqlite3.wasm").
+const db = await newBrowserSqliteDb({ path: "local.db" });
+await db.exec("CREATE TABLE t (x INTEGER)");
+await db.query("SELECT * FROM t");
+```
+
+## API
+
+- `newBrowserSqliteDb(options?)` — initializes the libSQL-WASM engine and returns a `Db`.
+  `options.path` selects file-backed vs in-memory; `options.wasmUrl` locates the `sqlite3.wasm` asset.
+
+## Related
+
+- `@statewalker/db-api` — interface contract.
+- `@statewalker/db-sqlite-node` — Node-side counterpart.

package/dist/index.d.mts

@@ -0,0 +1,19 @@
+import { Db, Db as Db$1, DbEntry, DbOptions, DbOptions as DbOptions$1 } from "@statewalker/db-api";
+//#region src/browser-sqlite-db.d.ts
+type BrowserDbOptions = DbOptions$1 & {
+  /** URL to the sqlite3.wasm file. Defaults to "/sqlite3.wasm". */
+  wasmUrl?: string;
+};
+/**
+ * Create a libSQL WASM-backed {@link Db} in the browser.
+ *
+ * Uses `@libsql/libsql-wasm-experimental` which provides the full libSQL
+ * engine (FTS5, vector search) compiled to WebAssembly.
+ *
+ * @param options.path  File path for persistent storage. Omit for in-memory.
+ * @param options.wasmUrl  URL to the sqlite3.wasm file. Defaults to "/sqlite3.wasm".
+ */
+declare function newBrowserSqliteDb(options?: BrowserDbOptions): Promise<Db$1>;
+//#endregion
+export { type BrowserDbOptions, type Db, type DbEntry, type DbOptions, newBrowserSqliteDb };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/browser-sqlite-db.ts"],"mappings":";;KAIY,mBAAmB;;EAE7B;;;;;;;;;;;iBAuBoB,mBAAmB,UAAU,mBAAmB,QAAQ"}

package/dist/index.mjs

@@ -0,0 +1,40 @@
+import sqlite3InitModule from "@libsql/libsql-wasm-experimental";
+//#region src/browser-sqlite-db.ts
+let sqlite3Promise;
+function getSqlite3(wasmUrl) {
+	if (!sqlite3Promise) sqlite3Promise = sqlite3InitModule({ locateFile: (file) => file.endsWith(".wasm") ? wasmUrl : file });
+	return sqlite3Promise;
+}
+/**
+* Create a libSQL WASM-backed {@link Db} in the browser.
+*
+* Uses `@libsql/libsql-wasm-experimental` which provides the full libSQL
+* engine (FTS5, vector search) compiled to WebAssembly.
+*
+* @param options.path  File path for persistent storage. Omit for in-memory.
+* @param options.wasmUrl  URL to the sqlite3.wasm file. Defaults to "/sqlite3.wasm".
+*/
+async function newBrowserSqliteDb(options) {
+	const sqlite3 = await getSqlite3(options?.wasmUrl ?? "/sqlite3.wasm");
+	const dbPath = options?.path ?? ":memory:";
+	const db = new sqlite3.oo1.DB(dbPath, "c");
+	return {
+		async query(sql, params) {
+			return db.exec(sql, {
+				returnValue: "resultRows",
+				rowMode: "object",
+				bind: params
+			});
+		},
+		async exec(sql) {
+			db.exec(sql);
+		},
+		async close() {
+			db.close();
+		}
+	};
+}
+//#endregion
+export { newBrowserSqliteDb };
+
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/browser-sqlite-db.ts"],"sourcesContent":["import type { Database, Sqlite3Static } from \"@libsql/libsql-wasm-experimental\";\nimport sqlite3InitModule from \"@libsql/libsql-wasm-experimental\";\nimport type { Db, DbEntry, DbOptions } from \"@statewalker/db-api\";\n\nexport type BrowserDbOptions = DbOptions & {\n  /** URL to the sqlite3.wasm file. Defaults to \"/sqlite3.wasm\". */\n  wasmUrl?: string;\n};\n\nlet sqlite3Promise: Promise<Sqlite3Static> | undefined;\n\nfunction getSqlite3(wasmUrl: string): Promise<Sqlite3Static> {\n  if (!sqlite3Promise) {\n    sqlite3Promise = sqlite3InitModule({\n      locateFile: (file: string) => (file.endsWith(\".wasm\") ? wasmUrl : file),\n    });\n  }\n  return sqlite3Promise;\n}\n\n/**\n * Create a libSQL WASM-backed {@link Db} in the browser.\n *\n * Uses `@libsql/libsql-wasm-experimental` which provides the full libSQL\n * engine (FTS5, vector search) compiled to WebAssembly.\n *\n * @param options.path  File path for persistent storage. Omit for in-memory.\n * @param options.wasmUrl  URL to the sqlite3.wasm file. Defaults to \"/sqlite3.wasm\".\n */\nexport async function newBrowserSqliteDb(options?: BrowserDbOptions): Promise<Db> {\n  const wasmUrl = options?.wasmUrl ?? \"/sqlite3.wasm\";\n  const sqlite3 = await getSqlite3(wasmUrl);\n  const dbPath = options?.path ?? \":memory:\";\n  const db: Database = new sqlite3.oo1.DB(dbPath, \"c\");\n\n  return {\n    async query<T = DbEntry>(sql: string, params?: unknown[]): Promise<T[]> {\n      const rows = db.exec(sql, {\n        returnValue: \"resultRows\",\n        rowMode: \"object\",\n        bind: params as never[],\n      });\n      return rows as unknown as T[];\n    },\n\n    async exec(sql: string): Promise<void> {\n      db.exec(sql);\n    },\n\n    async close(): Promise<void> {\n      db.close();\n    },\n  };\n}\n"],"mappings":";;AASA,IAAI;AAEJ,SAAS,WAAW,SAAyC;CAC3D,IAAI,CAAC,gBACH,iBAAiB,kBAAkB,EACjC,aAAa,SAAkB,KAAK,SAAS,OAAO,IAAI,UAAU,KACpE,CAAC;CAEH,OAAO;AACT;;;;;;;;;;AAWA,eAAsB,mBAAmB,SAAyC;CAEhF,MAAM,UAAU,MAAM,WADN,SAAS,WAAW,eACI;CACxC,MAAM,SAAS,SAAS,QAAQ;CAChC,MAAM,KAAe,IAAI,QAAQ,IAAI,GAAG,QAAQ,GAAG;CAEnD,OAAO;EACL,MAAM,MAAmB,KAAa,QAAkC;GAMtE,OALa,GAAG,KAAK,KAAK;IACxB,aAAa;IACb,SAAS;IACT,MAAM;GACR,CACU;EACZ;EAEA,MAAM,KAAK,KAA4B;GACrC,GAAG,KAAK,GAAG;EACb;EAEA,MAAM,QAAuB;GAC3B,GAAG,MAAM;EACX;CACF;AACF"}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@statewalker/db-sqlite-browser",
+  "version": "0.1.1",
+  "private": false,
+  "type": "module",
+  "description": "libSQL/SQLite WASM driver for @statewalker/db-api, targeting browser environments.",
+  "homepage": "https://github.com/statewalker/statewalker-db",
+  "author": {
+    "name": "Mikhail Kotelnikov",
+    "email": "mikhail.kotelnikov@gmail.com"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/statewalker/statewalker-db.git"
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "@libsql/libsql-wasm-experimental": "^0.0.3",
+    "@statewalker/db-api": "0.1.1"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.62.1",
+    "@vitest/browser": "^4.1.10",
+    "@vitest/browser-playwright": "^4.1.10",
+    "playwright": "^1.62.1",
+    "rimraf": "^6.1.3",
+    "tsdown": "^0.22.14",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10",
+    "@statewalker/db-tests": "0.1.1"
+  },
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:browser": "vitest run --config vitest.browser.config.ts",
+    "typecheck": "tsc --noEmit",
+    "clean": "rimraf dist",
+    "lint": "biome check --write .",
+    "format": "biome format --write ."
+  }
+}

package/src/browser-sqlite-db.browser.test.ts

@@ -0,0 +1,159 @@
+import type { Db } from "@statewalker/db-api";
+import { runDbConformance } from "@statewalker/db-tests";
+import { afterEach, describe, expect, it } from "vitest";
+import { newBrowserSqliteDb } from "./browser-sqlite-db.js";
+
+/**
+ * The libSQL-WASM browser adapter, exercised in a REAL browser (Vitest browser
+ * mode + Playwright/Chromium). Launched only by `vitest.browser.config.ts` (the
+ * `test:browser` script) — the Node config excludes `*.browser.test.ts`.
+ *
+ * The engine is served from `/sqlite3.wasm` by the config's `publicDir`, so the
+ * adapter's default `wasmUrl` resolves. Everything runs in-memory; the node-only
+ * file-persistence scenario is skipped via `skipFilePersistence`.
+ */
+
+// Shared contract: CRUD, parameter binding, injection safety, cardinality,
+// close, error paths. File persistence is node-only, hence skipped here.
+runDbConformance(() => newBrowserSqliteDb(), {
+  // libsql dialect: `?` placeholder; the spread normalizer drops libsql Row's
+  // non-enumerable positional keys so a plain `toEqual` matches.
+  placeholder: "?",
+  normalizeRow: (row) => ({ ...row }),
+  skipFilePersistence: true,
+});
+
+// Dialect-specific browser behavior the shared suite does not cover: libSQL's
+// FTS5 full-text search and native vector index.
+describe("newBrowserSqliteDb", () => {
+  let db: Db;
+
+  afterEach(async () => {
+    if (db) {
+      await db.close();
+    }
+  });
+
+  describe("FTS5", () => {
+    it("returns empty results for unmatched search terms", async () => {
+      db = await newBrowserSqliteDb();
+      await db.exec("CREATE VIRTUAL TABLE docs2_fts USING fts5(content)");
+      await db.exec(
+        "INSERT INTO docs2_fts (rowid, content) VALUES (1, 'hello world'), (2, 'goodbye world')",
+      );
+
+      const rows = await db.query<{ content: string }>(
+        "SELECT content FROM docs2_fts WHERE docs2_fts MATCH 'nonexistent'",
+      );
+      expect(rows).toHaveLength(0);
+    });
+
+    it("searches across multiple text columns", async () => {
+      db = await newBrowserSqliteDb();
+      await db.exec("CREATE VIRTUAL TABLE articles_fts USING fts5(title, body, tokenize='porter')");
+      await db.exec(`
+        INSERT INTO articles_fts (rowid, title, body) VALUES
+          (1, 'Travel Guide', 'Visit the beautiful lakes of Switzerland'),
+          (2, 'Cooking Tips', 'How to make a perfect lake trout'),
+          (3, 'Programming', 'Learn about SQL databases')
+      `);
+
+      const rows = await db.query<{ rowid: number; title: string; score: number }>(`
+        SELECT rowid, title, bm25(articles_fts) AS score
+        FROM articles_fts
+        WHERE articles_fts MATCH 'lake'
+        ORDER BY score
+      `);
+      expect(rows).toHaveLength(2);
+      const titles = rows.map((r) => r.title);
+      expect(titles).toContain("Travel Guide");
+      expect(titles).toContain("Cooking Tips");
+    });
+
+    it("creates an FTS5 index and performs full-text search", async () => {
+      db = await newBrowserSqliteDb();
+      await db.exec("CREATE VIRTUAL TABLE docs_fts USING fts5(content)");
+      await db.exec(`
+        INSERT INTO docs_fts (rowid, content) VALUES
+          (1, 'the quick brown fox jumps over the lazy dog'),
+          (2, 'a lazy cat sleeps on the mat'),
+          (3, 'the fox and the hound are friends')
+      `);
+
+      const rows = await db.query<{ rowid: number; content: string; score: number }>(`
+        SELECT rowid, content, bm25(docs_fts) AS score
+        FROM docs_fts
+        WHERE docs_fts MATCH 'fox'
+        ORDER BY score
+      `);
+
+      expect(rows.length).toBeGreaterThanOrEqual(1);
+      const rowids = rows.map((r) => r.rowid);
+      expect(rowids).toContain(1);
+      expect(rowids).toContain(3);
+    });
+  });
+
+  describe("vector search", () => {
+    it("creates index and performs vector similarity search", async () => {
+      db = await newBrowserSqliteDb();
+
+      await db.exec("CREATE TABLE embeddings (id INTEGER PRIMARY KEY, vec F32_BLOB(3))");
+      await db.exec("CREATE INDEX vec_idx ON embeddings (libsql_vector_idx(vec))");
+      await db.exec(`
+        INSERT INTO embeddings VALUES
+          (1, vector32('[1.0, 0.0, 0.0]')),
+          (2, vector32('[0.0, 1.0, 0.0]')),
+          (3, vector32('[0.0, 0.0, 1.0]'))
+      `);
+
+      const rows = await db.query<{ id: number }>(
+        "SELECT e.id FROM vector_top_k('vec_idx', '[1.0, 0.1, 0.0]', 1) AS v JOIN embeddings e ON e.rowid = v.id",
+      );
+
+      expect(rows).toHaveLength(1);
+      expect(rows[0]?.id).toBe(1);
+    });
+
+    it("returns k nearest neighbors ordered by distance", async () => {
+      db = await newBrowserSqliteDb();
+
+      await db.exec("CREATE TABLE vectors (id INTEGER PRIMARY KEY, vec F32_BLOB(3))");
+      await db.exec("CREATE INDEX vec_idx2 ON vectors (libsql_vector_idx(vec))");
+      await db.exec(`
+        INSERT INTO vectors VALUES
+          (1, vector32('[1.0, 0.0, 0.0]')),
+          (2, vector32('[0.9, 0.1, 0.0]')),
+          (3, vector32('[0.0, 1.0, 0.0]')),
+          (4, vector32('[0.0, 0.0, 1.0]'))
+      `);
+
+      const rows = await db.query<{ id: number }>(
+        "SELECT e.id FROM vector_top_k('vec_idx2', '[1.0, 0.0, 0.0]', 2) AS v JOIN vectors e ON e.rowid = v.id",
+      );
+
+      expect(rows).toHaveLength(2);
+      const ids = rows.map((r) => r.id);
+      expect(ids).toContain(1);
+      expect(ids).toContain(2);
+    });
+
+    it("works without index (brute-force scan)", async () => {
+      db = await newBrowserSqliteDb();
+
+      await db.exec("CREATE TABLE vecs_no_idx (id INTEGER PRIMARY KEY, vec F32_BLOB(3))");
+      await db.exec(`
+        INSERT INTO vecs_no_idx VALUES
+          (1, vector32('[1.0, 0.0, 0.0]')),
+          (2, vector32('[0.0, 1.0, 0.0]'))
+      `);
+
+      const rows = await db.query<{ id: number }>(
+        "SELECT id FROM vecs_no_idx ORDER BY vector_distance_cos(vec, vector32('[0.0, 0.9, 0.1]')) LIMIT 1",
+      );
+
+      expect(rows).toHaveLength(1);
+      expect(rows[0]?.id).toBe(2);
+    });
+  });
+});

package/src/browser-sqlite-db.test.ts

@@ -0,0 +1,14 @@
+import { describe, expect, it } from "vitest";
+
+/**
+ * Node-safe smoke test. The real browser coverage (shared conformance suite +
+ * FTS5/vector) lives in `browser-sqlite-db.browser.test.ts`, run via Vitest
+ * browser mode (`pnpm test:browser`); this file only checks the module loads
+ * and exports its factory, since libSQL-WASM cannot instantiate under Node.
+ */
+describe("browser-sqlite-db module", () => {
+  it("exports newBrowserSqliteDb function", async () => {
+    const mod = await import("./browser-sqlite-db.js");
+    expect(typeof mod.newBrowserSqliteDb).toBe("function");
+  });
+});

package/src/browser-sqlite-db.ts

@@ -0,0 +1,54 @@
+import type { Database, Sqlite3Static } from "@libsql/libsql-wasm-experimental";
+import sqlite3InitModule from "@libsql/libsql-wasm-experimental";
+import type { Db, DbEntry, DbOptions } from "@statewalker/db-api";
+
+export type BrowserDbOptions = DbOptions & {
+  /** URL to the sqlite3.wasm file. Defaults to "/sqlite3.wasm". */
+  wasmUrl?: string;
+};
+
+let sqlite3Promise: Promise<Sqlite3Static> | undefined;
+
+function getSqlite3(wasmUrl: string): Promise<Sqlite3Static> {
+  if (!sqlite3Promise) {
+    sqlite3Promise = sqlite3InitModule({
+      locateFile: (file: string) => (file.endsWith(".wasm") ? wasmUrl : file),
+    });
+  }
+  return sqlite3Promise;
+}
+
+/**
+ * Create a libSQL WASM-backed {@link Db} in the browser.
+ *
+ * Uses `@libsql/libsql-wasm-experimental` which provides the full libSQL
+ * engine (FTS5, vector search) compiled to WebAssembly.
+ *
+ * @param options.path  File path for persistent storage. Omit for in-memory.
+ * @param options.wasmUrl  URL to the sqlite3.wasm file. Defaults to "/sqlite3.wasm".
+ */
+export async function newBrowserSqliteDb(options?: BrowserDbOptions): Promise<Db> {
+  const wasmUrl = options?.wasmUrl ?? "/sqlite3.wasm";
+  const sqlite3 = await getSqlite3(wasmUrl);
+  const dbPath = options?.path ?? ":memory:";
+  const db: Database = new sqlite3.oo1.DB(dbPath, "c");
+
+  return {
+    async query<T = DbEntry>(sql: string, params?: unknown[]): Promise<T[]> {
+      const rows = db.exec(sql, {
+        returnValue: "resultRows",
+        rowMode: "object",
+        bind: params as never[],
+      });
+      return rows as unknown as T[];
+    },
+
+    async exec(sql: string): Promise<void> {
+      db.exec(sql);
+    },
+
+    async close(): Promise<void> {
+      db.close();
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export type { Db, DbEntry, DbOptions } from "@statewalker/db-api";
+export type { BrowserDbOptions } from "./browser-sqlite-db.js";
+export { newBrowserSqliteDb } from "./browser-sqlite-db.js";