@statewalker/db-duckdb-node 0.1.6 → 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 CHANGED
@@ -42,8 +42,14 @@ await db.close();
42
42
 
43
43
  ## Internals
44
44
 
45
- - **One instance, one connection.** The factory creates a `DuckDBInstance`
46
- and a single connection; `close()` closes both synchronously.
45
+ - **One instance, one connection, one call at a time.** The factory creates a
46
+ `DuckDBInstance` and a single connection, wrapped by `newSerialisedDb` from
47
+ `@statewalker/db-sqlite` (the lifecycle every driver shares): calls run in
48
+ call order, `close()` waits for the calls made before it and then closes
49
+ both handles, later calls reject with
50
+ `db-duckdb-node: the database is closed`, and a second `close()` is a no-op.
51
+ Closing during a query used to fail it with `bad_weak_ptr` or crash the
52
+ process.
47
53
  - **Parameters.** With parameters, `query` prepares the statement, binds the
48
54
  array and runs it, then destroys the prepared statement. Both `$1` and `?`
49
55
  placeholders work. Supported parameter values:
@@ -70,14 +76,20 @@ await db.close();
70
76
  - **One statement per `query`.** `query` rejects SQL holding several
71
77
  statements (`query() runs one statement, ...`) instead of returning only the
72
78
  first one's rows; run scripts with `exec`.
73
- - **Rows are plain JS objects** (`getRowObjectsJS()`). DuckDB `BIGINT` values,
74
- including `count(*)`, come back as `bigint`, not `number`.
79
+ - **Rows are plain JS objects** (`getRowObjectsJS()`), with the integers the
80
+ `Db` contract asks for: a `number` within ±(2^53 - 1), a `bigint` beyond,
81
+ whatever the column type (`BIGINT`, `UBIGINT`, `HUGEINT`, `count(*)`), also
82
+ inside lists and structs. `TIME` (microseconds since midnight) and the
83
+ `micros` of an `INTERVAL` follow the same rule. `DECIMAL` comes back as a
84
+ `number` (the nearest double), `DATE` and `TIMESTAMP` as a `Date`, `BLOB` as
85
+ a `Buffer` (a `Uint8Array`).
75
86
  - **Errors are DuckDB's.** A bad path rejects with
76
87
  `IO Error: Cannot open file "...": No such file or directory`. Bad SQL rejects
77
88
  with `Parser Error: ...`. A call after `close()` rejects with
78
- `Failed to query: connection disconnected`.
89
+ `db-duckdb-node: the database is closed`.
79
90
  - **Dependencies:** `@duckdb/node-api` (the engine), `@statewalker/db-api`
80
- (the interface types).
91
+ (the interface types), `@statewalker/db-sqlite` (`newSerialisedDb`, the
92
+ shared lifecycle wrapper; no SQLite engine comes with it).
81
93
 
82
94
  ## License
83
95
 
package/dist/index.d.mts CHANGED
@@ -1,7 +1,10 @@
1
1
  import { Db, Db as Db$1, DbEntry, DbOptions, DbOptions as DbOptions$1 } from "@statewalker/db-api";
2
2
  //#region src/node-duckdb.d.ts
3
3
  /**
4
- * Create a DuckDB-backed {@link Db} using native Node.js bindings.
4
+ * Create a DuckDB-backed {@link Db} using native Node.js bindings. Calls run one at a time, in
5
+ * call order; `close()` waits for them, then closes; later calls reject with
6
+ * `db-duckdb-node: the database is closed`. Integers come back as numbers when safe, as bigints
7
+ * beyond ±(2^53 - 1).
5
8
  *
6
9
  * @param options.path File path for persistent storage. Omit for in-memory.
7
10
  */
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.mts","names":["DbOptions","Db"],"sources":["../src/node-duckdb.ts"],"mappings":";;;;;;;wBA+BsB,cAAc,UAAUA,cAAY,QAAQC"}
1
+ {"version":3,"file":"index.d.mts","names":["DbOptions","Db"],"sources":["../src/node-duckdb.ts"],"mappings":";;;;;;;;;;wBAmCsB,cAAc,UAAUA,cAAY,QAAQC"}
package/dist/index.mjs CHANGED
@@ -1,17 +1,21 @@
1
1
  import { BIGINT, BLOB, BOOLEAN, DOUBLE, DuckDBInstance, DuckDBTypeId, HUGEINT, INTEGER, LIST, TIMESTAMP, TIMESTAMPTZ, VARCHAR, blobValue, listValue, timestampTZValue, timestampValue } from "@duckdb/node-api";
