@statewalker/db-duckdb-node 0.1.6 → 0.2.1
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 +18 -6
- package/dist/index.d.mts +4 -1
- package/dist/index.d.mts.map +1 -1
- package/dist/index.mjs +9 -5
- package/dist/index.mjs.map +1 -1
- package/package.json +3 -2
- package/src/node-duckdb.ts +31 -26
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
|
|
46
|
-
and a single connection
|
|
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()`)
|
|
74
|
-
|
|
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
|
-
`
|
|
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
|
*/
|
package/dist/index.d.mts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.mts","names":["DbOptions","Db"],"sources":["../src/node-duckdb.ts"],"mappings":"
|
|
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
|
|
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
|
-
|
|
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
|
package/dist/index.mjs.map
CHANGED
|
@@ -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
|
|
3
|
+
"version": "0.2.1",
|
|
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.
|
|
36
|
+
"@statewalker/db-api": "^0.1.7",
|
|
37
|
+
"@statewalker/db-sqlite": "^0.1.4"
|
|
37
38
|
},
|
|
38
39
|
"devDependencies": {
|
|
39
40
|
"@types/node": "^26.6.4",
|
package/src/node-duckdb.ts
CHANGED
|
@@ -22,10 +22,14 @@ import {
|
|
|
22
22
|
timestampValue,
|
|
23
23
|
VARCHAR,
|
|
24
24
|
} from "@duckdb/node-api";
|
|
25
|
-
import type { Db,
|
|
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
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
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
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
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
|
-
|
|
58
|
-
connection.closeSync();
|
|
59
|
-
instance.closeSync();
|
|
60
|
-
},
|
|
61
|
-
};
|
|
65
|
+
{ name: "db-duckdb-node" },
|
|
66
|
+
);
|
|
62
67
|
}
|
|
63
68
|
|
|
64
69
|
/**
|