@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 CHANGED
@@ -1,27 +1,105 @@
1
1
  # @statewalker/db-duckdb-browser
2
2
 
3
- DuckDB WASM driver implementing `@statewalker/db-api` for browser environments.
3
+ ## What it is
4
4
 
5
- ## Installation
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
- ## Usage
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 { createDuckDbBrowserClient } from "@statewalker/db-duckdb-browser";
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 createDuckDbBrowserClient();
17
- await db.execute("CREATE TABLE t (x INTEGER)");
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
- ## API
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
- - `createDuckDbBrowserClient(options?)` — spins up an in-browser DuckDB WASM instance and returns a `DbClient`.
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
- ## Related
103
+ ## License
25
104
 
26
- - `@statewalker/db-api` — interface contract.
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 { type BrowserDuckDbOptions, type Db, type DbEntry, type DbOptions, newBrowserDuckDb };
27
+ export type { BrowserDuckDbOptions, Db, DbEntry, DbOptions };
28
28
  //# sourceMappingURL=index.d.mts.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.mts","names":[],"sources":["../src/browser-duckdb.ts"],"mappings":";;;;UAoBiB,6BAA6B;;;;;;;;EAQ5C,UAAU,OAAO;;;;;;;;;;;;iBAaG,iBAAiB,UAAU,uBAAuB,QAAQ"}
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.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
- "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-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+ssh://git@github.com/statewalker/statewalker-db.git"
18
+ "url": "git+https://github.com/statewalker/statewalker-db.git",
19
+ "directory": "packages/db-duckdb-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
  "@duckdb/duckdb-wasm": "^1.33.1-dev57.0",
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": {