@statewalker/db-duckdb-node 0.1.5 → 0.1.6

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
@@ -45,7 +45,31 @@ await db.close();
45
45
  - **One instance, one connection.** The factory creates a `DuckDBInstance`
46
46
  and a single connection; `close()` closes both synchronously.
47
47
  - **Parameters.** With parameters, `query` prepares the statement, binds the
48
- array and runs it. Both `$1` and `?` placeholders work.
48
+ array and runs it, then destroys the prepared statement. Both `$1` and `?`
49
+ placeholders work. Supported parameter values:
50
+
51
+ | JS value | Bound as |
52
+ | --- | --- |
53
+ | `null` | `NULL` |
54
+ | `boolean` | `BOOLEAN` |
55
+ | `number` | `INTEGER` (or `BIGINT` outside 32 bits) when integral, else `DOUBLE` |
56
+ | `bigint` | `HUGEINT` |
57
+ | `string` | `VARCHAR` |
58
+ | `Uint8Array` (and `Buffer`) | `BLOB` |
59
+ | `Date` | `TIMESTAMP` (UTC, microsecond precision), or `TIMESTAMPTZ` where the statement expects one (also as the items of a `TIMESTAMPTZ[]`), so the instant is kept whatever the session time zone; an invalid `Date` throws |
60
+ | array, or a non-byte typed array such as `Float32Array` | `LIST`, recursively; the item type comes from all items, so `[0, 0.5]` is `DOUBLE[]` |
61
+
62
+ DuckDB casts these to the column or the cast type, so an array binds into a
63
+ `FLOAT[3]` or `INTEGER[]` column and `$1::FLOAT[3]` works. An empty array
64
+ needs a known list type: a `LIST` column or a cast such as `$1::INTEGER[]`.
65
+ Other `@duckdb/node-api` values (`DuckDBValue`) pass through unchanged.
66
+ A `Date` keeps its instant in a `TIMESTAMPTZ` position only when DuckDB reports
67
+ the parameter's type. It does not for a cast array subscripted in the same
68
+ expression (`($1::TIMESTAMPTZ[2])[1]`): there, the Date binds as `TIMESTAMP` and
69
+ is read in the session time zone. Bind into a column or cast without the subscript.
70
+ - **One statement per `query`.** `query` rejects SQL holding several
71
+ statements (`query() runs one statement, ...`) instead of returning only the
72
+ first one's rows; run scripts with `exec`.
49
73
  - **Rows are plain JS objects** (`getRowObjectsJS()`). DuckDB `BIGINT` values,
50
74
  including `count(*)`, come back as `bigint`, not `number`.
51
75
  - **Errors are DuckDB's.** A bad path rejects with
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.mts","names":["DbOptions","Db"],"sources":["../src/node-duckdb.ts"],"mappings":";;;;;;;wBASsB,cAAc,UAAUA,cAAY,QAAQC"}
1
+ {"version":3,"file":"index.d.mts","names":["DbOptions","Db"],"sources":["../src/node-duckdb.ts"],"mappings":";;;;;;;wBA+BsB,cAAc,UAAUA,cAAY,QAAQC"}
package/dist/index.mjs CHANGED
@@ -1,4 +1,4 @@
1
- import { DuckDBInstance } from "@duckdb/node-api";
1
+ import { BIGINT, BLOB, BOOLEAN, DOUBLE, DuckDBInstance, DuckDBTypeId, HUGEINT, INTEGER, LIST, TIMESTAMP, TIMESTAMPTZ, VARCHAR, blobValue, listValue, timestampTZValue, timestampValue } from "@duckdb/node-api";
2
2
  //#region src/node-duckdb.ts
