@statewalker/db-sqlite-browser 0.1.3 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -2,16 +2,17 @@
2
2
 
3
3
  ## What it is
4
4
 
5
- A libSQL/SQLite driver for the browser that implements `Db` from
6
- `@statewalker/db-api`. It runs `@libsql/libsql-wasm-experimental`, a
7
- WebAssembly build of libSQL that includes FTS5 full-text search and libSQL
8
- vector search (`F32_BLOB`, `vector32`, `libsql_vector_idx`, `vector_top_k`).
5
+ A SQLite driver for the browser that implements `Db` from `@statewalker/db-api` on the official
6
+ WebAssembly build, `@sqlite.org/sqlite-wasm` (SQLite 3.53, FTS5 with the `unicode61`, `porter`
7
+ and `trigram` tokenizers). It opens an in-memory database anywhere, and a persistent database in
8
+ the origin-private file system (OPFS) from a Dedicated Worker. Its Db works with `inTransaction`
9
+ from `@statewalker/db-sqlite`.
9
10
 
10
11
  ## Why it exists
11
12
 
12
- It gives browser code SQLite with full-text and vector search behind the same
13
- `Db` interface that `@statewalker/db-sqlite-node` provides in Node.js, so
14
- search and storage code runs unchanged in both places.
13
+ It lets code written against `Db` run on SQLite in the browser with the same SQL as on Node.js
14
+ (`@statewalker/db-sqlite-node`) and in Durable Objects (`@statewalker/db-sqlite-do`), so search
15
+ and storage code is written and tested once.
15
16
 
16
17
  ## How to use
17
18
 
@@ -19,69 +20,44 @@ search and storage code runs unchanged in both places.
19
20
  pnpm add @statewalker/db-sqlite-browser
20
21
  ```
21
22
 
22
- You must serve the engine's `sqlite3.wasm`. It is in
23
- `@libsql/libsql-wasm-experimental/sqlite-wasm/jswasm/`. The driver loads it
24
- from `/sqlite3.wasm` unless you pass `wasmUrl`.
25
-
26
23
  | Import | Gives | Environment |
27
24
  | --- | --- | --- |
28
- | `@statewalker/db-sqlite-browser` | `newBrowserSqliteDb`, type `BrowserDbOptions`; types `Db`, `DbEntry`, `DbOptions` re-exported from `@statewalker/db-api` | browser |
29
-
30
- `newBrowserSqliteDb(options?)` returns `Promise<Db>`.
31
-
32
- - `options.wasmUrl`: URL of `sqlite3.wasm`. Default `"/sqlite3.wasm"`.
33
- - `options.path`: database name passed to the engine. Default `:memory:`.
25
+ | `@statewalker/db-sqlite-browser` | `newBrowserSqliteDb`; types `BrowserDbOptions`, `Db`, `DbEntry`, `DbOptions` | browser: main thread (in-memory) or Dedicated Worker (OPFS); Node.js (in-memory) |
34
26
 
35
- The `Db` implements `query`, `exec` and `close`; it has no `flush`. Use `?`
36
- placeholders.
27
+ `newBrowserSqliteDb({ path?, wasmUrl? })` returns `Promise<Db>`. Without `path` the database is
28
+ in memory; that also works under Node.js (where a `wasmUrl`, if given, is a file path). With
29
+ `path` it lives in OPFS through the `opfs-sahpool` VFS, which works only in a Dedicated Worker.
30
+ Use `?` placeholders. Bundlers must not pre-bundle `@sqlite.org/sqlite-wasm` (Vite:
31
+ `optimizeDeps.exclude`), or pass `wasmUrl`.
37
32
 
38
33
  ## Examples
39
34
 
40
- Full-text search:
41
-
42
- ```ts
43
- import { newBrowserSqliteDb } from "@statewalker/db-sqlite-browser";
44
-
45
- const db = await newBrowserSqliteDb({ wasmUrl: "/assets/sqlite3.wasm" });
46
- await db.exec("CREATE VIRTUAL TABLE docs USING fts5(content)");
47
- await db.exec("INSERT INTO docs (rowid, content) VALUES (1, 'hello world')");
48
- const hits = await db.query<{ content: string }>(
49
- "SELECT content FROM docs WHERE docs MATCH ?",
50
- ["hello"],
51
- );
52
- await db.close();
53
- ```
54
-
55
- Vector search:
56
-
57
35
  ```ts
36
+ // worker.ts — started with new Worker(new URL("./worker.ts", import.meta.url), { type: "module" })
58
37
  import { newBrowserSqliteDb } from "@statewalker/db-sqlite-browser";
59
38
 