2
+ import { newSerialisedDb } from "@statewalker/db-sqlite";
2
3
  //#region src/node-duckdb.ts
3
4
  /**
4
- * Create a DuckDB-backed {@link Db} using native Node.js bindings.
5
+ * Create a DuckDB-backed {@link Db} using native Node.js bindings. Calls run one at a time, in
6
+ * call order; `close()` waits for them, then closes; later calls reject with
7
+ * `db-duckdb-node: the database is closed`. Integers come back as numbers when safe, as bigints
8
+ * beyond ±(2^53 - 1).
5
9
  *
6
10
  * @param options.path File path for persistent storage. Omit for in-memory.
7
11
  */
8
12
  async function newNodeDuckDb(options) {
9
13
  const instance = await DuckDBInstance.create(options?.path ?? ":memory:");
10
14
  const connection = await instance.connect();
11
- return {
15
+ return newSerialisedDb({
12
16
  async query(sql, params) {
13
17
  await assertSingleStatement(connection, sql);
14
- if (params && params.length > 0) {
18
+ if (params.length > 0) {
15
19
  const prepared = await connection.prepare(sql);
16
20
  try {
17
21
  bindParams(prepared, params);
@@ -25,11 +29,11 @@ async function newNodeDuckDb(options) {
25
29
  async exec(sql) {
26
30
  await connection.run(sql);
27
31
  },
28
- async close() {
32
+ close() {
29
33
  connection.closeSync();
30
34
  instance.closeSync();
31
35
  }
32
- };
36
+ }, { name: "db-duckdb-node" });
33
37
  }
34
38
  /**
35
39
  * `query` returns one result set, so it refuses SQL holding several
@@ -1 +1 @@
1
- {"version":3,"file":"index.mjs","names":[],"sources":["../src/node-duckdb.ts"],"sourcesContent":["import type {\n DuckDBConnection,\n DuckDBPreparedStatement,\n DuckDBType,\n DuckDBValue,\n} from \"@duckdb/node-api\";\nimport {\n BIGINT,\n BLOB,\n BOOLEAN,\n blobValue,\n DOUBLE,\n DuckDBInstance,\n DuckDBTypeId,\n HUGEINT,\n INTEGER,\n LIST,\n listValue,\n TIMESTAMP,\n TIMESTAMPTZ,\n timestampTZValue,\n timestampValue,\n VARCHAR,\n} from \"@duckdb/node-api\";\nimport type { Db, DbEntry, DbOptions } from \"@statewalker/db-api\";\n\n/**\n * Create a DuckDB-backed {@link Db} using native Node.js bindings.\n *\n * @param options.path File path for persistent storage. Omit for in-memory.\n */\nexport async function newNodeDuckDb(options?: DbOptions): Promise<Db> {\n const instance = await DuckDBInstance.create(options?.path ?? \":memory:\");\n const connection = await instance.connect();\n\n return {\n async query<T = DbEntry>(sql: string, params?: unknown[]): Promise<T[]> {\n await assertSingleStatement(connection, sql);\n if (params && params.length > 0) {\n const prepared = await connection.prepare(sql);\n try {\n bindParams(prepared, params);\n const reader = await prepared.runAndReadAll();\n return reader.getRowObjectsJS() as T[];\n } finally {\n prepared.destroySync();\n }\n }\n const reader = await connection.runAndReadAll(sql);\n return reader.getRowObjectsJS() as T[];\n },\n\n async exec(sql: string): Promise<void> {\n await connection.run(sql);\n },\n\n async close(): Promise<void> {\n connection.closeSync();\n instance.closeSync();\n },\n };\n}\n\n/**\n * `query` returns one result set, so it refuses SQL holding several\n * statements (DuckDB would otherwise silently return the first one's rows).\n * When extraction itself fails (empty SQL, a syntax error), the statement\n * runs as usual and DuckDB reports its own result or error.\n */\nasync function assertSingleStatement(connection: DuckDBConnection, sql: string): Promise<void> {\n let count: number;\n try {\n count = (await connection.extractStatements(sql)).count;\n } catch {\n return;\n }\n if (count > 1) {\n throw new Error(\n `query() runs one statement, but the SQL holds ${count}; use exec() for several statements.`,\n );\n }\n}\n\nfunction bindParams(prepared: DuckDBPreparedStatement, params: unknown[]): void {\n for (let i = 0; i < params.length; i++) {\n const param = params[i];\n const index = i + 1;\n if (isListLike(param)) {\n // Dates bound into TIMESTAMPTZ[] must be instants too, not TIMESTAMPs cast in the session\n // time zone: bind with the statement's type and TIMESTAMPTZ items.\n const tzType = onlyDates(param) ? timestampTzListType(prepared, index) : undefined;\n if (tzType) {\n prepared.bindValue(index, toDuckDBValue(param, true), tzType);\n continue;\n }\n // DuckDB infers a list's type from its first item, so `[0, 0.5]` would\n // become INTEGER[] and fail; infer it from all items instead. An empty\n // list has no items: take its type from the statement when it is known.\n const type = listType(param) ?? listParameterType(prepared, index);\n if (type) {\n prepared.bindValue(index, toDuckDBValue(param), type);\n continue;\n }\n }\n if (param instanceof Date && parameterTypeId(prepared, index) === DuckDBTypeId.TIMESTAMP_TZ) {\n // A TIMESTAMP is cast to TIMESTAMPTZ in the session time zone, which would shift the\n // instant by the local offset: bind the instant itself.\n prepared.bindValue(index, timestampTZValue(dateMicros(param)), TIMESTAMPTZ);\n continue;\n }\n prepared.bindValue(index, toDuckDBValue(param));\n }\n}\n\n/** Whether a (nested) list holds at least one Date and nothing else but nulls. */\nfunction onlyDates(list: ListLike): boolean {\n let dates = 0;\n const visit = (items: ListLike): boolean => {\n for (const item of Array.from(items)) {\n if (item === null || item === undefined) continue;\n if (item instanceof Date) dates++;\n else if (!isListLike(item) || !visit(item)) return false;\n }\n return true;\n };\n return visit(list) && dates > 0;\n}\n\n/**\n * The statement's type for parameter `index` when it is a (nested) list or array of TIMESTAMPTZ,\n * as nested LISTs (DuckDB casts a list into a fixed-size array); otherwise `undefined`.\n */\nfunction timestampTzListType(\n prepared: DuckDBPreparedStatement,\n index: number,\n): DuckDBType | undefined {\n let type: DuckDBType;\n try {\n type = prepared.parameterType(index);\n } catch {\n return undefined;\n }\n const rebuild = (t: DuckDBType): DuckDBType | undefined => {\n if (t.typeId === DuckDBTypeId.LIST || t.typeId === DuckDBTypeId.ARRAY) {\n const item = rebuild(t.valueType);\n return item ? LIST(item) : undefined;\n }\n return t.typeId === DuckDBTypeId.TIMESTAMP_TZ ? TIMESTAMPTZ : undefined;\n };\n return type.typeId === DuckDBTypeId.LIST || type.typeId === DuckDBTypeId.ARRAY\n ? rebuild(type)\n : undefined;\n}\n\nfunction parameterTypeId(prepared: DuckDBPreparedStatement, index: number) {\n try {\n return prepared.parameterType(index).typeId;\n } catch {\n return undefined;\n }\n}\n\n/** Microseconds since the epoch; an invalid `Date` throws. */\nfunction dateMicros(value: Date): bigint {\n const millis = value.getTime();\n if (Number.isNaN(millis)) {\n throw new TypeError(\"Invalid Date passed as a query parameter.\");\n }\n return BigInt(millis) * 1000n;\n}\n\nfunction listParameterType(prepared: DuckDBPreparedStatement, index: number) {\n try {\n const type = prepared.parameterType(index);\n return type.typeId === DuckDBTypeId.LIST ? type : undefined;\n } catch {\n return undefined;\n }\n}\n\n/** The LIST type of a JS list, or `undefined` when its items do not tell. */\nfunction listType(list: ListLike): DuckDBType | undefined {\n const itemType = commonType(Array.from(list));\n return itemType ? LIST(itemType) : undefined;\n}\n\nfunction commonType(items: unknown[]): DuckDBType | undefined {\n const present = items.filter((item) => item !== null && item !== undefined);\n if (present.length === 0) return undefined;\n if (present.every((item) => typeof item === \"number\")) {\n if (!present.every(Number.isInteger)) return DOUBLE;\n return present.every((n) => n >= -2_147_483_648 && n <= 2_147_483_647) ? INTEGER : BIGINT;\n }\n if (present.every(isListLike)) {\n const itemType = commonType(present.flatMap((list) => Array.from(list)));\n return itemType ? LIST(itemType) : undefined;\n }\n if (present.every((item) => typeof item === \"string\")) return VARCHAR;\n if (present.every((item) => typeof item === \"boolean\")) return BOOLEAN;\n if (present.every((item) => typeof item === \"bigint\")) return HUGEINT;\n if (present.every((item) => item instanceof Uint8Array)) return BLOB;\n if (present.every((item) => item instanceof Date)) return TIMESTAMP;\n return undefined;\n}\n\ntype ListLike = ArrayLike<unknown> & Iterable<unknown>;\n\nfunction isListLike(value: unknown): value is ListLike {\n return (\n Array.isArray(value) ||\n (ArrayBuffer.isView(value) && !(value instanceof DataView) && !(value instanceof Uint8Array))\n );\n}\n\n/**\n * Map JS values DuckDB cannot type on its own: `Uint8Array` to BLOB, `Date`\n * to TIMESTAMP (microseconds since the epoch, UTC; `bindParams` binds TIMESTAMPTZ\n * where the statement expects one), arrays and non-byte typed\n * arrays to LIST (recursively). Everything else is bound as is.\n */\nfunction toDuckDBValue(value: unknown, timestampTz = false): DuckDBValue {\n if (value instanceof Uint8Array) {\n return blobValue(value);\n }\n if (value instanceof Date) {\n const micros = dateMicros(value);\n return timestampTz ? timestampTZValue(micros) : timestampValue(micros);\n }\n if (isListLike(value)) {\n return listValue(Array.from(value, (item) => toDuckDBValue(item, timestampTz)));\n }\n return value as DuckDBValue;\n}\n"],"mappings":"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"}
1
+ {"version":3,"file":"index.mjs","names":[],"sources":["../src/node-duckdb.ts"],"sourcesContent":["import type {\n DuckDBConnection,\n DuckDBPreparedStatement,\n DuckDBType,\n DuckDBValue,\n} from \"@duckdb/node-api\";\nimport {\n BIGINT,\n BLOB,\n BOOLEAN,\n blobValue,\n DOUBLE,\n DuckDBInstance,\n DuckDBTypeId,\n HUGEINT,\n INTEGER,\n LIST,\n listValue,\n TIMESTAMP,\n TIMESTAMPTZ,\n timestampTZValue,\n timestampValue,\n VARCHAR,\n} from \"@duckdb/node-api\";\nimport type { Db, DbOptions } from \"@statewalker/db-api\";\nimport { newSerialisedDb } from \"@statewalker/db-sqlite\";\n\n/**\n * Create a DuckDB-backed {@link Db} using native Node.js bindings. Calls run one at a time, in\n * call order; `close()` waits for them, then closes; later calls reject with\n * `db-duckdb-node: the database is closed`. Integers come back as numbers when safe, as bigints\n * beyond ±(2^53 - 1).\n *\n * @param options.path File path for persistent storage. Omit for in-memory.\n */\nexport async function newNodeDuckDb(options?: DbOptions): Promise<Db> {\n const instance = await DuckDBInstance.create(options?.path ?? \":memory:\");\n const connection = await instance.connect();\n\n return newSerialisedDb(\n {\n async query(sql, params) {\n await assertSingleStatement(connection, sql);\n if (params.length > 0) {\n const prepared = await connection.prepare(sql);\n try {\n bindParams(prepared, params);\n const reader = await prepared.runAndReadAll();\n return reader.getRowObjectsJS() as Record<string, unknown>[];\n } finally {\n prepared.destroySync();\n }\n }\n const reader = await connection.runAndReadAll(sql);\n return reader.getRowObjectsJS() as Record<string, unknown>[];\n },\n async exec(sql) {\n await connection.run(sql);\n },\n close() {\n connection.closeSync();\n instance.closeSync();\n },\n },\n { name: \"db-duckdb-node\" },\n );\n}\n\n/**\n * `query` returns one result set, so it refuses SQL holding several\n * statements (DuckDB would otherwise silently return the first one's rows).\n * When extraction itself fails (empty SQL, a syntax error), the statement\n * runs as usual and DuckDB reports its own result or error.\n */\nasync function assertSingleStatement(connection: DuckDBConnection, sql: string): Promise<void> {\n let count: number;\n try {\n count = (await connection.extractStatements(sql)).count;\n } catch {\n return;\n }\n if (count > 1) {\n throw new Error(\n `query() runs one statement, but the SQL holds ${count}; use exec() for several statements.`,\n );\n }\n}\n\nfunction bindParams(prepared: DuckDBPreparedStatement, params: unknown[]): void {\n for (let i = 0; i < params.length; i++) {\n const param = params[i];\n const index = i + 1;\n if (isListLike(param)) {\n // Dates bound into TIMESTAMPTZ[] must be instants too, not TIMESTAMPs cast in the session\n // time zone: bind with the statement's type and TIMESTAMPTZ items.\n const tzType = onlyDates(param) ? timestampTzListType(prepared, index) : undefined;\n if (tzType) {\n prepared.bindValue(index, toDuckDBValue(param, true), tzType);\n continue;\n }\n // DuckDB infers a list's type from its first item, so `[0, 0.5]` would\n // become INTEGER[] and fail; infer it from all items instead. An empty\n // list has no items: take its type from the statement when it is known.\n const type = listType(param) ?? listParameterType(prepared, index);\n if (type) {\n prepared.bindValue(index, toDuckDBValue(param), type);\n continue;\n }\n }\n if (param instanceof Date && parameterTypeId(prepared, index) === DuckDBTypeId.TIMESTAMP_TZ) {\n // A TIMESTAMP is cast to TIMESTAMPTZ in the session time zone, which would shift the\n // instant by the local offset: bind the instant itself.\n prepared.bindValue(index, timestampTZValue(dateMicros(param)), TIMESTAMPTZ);\n continue;\n }\n prepared.bindValue(index, toDuckDBValue(param));\n }\n}\n\n/** Whether a (nested) list holds at least one Date and nothing else but nulls. */\nfunction onlyDates(list: ListLike): boolean {\n let dates = 0;\n const visit = (items: ListLike): boolean => {\n for (const item of Array.from(items)) {\n if (item === null || item === undefined) continue;\n if (item instanceof Date) dates++;\n else if (!isListLike(item) || !visit(item)) return false;\n }\n return true;\n };\n return visit(list) && dates > 0;\n}\n\n/**\n * The statement's type for parameter `index` when it is a (nested) list or array of TIMESTAMPTZ,\n * as nested LISTs (DuckDB casts a list into a fixed-size array); otherwise `undefined`.\n */\nfunction timestampTzListType(\n prepared: DuckDBPreparedStatement,\n index: number,\n): DuckDBType | undefined {\n let type: DuckDBType;\n try {\n type = prepared.parameterType(index);\n } catch {\n return undefined;\n }\n const rebuild = (t: DuckDBType): DuckDBType | undefined => {\n if (t.typeId === DuckDBTypeId.LIST || t.typeId === DuckDBTypeId.ARRAY) {\n const item = rebuild(t.valueType);\n return item ? LIST(item) : undefined;\n }\n return t.typeId === DuckDBTypeId.TIMESTAMP_TZ ? TIMESTAMPTZ : undefined;\n };\n return type.typeId === DuckDBTypeId.LIST || type.typeId === DuckDBTypeId.ARRAY\n ? rebuild(type)\n : undefined;\n}\n\nfunction parameterTypeId(prepared: DuckDBPreparedStatement, index: number) {\n try {\n return prepared.parameterType(index).typeId;\n } catch {\n return undefined;\n }\n}\n\n/** Microseconds since the epoch; an invalid `Date` throws. */\nfunction dateMicros(value: Date): bigint {\n const millis = value.getTime();\n if (Number.isNaN(millis)) {\n throw new TypeError(\"Invalid Date passed as a query parameter.\");\n }\n return BigInt(millis) * 1000n;\n}\n\nfunction listParameterType(prepared: DuckDBPreparedStatement, index: number) {\n try {\n const type = prepared.parameterType(index);\n return type.typeId === DuckDBTypeId.LIST ? type : undefined;\n } catch {\n return undefined;\n }\n}\n\n/** The LIST type of a JS list, or `undefined` when its items do not tell. */\nfunction listType(list: ListLike): DuckDBType | undefined {\n const itemType = commonType(Array.from(list));\n return itemType ? LIST(itemType) : undefined;\n}\n\nfunction commonType(items: unknown[]): DuckDBType | undefined {\n const present = items.filter((item) => item !== null && item !== undefined);\n if (present.length === 0) return undefined;\n if (present.every((item) => typeof item === \"number\")) {\n if (!present.every(Number.isInteger)) return DOUBLE;\n return present.every((n) => n >= -2_147_483_648 && n <= 2_147_483_647) ? INTEGER : BIGINT;\n }\n if (present.every(isListLike)) {\n const itemType = commonType(present.flatMap((list) => Array.from(list)));\n return itemType ? LIST(itemType) : undefined;\n }\n if (present.every((item) => typeof item === \"string\")) return VARCHAR;\n if (present.every((item) => typeof item === \"boolean\")) return BOOLEAN;\n if (present.every((item) => typeof item === \"bigint\")) return HUGEINT;\n if (present.every((item) => item instanceof Uint8Array)) return BLOB;\n if (present.every((item) => item instanceof Date)) return TIMESTAMP;\n return undefined;\n}\n\ntype ListLike = ArrayLike<unknown> & Iterable<unknown>;\n\nfunction isListLike(value: unknown): value is ListLike {\n return (\n Array.isArray(value) ||\n (ArrayBuffer.isView(value) && !(value instanceof DataView) && !(value instanceof Uint8Array))\n );\n}\n\n/**\n * Map JS values DuckDB cannot type on its own: `Uint8Array` to BLOB, `Date`\n * to TIMESTAMP (microseconds since the epoch, UTC; `bindParams` binds TIMESTAMPTZ\n * where the statement expects one), arrays and non-byte typed\n * arrays to LIST (recursively). Everything else is bound as is.\n */\nfunction toDuckDBValue(value: unknown, timestampTz = false): DuckDBValue {\n if (value instanceof Uint8Array) {\n return blobValue(value);\n }\n if (value instanceof Date) {\n const micros = dateMicros(value);\n return timestampTz ? timestampTZValue(micros) : timestampValue(micros);\n }\n if (isListLike(value)) {\n return listValue(Array.from(value, (item) => toDuckDBValue(item, timestampTz)));\n }\n return value as DuckDBValue;\n}\n"],"mappings":"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"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@statewalker/db-duckdb-node",
3
- "version": "0.1.6",
3
+ "version": "0.2.0",
4
4
  "private": false,
5
5
  "type": "module",
6
6
  "description": "DuckDB Node.js driver for @statewalker/db-api using @duckdb/node-api.",
@@ -33,7 +33,8 @@
33
33
  ],
34
34
  "dependencies": {
35
35
  "@duckdb/node-api": "^1.5.5-r.4",
36
- "@statewalker/db-api": "^0.1.6"
36
+ "@statewalker/db-api": "^0.1.7",
37
+ "@statewalker/db-sqlite": "^0.1.3"
37
38
  },
38
39
  "devDependencies": {
39
40
  "@types/node": "^26.6.4",
@@ -22,10 +22,14 @@ import {
22
22
  timestampValue,
23
23
  VARCHAR,
24
24
  } from "@duckdb/node-api";
25
- import type { Db, DbEntry, DbOptions } from "@statewalker/db-api";
25
+ import type { Db, DbOptions } from "@statewalker/db-api";
26
+ import { newSerialisedDb } from "@statewalker/db-sqlite";
26
27
 
27
28
  /**
28
- * Create a DuckDB-backed {@link Db} using native Node.js bindings.
29
+ * Create a DuckDB-backed {@link Db} using native Node.js bindings. Calls run one at a time, in
30
+ * call order; `close()` waits for them, then closes; later calls reject with
31
+ * `db-duckdb-node: the database is closed`. Integers come back as numbers when safe, as bigints
32
+ * beyond ±(2^53 - 1).
29
33
  *
30
34
  * @param options.path File path for persistent storage. Omit for in-memory.
31
35
  */
@@ -33,32 +37,33 @@ export async function newNodeDuckDb(options?: DbOptions): Promise<Db> {
33
37
  const instance = await DuckDBInstance.create(options?.path ?? ":memory:");
34
38
  const connection = await instance.connect();
35
39
 
36
- return {
37
- async query<T = DbEntry>(sql: string, params?: unknown[]): Promise<T[]> {
38
- await assertSingleStatement(connection, sql);
39
- if (params && params.length > 0) {
40
- const prepared = await connection.prepare(sql);
41
- try {
42
- bindParams(prepared, params);
43
- const reader = await prepared.runAndReadAll();
44
- return reader.getRowObjectsJS() as T[];
45
- } finally {
46
- prepared.destroySync();
40
+ return newSerialisedDb(
41
+ {
42
+ async query(sql, params) {
43
+ await assertSingleStatement(connection, sql);
44
+ if (params.length > 0) {
45
+ const prepared = await connection.prepare(sql);
46
+ try {
47
+ bindParams(prepared, params);
48
+ const reader = await prepared.runAndReadAll();
49
+ return reader.getRowObjectsJS() as Record<string, unknown>[];
50
+ } finally {
51
+ prepared.destroySync();
52
+ }
47
53
  }
48
- }
49
- const reader = await connection.runAndReadAll(sql);
50
- return reader.getRowObjectsJS() as T[];
51
- },
52
-
53
- async exec(sql: string): Promise<void> {
54
- await connection.run(sql);
54
+ const reader = await connection.runAndReadAll(sql);
55
+ return reader.getRowObjectsJS() as Record<string, unknown>[];
56
+ },
57
+ async exec(sql) {
58
+ await connection.run(sql);
59
+ },
60
+ close() {
61
+ connection.closeSync();
62
+ instance.closeSync();
63
+ },
55
64
  },
56
-
57
- async close(): Promise<void> {
58
- connection.closeSync();
59
- instance.closeSync();
60
- },
61
- };
65
+ { name: "db-duckdb-node" },
66
+ );
62
67
  }
63
68
 
64
69
  /**