3
3
  /**
4
4
  * Create a DuckDB-backed {@link Db} using native Node.js bindings.
@@ -10,10 +10,15 @@ async function newNodeDuckDb(options) {
10
10
  const connection = await instance.connect();
11
11
  return {
12
12
  async query(sql, params) {
13
+ await assertSingleStatement(connection, sql);
13
14
  if (params && params.length > 0) {
14
15
  const prepared = await connection.prepare(sql);
15
- prepared.bind(params);
16
- return (await prepared.runAndReadAll()).getRowObjectsJS();
16
+ try {
17
+ bindParams(prepared, params);
18
+ return (await prepared.runAndReadAll()).getRowObjectsJS();
19
+ } finally {
20
+ prepared.destroySync();
21
+ }
17
22
  }
18
23
  return (await connection.runAndReadAll(sql)).getRowObjectsJS();
19
24
  },
@@ -26,6 +31,138 @@ async function newNodeDuckDb(options) {
26
31
  }
27
32
  };
28
33
  }
34
+ /**
35
+ * `query` returns one result set, so it refuses SQL holding several
36
+ * statements (DuckDB would otherwise silently return the first one's rows).
37
+ * When extraction itself fails (empty SQL, a syntax error), the statement
38
+ * runs as usual and DuckDB reports its own result or error.
39
+ */
40
+ async function assertSingleStatement(connection, sql) {
41
+ let count;
42
+ try {
43
+ count = (await connection.extractStatements(sql)).count;
44
+ } catch {
45
+ return;
46
+ }
47
+ if (count > 1) throw new Error(`query() runs one statement, but the SQL holds ${count}; use exec() for several statements.`);
48
+ }
49
+ function bindParams(prepared, params) {
50
+ for (let i = 0; i < params.length; i++) {
51
+ const param = params[i];
52
+ const index = i + 1;
53
+ if (isListLike(param)) {
54
+ const tzType = onlyDates(param) ? timestampTzListType(prepared, index) : void 0;
55
+ if (tzType) {
56
+ prepared.bindValue(index, toDuckDBValue(param, true), tzType);
57
+ continue;
58
+ }
59
+ const type = listType(param) ?? listParameterType(prepared, index);
60
+ if (type) {
61
+ prepared.bindValue(index, toDuckDBValue(param), type);
62
+ continue;
63
+ }
64
+ }
65
+ if (param instanceof Date && parameterTypeId(prepared, index) === DuckDBTypeId.TIMESTAMP_TZ) {
66
+ prepared.bindValue(index, timestampTZValue(dateMicros(param)), TIMESTAMPTZ);
67
+ continue;
68
+ }
69
+ prepared.bindValue(index, toDuckDBValue(param));
70
+ }
71
+ }
72
+ /** Whether a (nested) list holds at least one Date and nothing else but nulls. */
73
+ function onlyDates(list) {
74
+ let dates = 0;
75
+ const visit = (items) => {
76
+ for (const item of Array.from(items)) {
77
+ if (item === null || item === void 0) continue;
78
+ if (item instanceof Date) dates++;
79
+ else if (!isListLike(item) || !visit(item)) return false;
80
+ }
81
+ return true;
82
+ };
83
+ return visit(list) && dates > 0;
84
+ }
85
+ /**
86
+ * The statement's type for parameter `index` when it is a (nested) list or array of TIMESTAMPTZ,
87
+ * as nested LISTs (DuckDB casts a list into a fixed-size array); otherwise `undefined`.
88
+ */
89
+ function timestampTzListType(prepared, index) {
90
+ let type;
91
+ try {
92
+ type = prepared.parameterType(index);
93
+ } catch {
94
+ return;
95
+ }
96
+ const rebuild = (t) => {
97
+ if (t.typeId === DuckDBTypeId.LIST || t.typeId === DuckDBTypeId.ARRAY) {
98
+ const item = rebuild(t.valueType);
99
+ return item ? LIST(item) : void 0;
100
+ }
101
+ return t.typeId === DuckDBTypeId.TIMESTAMP_TZ ? TIMESTAMPTZ : void 0;
102
+ };
103
+ return type.typeId === DuckDBTypeId.LIST || type.typeId === DuckDBTypeId.ARRAY ? rebuild(type) : void 0;
104
+ }
105
+ function parameterTypeId(prepared, index) {
106
+ try {
107
+ return prepared.parameterType(index).typeId;
108
+ } catch {
109
+ return;
110
+ }
111
+ }
112
+ /** Microseconds since the epoch; an invalid `Date` throws. */
113
+ function dateMicros(value) {
114
+ const millis = value.getTime();
115
+ if (Number.isNaN(millis)) throw new TypeError("Invalid Date passed as a query parameter.");
116
+ return BigInt(millis) * 1000n;
117
+ }
118
+ function listParameterType(prepared, index) {
119
+ try {
120
+ const type = prepared.parameterType(index);
121
+ return type.typeId === DuckDBTypeId.LIST ? type : void 0;
122
+ } catch {
123
+ return;
124
+ }
125
+ }
126
+ /** The LIST type of a JS list, or `undefined` when its items do not tell. */
127
+ function listType(list) {
128
+ const itemType = commonType(Array.from(list));
129
+ return itemType ? LIST(itemType) : void 0;
130
+ }
131
+ function commonType(items) {
132
+ const present = items.filter((item) => item !== null && item !== void 0);
133
+ if (present.length === 0) return void 0;
134
+ if (present.every((item) => typeof item === "number")) {
135
+ if (!present.every(Number.isInteger)) return DOUBLE;
136
+ return present.every((n) => n >= -2147483648 && n <= 2147483647) ? INTEGER : BIGINT;
137
+ }
138
+ if (present.every(isListLike)) {
139
+ const itemType = commonType(present.flatMap((list) => Array.from(list)));
140
+ return itemType ? LIST(itemType) : void 0;
141
+ }
142
+ if (present.every((item) => typeof item === "string")) return VARCHAR;
143
+ if (present.every((item) => typeof item === "boolean")) return BOOLEAN;
144
+ if (present.every((item) => typeof item === "bigint")) return HUGEINT;
145
+ if (present.every((item) => item instanceof Uint8Array)) return BLOB;
146
+ if (present.every((item) => item instanceof Date)) return TIMESTAMP;
147
+ }
148
+ function isListLike(value) {
149
+ return Array.isArray(value) || ArrayBuffer.isView(value) && !(value instanceof DataView) && !(value instanceof Uint8Array);
150
+ }
151
+ /**
152
+ * Map JS values DuckDB cannot type on its own: `Uint8Array` to BLOB, `Date`
153
+ * to TIMESTAMP (microseconds since the epoch, UTC; `bindParams` binds TIMESTAMPTZ
154
+ * where the statement expects one), arrays and non-byte typed
155
+ * arrays to LIST (recursively). Everything else is bound as is.
156
+ */
157
+ function toDuckDBValue(value, timestampTz = false) {
158
+ if (value instanceof Uint8Array) return blobValue(value);
159
+ if (value instanceof Date) {
160
+ const micros = dateMicros(value);
161
+ return timestampTz ? timestampTZValue(micros) : timestampValue(micros);
162
+ }
163
+ if (isListLike(value)) return listValue(Array.from(value, (item) => toDuckDBValue(item, timestampTz)));
164
+ return value;
165
+ }
29
166
  //#endregion