60
- const db = await newBrowserSqliteDb();
61
- await db.exec("CREATE TABLE emb (id INTEGER PRIMARY KEY, vec F32_BLOB(3))");
62
- await db.exec("CREATE INDEX emb_idx ON emb (libsql_vector_idx(vec))");
63
- await db.exec("INSERT INTO emb VALUES (1, vector32('[1,0,0]')), (2, vector32('[0,1,0]'))");
64
- const nearest = await db.query<{ id: number }>(
65
- "SELECT e.id FROM vector_top_k('emb_idx', '[1,0.1,0]', 1) AS v JOIN emb e ON e.rowid = v.id",
66
- );
39
+ const db = await newBrowserSqliteDb({ path: "/notes.db" });
40
+ await db.exec("CREATE VIRTUAL TABLE IF NOT EXISTS notes USING fts5(body)");
41
+ const hits = await db.query("SELECT rowid FROM notes WHERE notes MATCH ?", ["sqlite"]);
67
42
  ```
68
43
 
69
44
  ## Internals
70
45
 
71
- - **The engine loads once per page.** The first call starts the WASM module;
72
- later calls reuse it, and their `wasmUrl` is ignored. A failed start is
73
- cached too: if `sqlite3.wasm` was not found, every later call in that page
74
- fails the same way until the page reloads.
75
- - **No OPFS.** `options.path` goes to `new sqlite3.oo1.DB(path, "c")`. The
76
- driver does not install or select an OPFS VFS.
77
- - **Synchronous engine, async interface.** `query` runs
78
- `db.exec(sql, { rowMode: "object", returnValue: "resultRows", bind })` on the
79
- calling thread; the `Db` methods are `async` only to match the interface.
80
- Long queries block the thread they run on.
81
- - **Under Node.js** the module imports, but `newBrowserSqliteDb()` aborts with
82
- `ENOENT ... '/sqlite3.wasm'`. Use `@statewalker/db-sqlite-node` there.
83
- - **Dependencies:** `@libsql/libsql-wasm-experimental` (the engine),
84
- `@statewalker/db-api` (the interface types).
46
+ - **Why OPFS only in a Dedicated Worker.** `opfs-sahpool` uses synchronous OPFS access handles,
47
+ which browsers provide only in workers. It needs no `SharedArrayBuffer`, so no COOP/COEP
48
+ headers. Outside a Dedicated Worker (the main thread, Node.js) a `path` rejects at once with
49
+ `newBrowserSqliteDb: { path } needs a Dedicated Worker ...` rather than falling back to memory.
50
+ - **One worker owns a database.** The pool holds its OPFS files open while the worker lives; a
51
+ second worker (or tab) opening the same `path` fails with an OPFS lock error until the first
52
+ one is terminated.
53
+ - **The pool has room for a few files.** Its default capacity is 6 files, and each database also
54
+ uses journal files, so a worker that opens many databases can run out of slots.
55
+ - **Calls are queued** and transactions open with `BEGIN IMMEDIATE` (see `@statewalker/db-sqlite`).
56
+ Rows are plain objects; BLOBs are `Uint8Array`.
57
+ - **The engine loads once per `wasmUrl`.** A failed load (for example a wrong `wasmUrl`) is not
58
+ retried for that URL.
59
+ - **Dependencies:** `@sqlite.org/sqlite-wasm` (the engine), `@statewalker/db-sqlite` (queue and
60
+ transactions), `@statewalker/db-api` (types).
85
61
 
86
62
  ## License
87
63
 
package/dist/index.d.mts CHANGED
@@ -1,17 +1,14 @@
1
1
  import { Db, Db as Db$1, DbEntry, DbOptions, DbOptions as DbOptions$1 } from "@statewalker/db-api";
2
2
  //#region src/browser-sqlite-db.d.ts
3
3
  type BrowserDbOptions = DbOptions$1 & {
4
- /** URL to the sqlite3.wasm file. Defaults to "/sqlite3.wasm". */
4
+ /** URL of `sqlite3.wasm`. Default: the package's own file, located by the bundler. */
5
5
  wasmUrl?: string;
6
6
  };
7
7
  /**
8
- * Create a libSQL WASM-backed {@link Db} in the browser.
8
+ * Create a SQLite {@link Db} on `@sqlite.org/sqlite-wasm`.
9
9
  *
10
- * Uses `@libsql/libsql-wasm-experimental` which provides the full libSQL
11
- * engine (FTS5, vector search) compiled to WebAssembly.
12
- *
13
- * @param options.path File path for persistent storage. Omit for in-memory.
14
- * @param options.wasmUrl URL to the sqlite3.wasm file. Defaults to "/sqlite3.wasm".
10
+ * @param options.path OPFS database name; Dedicated Worker only. Omit for in-memory.
11
+ * @param options.wasmUrl URL of `sqlite3.wasm`, when the bundler cannot locate it.
15
12
  */
16
13
  export declare function newBrowserSqliteDb(options?: BrowserDbOptions): Promise<Db$1>;
17
14
  //#endregion
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.mts","names":["DbOptions","Db"],"sources":["../src/browser-sqlite-db.ts"],"mappings":";;KAIY,mBAAmBA;;EAE7B;;;;;;;;;;;wBAuBoB,mBAAmB,UAAU,mBAAmB,QAAQC"}
1
+ {"version":3,"file":"index.d.mts","names":["DbOptions","Db"],"sources":["../src/browser-sqlite-db.ts"],"mappings":";;KASY,mBAAmBA;;EAE7B;;;;;;;;wBA4CoB,mBAAmB,UAAU,mBAAmB,QAAQC"}
package/dist/index.mjs CHANGED
@@ -1,38 +1,50 @@
1
- import sqlite3InitModule from "@libsql/libsql-wasm-experimental";
1
+ import sqlite3InitModule from "@sqlite.org/sqlite-wasm";
2
+ import { newSerialisedSqliteDb } from "@statewalker/db-sqlite";
2
3
  //#region src/browser-sqlite-db.ts
3
- let sqlite3Promise;
4
+ const MAIN_THREAD_PATH = "newBrowserSqliteDb: { path } needs a Dedicated Worker (the \"opfs-sahpool\" OPFS VFS runs only there). On the main thread, omit path for an in-memory database.";
5
+ /** One engine per wasmUrl, started on first use; one OPFS pool per engine. */
6
+ const engines = /* @__PURE__ */ new Map();
7
+ const pools = /* @__PURE__ */ new WeakMap();
4
8
  function getSqlite3(wasmUrl) {
5
- if (!sqlite3Promise) sqlite3Promise = sqlite3InitModule({ locateFile: (file) => file.endsWith(".wasm") ? wasmUrl : file });
6
- return sqlite3Promise;
9
+ const key = wasmUrl ?? "";
10
+ let engine = engines.get(key);
11
+ if (!engine) {
12
+ engine = sqlite3InitModule(wasmUrl ? { locateFile: (file) => file.endsWith(".wasm") ? wasmUrl : file } : void 0);
13
+ engines.set(key, engine);
14
+ }
15
+ return engine;
7
16
  }
17
+ function getPool(sqlite3) {
18
+ let pool = pools.get(sqlite3);
19
+ if (!pool) {
20
+ pool = sqlite3.installOpfsSAHPoolVfs({});
21
+ pools.set(sqlite3, pool);
22
+ }
23
+ return pool;
24
+ }
25
+ const inDedicatedWorker = () => typeof globalThis.DedicatedWorkerGlobalScope !== "undefined";
8
26
  /**
9
- * Create a libSQL WASM-backed {@link Db} in the browser.
10
- *
11
- * Uses `@libsql/libsql-wasm-experimental` which provides the full libSQL
12
- * engine (FTS5, vector search) compiled to WebAssembly.
27
+ * Create a SQLite {@link Db} on `@sqlite.org/sqlite-wasm`.
13
28
  *
14
- * @param options.path File path for persistent storage. Omit for in-memory.
15
- * @param options.wasmUrl URL to the sqlite3.wasm file. Defaults to "/sqlite3.wasm".
29
+ * @param options.path OPFS database name; Dedicated Worker only. Omit for in-memory.
30
+ * @param options.wasmUrl URL of `sqlite3.wasm`, when the bundler cannot locate it.
16
31
  */
17
32
  async function newBrowserSqliteDb(options) {
18
- const sqlite3 = await getSqlite3(options?.wasmUrl ?? "/sqlite3.wasm");
19
- const dbPath = options?.path ?? ":memory:";
20
- const db = new sqlite3.oo1.DB(dbPath, "c");
21
- return {
22
- async query(sql, params) {
23
- return db.exec(sql, {
24
- returnValue: "resultRows",
25
- rowMode: "object",
26
- bind: params
27
- });
28
- },
29
- async exec(sql) {
33
+ if (options?.path && !inDedicatedWorker()) throw new Error(MAIN_THREAD_PATH);
34
+ const sqlite3 = await getSqlite3(options?.wasmUrl);
35
+ const db = options?.path ? new (await (getPool(sqlite3))).OpfsSAHPoolDb(options.path) : new sqlite3.oo1.DB(":memory:", "c");
36
+ return newSerialisedSqliteDb({
37
+ all: (sql, params) => db.exec({
38
+ sql,
39
+ bind: params.length > 0 ? params : void 0,
40
+ rowMode: "object",
41
+ returnValue: "resultRows"
42
+ }),
43
+ exec: (sql) => {
30
44
  db.exec(sql);
31
45
  },
32
- async close() {
33
- db.close();
34
- }
35
- };
46
+ close: () => db.close()
47
+ });
36
48
  }
37
49
  //#endregion
38
50
  export { newBrowserSqliteDb };
@@ -1 +1 @@
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"}
1
+ {"version":3,"file":"index.mjs","names":[],"sources":["../src/browser-sqlite-db.ts"],"sourcesContent":["import sqlite3InitModule, {\n type BindableValue,\n type Database,\n type SAHPoolUtil,\n type Sqlite3Static,\n} from \"@sqlite.org/sqlite-wasm\";\nimport type { Db, DbOptions } from \"@statewalker/db-api\";\nimport { newSerialisedSqliteDb } from \"@statewalker/db-sqlite\";\n\nexport type BrowserDbOptions = DbOptions & {\n /** URL of `sqlite3.wasm`. Default: the package's own file, located by the bundler. */\n wasmUrl?: string;\n};\n\nconst MAIN_THREAD_PATH =\n 'newBrowserSqliteDb: { path } needs a Dedicated Worker (the \"opfs-sahpool\" OPFS VFS runs only ' +\n \"there). On the main thread, omit path for an in-memory database.\";\n\ntype InitModule = (module?: { locateFile?: (file: string) => string }) => Promise<Sqlite3Static>;\n\n/** One engine per wasmUrl, started on first use; one OPFS pool per engine. */\nconst engines = new Map<string, Promise<Sqlite3Static>>();\nconst pools = new WeakMap<Sqlite3Static, Promise<SAHPoolUtil>>();\n\nfunction getSqlite3(wasmUrl: string | undefined): Promise<Sqlite3Static> {\n const key = wasmUrl ?? \"\";\n let engine = engines.get(key);\n if (!engine) {\n engine = (sqlite3InitModule as InitModule)(\n wasmUrl ? { locateFile: (file) => (file.endsWith(\".wasm\") ? wasmUrl : file) } : undefined,\n );\n engines.set(key, engine);\n }\n return engine;\n}\n\nfunction getPool(sqlite3: Sqlite3Static): Promise<SAHPoolUtil> {\n let pool = pools.get(sqlite3);\n if (!pool) {\n pool = sqlite3.installOpfsSAHPoolVfs({});\n pools.set(sqlite3, pool);\n }\n return pool;\n}\n\nconst inDedicatedWorker = () =>\n typeof (globalThis as { DedicatedWorkerGlobalScope?: unknown }).DedicatedWorkerGlobalScope !==\n \"undefined\";\n\n/**\n * Create a SQLite {@link Db} on `@sqlite.org/sqlite-wasm`.\n *\n * @param options.path OPFS database name; Dedicated Worker only. Omit for in-memory.\n * @param options.wasmUrl URL of `sqlite3.wasm`, when the bundler cannot locate it.\n */\nexport async function newBrowserSqliteDb(options?: BrowserDbOptions): Promise<Db> {\n if (options?.path && !inDedicatedWorker()) throw new Error(MAIN_THREAD_PATH);\n const sqlite3 = await getSqlite3(options?.wasmUrl);\n const db: Database = options?.path\n ? new (await getPool(sqlite3)).OpfsSAHPoolDb(options.path)\n : new sqlite3.oo1.DB(\":memory:\", \"c\");\n return newSerialisedSqliteDb({\n all: (sql, params) =>\n db.exec({\n sql,\n bind: params.length > 0 ? (params as BindableValue[]) : undefined,\n rowMode: \"object\",\n returnValue: \"resultRows\",\n }) as Record<string, unknown>[],\n exec: (sql) => {\n db.exec(sql);\n },\n close: () => db.close(),\n });\n}\n"],"mappings":";;;AAcA,MAAM,mBACJ;;AAMF,MAAM,0BAAU,IAAI,IAAoC;AACxD,MAAM,wBAAQ,IAAI,QAA6C;AAE/D,SAAS,WAAW,SAAqD;CACvE,MAAM,MAAM,WAAW;CACvB,IAAI,SAAS,QAAQ,IAAI,GAAG;CAC5B,IAAI,CAAC,QAAQ;EACX,SAAU,kBACR,UAAU,EAAE,aAAa,SAAU,KAAK,SAAS,OAAO,IAAI,UAAU,KAAM,IAAI,KAAA,CAClF;EACA,QAAQ,IAAI,KAAK,MAAM;CACzB;CACA,OAAO;AACT;AAEA,SAAS,QAAQ,SAA8C;CAC7D,IAAI,OAAO,MAAM,IAAI,OAAO;CAC5B,IAAI,CAAC,MAAM;EACT,OAAO,QAAQ,sBAAsB,CAAC,CAAC;EACvC,MAAM,IAAI,SAAS,IAAI;CACzB;CACA,OAAO;AACT;AAEA,MAAM,0BACJ,OAAQ,WAAwD,+BAChE;;;;;;;AAQF,eAAsB,mBAAmB,SAAyC;CAChF,IAAI,SAAS,QAAQ,CAAC,kBAAkB,GAAG,MAAM,IAAI,MAAM,gBAAgB;CAC3E,MAAM,UAAU,MAAM,WAAW,SAAS,OAAO;CACjD,MAAM,KAAe,SAAS,OAC1B,KAAK,OAAM,QAAQ,OAAO,GAAA,CAAG,cAAc,QAAQ,IAAI,IACvD,IAAI,QAAQ,IAAI,GAAG,YAAY,GAAG;CACtC,OAAO,sBAAsB;EAC3B,MAAM,KAAK,WACT,GAAG,KAAK;GACN;GACA,MAAM,OAAO,SAAS,IAAK,SAA6B,KAAA;GACxD,SAAS;GACT,aAAa;EACf,CAAC;EACH,OAAO,QAAQ;GACb,GAAG,KAAK,GAAG;EACb;EACA,aAAa,GAAG,MAAM;CACxB,CAAC;AACH"}
package/package.json CHANGED
@@ -1,9 +1,9 @@
1
1
  {
2
2
  "name": "@statewalker/db-sqlite-browser",
3
- "version": "0.1.3",
3
+ "version": "0.2.0",
4
4
  "private": false,
5
5
  "type": "module",
6
- "description": "libSQL/SQLite WASM driver for @statewalker/db-api, targeting browser environments.",
6
+ "description": "SQLite WASM (@sqlite.org/sqlite-wasm) driver for @statewalker/db-api in the browser: in-memory anywhere, OPFS persistence in a Dedicated Worker.",
7
7
  "bugs": {
8
8
  "url": "https://github.com/statewalker/statewalker-db/issues"
9
9
  },
@@ -30,11 +30,13 @@
30
30
  "src"
31
31
  ],
32
32
  "dependencies": {
33
- "@libsql/libsql-wasm-experimental": "^0.0.3",
34
- "@statewalker/db-api": "^0.1.3"
33
+ "@sqlite.org/sqlite-wasm": "3.53.0-build1",
34
+ "@statewalker/db-sqlite": "^0.1.0",
35
+ "@statewalker/db-api": "^0.1.4"
35
36
  },
36
37
  "devDependencies": {
37
38
  "@playwright/test": "^1.63.0",
39
+ "@types/node": "^26.6.4",
38
40
  "@vitest/browser": "^5.0.3",
39
41
  "@vitest/browser-playwright": "^5.0.3",
40
42
  "playwright": "^1.63.0",
@@ -1,30 +1,21 @@
1
1
  import type { Db } from "@statewalker/db-api";
2
- import { runDbConformance } from "@statewalker/db-tests";
2
+ import { runDbConformance, runSqliteTransactionConformance } from "@statewalker/db-tests";
3
3
  import { afterEach, describe, expect, it } from "vitest";
4
4
  import { newBrowserSqliteDb } from "./browser-sqlite-db.js";
5
5
 
6
6
  /**
7
- * The libSQL-WASM browser adapter, exercised in a REAL browser (Vitest browser
7
+ * The sqlite-wasm adapter, exercised in a REAL browser (Vitest browser
8
8
  * mode + Playwright/Chromium). Launched only by `vitest.browser.config.ts` (the
9
9
  * `test:browser` script) — the Node config excludes `*.browser.test.ts`.
10
10
  *
11
- * The engine is served from `/sqlite3.wasm` by the config's `publicDir`, so the
12
- * adapter's default `wasmUrl` resolves. Everything runs in-memory; the node-only
13
- * file-persistence scenario is skipped via `skipFilePersistence`.
11
+ * Everything runs in-memory except the OPFS tests, which use Dedicated Workers;
12
+ * the node-only file-persistence scenario is skipped via `skipFilePersistence`.
14
13
  */
15
14
 
16
- // Shared contract: CRUD, parameter binding, injection safety, cardinality,
17
- // close, error paths. File persistence is node-only, hence skipped here.
18
- runDbConformance(() => newBrowserSqliteDb(), {
19
- // libsql dialect: `?` placeholder; the spread normalizer drops libsql Row's
20
- // non-enumerable positional keys so a plain `toEqual` matches.
21
- placeholder: "?",
22
- normalizeRow: (row) => ({ ...row }),
23
- skipFilePersistence: true,
24
- });
15
+ runDbConformance(() => newBrowserSqliteDb(), { placeholder: "?", skipFilePersistence: true });
16
+ runSqliteTransactionConformance(() => newBrowserSqliteDb());
25
17
 
26
- // Dialect-specific browser behavior the shared suite does not cover: libSQL's
27
- // FTS5 full-text search and native vector index.
18
+ // Dialect-specific browser behavior the shared suite does not cover: FTS5 full-text search.
28
19
  describe("newBrowserSqliteDb", () => {
29
20
  let db: Db;
30
21
 
@@ -35,6 +26,14 @@ describe("newBrowserSqliteDb", () => {
35
26
  });
36
27
 
37
28
  describe("FTS5", () => {
29
+ it("has the trigram tokenizer (substring search)", async () => {
30
+ db = await newBrowserSqliteDb();
31
+ await db.exec("CREATE VIRTUAL TABLE g USING fts5(c, tokenize='trigram')");
32
+ await db.exec("INSERT INTO g VALUES ('idx_lefthand')");
33
+ const rows = await db.query<{ c: string }>("SELECT c FROM g WHERE g MATCH 'x_le'");
34
+ expect(rows.map((r) => r.c)).toEqual(["idx_lefthand"]);
35
+ });
36
+
38
37
  it("returns empty results for unmatched search terms", async () => {
39
38
  db = await newBrowserSqliteDb();
40
39
  await db.exec("CREATE VIRTUAL TABLE docs2_fts USING fts5(content)");
@@ -93,67 +92,49 @@ describe("newBrowserSqliteDb", () => {
93
92
  expect(rowids).toContain(3);
94
93
  });
95
94
  });
95
+ });
96
96
 
97
- describe("vector search", () => {
98
- it("creates index and performs vector similarity search", async () => {
99
- db = await newBrowserSqliteDb();
100
-
101
- await db.exec("CREATE TABLE embeddings (id INTEGER PRIMARY KEY, vec F32_BLOB(3))");
102
- await db.exec("CREATE INDEX vec_idx ON embeddings (libsql_vector_idx(vec))");
103
- await db.exec(`
104
- INSERT INTO embeddings VALUES
105
- (1, vector32('[1.0, 0.0, 0.0]')),
106
- (2, vector32('[0.0, 1.0, 0.0]')),
107
- (3, vector32('[0.0, 0.0, 1.0]'))
108
- `);
109
-
110
- const rows = await db.query<{ id: number }>(
111
- "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",
112
- );
113
-
114
- expect(rows).toHaveLength(1);
115
- expect(rows[0]?.id).toBe(1);
116
- });
117
-
118
- it("returns k nearest neighbors ordered by distance", async () => {
119
- db = await newBrowserSqliteDb();
120
-
121
- await db.exec("CREATE TABLE vectors (id INTEGER PRIMARY KEY, vec F32_BLOB(3))");
122
- await db.exec("CREATE INDEX vec_idx2 ON vectors (libsql_vector_idx(vec))");
123
- await db.exec(`
124
- INSERT INTO vectors VALUES
125
- (1, vector32('[1.0, 0.0, 0.0]')),
126
- (2, vector32('[0.9, 0.1, 0.0]')),
127
- (3, vector32('[0.0, 1.0, 0.0]')),
128
- (4, vector32('[0.0, 0.0, 1.0]'))
129
- `);
130
-
131
- const rows = await db.query<{ id: number }>(
132
- "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",
133
- );
134
-
135
- expect(rows).toHaveLength(2);
136
- const ids = rows.map((r) => r.id);
137
- expect(ids).toContain(1);
138
- expect(ids).toContain(2);
97
+ type TestWorker = {
98
+ onmessage: ((event: { data: { count?: number; error?: string } }) => void) | null;
99
+ onerror: ((event: { message: string }) => void) | null;
100
+ postMessage(message: unknown): void;
101
+ terminate(): void;
102
+ };
103
+ const WorkerClass = (
104
+ globalThis as unknown as {
105
+ Worker: new (url: URL, options: { type: "module" }) => TestWorker;
106
+ }
107
+ ).Worker;
108
+
109
+ /** Run one action in a fresh Dedicated Worker, then terminate it (as a page reload would). */
110
+ function inWorker(message: { path: string; action: "write" | "count" }): Promise<number> {
111
+ return new Promise((resolve, reject) => {
112
+ const worker = new WorkerClass(new URL("../test/opfs-test-worker.ts", import.meta.url), {
113
+ type: "module",
139
114
  });
115
+ worker.onmessage = ({ data }) => {
116
+ worker.terminate();
117
+ if (data.error) reject(new Error(data.error));
118
+ else resolve(Number(data.count));
119
+ };
120
+ worker.onerror = (event) => {
121
+ worker.terminate();
122
+ reject(new Error(event.message));
123
+ };
124
+ worker.postMessage(message);
125
+ });
126
+ }
140
127
 
141
- it("works without index (brute-force scan)", async () => {
142
- db = await newBrowserSqliteDb();
143
-
144
- await db.exec("CREATE TABLE vecs_no_idx (id INTEGER PRIMARY KEY, vec F32_BLOB(3))");
145
- await db.exec(`
146
- INSERT INTO vecs_no_idx VALUES
147
- (1, vector32('[1.0, 0.0, 0.0]')),
148
- (2, vector32('[0.0, 1.0, 0.0]'))
149
- `);
150
-
151
- const rows = await db.query<{ id: number }>(
152
- "SELECT id FROM vecs_no_idx ORDER BY vector_distance_cos(vec, vector32('[0.0, 0.9, 0.1]')) LIMIT 1",
153
- );
128
+ describe("OPFS persistence (opfs-sahpool)", () => {
129
+ it("rejects a persistent path on the main thread", async () => {
130
+ await expect(newBrowserSqliteDb({ path: "/main-thread.db" })).rejects.toThrow(
131
+ /Dedicated Worker/,
132
+ );
133
+ });
154
134
 
155
- expect(rows).toHaveLength(1);
156
- expect(rows[0]?.id).toBe(2);
157
- });
135
+ it("keeps a path's data from one worker to the next", async () => {
136
+ const path = `/persist-${Date.now()}.db`;
137
+ expect(await inWorker({ path, action: "write" })).toBe(1);
138
+ expect(await inWorker({ path, action: "count" })).toBe(1);
158
139
  });
159
140
  });
@@ -1,14 +1,25 @@
1
+ import { createRequire } from "node:module";
2
+ import { runDbConformance, runSqliteTransactionConformance } from "@statewalker/db-tests";
1
3
  import { describe, expect, it } from "vitest";
4
+ import { newBrowserSqliteDb } from "./browser-sqlite-db.js";
2
5
 
3
- /**
4
- * Node-safe smoke test. The real browser coverage (shared conformance suite +
5
- * FTS5/vector) lives in `browser-sqlite-db.browser.test.ts`, run via Vitest
6
- * browser mode (`pnpm test:browser`); this file only checks the module loads
7
- * and exports its factory, since libSQL-WASM cannot instantiate under Node.
8
- */
9
- describe("browser-sqlite-db module", () => {
10
- it("exports newBrowserSqliteDb function", async () => {
11
- const mod = await import("./browser-sqlite-db.js");
12
- expect(typeof mod.newBrowserSqliteDb).toBe("function");
6
+ // The same WASM engine as in the browser, in memory: the shared suites run under Node too.
7
+ runDbConformance(() => newBrowserSqliteDb(), { placeholder: "?", skipFilePersistence: true });
8
+ runSqliteTransactionConformance(() => newBrowserSqliteDb());
9
+
10
+ describe("newBrowserSqliteDb under Node", () => {
11
+ it("rejects a persistent path outside a Dedicated Worker", async () => {
12
+ await expect(newBrowserSqliteDb({ path: "/data.db" })).rejects.toThrow(/Dedicated Worker/);
13
+ });
14
+
15
+ it("honors a different wasmUrl after an earlier call", async () => {
16
+ await expect(newBrowserSqliteDb({ wasmUrl: "/nonexistent/sqlite3.wasm" })).rejects.toThrow();
17
+ const wasmPath = createRequire(import.meta.url).resolve("@sqlite.org/sqlite-wasm/sqlite3.wasm");
18
+ const db = await newBrowserSqliteDb({ wasmUrl: wasmPath });
19
+ try {
20
+ expect(await db.query("SELECT 1 AS x")).toEqual([{ x: 1 }]);
21
+ } finally {
22
+ await db.close();
23
+ }
13
24
  });
14
25
  });
@@ -1,54 +1,75 @@
1
- import type { Database, Sqlite3Static } from "@libsql/libsql-wasm-experimental";
2
- import sqlite3InitModule from "@libsql/libsql-wasm-experimental";
3
- import type { Db, DbEntry, DbOptions } from "@statewalker/db-api";
1
+ import sqlite3InitModule, {
2
+ type BindableValue,
3
+ type Database,
4
+ type SAHPoolUtil,
5
+ type Sqlite3Static,
6
+ } from "@sqlite.org/sqlite-wasm";
7
+ import type { Db, DbOptions } from "@statewalker/db-api";
8
+ import { newSerialisedSqliteDb } from "@statewalker/db-sqlite";
4
9
 
5
10
  export type BrowserDbOptions = DbOptions & {
6
- /** URL to the sqlite3.wasm file. Defaults to "/sqlite3.wasm". */
11
+ /** URL of `sqlite3.wasm`. Default: the package's own file, located by the bundler. */
7
12
  wasmUrl?: string;
8
13
  };
9
14
 
10
- let sqlite3Promise: Promise<Sqlite3Static> | undefined;
15
+ const MAIN_THREAD_PATH =
16
+ 'newBrowserSqliteDb: { path } needs a Dedicated Worker (the "opfs-sahpool" OPFS VFS runs only ' +
17
+ "there). On the main thread, omit path for an in-memory database.";
11
18
 
12
- function getSqlite3(wasmUrl: string): Promise<Sqlite3Static> {
13
- if (!sqlite3Promise) {
14
- sqlite3Promise = sqlite3InitModule({
15
- locateFile: (file: string) => (file.endsWith(".wasm") ? wasmUrl : file),
16
- });
19
+ type InitModule = (module?: { locateFile?: (file: string) => string }) => Promise<Sqlite3Static>;
20
+
21
+ /** One engine per wasmUrl, started on first use; one OPFS pool per engine. */
22
+ const engines = new Map<string, Promise<Sqlite3Static>>();
23
+ const pools = new WeakMap<Sqlite3Static, Promise<SAHPoolUtil>>();
24
+
25
+ function getSqlite3(wasmUrl: string | undefined): Promise<Sqlite3Static> {
26
+ const key = wasmUrl ?? "";
27
+ let engine = engines.get(key);
28
+ if (!engine) {
29
+ engine = (sqlite3InitModule as InitModule)(
30
+ wasmUrl ? { locateFile: (file) => (file.endsWith(".wasm") ? wasmUrl : file) } : undefined,
31
+ );
32
+ engines.set(key, engine);
17
33
  }
18
- return sqlite3Promise;
34
+ return engine;
19
35
  }
20
36
 
37
+ function getPool(sqlite3: Sqlite3Static): Promise<SAHPoolUtil> {
38
+ let pool = pools.get(sqlite3);
39
+ if (!pool) {
40
+ pool = sqlite3.installOpfsSAHPoolVfs({});
41
+ pools.set(sqlite3, pool);
42
+ }
43
+ return pool;
44
+ }
45
+
46
+ const inDedicatedWorker = () =>
47
+ typeof (globalThis as { DedicatedWorkerGlobalScope?: unknown }).DedicatedWorkerGlobalScope !==
48
+ "undefined";
49
+
21
50
  /**
22
- * Create a libSQL WASM-backed {@link Db} in the browser.
23
- *
24
- * Uses `@libsql/libsql-wasm-experimental` which provides the full libSQL
25
- * engine (FTS5, vector search) compiled to WebAssembly.
51
+ * Create a SQLite {@link Db} on `@sqlite.org/sqlite-wasm`.
26
52
  *
27
- * @param options.path File path for persistent storage. Omit for in-memory.
28
- * @param options.wasmUrl URL to the sqlite3.wasm file. Defaults to "/sqlite3.wasm".
53
+ * @param options.path OPFS database name; Dedicated Worker only. Omit for in-memory.
54
+ * @param options.wasmUrl URL of `sqlite3.wasm`, when the bundler cannot locate it.
29
55
  */
30
56
  export async function newBrowserSqliteDb(options?: BrowserDbOptions): Promise<Db> {
31
- const wasmUrl = options?.wasmUrl ?? "/sqlite3.wasm";
32
- const sqlite3 = await getSqlite3(wasmUrl);
33
- const dbPath = options?.path ?? ":memory:";
34
- const db: Database = new sqlite3.oo1.DB(dbPath, "c");
35
-
36
- return {
37
- async query<T = DbEntry>(sql: string, params?: unknown[]): Promise<T[]> {
38
- const rows = db.exec(sql, {
39
- returnValue: "resultRows",
57
+ if (options?.path && !inDedicatedWorker()) throw new Error(MAIN_THREAD_PATH);
58
+ const sqlite3 = await getSqlite3(options?.wasmUrl);
59
+ const db: Database = options?.path
60
+ ? new (await getPool(sqlite3)).OpfsSAHPoolDb(options.path)
61
+ : new sqlite3.oo1.DB(":memory:", "c");
62
+ return newSerialisedSqliteDb({
63
+ all: (sql, params) =>
64
+ db.exec({
65
+ sql,
66
+ bind: params.length > 0 ? (params as BindableValue[]) : undefined,
40
67
  rowMode: "object",
41
- bind: params as never[],
42
- });
43
- return rows as unknown as T[];
44
- },
45
-
46
- async exec(sql: string): Promise<void> {
68
+ returnValue: "resultRows",
69
+ }) as Record<string, unknown>[],
70
+ exec: (sql) => {
47
71
  db.exec(sql);
48
72
  },
49
-
50
- async close(): Promise<void> {
51
- db.close();
52
- },
53
- };
73
+ close: () => db.close(),
74
+ });
54
75
  }