@statewalker/db-duckdb-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,27 @@
+# @statewalker/db-duckdb-browser
+
+DuckDB WASM driver implementing `@statewalker/db-api` for browser environments.
+
+## Installation
+
+```sh
+pnpm add @statewalker/db-duckdb-browser
+```
+
+## Usage
+
+```ts
+import { createDuckDbBrowserClient } from "@statewalker/db-duckdb-browser";
+
+const db = await createDuckDbBrowserClient();
+await db.execute("CREATE TABLE t (x INTEGER)");
+```
+
+## API
+
+- `createDuckDbBrowserClient(options?)` — spins up an in-browser DuckDB WASM instance and returns a `DbClient`.
+
+## Related
+
+- `@statewalker/db-api` — interface contract.
+- `@statewalker/db-duckdb-node` — Node-side counterpart.

package/dist/index.d.mts

@@ -0,0 +1,28 @@
+import * as duckdb from "@duckdb/duckdb-wasm";
+import { Db, Db as Db$1, DbEntry, DbOptions, DbOptions as DbOptions$1 } from "@statewalker/db-api";
+//#region src/browser-duckdb.d.ts
+/** Browser-specific options for {@link newBrowserDuckDb}. */
+interface BrowserDuckDbOptions extends DbOptions$1 {
+  /**
+   * Self-hosted DuckDB bundle URLs (served same-origin, e.g. via a bundler's
+   * `?url` import). Passing these makes the factory spawn a **same-origin**
+   * worker, which OPFS database persistence requires — a cross-origin worker
+   * (the jsDelivr fallback, loaded via a Blob `importScripts` shim) crashes on
+   * OPFS file I/O. Omit to load from jsDelivr (in-memory use only).
+   */
+  bundles?: duckdb.DuckDBBundles;
+}
+/**
+ * Create a DuckDB-backed {@link Db} using WebAssembly in the browser.
+ *
+ * With `options.path` set to an `opfs://` URL **and** self-hosted
+ * `options.bundles`, the database persists across reloads on OPFS. Otherwise it
+ * runs in-memory.
+ *
+ * @param options.path     `opfs://` path for persistent storage. Omit for in-memory.
+ * @param options.bundles  Same-origin bundle URLs (required for OPFS).
+ */
+declare function newBrowserDuckDb(options?: BrowserDuckDbOptions): Promise<Db$1>;
+//#endregion
+export { type BrowserDuckDbOptions, type Db, type DbEntry, type DbOptions, newBrowserDuckDb };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/browser-duckdb.ts"],"mappings":";;;;UAoBiB,6BAA6B;;;;;;;;EAQ5C,UAAU,OAAO;;;;;;;;;;;;iBAaG,iBAAiB,UAAU,uBAAuB,QAAQ"}

package/dist/index.mjs