30
167
  export { newNodeDuckDb };
31
168
 
@@ -1 +1 @@
1
- {"version":3,"file":"index.mjs","names":[],"sources":["../src/node-duckdb.ts"],"sourcesContent":["import type { DuckDBValue } from \"@duckdb/node-api\";\nimport { DuckDBInstance } 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 if (params && params.length > 0) {\n const prepared = await connection.prepare(sql);\n prepared.bind(params as DuckDBValue[]);\n const reader = await prepared.runAndReadAll();\n return reader.getRowObjectsJS() as T[];\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"],"mappings":";;;;;;;AASA,eAAsB,cAAc,SAAkC;CACpE,MAAM,WAAW,MAAM,eAAe,OAAO,SAAS,QAAQ,UAAU;CACxE,MAAM,aAAa,MAAM,SAAS,QAAQ;CAE1C,OAAO;EACL,MAAM,MAAmB,KAAa,QAAkC;GACtE,IAAI,UAAU,OAAO,SAAS,GAAG;IAC/B,MAAM,WAAW,MAAM,WAAW,QAAQ,GAAG;IAC7C,SAAS,KAAK,MAAuB;IAErC,QAAO,MADc,SAAS,cAAc,EAAA,CAC9B,gBAAgB;GAChC;GAEA,QAAO,MADc,WAAW,cAAc,GAAG,EAAA,CACnC,gBAAgB;EAChC;EAEA,MAAM,KAAK,KAA4B;GACrC,MAAM,WAAW,IAAI,GAAG;EAC1B;EAEA,MAAM,QAAuB;GAC3B,WAAW,UAAU;GACrB,SAAS,UAAU;EACrB;CACF;AACF"}
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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"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@statewalker/db-duckdb-node",
3
- "version": "0.1.5",
3
+ "version": "0.1.6",
4
4
  "private": false,
