@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 +33 -57
- package/dist/index.d.mts +4 -7
- package/dist/index.d.mts.map +1 -1
- package/dist/index.mjs +38 -26
- package/dist/index.mjs.map +1 -1
- package/package.json +6 -4
- package/src/browser-sqlite-db.browser.test.ts +55 -74
- package/src/browser-sqlite-db.test.ts +21 -10
- package/src/browser-sqlite-db.ts +58 -37
package/README.md
CHANGED
|
@@ -2,16 +2,17 @@
|
|
|
2
2
|
|
|
3
3
|
## What it is
|
|
4
4
|
|
|
5
|
-
A
|
|
6
|
-
`@
|
|
7
|
-
|
|
8
|
-
|
|
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
|
|
13
|
-
|
|
14
|
-
|
|
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
|
|
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
|
-
|
|
36
|
-
|
|
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
|
|
62
|
-
await db.
|
|
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
|
-
- **
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
- **
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
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
|
|
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
|
|
8
|
+
* Create a SQLite {@link Db} on `@sqlite.org/sqlite-wasm`.
|
|
9
9
|
*
|
|
10
|
-
*
|
|
11
|
-
*
|
|
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
|
package/dist/index.d.mts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.mts","names":["DbOptions","Db"],"sources":["../src/browser-sqlite-db.ts"],"mappings":";;
|
|
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 "@
|
|
1
|
+
import sqlite3InitModule from "@sqlite.org/sqlite-wasm";
|
|
2
|
+
import { newSerialisedSqliteDb } from "@statewalker/db-sqlite";
|
|
2
3
|
//#region src/browser-sqlite-db.ts
|
|
3
|
-
|
|
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
|
-
|
|
6
|
-
|
|
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
|
|
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
|
|
15
|
-
* @param options.wasmUrl URL
|
|
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
|
-
|
|
19
|
-
const
|
|
20
|
-
const db = new sqlite3.oo1.DB(
|
|
21
|
-
return {
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
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
|
-
|
|
33
|
-
|
|
34
|
-
}
|
|
35
|
-
};
|
|
46
|
+
close: () => db.close()
|
|
47
|
+
});
|
|
36
48
|
}
|
|
37
49
|
//#endregion
|
|
38
50
|
export { newBrowserSqliteDb };
|
package/dist/index.mjs.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.mjs","names":[],"sources":["../src/browser-sqlite-db.ts"],"sourcesContent":["import
|
|
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.
|
|
3
|
+
"version": "0.2.0",
|
|
4
4
|
"private": false,
|
|
5
5
|
"type": "module",
|
|
6
|
-
"description": "
|
|
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
|
-
"@
|
|
34
|
-
"@statewalker/db-
|
|
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
|
|
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
|
-
*
|
|
12
|
-
*
|
|
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
|
-
|
|
17
|
-
|
|
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:
|
|
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
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
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
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
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
|
-
|
|
156
|
-
|
|
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
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
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
|
});
|
package/src/browser-sqlite-db.ts
CHANGED
|
@@ -1,54 +1,75 @@
|
|
|
1
|
-
import
|
|
2
|
-
|
|
3
|
-
|
|
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
|
|
11
|
+
/** URL of `sqlite3.wasm`. Default: the package's own file, located by the bundler. */
|
|
7
12
|
wasmUrl?: string;
|
|
8
13
|
};
|
|
9
14
|
|
|
10
|
-
|
|
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
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
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
|
|
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
|
|
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
|
|
28
|
-
* @param options.wasmUrl URL
|
|
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
|
-
|
|
32
|
-
const sqlite3 = await getSqlite3(wasmUrl);
|
|
33
|
-
const
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
return {
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
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
|
-
|
|
42
|
-
})
|
|
43
|
-
|
|
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
|
-
|
|
51
|
-
db.close();
|
|
52
|
-
},
|
|
53
|
-
};
|
|
73
|
+
close: () => db.close(),
|
|
74
|
+
});
|
|
54
75
|
}
|