@@ -0,0 +1,67 @@
+import * as duckdb from "@duckdb/duckdb-wasm";
+//#region src/browser-duckdb.ts
+/**
+* Convert an Arrow Table (returned by duckdb-wasm queries) to plain JS objects.
+*/
+function arrowToObjects(table) {
+	const fields = table.schema.fields.map((f) => f.name);
+	return table.toArray().map((row) => {
+		const obj = {};
+		for (const field of fields) obj[field] = row[field];
+		return obj;
+	});
+}
+/**
+* Create a DuckDB-backed {@link Db} using WebAssembly in the browser.
+*
+* With `options.path` set to an `opfs://` URL **and** self-hosted
+* `options.bundles`, the database persists across reloads on OPFS. Otherwise it
+* runs in-memory.
+*
+* @param options.path     `opfs://` path for persistent storage. Omit for in-memory.
+* @param options.bundles  Same-origin bundle URLs (required for OPFS).
+*/
+async function newBrowserDuckDb(options) {
+	const selfHosted = options?.bundles;
+	const bundle = await duckdb.selectBundle(selfHosted ?? duckdb.getJsDelivrBundles());
+	let worker;
+	let blobUrl;
+	if (selfHosted) worker = new Worker(bundle.mainWorker);
+	else {
+		blobUrl = URL.createObjectURL(new Blob([`importScripts("${bundle.mainWorker ?? ""}");`], { type: "text/javascript" }));
+		worker = new Worker(blobUrl);
+	}
+	const logger = new duckdb.ConsoleLogger();
+	const db = new duckdb.AsyncDuckDB(logger, worker);
+	await db.instantiate(bundle.mainModule, bundle.pthreadWorker);
+	if (blobUrl) URL.revokeObjectURL(blobUrl);
+	const persistent = Boolean(options?.path) && typeof navigator !== "undefined" && Boolean(navigator.storage);
+	if (options?.path && persistent) try {
+		await db.open({
+			path: options.path,
+			accessMode: duckdb.DuckDBAccessMode.READ_WRITE
+		});
+	} catch {}
+	const conn = await db.connect();
+	return {
+		async query(sql, params) {
+			if (params && params.length > 0) return arrowToObjects(await (await conn.prepare(sql)).query(...params));
+			return arrowToObjects(await conn.query(sql));
+		},
+		async exec(sql) {
+			await conn.query(sql);
+		},
+		async flush() {
+			if (persistent) await conn.query("CHECKPOINT");
+		},
+		async close() {
+			await conn.close();
+			await db.terminate();
+			worker.terminate();
+		}
+	};
+}
+//#endregion
+export { newBrowserDuckDb };
+
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/browser-duckdb.ts"],"sourcesContent":["import * as duckdb from \"@duckdb/duckdb-wasm\";\nimport type { Db, DbEntry, DbOptions } from \"@statewalker/db-api\";\n\ntype Table = Awaited<ReturnType<duckdb.AsyncPreparedStatement[\"query\"]>>;\n\n/**\n * Convert an Arrow Table (returned by duckdb-wasm queries) to plain JS objects.\n */\nfunction arrowToObjects<T>(table: Table): T[] {\n  const fields = table.schema.fields.map((f: { name: string }) => f.name);\n  return table.toArray().map((row: Record<string, unknown>) => {\n    const obj: Record<string, unknown> = {};\n    for (const field of fields) {\n      obj[field] = row[field];\n    }\n    return obj as T;\n  });\n}\n\n/** Browser-specific options for {@link newBrowserDuckDb}. */\nexport interface BrowserDuckDbOptions extends DbOptions {\n  /**\n   * Self-hosted DuckDB bundle URLs (served same-origin, e.g. via a bundler's\n   * `?url` import). Passing these makes the factory spawn a **same-origin**\n   * worker, which OPFS database persistence requires — a cross-origin worker\n   * (the jsDelivr fallback, loaded via a Blob `importScripts` shim) crashes on\n   * OPFS file I/O. Omit to load from jsDelivr (in-memory use only).\n   */\n  bundles?: duckdb.DuckDBBundles;\n}\n\n/**\n * Create a DuckDB-backed {@link Db} using WebAssembly in the browser.\n *\n * With `options.path` set to an `opfs://` URL **and** self-hosted\n * `options.bundles`, the database persists across reloads on OPFS. Otherwise it\n * runs in-memory.\n *\n * @param options.path     `opfs://` path for persistent storage. Omit for in-memory.\n * @param options.bundles  Same-origin bundle URLs (required for OPFS).\n */\nexport async function newBrowserDuckDb(options?: BrowserDuckDbOptions): Promise<Db> {\n  const selfHosted = options?.bundles;\n  const bundle = await duckdb.selectBundle(selfHosted ?? duckdb.getJsDelivrBundles());\n\n  // OPFS file I/O needs a same-origin worker. Self-hosted bundles give a\n  // same-origin URL we load directly; the jsDelivr fallback is cross-origin and\n  // must be wrapped in a Blob that `importScripts` it.\n  let worker: Worker;\n  let blobUrl: string | undefined;\n  if (selfHosted) {\n    worker = new Worker(bundle.mainWorker as string);\n  } else {\n    blobUrl = URL.createObjectURL(\n      new Blob([`importScripts(\"${bundle.mainWorker ?? \"\"}\");`], {\n        type: \"text/javascript\",\n      }),\n    );\n    worker = new Worker(blobUrl);\n  }\n\n  const logger = new duckdb.ConsoleLogger();\n  const db = new duckdb.AsyncDuckDB(logger, worker);\n  await db.instantiate(bundle.mainModule, bundle.pthreadWorker);\n  if (blobUrl) URL.revokeObjectURL(blobUrl);\n\n  // Enable OPFS persistence when a path is provided and the API is available.\n  const persistent =\n    Boolean(options?.path) && typeof navigator !== \"undefined\" && Boolean(navigator.storage);\n  if (options?.path && persistent) {\n    try {\n      await db.open({\n        path: options.path,\n        accessMode: duckdb.DuckDBAccessMode.READ_WRITE,\n      });\n    } catch {\n      // Fall back to in-memory if OPFS is unavailable\n    }\n  }\n\n  const conn = await db.connect();\n\n  return {\n    async query<T = DbEntry>(sql: string, params?: unknown[]): Promise<T[]> {\n      if (params && params.length > 0) {\n        const stmt = await conn.prepare(sql);\n        const result = await stmt.query(...params);\n        return arrowToObjects<T>(result);\n      }\n      const result = await conn.query(sql);\n      return arrowToObjects<T>(result);\n    },\n\n    async exec(sql: string): Promise<void> {\n      await conn.query(sql);\n    },\n\n    async flush(): Promise<void> {\n      // CHECKPOINT writes the WAL into the OPFS database file so committed\n      // changes survive a reload. Crucial for OPFS persistence.\n      if (persistent) await conn.query(\"CHECKPOINT\");\n    },\n\n    async close(): Promise<void> {\n      await conn.close();\n      await db.terminate();\n      worker.terminate();\n    },\n  };\n}\n"],"mappings":";;;;;AAQA,SAAS,eAAkB,OAAmB;CAC5C,MAAM,SAAS,MAAM,OAAO,OAAO,KAAK,MAAwB,EAAE,IAAI;CACtE,OAAO,MAAM,QAAQ,CAAC,CAAC,KAAK,QAAiC;EAC3D,MAAM,MAA+B,CAAC;EACtC,KAAK,MAAM,SAAS,QAClB,IAAI,SAAS,IAAI;EAEnB,OAAO;CACT,CAAC;AACH;;;;;;;;;;;AAwBA,eAAsB,iBAAiB,SAA6C;CAClF,MAAM,aAAa,SAAS;CAC5B,MAAM,SAAS,MAAM,OAAO,aAAa,cAAc,OAAO,mBAAmB,CAAC;CAKlF,IAAI;CACJ,IAAI;CACJ,IAAI,YACF,SAAS,IAAI,OAAO,OAAO,UAAoB;MAC1C;EACL,UAAU,IAAI,gBACZ,IAAI,KAAK,CAAC,kBAAkB,OAAO,cAAc,GAAG,IAAI,GAAG,EACzD,MAAM,kBACR,CAAC,CACH;EACA,SAAS,IAAI,OAAO,OAAO;CAC7B;CAEA,MAAM,SAAS,IAAI,OAAO,cAAc;CACxC,MAAM,KAAK,IAAI,OAAO,YAAY,QAAQ,MAAM;CAChD,MAAM,GAAG,YAAY,OAAO,YAAY,OAAO,aAAa;CAC5D,IAAI,SAAS,IAAI,gBAAgB,OAAO;CAGxC,MAAM,aACJ,QAAQ,SAAS,IAAI,KAAK,OAAO,cAAc,eAAe,QAAQ,UAAU,OAAO;CACzF,IAAI,SAAS,QAAQ,YACnB,IAAI;EACF,MAAM,GAAG,KAAK;GACZ,MAAM,QAAQ;GACd,YAAY,OAAO,iBAAiB;EACtC,CAAC;CACH,QAAQ,CAER;CAGF,MAAM,OAAO,MAAM,GAAG,QAAQ;CAE9B,OAAO;EACL,MAAM,MAAmB,KAAa,QAAkC;GACtE,IAAI,UAAU,OAAO,SAAS,GAG5B,OAAO,eAAkB,OADJ,MADF,KAAK,QAAQ,GAAG,EAAA,CACT,MAAM,GAAG,MAAM,CACV;GAGjC,OAAO,eAAkB,MADJ,KAAK,MAAM,GAAG,CACJ;EACjC;EAEA,MAAM,KAAK,KAA4B;GACrC,MAAM,KAAK,MAAM,GAAG;EACtB;EAEA,MAAM,QAAuB;GAG3B,IAAI,YAAY,MAAM,KAAK,MAAM,YAAY;EAC/C;EAEA,MAAM,QAAuB;GAC3B,MAAM,KAAK,MAAM;GACjB,MAAM,GAAG,UAAU;GACnB,OAAO,UAAU;EACnB;CACF;AACF"}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@statewalker/db-duckdb-browser",
+  "version": "0.1.1",
+  "private": false,
+  "type": "module",
+  "description": "DuckDB 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": {
+    "@duckdb/duckdb-wasm": "^1.33.1-dev57.0",
+    "@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-duckdb.browser.test.ts

@@ -0,0 +1,171 @@
+import type { Db } from "@statewalker/db-api";
+import { runDbConformance } from "@statewalker/db-tests";
+import { afterEach, describe, expect, it } from "vitest";
+import { newBrowserDuckDb } from "./browser-duckdb.js";
+
+/**
+ * The DuckDB-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`.
+ *
+ * With no `bundles`/`path`, the adapter loads the default DuckDB bundle from
+ * jsDelivr and runs in-memory (a Worker inside the browser page), so the run
+ * needs outbound network access from Chromium. The node-only file-persistence
+ * scenario is skipped via `skipFilePersistence`.
+ */
+
+// Shared contract: CRUD, parameter binding, injection safety, cardinality,
+// close, flush, error paths. File persistence is node-only, hence skipped here.
+runDbConformance(() => newBrowserDuckDb(), {
+  // duckdb dialect: `$1` placeholder; rows are already plain objects, so the
+  // spread normalizer is an identity-style copy.
+  placeholder: "$1",
+  normalizeRow: (row) => ({ ...row }),
+  skipFilePersistence: true,
+});
+
+// Dialect-specific browser behavior the shared suite does not cover: DuckDB's
+// FTS extension and VSS/HNSW vector index.
+describe("newBrowserDuckDb", () => {
+  let db: Db;
+
+  afterEach(async () => {
+    if (db) {
+      await db.close();
+    }
+  });
+
+  describe("FTS extension", () => {
+    it("returns empty results for unmatched search terms", async () => {
+      db = await newBrowserDuckDb();
+      await db.exec("INSTALL fts; LOAD fts;");
+      await db.exec("CREATE TABLE docs2 (id INTEGER, content VARCHAR)");
+      await db.exec("INSERT INTO docs2 VALUES (1, 'hello world'), (2, 'goodbye world')");
+      await db.exec("PRAGMA create_fts_index('docs2', 'id', 'content')");
+
+      const rows = await db.query<{ id: number; score: number | null }>(`
+        SELECT id, score FROM (
+          SELECT *, fts_main_docs2.match_bm25(id, 'nonexistent') AS score FROM docs2
+        ) sq WHERE score IS NOT NULL
+      `);
+      expect(rows).toHaveLength(0);
+    });
+
+    it("searches across multiple text columns", async () => {
+      db = await newBrowserDuckDb();
+      await db.exec("INSTALL fts; LOAD fts;");
+      await db.exec("CREATE TABLE articles (id INTEGER, title VARCHAR, body VARCHAR)");
+      await db.exec(`
+        INSERT INTO articles 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')
+      `);
+      await db.exec("PRAGMA create_fts_index('articles', 'id', 'title', 'body')");
+
+      const rows = await db.query<{ id: number; score: number | null }>(`
+        SELECT id, score FROM (
+          SELECT *, fts_main_articles.match_bm25(id, 'lake') AS score FROM articles
+        ) sq WHERE score IS NOT NULL
+      `);
+      expect(rows.length).toBe(2);
+      const ids = rows.map((r) => r.id);
+      expect(ids).toContain(1);
+      expect(ids).toContain(2);
+    });
+
+    it("creates an FTS index and performs full-text search", async () => {
+      db = await newBrowserDuckDb();
+      await db.exec("INSTALL fts; LOAD fts;");
+      await db.exec("CREATE TABLE docs (id INTEGER, content VARCHAR)");
+      await db.exec(`
+        INSERT INTO docs 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')
+      `);
+      await db.exec("PRAGMA create_fts_index('docs', 'id', 'content')");
+
+      const rows = await db.query<{
+        id: number;
+        content: string;
+        score: number | null;
+      }>(`
+        SELECT id, content, score
+        FROM (
+          SELECT *, fts_main_docs.match_bm25(id, 'fox') AS score
+          FROM docs
+        ) sq
+        WHERE score IS NOT NULL
+        ORDER BY score
+      `);
+
+      expect(rows.length).toBeGreaterThanOrEqual(1);
+      const ids = rows.map((r) => r.id);
+      expect(ids).toContain(1);
+      expect(ids).toContain(3);
+    });
+  });
+
+  describe("VSS extension", () => {
+    it("creates HNSW index and performs vector similarity search", async () => {
+      db = await newBrowserDuckDb();
+      await db.exec("INSTALL vss; LOAD vss;");
+      await db.exec("CREATE TABLE embeddings (id INTEGER, vec FLOAT[3])");
+      await db.exec(`
+        INSERT INTO embeddings VALUES
+          (1, [1.0, 0.0, 0.0]),
+          (2, [0.0, 1.0, 0.0]),
+          (3, [0.0, 0.0, 1.0])
+      `);
+      await db.exec("CREATE INDEX vec_idx ON embeddings USING HNSW (vec)");
+
+      const rows = await db.query<{ id: number }>(
+        "SELECT id FROM embeddings ORDER BY array_distance(vec, [1.0, 0.1, 0.0]::FLOAT[3]) LIMIT 1",
+      );
+
+      expect(rows).toHaveLength(1);
+      expect(rows[0]?.id).toBe(1);
+    });
+
+    it("returns k nearest neighbors ordered by distance", async () => {
+      db = await newBrowserDuckDb();
+      await db.exec("INSTALL vss; LOAD vss;");
+      await db.exec("CREATE TABLE vectors (id INTEGER, vec FLOAT[3])");
+      await db.exec(`
+        INSERT INTO vectors VALUES
+          (1, [1.0, 0.0, 0.0]),
+          (2, [0.9, 0.1, 0.0]),
+          (3, [0.0, 1.0, 0.0]),
+          (4, [0.0, 0.0, 1.0])
+      `);
+      await db.exec("CREATE INDEX vec_idx2 ON vectors USING HNSW (vec)");
+
+      const rows = await db.query<{ id: number }>(
+        "SELECT id FROM vectors ORDER BY array_distance(vec, [1.0, 0.0, 0.0]::FLOAT[3]) LIMIT 2",
+      );
+
+      expect(rows).toHaveLength(2);
+      expect(rows[0]?.id).toBe(1);
+      expect(rows[1]?.id).toBe(2);
+    });
+
+    it("works without HNSW index (brute-force scan)", async () => {
+      db = await newBrowserDuckDb();
+      await db.exec("INSTALL vss; LOAD vss;");
+      await db.exec("CREATE TABLE vecs_no_idx (id INTEGER, vec FLOAT[3])");
+      await db.exec(`
+        INSERT INTO vecs_no_idx VALUES
+          (1, [1.0, 0.0, 0.0]),
+          (2, [0.0, 1.0, 0.0])
+      `);
+
+      const rows = await db.query<{ id: number }>(
+        "SELECT id FROM vecs_no_idx ORDER BY array_distance(vec, [0.0, 0.9, 0.1]::FLOAT[3]) LIMIT 1",
+      );
+
+      expect(rows).toHaveLength(1);
+      expect(rows[0]?.id).toBe(2);
+    });
+  });
+});

package/src/browser-duckdb.test.ts

@@ -0,0 +1,14 @@
+import { describe, expect, it } from "vitest";
+
+/**
+ * Node-safe smoke test. The real browser coverage (shared conformance suite +
+ * FTS/VSS) lives in `browser-duckdb.browser.test.ts`, run via Vitest browser
+ * mode (`pnpm test:browser`); this file only checks the module loads and
+ * exports its factory, since duckdb-wasm needs a browser Worker to run.
+ */
+describe("browser-duckdb module", () => {
+  it("exports newBrowserDuckDb function", async () => {
+    const mod = await import("./browser-duckdb.js");
+    expect(typeof mod.newBrowserDuckDb).toBe("function");
+  });
+});

package/src/browser-duckdb.ts

@@ -0,0 +1,110 @@
+import * as duckdb from "@duckdb/duckdb-wasm";
+import type { Db, DbEntry, DbOptions } from "@statewalker/db-api";
+
+type Table = Awaited<ReturnType<duckdb.AsyncPreparedStatement["query"]>>;
+
+/**
+ * Convert an Arrow Table (returned by duckdb-wasm queries) to plain JS objects.
+ */
+function arrowToObjects<T>(table: Table): T[] {
+  const fields = table.schema.fields.map((f: { name: string }) => f.name);
+  return table.toArray().map((row: Record<string, unknown>) => {
+    const obj: Record<string, unknown> = {};
+    for (const field of fields) {
+      obj[field] = row[field];
+    }
+    return obj as T;
+  });
+}
+
+/** Browser-specific options for {@link newBrowserDuckDb}. */
+export interface BrowserDuckDbOptions extends DbOptions {
+  /**
+   * Self-hosted DuckDB bundle URLs (served same-origin, e.g. via a bundler's
+   * `?url` import). Passing these makes the factory spawn a **same-origin**
+   * worker, which OPFS database persistence requires — a cross-origin worker
+   * (the jsDelivr fallback, loaded via a Blob `importScripts` shim) crashes on
+   * OPFS file I/O. Omit to load from jsDelivr (in-memory use only).
+   */
+  bundles?: duckdb.DuckDBBundles;
+}
+
+/**
+ * Create a DuckDB-backed {@link Db} using WebAssembly in the browser.
+ *
+ * With `options.path` set to an `opfs://` URL **and** self-hosted
+ * `options.bundles`, the database persists across reloads on OPFS. Otherwise it
+ * runs in-memory.
+ *
+ * @param options.path     `opfs://` path for persistent storage. Omit for in-memory.
+ * @param options.bundles  Same-origin bundle URLs (required for OPFS).
+ */
+export async function newBrowserDuckDb(options?: BrowserDuckDbOptions): Promise<Db> {
+  const selfHosted = options?.bundles;
+  const bundle = await duckdb.selectBundle(selfHosted ?? duckdb.getJsDelivrBundles());
+
+  // OPFS file I/O needs a same-origin worker. Self-hosted bundles give a
+  // same-origin URL we load directly; the jsDelivr fallback is cross-origin and
+  // must be wrapped in a Blob that `importScripts` it.
+  let worker: Worker;
+  let blobUrl: string | undefined;
+  if (selfHosted) {
+    worker = new Worker(bundle.mainWorker as string);
+  } else {
+    blobUrl = URL.createObjectURL(
+      new Blob([`importScripts("${bundle.mainWorker ?? ""}");`], {
+        type: "text/javascript",
+      }),
+    );
+    worker = new Worker(blobUrl);
+  }
+
+  const logger = new duckdb.ConsoleLogger();
+  const db = new duckdb.AsyncDuckDB(logger, worker);
+  await db.instantiate(bundle.mainModule, bundle.pthreadWorker);
+  if (blobUrl) URL.revokeObjectURL(blobUrl);
+
+  // Enable OPFS persistence when a path is provided and the API is available.
+  const persistent =
+    Boolean(options?.path) && typeof navigator !== "undefined" && Boolean(navigator.storage);
+  if (options?.path && persistent) {
+    try {
+      await db.open({
+        path: options.path,
+        accessMode: duckdb.DuckDBAccessMode.READ_WRITE,
+      });
+    } catch {
+      // Fall back to in-memory if OPFS is unavailable
+    }
+  }
+
+  const conn = await db.connect();
+
+  return {
+    async query<T = DbEntry>(sql: string, params?: unknown[]): Promise<T[]> {
+      if (params && params.length > 0) {
+        const stmt = await conn.prepare(sql);
+        const result = await stmt.query(...params);
+        return arrowToObjects<T>(result);
+      }
+      const result = await conn.query(sql);
+      return arrowToObjects<T>(result);
+    },
+
+    async exec(sql: string): Promise<void> {
+      await conn.query(sql);
+    },
+
+    async flush(): Promise<void> {
+      // CHECKPOINT writes the WAL into the OPFS database file so committed
+      // changes survive a reload. Crucial for OPFS persistence.
+      if (persistent) await conn.query("CHECKPOINT");
+    },
+
+    async close(): Promise<void> {
+      await conn.close();
+      await db.terminate();
+      worker.terminate();
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export type { Db, DbEntry, DbOptions } from "@statewalker/db-api";
+export {
+  type BrowserDuckDbOptions,
+  newBrowserDuckDb,
+} from "./browser-duckdb.js";