@statewalker/db-sqlite-browser 0.1.1 → 0.1.3

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
@@ -1,31 +1,88 @@
1
1
  # @statewalker/db-sqlite-browser
2
2
 
3
- libSQL/SQLite WASM driver implementing `@statewalker/db-api` for browser environments,
4
- backed by `@libsql/libsql-wasm-experimental` (FTS5 + vector search compiled to WebAssembly).
3
+ ## What it is
5
4
 
6
- ## Installation
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
- ## Usage
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
- // In-memory (omit `path`) or file-backed; `wasmUrl` locates sqlite3.wasm (default "/sqlite3.wasm").
18
- const db = await newBrowserSqliteDb({ path: "local.db" });
19
- await db.exec("CREATE TABLE t (x INTEGER)");
20
- await db.query("SELECT * FROM t");
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
- ## API
69
+ ## Internals
24
70
 
25
- - `newBrowserSqliteDb(options?)` — initializes the libSQL-WASM engine and returns a `Db`.
26
- `options.path` selects file-backed vs in-memory; `options.wasmUrl` locates the `sqlite3.wasm` asset.
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).
27
85
 
28
- ## Related
86
+ ## License
29
87
 
30
- - `@statewalker/db-api` — interface contract.
31
- - `@statewalker/db-sqlite-node` — Node-side counterpart.
88
+ MIT
package/dist/index.d.mts CHANGED
@@ -13,7 +13,7 @@ type BrowserDbOptions = DbOptions$1 & {
13
13
  * @param options.path File path for persistent storage. Omit for in-memory.
14
14
  * @param options.wasmUrl URL to the sqlite3.wasm file. Defaults to "/sqlite3.wasm".
15
15
  */
16
- declare function newBrowserSqliteDb(options?: BrowserDbOptions): Promise<Db$1>;
16
+ export declare function newBrowserSqliteDb(options?: BrowserDbOptions): Promise<Db$1>;
17
17
  //#endregion
18
- export { type BrowserDbOptions, type Db, type DbEntry, type DbOptions, newBrowserSqliteDb };
18
+ export type { BrowserDbOptions, Db, DbEntry, DbOptions };
19
19
  //# sourceMappingURL=index.d.mts.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.mts","names":[],"sources":["../src/browser-sqlite-db.ts"],"mappings":";;KAIY,mBAAmB;;EAE7B;;;;;;;;;;;iBAuBoB,mBAAmB,UAAU,mBAAmB,QAAQ"}
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"}
package/package.json CHANGED
@@ -1,10 +1,13 @@
1
1
  {
2
2
  "name": "@statewalker/db-sqlite-browser",
3
- "version": "0.1.1",
3
+ "version": "0.1.3",
4
4
  "private": false,
5
5
  "type": "module",
6
6
  "description": "libSQL/SQLite WASM driver for @statewalker/db-api, targeting browser environments.",
7
- "homepage": "https://github.com/statewalker/statewalker-db",
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,10 +15,15 @@
12
15
  "license": "MIT",
13
16
  "repository": {
14
17
  "type": "git",
15
- "url": "git+ssh://git@github.com/statewalker/statewalker-db.git"
18
+ "url": "git+https://github.com/statewalker/statewalker-db.git",
19
+ "directory": "packages/db-sqlite-browser"
16
20
  },
17
21
  "exports": {
18
- ".": "./src/index.ts"
22
+ ".": {
23
+ "source": "./src/index.ts",
24
+ "types": "./dist/index.d.mts",
25
+ "import": "./dist/index.mjs"
26
+ }
19
27
  },
20
28
  "files": [
21
29
  "dist",
@@ -23,18 +31,18 @@
23
31
  ],
24
32
  "dependencies": {
25
33
  "@libsql/libsql-wasm-experimental": "^0.0.3",
26
- "@statewalker/db-api": "0.1.1"
34
+ "@statewalker/db-api": "^0.1.3"
27
35
  },
28
36
  "devDependencies": {
29
- "@playwright/test": "^1.62.1",
30
- "@vitest/browser": "^4.1.10",
31
- "@vitest/browser-playwright": "^4.1.10",
32
- "playwright": "^1.62.1",
37
+ "@playwright/test": "^1.63.0",
38
+ "@vitest/browser": "^5.0.3",
39
+ "@vitest/browser-playwright": "^5.0.3",
40
+ "playwright": "^1.63.0",
33
41
  "rimraf": "^6.1.3",
34
- "tsdown": "^0.22.14",
42
+ "tsdown": "^0.23.0",
35
43
  "typescript": "^7.0.2",
36
- "vitest": "^4.1.10",
37
- "@statewalker/db-tests": "0.1.1"
44
+ "vitest": "^5.0.3",
45
+ "@statewalker/db-tests": "^0.1.1"
38
46
  },
39
47
  "sideEffects": false,
40
48
  "publishConfig": {