5
5
  "type": "module",
6
6
  "description": "DuckDB Node.js driver for @statewalker/db-api using @duckdb/node-api.",
@@ -22,16 +22,18 @@
22
22
  ".": {
23
23
  "source": "./src/index.ts",
24
24
  "types": "./dist/index.d.mts",
25
- "import": "./dist/index.mjs"
25
+ "import": "./dist/index.mjs",
26
+ "default": "./dist/index.mjs"
26
27
  }
27
28
  },
28
29
  "files": [
29
30
  "dist",
30
- "src"
31
+ "src",
32
+ "!src/**/*.test.ts"
31
33
  ],
32
34
  "dependencies": {
33
35
  "@duckdb/node-api": "^1.5.5-r.4",
34
- "@statewalker/db-api": "^0.1.5"
36
+ "@statewalker/db-api": "^0.1.6"
35
37
  },
36
38
  "devDependencies": {
37
39
  "@types/node": "^26.6.4",
@@ -1,5 +1,27 @@
1
- import type { DuckDBValue } from "@duckdb/node-api";
2
- import { DuckDBInstance } from "@duckdb/node-api";
1
+ import type {
2
+ DuckDBConnection,
3
+ DuckDBPreparedStatement,
4
+ DuckDBType,
5
+ DuckDBValue,
6
+ } from "@duckdb/node-api";
7
+ import {
8
+ BIGINT,
9
+ BLOB,
10
+ BOOLEAN,
11
+ blobValue,
12
+ DOUBLE,
13
+ DuckDBInstance,
14
+ DuckDBTypeId,
15
+ HUGEINT,
16
+ INTEGER,
17
+ LIST,
18
+ listValue,
19
+ TIMESTAMP,
20
+ TIMESTAMPTZ,
21
+ timestampTZValue,
22
+ timestampValue,
23
+ VARCHAR,
24
+ } from "@duckdb/node-api";
3
25
  import type { Db, DbEntry, DbOptions } from "@statewalker/db-api";
4
26
 
5
27
  /**
@@ -13,11 +35,16 @@ export async function newNodeDuckDb(options?: DbOptions): Promise<Db> {
13
35
 
14
36
  return {
15
37
  async query<T = DbEntry>(sql: string, params?: unknown[]): Promise<T[]> {
38
+ await assertSingleStatement(connection, sql);
16
39
  if (params && params.length > 0) {
17
40
  const prepared = await connection.prepare(sql);
18
- prepared.bind(params as DuckDBValue[]);
19
- const reader = await prepared.runAndReadAll();
20
- return reader.getRowObjectsJS() as T[];
41
+ try {
42
+ bindParams(prepared, params);
43
+ const reader = await prepared.runAndReadAll();
44
+ return reader.getRowObjectsJS() as T[];
45
+ } finally {
46
+ prepared.destroySync();
47
+ }
21
48
  }
22
49
  const reader = await connection.runAndReadAll(sql);
23
50
  return reader.getRowObjectsJS() as T[];
@@ -33,3 +60,174 @@ export async function newNodeDuckDb(options?: DbOptions): Promise<Db> {
33
60
  },
34
61
  };
35
62
  }
63
+
64
+ /**
65
+ * `query` returns one result set, so it refuses SQL holding several
66
+ * statements (DuckDB would otherwise silently return the first one's rows).
67
+ * When extraction itself fails (empty SQL, a syntax error), the statement
68
+ * runs as usual and DuckDB reports its own result or error.
69
+ */
70
+ async function assertSingleStatement(connection: DuckDBConnection, sql: string): Promise<void> {
71
+ let count: number;
72
+ try {
73
+ count = (await connection.extractStatements(sql)).count;
74
+ } catch {
75
+ return;
76
+ }
77
+ if (count > 1) {
78
+ throw new Error(
79
+ `query() runs one statement, but the SQL holds ${count}; use exec() for several statements.`,
80
+ );
81
+ }
82
+ }
83
+
84
+ function bindParams(prepared: DuckDBPreparedStatement, params: unknown[]): void {
85
+ for (let i = 0; i < params.length; i++) {
86
+ const param = params[i];
87
+ const index = i + 1;
88
+ if (isListLike(param)) {
89
+ // Dates bound into TIMESTAMPTZ[] must be instants too, not TIMESTAMPs cast in the session
90
+ // time zone: bind with the statement's type and TIMESTAMPTZ items.
91
+ const tzType = onlyDates(param) ? timestampTzListType(prepared, index) : undefined;
92
+ if (tzType) {
93
+ prepared.bindValue(index, toDuckDBValue(param, true), tzType);
94
+ continue;
95
+ }
96
+ // DuckDB infers a list's type from its first item, so `[0, 0.5]` would
97
+ // become INTEGER[] and fail; infer it from all items instead. An empty
98
+ // list has no items: take its type from the statement when it is known.
99
+ const type = listType(param) ?? listParameterType(prepared, index);
100
+ if (type) {
101
+ prepared.bindValue(index, toDuckDBValue(param), type);
102
+ continue;
103
+ }
104
+ }
105
+ if (param instanceof Date && parameterTypeId(prepared, index) === DuckDBTypeId.TIMESTAMP_TZ) {
106
+ // A TIMESTAMP is cast to TIMESTAMPTZ in the session time zone, which would shift the
107
+ // instant by the local offset: bind the instant itself.
108
+ prepared.bindValue(index, timestampTZValue(dateMicros(param)), TIMESTAMPTZ);
109
+ continue;
110
+ }
111
+ prepared.bindValue(index, toDuckDBValue(param));
112
+ }
113
+ }
114
+
115
+ /** Whether a (nested) list holds at least one Date and nothing else but nulls. */
116
+ function onlyDates(list: ListLike): boolean {
117
+ let dates = 0;
118
+ const visit = (items: ListLike): boolean => {
119
+ for (const item of Array.from(items)) {
120
+ if (item === null || item === undefined) continue;
121
+ if (item instanceof Date) dates++;
122
+ else if (!isListLike(item) || !visit(item)) return false;
123
+ }
124
+ return true;
125
+ };
126
+ return visit(list) && dates > 0;
127
+ }
128
+
129
+ /**
130
+ * The statement's type for parameter `index` when it is a (nested) list or array of TIMESTAMPTZ,
131
+ * as nested LISTs (DuckDB casts a list into a fixed-size array); otherwise `undefined`.
132
+ */
133
+ function timestampTzListType(
134
+ prepared: DuckDBPreparedStatement,
135
+ index: number,
136
+ ): DuckDBType | undefined {
137
+ let type: DuckDBType;
138
+ try {
139
+ type = prepared.parameterType(index);
140
+ } catch {
141
+ return undefined;
142
+ }
143
+ const rebuild = (t: DuckDBType): DuckDBType | undefined => {
144
+ if (t.typeId === DuckDBTypeId.LIST || t.typeId === DuckDBTypeId.ARRAY) {
145
+ const item = rebuild(t.valueType);
146
+ return item ? LIST(item) : undefined;
147
+ }
148
+ return t.typeId === DuckDBTypeId.TIMESTAMP_TZ ? TIMESTAMPTZ : undefined;
149
+ };
150
+ return type.typeId === DuckDBTypeId.LIST || type.typeId === DuckDBTypeId.ARRAY
151
+ ? rebuild(type)
152
+ : undefined;
153
+ }
154
+
155
+ function parameterTypeId(prepared: DuckDBPreparedStatement, index: number) {
156
+ try {
157
+ return prepared.parameterType(index).typeId;
158
+ } catch {
159
+ return undefined;
160
+ }
161
+ }
162
+
163
+ /** Microseconds since the epoch; an invalid `Date` throws. */
164
+ function dateMicros(value: Date): bigint {
165
+ const millis = value.getTime();
166
+ if (Number.isNaN(millis)) {
167
+ throw new TypeError("Invalid Date passed as a query parameter.");
168
+ }
169
+ return BigInt(millis) * 1000n;
170
+ }
171
+
172
+ function listParameterType(prepared: DuckDBPreparedStatement, index: number) {
173
+ try {
174
+ const type = prepared.parameterType(index);
175
+ return type.typeId === DuckDBTypeId.LIST ? type : undefined;
176
+ } catch {
177
+ return undefined;
178
+ }
179
+ }
180
+
181
+ /** The LIST type of a JS list, or `undefined` when its items do not tell. */
182
+ function listType(list: ListLike): DuckDBType | undefined {
183
+ const itemType = commonType(Array.from(list));
184
+ return itemType ? LIST(itemType) : undefined;
185
+ }
186
+
187
+ function commonType(items: unknown[]): DuckDBType | undefined {
188
+ const present = items.filter((item) => item !== null && item !== undefined);
189
+ if (present.length === 0) return undefined;
190
+ if (present.every((item) => typeof item === "number")) {
191
+ if (!present.every(Number.isInteger)) return DOUBLE;
192
+ return present.every((n) => n >= -2_147_483_648 && n <= 2_147_483_647) ? INTEGER : BIGINT;
193
+ }
194
+ if (present.every(isListLike)) {
195
+ const itemType = commonType(present.flatMap((list) => Array.from(list)));
196
+ return itemType ? LIST(itemType) : undefined;
197
+ }
198
+ if (present.every((item) => typeof item === "string")) return VARCHAR;
199
+ if (present.every((item) => typeof item === "boolean")) return BOOLEAN;
200
+ if (present.every((item) => typeof item === "bigint")) return HUGEINT;
201
+ if (present.every((item) => item instanceof Uint8Array)) return BLOB;
202
+ if (present.every((item) => item instanceof Date)) return TIMESTAMP;
203
+ return undefined;
204
+ }
205
+
206
+ type ListLike = ArrayLike<unknown> & Iterable<unknown>;
207
+
208
+ function isListLike(value: unknown): value is ListLike {
209
+ return (
210
+ Array.isArray(value) ||
211
+ (ArrayBuffer.isView(value) && !(value instanceof DataView) && !(value instanceof Uint8Array))
212
+ );
213
+ }
214
+
215
+ /**
216
+ * Map JS values DuckDB cannot type on its own: `Uint8Array` to BLOB, `Date`
217
+ * to TIMESTAMP (microseconds since the epoch, UTC; `bindParams` binds TIMESTAMPTZ
218
+ * where the statement expects one), arrays and non-byte typed
219
+ * arrays to LIST (recursively). Everything else is bound as is.
220
+ */
221
+ function toDuckDBValue(value: unknown, timestampTz = false): DuckDBValue {
222
+ if (value instanceof Uint8Array) {
223
+ return blobValue(value);
224
+ }
225
+ if (value instanceof Date) {
226
+ const micros = dateMicros(value);
227
+ return timestampTz ? timestampTZValue(micros) : timestampValue(micros);
228
+ }
229
+ if (isListLike(value)) {
230
+ return listValue(Array.from(value, (item) => toDuckDBValue(item, timestampTz)));
231
+ }
232
+ return value as DuckDBValue;
233
+ }
@@ -1,172 +0,0 @@
1
- import type { Db } from "@statewalker/db-api";
2
- import { runDbConformance } from "@statewalker/db-tests";
3
- import { afterEach, describe, expect, it } from "vitest";
4
- import { newNodeDuckDb } from "./node-duckdb.js";
5
-
6
- // Common contract (CRUD, parameter binding, cardinality, close, file
7
- // persistence, error paths) is covered by the shared conformance suite.
8
- // duckdb dialect: `$1` placeholder; rows are already plain, so the spread
9
- // normalizer is an identity-style copy.
10
- runDbConformance(newNodeDuckDb, {
11
- placeholder: "$1",
12
- normalizeRow: (row) => ({ ...row }),
13
- });
14
-
15
- // Dialect-specific behavior kept per-adapter: DuckDB FTS extension + VSS/HNSW.
16
- describe("newNodeDuckDb", () => {
17
- let db: Db;
18
-
19
- afterEach(async () => {
20
- if (db) {
21
- await db.close();
22
- }
23
- });
24
-
25
- describe("FTS extension", () => {
26
- it("returns empty results for unmatched search terms", async () => {
27
- db = await newNodeDuckDb();
28
- await db.exec("INSTALL fts");
29
- await db.exec("LOAD fts");
30
- await db.exec("CREATE TABLE docs2 (id INTEGER, content VARCHAR)");
31
- await db.exec("INSERT INTO docs2 VALUES (1, 'hello world'), (2, 'goodbye world')");
32
- await db.exec("PRAGMA create_fts_index('docs2', 'id', 'content')");
33
-
34
- const rows = await db.query<{ id: number; score: number | null }>(`
35
- SELECT id, score FROM (
36
- SELECT *, fts_main_docs2.match_bm25(id, 'nonexistent') AS score FROM docs2
37
- ) sq WHERE score IS NOT NULL
38
- `);
39
- expect(rows).toHaveLength(0);
40
- });
41
-
42
- it("searches across multiple text columns", async () => {
43
- db = await newNodeDuckDb();
44
- await db.exec("INSTALL fts");
45
- await db.exec("LOAD fts");
46
- await db.exec("CREATE TABLE articles (id INTEGER, title VARCHAR, body VARCHAR)");
47
- await db.exec(`
48
- INSERT INTO articles VALUES
49
- (1, 'Travel Guide', 'Visit the beautiful lakes of Switzerland'),
50
- (2, 'Cooking Tips', 'How to make a perfect lake trout'),
51
- (3, 'Programming', 'Learn about SQL databases')
52
- `);
53
- await db.exec("PRAGMA create_fts_index('articles', 'id', 'title', 'body')");
54
-
55
- const rows = await db.query<{ id: number; score: number | null }>(`
56
- SELECT id, score FROM (
57
- SELECT *, fts_main_articles.match_bm25(id, 'lake') AS score FROM articles
58
- ) sq WHERE score IS NOT NULL
59
- `);
60
- expect(rows.length).toBe(2);
61
- const ids = rows.map((r) => r.id);
62
- expect(ids).toContain(1);
63
- expect(ids).toContain(2);
64
- });
65
-
66
- it("creates an FTS index and performs full-text search", async () => {
67
- db = await newNodeDuckDb();
68
-
69
- await db.exec("INSTALL fts");
70
- await db.exec("LOAD fts");
71
-
72
- await db.exec("CREATE TABLE docs (id INTEGER, content VARCHAR)");
73
- await db.exec(`
74
- INSERT INTO docs VALUES
75
- (1, 'the quick brown fox jumps over the lazy dog'),
76
- (2, 'a lazy cat sleeps on the mat'),
77
- (3, 'the fox and the hound are friends')
78
- `);
79
-
80
- await db.exec("PRAGMA create_fts_index('docs', 'id', 'content')");
81
-
82
- const rows = await db.query<{
83
- id: number;
84
- content: string;
85
- score: number | null;
86
- }>(`
87
- SELECT id, content, score
88
- FROM (
89
- SELECT *, fts_main_docs.match_bm25(id, 'fox') AS score
90
- FROM docs
91
- ) sq
92
- WHERE score IS NOT NULL
93
- ORDER BY score
94
- `);
95
-
96
- expect(rows.length).toBeGreaterThanOrEqual(1);
97
- const ids = rows.map((r) => r.id);
98
- expect(ids).toContain(1);
99
- expect(ids).toContain(3);
100
- });
101
- });
102
-
103
- describe("VSS extension", () => {
104
- it("creates HNSW index and performs vector similarity search", async () => {
105
- db = await newNodeDuckDb();
106
-
107
- await db.exec("INSTALL vss");
108
- await db.exec("LOAD vss");
109
-
110
- await db.exec("CREATE TABLE embeddings (id INTEGER, vec FLOAT[3])");
111
- await db.exec(`
112
- INSERT INTO embeddings VALUES
113
- (1, [1.0, 0.0, 0.0]),
114
- (2, [0.0, 1.0, 0.0]),
115
- (3, [0.0, 0.0, 1.0])
116
- `);
117
-
118
- await db.exec("CREATE INDEX vec_idx ON embeddings USING HNSW (vec)");
119
-
120
- const rows = await db.query<{ id: number }>(
121
- "SELECT id FROM embeddings ORDER BY array_distance(vec, [1.0, 0.1, 0.0]::FLOAT[3]) LIMIT 1",
122
- );
123
-
124
- expect(rows).toHaveLength(1);
125
- expect(rows[0]?.id).toBe(1);
126
- });
127
-
128
- it("returns k nearest neighbors ordered by distance", async () => {
129
- db = await newNodeDuckDb();
130
- await db.exec("INSTALL vss");
131
- await db.exec("LOAD vss");
132
-
133
- await db.exec("CREATE TABLE vectors (id INTEGER, vec FLOAT[3])");
134
- await db.exec(`
135
- INSERT INTO vectors VALUES
136
- (1, [1.0, 0.0, 0.0]),
137
- (2, [0.9, 0.1, 0.0]),
138
- (3, [0.0, 1.0, 0.0]),
139
- (4, [0.0, 0.0, 1.0])
140
- `);
141
- await db.exec("CREATE INDEX vec_idx2 ON vectors USING HNSW (vec)");
142
-
143
- const rows = await db.query<{ id: number }>(
144
- "SELECT id FROM vectors ORDER BY array_distance(vec, [1.0, 0.0, 0.0]::FLOAT[3]) LIMIT 2",
145
- );
146
-
147
- expect(rows).toHaveLength(2);
148
- expect(rows[0]?.id).toBe(1);
149
- expect(rows[1]?.id).toBe(2);
150
- });
151
-
152
- it("works without HNSW index (brute-force scan)", async () => {
153
- db = await newNodeDuckDb();
154
- await db.exec("INSTALL vss");
155
- await db.exec("LOAD vss");
156
-
157
- await db.exec("CREATE TABLE vecs_no_idx (id INTEGER, vec FLOAT[3])");
158
- await db.exec(`
159
- INSERT INTO vecs_no_idx VALUES
160
- (1, [1.0, 0.0, 0.0]),
161
- (2, [0.0, 1.0, 0.0])
162
- `);
163
-
164
- const rows = await db.query<{ id: number }>(
165
- "SELECT id FROM vecs_no_idx ORDER BY array_distance(vec, [0.0, 0.9, 0.1]::FLOAT[3]) LIMIT 1",
166
- );
167
-
168
- expect(rows).toHaveLength(1);
169
- expect(rows[0]?.id).toBe(2);
170
- });
171
- });
172
- });