@statewalker/db-duckdb-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 +89 -11
- package/dist/index.d.mts +2 -2
- package/dist/index.d.mts.map +1 -1
- package/package.json +20 -12
package/README.md
CHANGED
|
@@ -1,27 +1,105 @@
|
|
|
1
1
|
# @statewalker/db-duckdb-browser
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
## What it is
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
A DuckDB driver for the browser that implements `Db` from
|
|
6
|
+
`@statewalker/db-api`. It runs DuckDB WASM (`@duckdb/duckdb-wasm`) in a Web
|
|
7
|
+
Worker. The database lives in memory, or in an OPFS file that survives page
|
|
8
|
+
reloads.
|
|
9
|
+
|
|
10
|
+
## Why it exists
|
|
11
|
+
|
|
12
|
+
DuckDB WASM has its own asynchronous API built around Arrow tables, worker
|
|
13
|
+
setup and bundle selection. This package hides that behind the four `Db`
|
|
14
|
+
methods and returns rows as plain objects, so the same code runs on this
|
|
15
|
+
driver and on `@statewalker/db-duckdb-node`.
|
|
16
|
+
|
|
17
|
+
## How to use
|
|
6
18
|
|
|
7
19
|
```sh
|
|
8
20
|
pnpm add @statewalker/db-duckdb-browser
|
|
9
21
|
```
|
|
10
22
|
|
|
11
|
-
|
|
23
|
+
| Import | Gives | Environment |
|
|
24
|
+
| --- | --- | --- |
|
|
25
|
+
| `@statewalker/db-duckdb-browser` | `newBrowserDuckDb`, type `BrowserDuckDbOptions`; types `Db`, `DbEntry`, `DbOptions` re-exported from `@statewalker/db-api` | browser (needs `Worker`) |
|
|
26
|
+
|
|
27
|
+
`newBrowserDuckDb(options?)` returns `Promise<Db>`.
|
|
28
|
+
|
|
29
|
+
- `options.path`: an OPFS path such as `opfs://app.duckdb`. Omit it for an
|
|
30
|
+
in-memory database.
|
|
31
|
+
- `options.bundles`: same-origin `DuckDBBundles` URLs. Required for OPFS.
|
|
32
|
+
Without it, the bundle is loaded from jsDelivr.
|
|
33
|
+
|
|
34
|
+
The returned `Db` implements `query`, `exec`, `flush` and `close`. Placeholders
|
|
35
|
+
are DuckDB's (`$1`, `$2`, ...).
|
|
36
|
+
|
|
37
|
+
## Examples
|
|
38
|
+
|
|
39
|
+
In memory, bundle from jsDelivr:
|
|
40
|
+
|
|
41
|
+
```ts
|
|
42
|
+
import { newBrowserDuckDb } from "@statewalker/db-duckdb-browser";
|
|
43
|
+
|
|
44
|
+
const db = await newBrowserDuckDb();
|
|
45
|
+
await db.exec("CREATE TABLE t (x INTEGER)");
|
|
46
|
+
await db.exec("INSERT INTO t VALUES (1), (2)");
|
|
47
|
+
const rows = await db.query<{ x: number }>("SELECT x FROM t WHERE x > $1", [1]);
|
|
48
|
+
await db.close();
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
Persistent on OPFS, with bundles served by Vite from your own origin (add
|
|
52
|
+
`@duckdb/duckdb-wasm` to your dependencies to import its files):
|
|
12
53
|
|
|
13
54
|
```ts
|
|
14
|
-
import {
|
|
55
|
+
import { newBrowserDuckDb } from "@statewalker/db-duckdb-browser";
|
|
56
|
+
import mvpWasm from "@duckdb/duckdb-wasm/dist/duckdb-mvp.wasm?url";
|
|
57
|
+
import mvpWorker from "@duckdb/duckdb-wasm/dist/duckdb-browser-mvp.worker.js?url";
|
|
58
|
+
import ehWasm from "@duckdb/duckdb-wasm/dist/duckdb-eh.wasm?url";
|
|
59
|
+
import ehWorker from "@duckdb/duckdb-wasm/dist/duckdb-browser-eh.worker.js?url";
|
|
15
60
|
|
|
16
|
-
const db = await
|
|
17
|
-
|
|
61
|
+
const db = await newBrowserDuckDb({
|
|
62
|
+
path: "opfs://app.duckdb",
|
|
63
|
+
bundles: {
|
|
64
|
+
mvp: { mainModule: mvpWasm, mainWorker: mvpWorker },
|
|
65
|
+
eh: { mainModule: ehWasm, mainWorker: ehWorker },
|
|
66
|
+
},
|
|
67
|
+
});
|
|
68
|
+
await db.exec("CREATE TABLE IF NOT EXISTS notes (id INTEGER, body VARCHAR)");
|
|
69
|
+
await db.exec("INSERT INTO notes VALUES (1, 'hello')");
|
|
70
|
+
await db.flush?.(); // CHECKPOINT: without it the insert can be lost on reload
|
|
18
71
|
```
|
|
19
72
|
|
|
20
|
-
##
|
|
73
|
+
## Internals
|
|
74
|
+
|
|
75
|
+
```
|
|
76
|
+
page Web Worker
|
|
77
|
+
newBrowserDuckDb() --- AsyncDuckDB ---> DuckDB WASM ---> OPFS file (optional)
|
|
78
|
+
query() <-- Arrow table --> plain objects
|
|
79
|
+
```
|
|
21
80
|
|
|
22
|
-
-
|
|
81
|
+
- **Same-origin worker for OPFS.** OPFS file I/O works only in a same-origin
|
|
82
|
+
worker. With `bundles`, the worker is created directly from your URL. Without
|
|
83
|
+
them, the jsDelivr worker is cross-origin and is started through a Blob that
|
|
84
|
+
calls `importScripts`; that worker crashes on OPFS file I/O, so use it for
|
|
85
|
+
in-memory databases only.
|
|
86
|
+
- **`flush` runs `CHECKPOINT`.** DuckDB WASM writes the OPFS database file only
|
|
87
|
+
on `CHECKPOINT`. Writes not yet checkpointed can be lost on an abrupt
|
|
88
|
+
teardown such as a page reload. On an in-memory database `flush` does
|
|
89
|
+
nothing.
|
|
90
|
+
- **Silent fallback to memory.** If `options.path` is set but opening it
|
|
91
|
+
throws, or `navigator.storage` is missing, the driver continues with an
|
|
92
|
+
in-memory database and raises no error. The symptom is data that is gone
|
|
93
|
+
after a reload.
|
|
94
|
+
- **Rows.** Query results are Arrow tables; the driver copies each row's
|
|
95
|
+
fields into a plain object. Calls with parameters go through
|
|
96
|
+
`conn.prepare(sql)` and `stmt.query(...params)`; calls without parameters use
|
|
97
|
+
`conn.query(sql)`.
|
|
98
|
+
- **Under Node.js** the module imports, but `newBrowserDuckDb()` rejects with
|
|
99
|
+
`Worker is not defined`. Use `@statewalker/db-duckdb-node` there.
|
|
100
|
+
- **Dependencies:** `@duckdb/duckdb-wasm` (the engine), `@statewalker/db-api`
|
|
101
|
+
(the interface types).
|
|
23
102
|
|
|
24
|
-
##
|
|
103
|
+
## License
|
|
25
104
|
|
|
26
|
-
|
|
27
|
-
- `@statewalker/db-duckdb-node` — Node-side counterpart.
|
|
105
|
+
MIT
|
package/dist/index.d.mts
CHANGED
|
@@ -22,7 +22,7 @@ interface BrowserDuckDbOptions extends DbOptions$1 {
|
|
|
22
22
|
* @param options.path `opfs://` path for persistent storage. Omit for in-memory.
|
|
23
23
|
* @param options.bundles Same-origin bundle URLs (required for OPFS).
|
|
24
24
|
*/
|
|
25
|
-
declare function newBrowserDuckDb(options?: BrowserDuckDbOptions): Promise<Db$1>;
|
|
25
|
+
export declare function newBrowserDuckDb(options?: BrowserDuckDbOptions): Promise<Db$1>;
|
|
26
26
|
//#endregion
|
|
27
|
-
export {
|
|
27
|
+
export type { BrowserDuckDbOptions, Db, DbEntry, DbOptions };
|
|
28
28
|
//# sourceMappingURL=index.d.mts.map
|
package/dist/index.d.mts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.mts","names":[],"sources":["../src/browser-duckdb.ts"],"mappings":";;;;UAoBiB,
|
|
1
|
+
{"version":3,"file":"index.d.mts","names":["DbOptions","Db"],"sources":["../src/browser-duckdb.ts"],"mappings":";;;;UAoBiB,6BAA6BA;;;;;;;;EAQ5C,UAAU,OAAO;;;;;;;;;;;;wBAaG,iBAAiB,UAAU,uBAAuB,QAAQC"}
|
package/package.json
CHANGED
|
@@ -1,10 +1,13 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@statewalker/db-duckdb-browser",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.3",
|
|
4
4
|
"private": false,
|
|
5
5
|
"type": "module",
|
|
6
6
|
"description": "DuckDB 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-duckdb-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+
|
|
18
|
+
"url": "git+https://github.com/statewalker/statewalker-db.git",
|
|
19
|
+
"directory": "packages/db-duckdb-browser"
|
|
16
20
|
},
|
|
17
21
|
"exports": {
|
|
18
|
-
".":
|
|
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
|
"@duckdb/duckdb-wasm": "^1.33.1-dev57.0",
|
|
26
|
-
"@statewalker/db-api": "0.1.
|
|
34
|
+
"@statewalker/db-api": "^0.1.3"
|
|
27
35
|
},
|
|
28
36
|
"devDependencies": {
|
|
29
|
-
"@playwright/test": "^1.
|
|
30
|
-
"@vitest/browser": "^
|
|
31
|
-
"@vitest/browser-playwright": "^
|
|
32
|
-
"playwright": "^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.
|
|
42
|
+
"tsdown": "^0.23.0",
|
|
35
43
|
"typescript": "^7.0.2",
|
|
36
|
-
"vitest": "^
|
|
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": {
|