@statewalker/db-duckdb-browser 0.1.7 → 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 +12 -8
- package/dist/index.d.mts +5 -0
- package/dist/index.d.mts.map +1 -1
- package/dist/index.mjs +9 -3
- package/dist/index.mjs.map +1 -1
- package/package.json +4 -3
- package/src/browser-duckdb.ts +40 -29
package/README.md
CHANGED
|
@@ -7,11 +7,6 @@ A DuckDB driver for the browser that implements `Db` from
|
|
|
7
7
|
Worker. The database lives in memory, or in an OPFS file that survives page
|
|
8
8
|
reloads.
|
|
9
9
|
|
|
10
|
-
> **Known issue:** with `@duckdb/duckdb-wasm` 1.33.1-dev57.0, a new OPFS database is not
|
|
11
|
-
> actually written to OPFS, so it does not survive a reopen
|
|
12
|
-
> ([#74](https://github.com/statewalker/statewalker-db/issues/74)). The persistence tests in
|
|
13
|
-
> `src/opfs-persistence.browser.test.ts` are marked as expected failures until that is fixed.
|
|
14
|
-
|
|
15
10
|
## Why it exists
|
|
16
11
|
|
|
17
12
|
DuckDB WASM has its own asynchronous API built around Arrow tables, worker
|
|
@@ -49,7 +44,7 @@ Rows come back with the same JS values as `@statewalker/db-duckdb-node`:
|
|
|
49
44
|
| DuckDB type | JS value |
|
|
50
45
|
| --- | --- |
|
|
51
46
|
| `DECIMAL` | `number` (scaled; `1.25::DECIMAL(10,2)` is `1.25`) |
|
|
52
|
-
| `BIGINT`, `UBIGINT`, `HUGEINT`, `TIME` | `bigint` |
|
|
47
|
+
| `BIGINT`, `UBIGINT`, `HUGEINT`, `TIME` | `number` within ±(2^53 - 1), `bigint` beyond |
|
|
53
48
|
| `INTEGER`, `DOUBLE`, ... | `number` |
|
|
54
49
|
| `DATE`, `TIMESTAMP`, `TIMESTAMPTZ` | `Date` |
|
|
55
50
|
| `LIST`, fixed-size `ARRAY` | array, converted recursively |
|
|
@@ -60,7 +55,8 @@ Rows come back with the same JS values as `@statewalker/db-duckdb-node`:
|
|
|
60
55
|
`INTERVAL` is returned as duckdb-wasm's Arrow layer decodes it and does not
|
|
61
56
|
match the node driver; cast it in SQL (for example to `VARCHAR`) if you need
|
|
62
57
|
it. A `HUGEINT` and a `DECIMAL(38,0)` look the same in Arrow, so both come
|
|
63
|
-
back as `bigint
|
|
58
|
+
back as integers (`number` when safe, `bigint` beyond). The integer rule
|
|
59
|
+
applies inside lists, structs and maps too.
|
|
64
60
|
|
|
65
61
|
### Parameter limits
|
|
66
62
|
|
|
@@ -138,6 +134,13 @@ await db.flush?.(); // CHECKPOINT: without it the insert can be lost on reload
|
|
|
138
134
|
the path or connecting fails, the engine and its worker are terminated and
|
|
139
135
|
the jsDelivr Blob URL is revoked before the call rejects with the original
|
|
140
136
|
error (`src/start-duckdb.ts`).
|
|
137
|
+
- **One call at a time.** The `Db` is built by `newSerialisedDb` from
|
|
138
|
+
`@statewalker/db-sqlite` (the lifecycle every driver shares): calls,
|
|
139
|
+
`flush` included, run in call order; `close()` waits for the calls made
|
|
140
|
+
before it, then closes the connection and terminates the engine and its
|
|
141
|
+
worker; later calls reject with `db-duckdb-browser: the database is closed`;
|
|
142
|
+
a second `close()` is a no-op. Terminating the worker under a pending query
|
|
143
|
+
used to leave that query unsettled forever.
|
|
141
144
|
- **`flush` runs `CHECKPOINT`.** DuckDB WASM writes the OPFS database file only
|
|
142
145
|
on `CHECKPOINT`. Writes not yet checkpointed can be lost on an abrupt
|
|
143
146
|
teardown such as a page reload. On an in-memory database `flush` does
|
|
@@ -159,7 +162,8 @@ await db.flush?.(); // CHECKPOINT: without it the insert can be lost on reload
|
|
|
159
162
|
- **Under Node.js** the module imports, but `newBrowserDuckDb()` rejects with
|
|
160
163
|
`Worker is not defined`. Use `@statewalker/db-duckdb-node` there.
|
|
161
164
|
- **Dependencies:** `@duckdb/duckdb-wasm` (the engine), `@statewalker/db-api`
|
|
162
|
-
(the interface types)
|
|
165
|
+
(the interface types), `@statewalker/db-sqlite` (`newSerialisedDb`, the
|
|
166
|
+
shared lifecycle wrapper; no SQLite engine comes with it).
|
|
163
167
|
|
|
164
168
|
## License
|
|
165
169
|
|
package/dist/index.d.mts
CHANGED
|
@@ -22,6 +22,11 @@ interface BrowserDuckDbOptions extends DbOptions$1 {
|
|
|
22
22
|
* returned promise rejects; it never falls back to an in-memory database.
|
|
23
23
|
* `options.path` without `options.bundles` rejects before any worker starts.
|
|
24
24
|
*
|
|
25
|
+
* Calls run one at a time, in call order; `close()` waits for them, then
|
|
26
|
+
* terminates the worker; later calls reject with
|
|
27
|
+
* `db-duckdb-browser: the database is closed`. Integers come back as numbers
|
|
28
|
+
* when safe, as bigints beyond ±(2^53 - 1).
|
|
29
|
+
*
|
|
25
30
|
* @param options.path `opfs://` path for persistent storage. Omit for in-memory.
|
|
26
31
|
* @param options.bundles Same-origin bundle URLs (required for OPFS).
|
|
27
32
|
*/
|
package/dist/index.d.mts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.mts","names":["DbOptions","Db"],"sources":["../src/browser-duckdb.ts"],"mappings":";;;;
|
|
1
|
+
{"version":3,"file":"index.d.mts","names":["DbOptions","Db"],"sources":["../src/browser-duckdb.ts"],"mappings":";;;;UAQiB,6BAA6BA;;;;;;;;;EAS5C,UAAU,OAAO;;;;;;;;;;;;;;;;;;;wBAoBG,iBAAiB,UAAU,uBAAuB,QAAQC"}
|
package/dist/index.mjs
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import * as duckdb from "@duckdb/duckdb-wasm";
|
|
2
|
+
import { newSerialisedDb } from "@statewalker/db-sqlite";
|
|
2
3
|
//#region src/arrow-values.ts
|
|
3
4
|
/**
|
|
4
5
|
* Conversion of Arrow values (as duckdb-wasm returns them) into the plain JS
|
|
@@ -223,6 +224,11 @@ async function startDuckDb(bundle, options, env) {
|
|
|
223
224
|
* returned promise rejects; it never falls back to an in-memory database.
|
|
224
225
|
* `options.path` without `options.bundles` rejects before any worker starts.
|
|
225
226
|
*
|
|
227
|
+
* Calls run one at a time, in call order; `close()` waits for them, then
|
|
228
|
+
* terminates the worker; later calls reject with
|
|
229
|
+
* `db-duckdb-browser: the database is closed`. Integers come back as numbers
|
|
230
|
+
* when safe, as bigints beyond ±(2^53 - 1).
|
|
231
|
+
*
|
|
226
232
|
* @param options.path `opfs://` path for persistent storage. Omit for in-memory.
|
|
227
233
|
* @param options.bundles Same-origin bundle URLs (required for OPFS).
|
|
228
234
|
*/
|
|
@@ -235,9 +241,9 @@ async function newBrowserDuckDb(options) {
|
|
|
235
241
|
selfHosted: selfHosted !== void 0,
|
|
236
242
|
path
|
|
237
243
|
}, browserStartEnv);
|
|
238
|
-
return {
|
|
244
|
+
return newSerialisedDb({
|
|
239
245
|
async query(sql, params) {
|
|
240
|
-
if (params
|
|
246
|
+
if (params.length > 0) {
|
|
241
247
|
const bound = toDuckDbParams(params);
|
|
242
248
|
const stmt = await conn.prepare(sql);
|
|
243
249
|
try {
|
|
@@ -259,7 +265,7 @@ async function newBrowserDuckDb(options) {
|
|
|
259
265
|
await db.terminate();
|
|
260
266
|
worker.terminate();
|
|
261
267
|
}
|
|
262
|
-
};
|
|
268
|
+
}, { name: "db-duckdb-browser" });
|
|
263
269
|
}
|
|
264
270
|
//#endregion
|
|
265
271
|
export { newBrowserDuckDb };
|
package/dist/index.mjs.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.mjs","names":[],"sources":["../src/arrow-values.ts","../src/params.ts","../src/start-duckdb.ts","../src/browser-duckdb.ts"],"sourcesContent":["/**\n * Conversion of Arrow values (as duckdb-wasm returns them) into the plain JS\n * values `@statewalker/db-duckdb-node` returns for the same SQL types.\n *\n * Typed structurally so this module does not import `apache-arrow` at runtime.\n * Type ids are Arrow's `Type` enum (apache-arrow 17, the version duckdb-wasm\n * depends on).\n */\n\nconst TypeId = {\n Dictionary: -1,\n Decimal: 7,\n Date: 8,\n Timestamp: 10,\n List: 12,\n Struct: 13,\n FixedSizeList: 16,\n Map: 17,\n} as const;\n\n/** Arrow `TimeUnit`. */\nconst TimeUnit = { SECOND: 0, MILLISECOND: 1, MICROSECOND: 2, NANOSECOND: 3 } as const;\n\n/** The parts of an Arrow `Field` this module reads. */\nexport interface ArrowFieldLike {\n name: string;\n type: ArrowTypeLike;\n}\n\n/** The parts of an Arrow `DataType` this module reads. */\nexport interface ArrowTypeLike {\n typeId: number;\n scale?: number;\n precision?: number;\n unit?: number;\n children?: ArrowFieldLike[] | null;\n dictionary?: ArrowTypeLike;\n}\n\n/** The parts of an Arrow `Table` this module reads. */\nexport interface ArrowTableLike {\n schema: { fields: ArrowFieldLike[] };\n toArray(): ArrayLike<unknown>;\n}\n\n/**\n * Convert an Arrow table into plain row objects, converting each value by its\n * field's Arrow type ({@link arrowValueToJs}).\n */\nexport function arrowTableToObjects<T>(table: ArrowTableLike): T[] {\n const fields = table.schema.fields;\n return Array.from(table.toArray(), (row) => {\n const source = row as Record<string, unknown>;\n const obj: Record<string, unknown> = {};\n for (const field of fields) {\n obj[field.name] = arrowValueToJs(source[field.name], field.type);\n }\n return obj as T;\n });\n}\n\n/**\n * Convert one Arrow value into the plain JS value the node driver returns:\n *\n * - DECIMAL: a `number` scaled by the type's scale (HUGEINT, which DuckDB sends\n * as DECIMAL(38,0), becomes a `bigint`);\n * - DATE, TIMESTAMP: a `Date`;\n * - LIST, fixed-size ARRAY: an array, converted recursively;\n * - STRUCT: a plain object, converted recursively;\n * - MAP: an array of `{ key, value }`, converted recursively.\n *\n * Other values (numbers, `bigint` for BIGINT, strings, booleans, `Uint8Array`\n * for BLOB, `null`) are returned as they are.\n */\nexport function arrowValueToJs(value: unknown, type: ArrowTypeLike): unknown {\n if (value === null || value === undefined) return null;\n switch (type.typeId) {\n case TypeId.Decimal:\n return decimalToJs(value, type);\n case TypeId.Date:\n return typeof value === \"number\" ? new Date(value) : value;\n case TypeId.Timestamp:\n return timestampToDate(value, type.unit);\n case TypeId.List:\n case TypeId.FixedSizeList: {\n const childType = type.children?.[0]?.type;\n const items = Array.from(value as Iterable<unknown>);\n return childType ? items.map((item) => arrowValueToJs(item, childType)) : items;\n }\n case TypeId.Struct: {\n const row = value as Record<string, unknown>;\n const obj: Record<string, unknown> = {};\n for (const child of type.children ?? []) {\n obj[child.name] = arrowValueToJs(row[child.name], child.type);\n }\n return obj;\n }\n case TypeId.Map: {\n const entryFields = type.children?.[0]?.type.children ?? [];\n const keyType = entryFields[0]?.type;\n const valueType = entryFields[1]?.type;\n return Array.from(value as Iterable<[unknown, unknown]>, ([key, val]) => ({\n key: keyType ? arrowValueToJs(key, keyType) : key,\n value: valueType ? arrowValueToJs(val, valueType) : val,\n }));\n }\n case TypeId.Dictionary:\n return type.dictionary ? arrowValueToJs(value, type.dictionary) : value;\n default:\n return value;\n }\n}\n\n/**\n * Arrow decimals are unscaled integers (`String(v)` gives the digits). Insert\n * the decimal point by text and parse, so the result is the nearest double to\n * the exact decimal value.\n */\nfunction decimalToJs(value: unknown, type: ArrowTypeLike): number | bigint {\n const digits = String(value);\n const scale = type.scale ?? 0;\n if (scale === 0) {\n // DuckDB sends HUGEINT as DECIMAL(38,0); the node driver returns bigint.\n return type.precision === 38 ? BigInt(digits) : Number(digits);\n }\n const negative = digits.startsWith(\"-\");\n const abs = (negative ? digits.slice(1) : digits).padStart(scale + 1, \"0\");\n const text = `${abs.slice(0, abs.length - scale)}.${abs.slice(abs.length - scale)}`;\n return Number(negative ? `-${text}` : text);\n}\n\nfunction timestampToDate(value: unknown, unit: number | undefined): unknown {\n if (typeof value === \"number\") return new Date(value); // apache-arrow gives epoch ms\n if (typeof value === \"bigint\") {\n switch (unit) {\n case TimeUnit.SECOND:\n return new Date(Number(value) * 1000);\n case TimeUnit.MICROSECOND:\n return new Date(Number(value / 1000n));\n case TimeUnit.NANOSECOND:\n return new Date(Number(value / 1000000n));\n default:\n return new Date(Number(value));\n }\n }\n return value;\n}\n","/** A value duckdb-wasm's prepared statements can bind (they JSON-encode params). */\nexport type DuckDbWasmParam = string | number | boolean | null;\n\n/**\n * Convert `Db.query` params into values duckdb-wasm can bind.\n *\n * duckdb-wasm passes prepared-statement params through `JSON.stringify`, so\n * only strings, finite numbers, booleans and `null` survive. This maps:\n *\n * - `bigint` to its exact decimal string; DuckDB casts it to the column type\n * where the context fixes one (`WHERE id = $1`, `INSERT ... VALUES ($1)`),\n * elsewhere cast it in SQL (`$1::BIGINT`);\n * - `Date` to its ISO 8601 string, which DuckDB casts to TIMESTAMP the same way;\n * - `undefined` to `null`.\n *\n * Anything else (`Uint8Array` and other binary data, arrays, plain objects,\n * `NaN`, `Infinity`, symbols, functions, invalid dates) throws a `TypeError`\n * naming the parameter and its type instead of failing inside duckdb-wasm or\n * binding the wrong value.\n */\nexport function toDuckDbParams(params: readonly unknown[]): DuckDbWasmParam[] {\n return params.map(toDuckDbParam);\n}\n\nfunction toDuckDbParam(value: unknown, index: number): DuckDbWasmParam {\n switch (typeof value) {\n case \"string\":\n case \"boolean\":\n return value;\n case \"undefined\":\n return null;\n case \"bigint\":\n return value.toString();\n case \"number\":\n if (Number.isFinite(value)) return value;\n throw unsupported(index, String(value));\n case \"object\": {\n if (value === null) return null;\n if (value instanceof Date) {\n if (Number.isNaN(value.getTime())) throw unsupported(index, \"invalid Date\");\n return value.toISOString();\n }\n if (Array.isArray(value)) throw unsupported(index, \"array\");\n if (ArrayBuffer.isView(value) || value instanceof ArrayBuffer) {\n throw unsupported(index, value.constructor.name);\n }\n throw unsupported(index, `object (${value.constructor?.name ?? \"null prototype\"})`);\n }\n default:\n throw unsupported(index, typeof value);\n }\n}\n\nfunction unsupported(index: number, type: string): TypeError {\n return new TypeError(\n `db-duckdb-browser: cannot bind parameter $${index + 1} of type ${type}; ` +\n \"duckdb-wasm binds only string, finite number, boolean, null, bigint and Date\",\n );\n}\n","import * as duckdb from \"@duckdb/duckdb-wasm\";\n\n/**\n * What {@link startDuckDb} needs from the page. The browser defaults are\n * {@link browserStartEnv}; tests pass fakes to drive failures.\n */\nexport interface DuckDbStartEnv {\n newWorker(url: string): Worker;\n newDb(worker: Worker): duckdb.AsyncDuckDB;\n createObjectURL(blob: Blob): string;\n revokeObjectURL(url: string): void;\n}\n\n/** A started engine: its worker, the engine and one open connection. */\nexport interface StartedDuckDb {\n worker: Worker;\n db: duckdb.AsyncDuckDB;\n conn: duckdb.AsyncDuckDBConnection;\n}\n\n/** The real browser environment: a Web Worker and the page's `URL`. */\nexport const browserStartEnv: DuckDbStartEnv = {\n newWorker: (url) => new Worker(url),\n newDb: (worker) => new duckdb.AsyncDuckDB(new duckdb.ConsoleLogger(), worker),\n createObjectURL: (blob) => URL.createObjectURL(blob),\n revokeObjectURL: (url) => URL.revokeObjectURL(url),\n};\n\n/**\n * Start a worker, instantiate DuckDB in it, open `path` if given, and connect.\n *\n * If any step fails, including the worker script failing to load, the engine\n * and its worker are terminated before the error is rethrown, so a failed start leaves no worker running. The Blob URL\n * of the jsDelivr shim is revoked whether the start succeeds or fails.\n */\nexport async function startDuckDb(\n bundle: duckdb.DuckDBBundle,\n options: { selfHosted: boolean; path?: string },\n env: DuckDbStartEnv,\n): Promise<StartedDuckDb> {\n const { selfHosted, path } = options;\n let blobUrl: string | undefined;\n let worker: Worker | undefined;\n let db: duckdb.AsyncDuckDB | undefined;\n // duckdb-wasm only logs a worker error (a script that fails to load) and drops the pending\n // request, so `instantiate` would never settle: turn the error event into a rejection.\n let onWorkerError: ((event: ErrorEvent) => void) | undefined;\n const workerFailed = new Promise<never>((_, reject) => {\n onWorkerError = (event) =>\n reject(new Error(`DuckDB worker failed to load: ${event.message ?? \"unknown error\"}`));\n });\n workerFailed.catch(() => {}); // only observed through the race below\n try {\n // OPFS file I/O needs a same-origin worker. Self-hosted bundles give a\n // same-origin URL we load directly; the jsDelivr fallback is cross-origin\n // and must be wrapped in a Blob that `importScripts` it.\n if (selfHosted) {\n worker = env.newWorker(bundle.mainWorker as string);\n } else {\n blobUrl = env.createObjectURL(\n new Blob([`importScripts(\"${bundle.mainWorker ?? \"\"}\");`], {\n type: \"text/javascript\",\n }),\n );\n worker = env.newWorker(blobUrl);\n }\n worker.addEventListener(\"error\", onWorkerError as (event: ErrorEvent) => void);\n db = env.newDb(worker);\n await Promise.race([db.instantiate(bundle.mainModule, bundle.pthreadWorker), workerFailed]);\n if (path) {\n try {\n await db.open({ path, accessMode: duckdb.DuckDBAccessMode.READ_WRITE });\n } catch (error) {\n throw new Error(`Cannot open DuckDB database \"${path}\"`, { cause: error });\n }\n }\n const conn = await db.connect();\n return { worker, db, conn };\n } catch (error) {\n // Best effort: a failing teardown must not hide the start error.\n try {\n await db?.terminate();\n } catch {}\n worker?.terminate();\n throw error;\n } finally {\n worker?.removeEventListener(\"error\", onWorkerError as (event: ErrorEvent) => void);\n if (blobUrl) env.revokeObjectURL(blobUrl);\n }\n}\n","import * as duckdb from \"@duckdb/duckdb-wasm\";\nimport type { Db, DbEntry, DbOptions } from \"@statewalker/db-api\";\nimport { arrowTableToObjects } from \"./arrow-values.js\";\nimport { toDuckDbParams } from \"./params.js\";\nimport { browserStartEnv, startDuckDb } from \"./start-duckdb.js\";\n\n/** Browser-specific options for {@link newBrowserDuckDb}. */\nexport interface BrowserDuckDbOptions extends DbOptions {\n /**\n * Self-hosted DuckDB bundle URLs (served same-origin, e.g. via a bundler's\n * `?url` import). Passing these makes the factory spawn a **same-origin**\n * worker, which OPFS database persistence requires — a cross-origin worker\n * (the jsDelivr fallback, loaded via a Blob `importScripts` shim) crashes on\n * OPFS file I/O. Omit to load from jsDelivr (in-memory use only); a `path`\n * without `bundles` is rejected.\n */\n bundles?: duckdb.DuckDBBundles;\n}\n\n/**\n * Create a DuckDB-backed {@link Db} using WebAssembly in the browser.\n *\n * With `options.path` set to an `opfs://` URL **and** self-hosted\n * `options.bundles`, the database persists across reloads on OPFS. Without\n * `options.path` it runs in-memory. If `options.path` cannot be opened, the\n * returned promise rejects; it never falls back to an in-memory database.\n * `options.path` without `options.bundles` rejects before any worker starts.\n *\n * @param options.path `opfs://` path for persistent storage. Omit for in-memory.\n * @param options.bundles Same-origin bundle URLs (required for OPFS).\n */\nexport async function newBrowserDuckDb(options?: BrowserDuckDbOptions): Promise<Db> {\n const path = options?.path;\n const selfHosted = options?.bundles;\n if (path && !selfHosted) {\n // The jsDelivr worker is cross-origin and crashes on OPFS file I/O.\n throw new Error(\n `Cannot open DuckDB database \"${path}\": OPFS needs self-hosted \\`bundles\\` (a same-origin worker)`,\n );\n }\n if (path && (typeof navigator === \"undefined\" || !navigator.storage)) {\n throw new Error(`Cannot open DuckDB database \"${path}\": OPFS is unavailable`);\n }\n const bundle = await duckdb.selectBundle(selfHosted ?? duckdb.getJsDelivrBundles());\n const { worker, db, conn } = await startDuckDb(\n bundle,\n { selfHosted: selfHosted !== undefined, path },\n browserStartEnv,\n );\n\n return {\n async query<T = DbEntry>(sql: string, params?: unknown[]): Promise<T[]> {\n if (params && params.length > 0) {\n // Convert first: an unsupported param throws before a statement exists.\n const bound = toDuckDbParams(params);\n const stmt = await conn.prepare(sql);\n try {\n const result = await stmt.query(...bound);\n return arrowTableToObjects<T>(result);\n } finally {\n await stmt.close();\n }\n }\n const result = await conn.query(sql);\n return arrowTableToObjects<T>(result);\n },\n\n async exec(sql: string): Promise<void> {\n await conn.query(sql);\n },\n\n async flush(): Promise<void> {\n // CHECKPOINT writes the WAL into the OPFS database file so committed\n // changes survive a reload. Crucial for OPFS persistence.\n if (path) await conn.query(\"CHECKPOINT\");\n },\n\n async close(): Promise<void> {\n await conn.close();\n await db.terminate();\n worker.terminate();\n },\n };\n}\n"],"mappings":"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"}
|
|
1
|
+
{"version":3,"file":"index.mjs","names":[],"sources":["../src/arrow-values.ts","../src/params.ts","../src/start-duckdb.ts","../src/browser-duckdb.ts"],"sourcesContent":["/**\n * Conversion of Arrow values (as duckdb-wasm returns them) into the plain JS\n * values `@statewalker/db-duckdb-node` returns for the same SQL types.\n *\n * Typed structurally so this module does not import `apache-arrow` at runtime.\n * Type ids are Arrow's `Type` enum (apache-arrow 17, the version duckdb-wasm\n * depends on).\n */\n\nconst TypeId = {\n Dictionary: -1,\n Decimal: 7,\n Date: 8,\n Timestamp: 10,\n List: 12,\n Struct: 13,\n FixedSizeList: 16,\n Map: 17,\n} as const;\n\n/** Arrow `TimeUnit`. */\nconst TimeUnit = { SECOND: 0, MILLISECOND: 1, MICROSECOND: 2, NANOSECOND: 3 } as const;\n\n/** The parts of an Arrow `Field` this module reads. */\nexport interface ArrowFieldLike {\n name: string;\n type: ArrowTypeLike;\n}\n\n/** The parts of an Arrow `DataType` this module reads. */\nexport interface ArrowTypeLike {\n typeId: number;\n scale?: number;\n precision?: number;\n unit?: number;\n children?: ArrowFieldLike[] | null;\n dictionary?: ArrowTypeLike;\n}\n\n/** The parts of an Arrow `Table` this module reads. */\nexport interface ArrowTableLike {\n schema: { fields: ArrowFieldLike[] };\n toArray(): ArrayLike<unknown>;\n}\n\n/**\n * Convert an Arrow table into plain row objects, converting each value by its\n * field's Arrow type ({@link arrowValueToJs}).\n */\nexport function arrowTableToObjects<T>(table: ArrowTableLike): T[] {\n const fields = table.schema.fields;\n return Array.from(table.toArray(), (row) => {\n const source = row as Record<string, unknown>;\n const obj: Record<string, unknown> = {};\n for (const field of fields) {\n obj[field.name] = arrowValueToJs(source[field.name], field.type);\n }\n return obj as T;\n });\n}\n\n/**\n * Convert one Arrow value into the plain JS value the node driver returns:\n *\n * - DECIMAL: a `number` scaled by the type's scale (HUGEINT, which DuckDB sends\n * as DECIMAL(38,0), becomes a `bigint`);\n * - DATE, TIMESTAMP: a `Date`;\n * - LIST, fixed-size ARRAY: an array, converted recursively;\n * - STRUCT: a plain object, converted recursively;\n * - MAP: an array of `{ key, value }`, converted recursively.\n *\n * Other values (numbers, `bigint` for BIGINT, strings, booleans, `Uint8Array`\n * for BLOB, `null`) are returned as they are.\n */\nexport function arrowValueToJs(value: unknown, type: ArrowTypeLike): unknown {\n if (value === null || value === undefined) return null;\n switch (type.typeId) {\n case TypeId.Decimal:\n return decimalToJs(value, type);\n case TypeId.Date:\n return typeof value === \"number\" ? new Date(value) : value;\n case TypeId.Timestamp:\n return timestampToDate(value, type.unit);\n case TypeId.List:\n case TypeId.FixedSizeList: {\n const childType = type.children?.[0]?.type;\n const items = Array.from(value as Iterable<unknown>);\n return childType ? items.map((item) => arrowValueToJs(item, childType)) : items;\n }\n case TypeId.Struct: {\n const row = value as Record<string, unknown>;\n const obj: Record<string, unknown> = {};\n for (const child of type.children ?? []) {\n obj[child.name] = arrowValueToJs(row[child.name], child.type);\n }\n return obj;\n }\n case TypeId.Map: {\n const entryFields = type.children?.[0]?.type.children ?? [];\n const keyType = entryFields[0]?.type;\n const valueType = entryFields[1]?.type;\n return Array.from(value as Iterable<[unknown, unknown]>, ([key, val]) => ({\n key: keyType ? arrowValueToJs(key, keyType) : key,\n value: valueType ? arrowValueToJs(val, valueType) : val,\n }));\n }\n case TypeId.Dictionary:\n return type.dictionary ? arrowValueToJs(value, type.dictionary) : value;\n default:\n return value;\n }\n}\n\n/**\n * Arrow decimals are unscaled integers (`String(v)` gives the digits). Insert\n * the decimal point by text and parse, so the result is the nearest double to\n * the exact decimal value.\n */\nfunction decimalToJs(value: unknown, type: ArrowTypeLike): number | bigint {\n const digits = String(value);\n const scale = type.scale ?? 0;\n if (scale === 0) {\n // DuckDB sends HUGEINT as DECIMAL(38,0); the node driver returns bigint.\n return type.precision === 38 ? BigInt(digits) : Number(digits);\n }\n const negative = digits.startsWith(\"-\");\n const abs = (negative ? digits.slice(1) : digits).padStart(scale + 1, \"0\");\n const text = `${abs.slice(0, abs.length - scale)}.${abs.slice(abs.length - scale)}`;\n return Number(negative ? `-${text}` : text);\n}\n\nfunction timestampToDate(value: unknown, unit: number | undefined): unknown {\n if (typeof value === \"number\") return new Date(value); // apache-arrow gives epoch ms\n if (typeof value === \"bigint\") {\n switch (unit) {\n case TimeUnit.SECOND:\n return new Date(Number(value) * 1000);\n case TimeUnit.MICROSECOND:\n return new Date(Number(value / 1000n));\n case TimeUnit.NANOSECOND:\n return new Date(Number(value / 1000000n));\n default:\n return new Date(Number(value));\n }\n }\n return value;\n}\n","/** A value duckdb-wasm's prepared statements can bind (they JSON-encode params). */\nexport type DuckDbWasmParam = string | number | boolean | null;\n\n/**\n * Convert `Db.query` params into values duckdb-wasm can bind.\n *\n * duckdb-wasm passes prepared-statement params through `JSON.stringify`, so\n * only strings, finite numbers, booleans and `null` survive. This maps:\n *\n * - `bigint` to its exact decimal string; DuckDB casts it to the column type\n * where the context fixes one (`WHERE id = $1`, `INSERT ... VALUES ($1)`),\n * elsewhere cast it in SQL (`$1::BIGINT`);\n * - `Date` to its ISO 8601 string, which DuckDB casts to TIMESTAMP the same way;\n * - `undefined` to `null`.\n *\n * Anything else (`Uint8Array` and other binary data, arrays, plain objects,\n * `NaN`, `Infinity`, symbols, functions, invalid dates) throws a `TypeError`\n * naming the parameter and its type instead of failing inside duckdb-wasm or\n * binding the wrong value.\n */\nexport function toDuckDbParams(params: readonly unknown[]): DuckDbWasmParam[] {\n return params.map(toDuckDbParam);\n}\n\nfunction toDuckDbParam(value: unknown, index: number): DuckDbWasmParam {\n switch (typeof value) {\n case \"string\":\n case \"boolean\":\n return value;\n case \"undefined\":\n return null;\n case \"bigint\":\n return value.toString();\n case \"number\":\n if (Number.isFinite(value)) return value;\n throw unsupported(index, String(value));\n case \"object\": {\n if (value === null) return null;\n if (value instanceof Date) {\n if (Number.isNaN(value.getTime())) throw unsupported(index, \"invalid Date\");\n return value.toISOString();\n }\n if (Array.isArray(value)) throw unsupported(index, \"array\");\n if (ArrayBuffer.isView(value) || value instanceof ArrayBuffer) {\n throw unsupported(index, value.constructor.name);\n }\n throw unsupported(index, `object (${value.constructor?.name ?? \"null prototype\"})`);\n }\n default:\n throw unsupported(index, typeof value);\n }\n}\n\nfunction unsupported(index: number, type: string): TypeError {\n return new TypeError(\n `db-duckdb-browser: cannot bind parameter $${index + 1} of type ${type}; ` +\n \"duckdb-wasm binds only string, finite number, boolean, null, bigint and Date\",\n );\n}\n","import * as duckdb from \"@duckdb/duckdb-wasm\";\n\n/**\n * What {@link startDuckDb} needs from the page. The browser defaults are\n * {@link browserStartEnv}; tests pass fakes to drive failures.\n */\nexport interface DuckDbStartEnv {\n newWorker(url: string): Worker;\n newDb(worker: Worker): duckdb.AsyncDuckDB;\n createObjectURL(blob: Blob): string;\n revokeObjectURL(url: string): void;\n}\n\n/** A started engine: its worker, the engine and one open connection. */\nexport interface StartedDuckDb {\n worker: Worker;\n db: duckdb.AsyncDuckDB;\n conn: duckdb.AsyncDuckDBConnection;\n}\n\n/** The real browser environment: a Web Worker and the page's `URL`. */\nexport const browserStartEnv: DuckDbStartEnv = {\n newWorker: (url) => new Worker(url),\n newDb: (worker) => new duckdb.AsyncDuckDB(new duckdb.ConsoleLogger(), worker),\n createObjectURL: (blob) => URL.createObjectURL(blob),\n revokeObjectURL: (url) => URL.revokeObjectURL(url),\n};\n\n/**\n * Start a worker, instantiate DuckDB in it, open `path` if given, and connect.\n *\n * If any step fails, including the worker script failing to load, the engine\n * and its worker are terminated before the error is rethrown, so a failed start leaves no worker running. The Blob URL\n * of the jsDelivr shim is revoked whether the start succeeds or fails.\n */\nexport async function startDuckDb(\n bundle: duckdb.DuckDBBundle,\n options: { selfHosted: boolean; path?: string },\n env: DuckDbStartEnv,\n): Promise<StartedDuckDb> {\n const { selfHosted, path } = options;\n let blobUrl: string | undefined;\n let worker: Worker | undefined;\n let db: duckdb.AsyncDuckDB | undefined;\n // duckdb-wasm only logs a worker error (a script that fails to load) and drops the pending\n // request, so `instantiate` would never settle: turn the error event into a rejection.\n let onWorkerError: ((event: ErrorEvent) => void) | undefined;\n const workerFailed = new Promise<never>((_, reject) => {\n onWorkerError = (event) =>\n reject(new Error(`DuckDB worker failed to load: ${event.message ?? \"unknown error\"}`));\n });\n workerFailed.catch(() => {}); // only observed through the race below\n try {\n // OPFS file I/O needs a same-origin worker. Self-hosted bundles give a\n // same-origin URL we load directly; the jsDelivr fallback is cross-origin\n // and must be wrapped in a Blob that `importScripts` it.\n if (selfHosted) {\n worker = env.newWorker(bundle.mainWorker as string);\n } else {\n blobUrl = env.createObjectURL(\n new Blob([`importScripts(\"${bundle.mainWorker ?? \"\"}\");`], {\n type: \"text/javascript\",\n }),\n );\n worker = env.newWorker(blobUrl);\n }\n worker.addEventListener(\"error\", onWorkerError as (event: ErrorEvent) => void);\n db = env.newDb(worker);\n await Promise.race([db.instantiate(bundle.mainModule, bundle.pthreadWorker), workerFailed]);\n if (path) {\n try {\n await db.open({ path, accessMode: duckdb.DuckDBAccessMode.READ_WRITE });\n } catch (error) {\n throw new Error(`Cannot open DuckDB database \"${path}\"`, { cause: error });\n }\n }\n const conn = await db.connect();\n return { worker, db, conn };\n } catch (error) {\n // Best effort: a failing teardown must not hide the start error.\n try {\n await db?.terminate();\n } catch {}\n worker?.terminate();\n throw error;\n } finally {\n worker?.removeEventListener(\"error\", onWorkerError as (event: ErrorEvent) => void);\n if (blobUrl) env.revokeObjectURL(blobUrl);\n }\n}\n","import * as duckdb from \"@duckdb/duckdb-wasm\";\nimport type { Db, DbOptions } from \"@statewalker/db-api\";\nimport { newSerialisedDb } from \"@statewalker/db-sqlite\";\nimport { arrowTableToObjects } from \"./arrow-values.js\";\nimport { toDuckDbParams } from \"./params.js\";\nimport { browserStartEnv, startDuckDb } from \"./start-duckdb.js\";\n\n/** Browser-specific options for {@link newBrowserDuckDb}. */\nexport interface BrowserDuckDbOptions extends DbOptions {\n /**\n * Self-hosted DuckDB bundle URLs (served same-origin, e.g. via a bundler's\n * `?url` import). Passing these makes the factory spawn a **same-origin**\n * worker, which OPFS database persistence requires — a cross-origin worker\n * (the jsDelivr fallback, loaded via a Blob `importScripts` shim) crashes on\n * OPFS file I/O. Omit to load from jsDelivr (in-memory use only); a `path`\n * without `bundles` is rejected.\n */\n bundles?: duckdb.DuckDBBundles;\n}\n\n/**\n * Create a DuckDB-backed {@link Db} using WebAssembly in the browser.\n *\n * With `options.path` set to an `opfs://` URL **and** self-hosted\n * `options.bundles`, the database persists across reloads on OPFS. Without\n * `options.path` it runs in-memory. If `options.path` cannot be opened, the\n * returned promise rejects; it never falls back to an in-memory database.\n * `options.path` without `options.bundles` rejects before any worker starts.\n *\n * Calls run one at a time, in call order; `close()` waits for them, then\n * terminates the worker; later calls reject with\n * `db-duckdb-browser: the database is closed`. Integers come back as numbers\n * when safe, as bigints beyond ±(2^53 - 1).\n *\n * @param options.path `opfs://` path for persistent storage. Omit for in-memory.\n * @param options.bundles Same-origin bundle URLs (required for OPFS).\n */\nexport async function newBrowserDuckDb(options?: BrowserDuckDbOptions): Promise<Db> {\n const path = options?.path;\n const selfHosted = options?.bundles;\n if (path && !selfHosted) {\n // The jsDelivr worker is cross-origin and crashes on OPFS file I/O.\n throw new Error(\n `Cannot open DuckDB database \"${path}\": OPFS needs self-hosted \\`bundles\\` (a same-origin worker)`,\n );\n }\n if (path && (typeof navigator === \"undefined\" || !navigator.storage)) {\n throw new Error(`Cannot open DuckDB database \"${path}\": OPFS is unavailable`);\n }\n const bundle = await duckdb.selectBundle(selfHosted ?? duckdb.getJsDelivrBundles());\n const { worker, db, conn } = await startDuckDb(\n bundle,\n { selfHosted: selfHosted !== undefined, path },\n browserStartEnv,\n );\n\n return newSerialisedDb(\n {\n async query(sql, params) {\n if (params.length > 0) {\n // Convert first: an unsupported param throws before a statement exists.\n const bound = toDuckDbParams(params);\n const stmt = await conn.prepare(sql);\n try {\n const result = await stmt.query(...bound);\n return arrowTableToObjects<Record<string, unknown>>(result);\n } finally {\n await stmt.close();\n }\n }\n const result = await conn.query(sql);\n return arrowTableToObjects<Record<string, unknown>>(result);\n },\n\n async exec(sql) {\n await conn.query(sql);\n },\n\n async flush() {\n // CHECKPOINT writes the WAL into the OPFS database file so committed\n // changes survive a reload. Crucial for OPFS persistence.\n if (path) await conn.query(\"CHECKPOINT\");\n },\n\n // Runs after every earlier call has settled: terminating the worker\n // while a request is pending would leave that request unsettled.\n async close() {\n await conn.close();\n await db.terminate();\n worker.terminate();\n },\n },\n { name: \"db-duckdb-browser\" },\n );\n}\n"],"mappings":"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"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@statewalker/db-duckdb-browser",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.2.0",
|
|
4
4
|
"private": false,
|
|
5
5
|
"type": "module",
|
|
6
6
|
"description": "DuckDB WASM driver for @statewalker/db-api, targeting browser environments.",
|
|
@@ -33,8 +33,9 @@
|
|
|
33
33
|
"!src/**/test-wasm-node.ts"
|
|
34
34
|
],
|
|
35
35
|
"dependencies": {
|
|
36
|
-
"@duckdb/duckdb-wasm": "
|
|
37
|
-
"@statewalker/db-
|
|
36
|
+
"@duckdb/duckdb-wasm": "1.33.1-dev65.0",
|
|
37
|
+
"@statewalker/db-sqlite": "^0.1.3",
|
|
38
|
+
"@statewalker/db-api": "^0.1.7"
|
|
38
39
|
},
|
|
39
40
|
"devDependencies": {
|
|
40
41
|
"@playwright/test": "^1.63.0",
|
package/src/browser-duckdb.ts
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import * as duckdb from "@duckdb/duckdb-wasm";
|
|
2
|
-
import type { Db,
|
|
2
|
+
import type { Db, DbOptions } from "@statewalker/db-api";
|
|
3
|
+
import { newSerialisedDb } from "@statewalker/db-sqlite";
|
|
3
4
|
import { arrowTableToObjects } from "./arrow-values.js";
|
|
4
5
|
import { toDuckDbParams } from "./params.js";
|
|
5
6
|
import { browserStartEnv, startDuckDb } from "./start-duckdb.js";
|
|
@@ -26,6 +27,11 @@ export interface BrowserDuckDbOptions extends DbOptions {
|
|
|
26
27
|
* returned promise rejects; it never falls back to an in-memory database.
|
|
27
28
|
* `options.path` without `options.bundles` rejects before any worker starts.
|
|
28
29
|
*
|
|
30
|
+
* Calls run one at a time, in call order; `close()` waits for them, then
|
|
31
|
+
* terminates the worker; later calls reject with
|
|
32
|
+
* `db-duckdb-browser: the database is closed`. Integers come back as numbers
|
|
33
|
+
* when safe, as bigints beyond ±(2^53 - 1).
|
|
34
|
+
*
|
|
29
35
|
* @param options.path `opfs://` path for persistent storage. Omit for in-memory.
|
|
30
36
|
* @param options.bundles Same-origin bundle URLs (required for OPFS).
|
|
31
37
|
*/
|
|
@@ -48,37 +54,42 @@ export async function newBrowserDuckDb(options?: BrowserDuckDbOptions): Promise<
|
|
|
48
54
|
browserStartEnv,
|
|
49
55
|
);
|
|
50
56
|
|
|
51
|
-
return
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
57
|
+
return newSerialisedDb(
|
|
58
|
+
{
|
|
59
|
+
async query(sql, params) {
|
|
60
|
+
if (params.length > 0) {
|
|
61
|
+
// Convert first: an unsupported param throws before a statement exists.
|
|
62
|
+
const bound = toDuckDbParams(params);
|
|
63
|
+
const stmt = await conn.prepare(sql);
|
|
64
|
+
try {
|
|
65
|
+
const result = await stmt.query(...bound);
|
|
66
|
+
return arrowTableToObjects<Record<string, unknown>>(result);
|
|
67
|
+
} finally {
|
|
68
|
+
await stmt.close();
|
|
69
|
+
}
|
|
62
70
|
}
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
},
|
|
71
|
+
const result = await conn.query(sql);
|
|
72
|
+
return arrowTableToObjects<Record<string, unknown>>(result);
|
|
73
|
+
},
|
|
67
74
|
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
75
|
+
async exec(sql) {
|
|
76
|
+
await conn.query(sql);
|
|
77
|
+
},
|
|
71
78
|
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
79
|
+
async flush() {
|
|
80
|
+
// CHECKPOINT writes the WAL into the OPFS database file so committed
|
|
81
|
+
// changes survive a reload. Crucial for OPFS persistence.
|
|
82
|
+
if (path) await conn.query("CHECKPOINT");
|
|
83
|
+
},
|
|
77
84
|
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
85
|
+
// Runs after every earlier call has settled: terminating the worker
|
|
86
|
+
// while a request is pending would leave that request unsettled.
|
|
87
|
+
async close() {
|
|
88
|
+
await conn.close();
|
|
89
|
+
await db.terminate();
|
|
90
|
+
worker.terminate();
|
|
91
|
+
},
|
|
82
92
|
},
|
|
83
|
-
|
|
93
|
+
{ name: "db-duckdb-browser" },
|
|
94
|
+
);
|
|
84
95
|
}
|