@statewalker/db-sqlite-browser 0.1.2 → 0.1.4
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 +72 -14
- package/dist/index.d.mts.map +1 -1
- package/dist/index.mjs +7 -2
- package/dist/index.mjs.map +1 -1
- package/package.json +8 -4
- package/src/browser-sqlite-db.test.ts +23 -3
- package/src/browser-sqlite-db.ts +4 -1
package/README.md
CHANGED
|
@@ -1,31 +1,89 @@
|
|
|
1
1
|
# @statewalker/db-sqlite-browser
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
backed by `@libsql/libsql-wasm-experimental` (FTS5 + vector search compiled to WebAssembly).
|
|
3
|
+
## What it is
|
|
5
4
|
|
|
6
|
-
|
|
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`).
|
|
9
|
+
|
|
10
|
+
## Why it exists
|
|
11
|
+
|
|
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.
|
|
15
|
+
|
|
16
|
+
## How to use
|
|
7
17
|
|
|
8
18
|
```sh
|
|
9
19
|
pnpm add @statewalker/db-sqlite-browser
|
|
10
20
|
```
|
|
11
21
|
|
|
12
|
-
|
|
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
|
+
| Import | Gives | Environment |
|
|
27
|
+
| --- | --- | --- |
|
|
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:`.
|
|
34
|
+
|
|
35
|
+
The `Db` implements `query`, `exec` and `close`; it has no `flush`. Use `?`
|
|
36
|
+
placeholders.
|
|
37
|
+
|
|
38
|
+
## Examples
|
|
39
|
+
|
|
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:
|
|
13
56
|
|
|
14
57
|
```ts
|
|
15
58
|
import { newBrowserSqliteDb } from "@statewalker/db-sqlite-browser";
|
|
16
59
|
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
await db.exec("CREATE
|
|
20
|
-
await db.
|
|
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
|
+
);
|
|
21
67
|
```
|
|
22
68
|
|
|
23
|
-
##
|
|
69
|
+
## Internals
|
|
24
70
|
|
|
25
|
-
-
|
|
26
|
-
`
|
|
71
|
+
- **The engine loads once per `wasmUrl`.** The first call with a given
|
|
72
|
+
`wasmUrl` starts the WASM module; later calls with the same URL reuse it, and
|
|
73
|
+
a call with a different URL starts a separate engine. A failed start is
|
|
74
|
+
cached too: if `sqlite3.wasm` was not found at a URL, every later call with
|
|
75
|
+
that URL fails the same way until the page reloads.
|
|
76
|
+
- **No OPFS.** `options.path` goes to `new sqlite3.oo1.DB(path, "c")`. The
|
|
77
|
+
driver does not install or select an OPFS VFS.
|
|
78
|
+
- **Synchronous engine, async interface.** `query` runs
|
|
79
|
+
`db.exec(sql, { rowMode: "object", returnValue: "resultRows", bind })` on the
|
|
80
|
+
calling thread; the `Db` methods are `async` only to match the interface.
|
|
81
|
+
Long queries block the thread they run on.
|
|
82
|
+
- **Under Node.js** the module imports, but `newBrowserSqliteDb()` aborts with
|
|
83
|
+
`ENOENT ... '/sqlite3.wasm'`. Use `@statewalker/db-sqlite-node` there.
|
|
84
|
+
- **Dependencies:** `@libsql/libsql-wasm-experimental` (the engine),
|
|
85
|
+
`@statewalker/db-api` (the interface types).
|
|
27
86
|
|
|
28
|
-
##
|
|
87
|
+
## License
|
|
29
88
|
|
|
30
|
-
|
|
31
|
-
- `@statewalker/db-sqlite-node` — Node-side counterpart.
|
|
89
|
+
MIT
|
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":";;KAIY,mBAAmBA;;EAE7B;;;;;;;;;;;
|
|
1
|
+
{"version":3,"file":"index.d.mts","names":["DbOptions","Db"],"sources":["../src/browser-sqlite-db.ts"],"mappings":";;KAIY,mBAAmBA;;EAE7B;;;;;;;;;;;wBA0BoB,mBAAmB,UAAU,mBAAmB,QAAQC"}
|
package/dist/index.mjs
CHANGED
|
@@ -1,8 +1,13 @@
|
|
|
1
1
|
import sqlite3InitModule from "@libsql/libsql-wasm-experimental";
|
|
2
2
|
//#region src/browser-sqlite-db.ts
|
|
3
|
-
|
|
3
|
+
/** One engine instance per `wasmUrl`, started on first use. */
|
|
4
|
+
const sqlite3Promises = /* @__PURE__ */ new Map();
|
|
4
5
|
function getSqlite3(wasmUrl) {
|
|
5
|
-
|
|
6
|
+
let sqlite3Promise = sqlite3Promises.get(wasmUrl);
|
|
7
|
+
if (!sqlite3Promise) {
|
|
8
|
+
sqlite3Promise = sqlite3InitModule({ locateFile: (file) => file.endsWith(".wasm") ? wasmUrl : file });
|
|
9
|
+
sqlite3Promises.set(wasmUrl, sqlite3Promise);
|
|
10
|
+
}
|
|
6
11
|
return sqlite3Promise;
|
|
7
12
|
}
|
|
8
13
|
/**
|
package/dist/index.mjs.map
CHANGED
|
@@ -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\
|
|
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\n/** One engine instance per `wasmUrl`, started on first use. */\nconst sqlite3Promises = new Map<string, Promise<Sqlite3Static>>();\n\nfunction getSqlite3(wasmUrl: string): Promise<Sqlite3Static> {\n let sqlite3Promise = sqlite3Promises.get(wasmUrl);\n if (!sqlite3Promise) {\n sqlite3Promise = sqlite3InitModule({\n locateFile: (file: string) => (file.endsWith(\".wasm\") ? wasmUrl : file),\n });\n sqlite3Promises.set(wasmUrl, sqlite3Promise);\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":";;;AAUA,MAAM,kCAAkB,IAAI,IAAoC;AAEhE,SAAS,WAAW,SAAyC;CAC3D,IAAI,iBAAiB,gBAAgB,IAAI,OAAO;CAChD,IAAI,CAAC,gBAAgB;EACnB,iBAAiB,kBAAkB,EACjC,aAAa,SAAkB,KAAK,SAAS,OAAO,IAAI,UAAU,KACpE,CAAC;EACD,gBAAgB,IAAI,SAAS,cAAc;CAC7C;CACA,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
CHANGED
|
@@ -1,10 +1,13 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@statewalker/db-sqlite-browser",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.4",
|
|
4
4
|
"private": false,
|
|
5
5
|
"type": "module",
|
|
6
6
|
"description": "libSQL/SQLite WASM driver for @statewalker/db-api, targeting browser environments.",
|
|
7
|
-
"
|
|
7
|
+
"bugs": {
|
|
8
|
+
"url": "https://github.com/statewalker/statewalker-db/issues"
|
|
9
|
+
},
|
|
10
|
+
"homepage": "https://github.com/statewalker/statewalker-db/tree/main/packages/db-sqlite-browser#readme",
|
|
8
11
|
"author": {
|
|
9
12
|
"name": "Mikhail Kotelnikov",
|
|
10
13
|
"email": "mikhail.kotelnikov@gmail.com"
|
|
@@ -12,7 +15,8 @@
|
|
|
12
15
|
"license": "MIT",
|
|
13
16
|
"repository": {
|
|
14
17
|
"type": "git",
|
|
15
|
-
"url": "git+
|
|
18
|
+
"url": "git+https://github.com/statewalker/statewalker-db.git",
|
|
19
|
+
"directory": "packages/db-sqlite-browser"
|
|
16
20
|
},
|
|
17
21
|
"exports": {
|
|
18
22
|
".": {
|
|
@@ -27,7 +31,7 @@
|
|
|
27
31
|
],
|
|
28
32
|
"dependencies": {
|
|
29
33
|
"@libsql/libsql-wasm-experimental": "^0.0.3",
|
|
30
|
-
"@statewalker/db-api": "^0.1.
|
|
34
|
+
"@statewalker/db-api": "^0.1.3"
|
|
31
35
|
},
|
|
32
36
|
"devDependencies": {
|
|
33
37
|
"@playwright/test": "^1.63.0",
|
|
@@ -1,14 +1,34 @@
|
|
|
1
1
|
import { describe, expect, it } from "vitest";
|
|
2
|
+
import { newBrowserSqliteDb } from "./browser-sqlite-db.js";
|
|
2
3
|
|
|
3
4
|
/**
|
|
4
|
-
* Node-
|
|
5
|
+
* Node-side tests. The real browser coverage (shared conformance suite +
|
|
5
6
|
* FTS5/vector) lives in `browser-sqlite-db.browser.test.ts`, run via Vitest
|
|
6
|
-
* browser mode (`pnpm test:browser`)
|
|
7
|
-
*
|
|
7
|
+
* browser mode (`pnpm test:browser`). Under Node the engine's loader reads
|
|
8
|
+
* `wasmUrl` as a file path, which is enough to check how the engine is loaded.
|
|
8
9
|
*/
|
|
10
|
+
const wasmPath = decodeURIComponent(
|
|
11
|
+
new URL(
|
|
12
|
+
"../node_modules/@libsql/libsql-wasm-experimental/sqlite-wasm/jswasm/sqlite3.wasm",
|
|
13
|
+
import.meta.url,
|
|
14
|
+
).pathname,
|
|
15
|
+
);
|
|
16
|
+
|
|
9
17
|
describe("browser-sqlite-db module", () => {
|
|
10
18
|
it("exports newBrowserSqliteDb function", async () => {
|
|
11
19
|
const mod = await import("./browser-sqlite-db.js");
|
|
12
20
|
expect(typeof mod.newBrowserSqliteDb).toBe("function");
|
|
13
21
|
});
|
|
22
|
+
|
|
23
|
+
it("honors a different wasmUrl after an earlier call", async () => {
|
|
24
|
+
await expect(newBrowserSqliteDb({ wasmUrl: "/nonexistent/sqlite3.wasm" })).rejects.toThrow(
|
|
25
|
+
/ENOENT/,
|
|
26
|
+
);
|
|
27
|
+
const db = await newBrowserSqliteDb({ wasmUrl: wasmPath });
|
|
28
|
+
try {
|
|
29
|
+
expect(await db.query("SELECT 1 AS x")).toEqual([{ x: 1 }]);
|
|
30
|
+
} finally {
|
|
31
|
+
await db.close();
|
|
32
|
+
}
|
|
33
|
+
});
|
|
14
34
|
});
|
package/src/browser-sqlite-db.ts
CHANGED
|
@@ -7,13 +7,16 @@ export type BrowserDbOptions = DbOptions & {
|
|
|
7
7
|
wasmUrl?: string;
|
|
8
8
|
};
|
|
9
9
|
|
|
10
|
-
|
|
10
|
+
/** One engine instance per `wasmUrl`, started on first use. */
|
|
11
|
+
const sqlite3Promises = new Map<string, Promise<Sqlite3Static>>();
|
|
11
12
|
|
|
12
13
|
function getSqlite3(wasmUrl: string): Promise<Sqlite3Static> {
|
|
14
|
+
let sqlite3Promise = sqlite3Promises.get(wasmUrl);
|
|
13
15
|
if (!sqlite3Promise) {
|
|
14
16
|
sqlite3Promise = sqlite3InitModule({
|
|
15
17
|
locateFile: (file: string) => (file.endsWith(".wasm") ? wasmUrl : file),
|
|
16
18
|
});
|
|
19
|
+
sqlite3Promises.set(wasmUrl, sqlite3Promise);
|
|
17
20
|
}
|
|
18
21
|
return sqlite3Promise;
|
|
19
22
|
}
|