@statewalker/db-duckdb-node 0.1.5 → 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,18 +42,54 @@ 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
- array and runs it. Both `$1` and `?` placeholders work.
49
- - **Rows are plain JS objects** (`getRowObjectsJS()`). DuckDB `BIGINT` values,
50
- including `count(*)`, come back as `bigint`, not `number`.
54
+ array and runs it, then destroys the prepared statement. Both `$1` and `?`
55
+ placeholders work. Supported parameter values:
56
+
57
+ | JS value | Bound as |
58
+ | --- | --- |
59
+ | `null` | `NULL` |
60
+ | `boolean` | `BOOLEAN` |
61
+ | `number` | `INTEGER` (or `BIGINT` outside 32 bits) when integral, else `DOUBLE` |
62
+ | `bigint` | `HUGEINT` |
63
+ | `string` | `VARCHAR` |
64
+ | `Uint8Array` (and `Buffer`) | `BLOB` |
65
+ | `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 |
66
+ | 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[]` |
67
+
68
+ DuckDB casts these to the column or the cast type, so an array binds into a
69
+ `FLOAT[3]` or `INTEGER[]` column and `$1::FLOAT[3]` works. An empty array
70
+ needs a known list type: a `LIST` column or a cast such as `$1::INTEGER[]`.
71
+ Other `@duckdb/node-api` values (`DuckDBValue`) pass through unchanged.
72
+ A `Date` keeps its instant in a `TIMESTAMPTZ` position only when DuckDB reports
73
+ the parameter's type. It does not for a cast array subscripted in the same
74
+ expression (`($1::TIMESTAMPTZ[2])[1]`): there, the Date binds as `TIMESTAMP` and
75
+ is read in the session time zone. Bind into a column or cast without the subscript.
76
+ - **One statement per `query`.** `query` rejects SQL holding several
77
+ statements (`query() runs one statement, ...`) instead of returning only the
78
+ first one's rows; run scripts with `exec`.
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`).
51
86
  - **Errors are DuckDB's.** A bad path rejects with
52
87
  `IO Error: Cannot open file "...": No such file or directory`. Bad SQL rejects
53
88
  with `Parser Error: ...`. A call after `close()` rejects with
54
- `Failed to query: connection disconnected`.
89
+ `db-duckdb-node: the database is closed`.
55
90
  - **Dependencies:** `@duckdb/node-api` (the engine), `@statewalker/db-api`
56
- (the interface types).
91
+ (the interface types), `@statewalker/db-sqlite` (`newSerialisedDb`, the
92
+ shared lifecycle wrapper; no SQLite engine comes with it).
57
93
 
58
94
  ## License
59
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":";;;;;;;wBASsB,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,30 +1,171 @@
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
+ 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
- if (params && params.length > 0) {
17
+ await assertSingleStatement(connection, sql);
18
+ if (params.length > 0) {
14
19
  const prepared = await connection.prepare(sql);
15
- prepared.bind(params);
16
- return (await prepared.runAndReadAll()).getRowObjectsJS();
20
+ try {
21
+ bindParams(prepared, params);
22
+ return (await prepared.runAndReadAll()).getRowObjectsJS();
23
+ } finally {
24
+ prepared.destroySync();
25
+ }
17
26
  }
18
27
  return (await connection.runAndReadAll(sql)).getRowObjectsJS();
19
28
  },
20
29
  async exec(sql) {
21
30
  await connection.run(sql);
22
31
  },
23
- async close() {
32
+ close() {
24
33
  connection.closeSync();
25
34
  instance.closeSync();
26
35
  }
36
+ }, { name: "db-duckdb-node" });
37
+ }
38
+ /**
39
+ * `query` returns one result set, so it refuses SQL holding several
40
+ * statements (DuckDB would otherwise silently return the first one's rows).
41
+ * When extraction itself fails (empty SQL, a syntax error), the statement
42
+ * runs as usual and DuckDB reports its own result or error.
43
+ */
44
+ async function assertSingleStatement(connection, sql) {
45
+ let count;
46
+ try {
47
+ count = (await connection.extractStatements(sql)).count;
48
+ } catch {
49
+ return;
50
+ }
51
+ if (count > 1) throw new Error(`query() runs one statement, but the SQL holds ${count}; use exec() for several statements.`);
52
+ }
53
+ function bindParams(prepared, params) {
54
+ for (let i = 0; i < params.length; i++) {
55
+ const param = params[i];
56
+ const index = i + 1;
57
+ if (isListLike(param)) {
58
+ const tzType = onlyDates(param) ? timestampTzListType(prepared, index) : void 0;
59
+ if (tzType) {
60
+ prepared.bindValue(index, toDuckDBValue(param, true), tzType);
61
+ continue;
62
+ }
63
+ const type = listType(param) ?? listParameterType(prepared, index);
64
+ if (type) {
65
+ prepared.bindValue(index, toDuckDBValue(param), type);
66
+ continue;
67
+ }
68
+ }
69
+ if (param instanceof Date && parameterTypeId(prepared, index) === DuckDBTypeId.TIMESTAMP_TZ) {
70
+ prepared.bindValue(index, timestampTZValue(dateMicros(param)), TIMESTAMPTZ);
71
+ continue;
72
+ }
73
+ prepared.bindValue(index, toDuckDBValue(param));
74
+ }
75
+ }
76
+ /** Whether a (nested) list holds at least one Date and nothing else but nulls. */
77
+ function onlyDates(list) {
78
+ let dates = 0;
79
+ const visit = (items) => {
80
+ for (const item of Array.from(items)) {
81
+ if (item === null || item === void 0) continue;
82
+ if (item instanceof Date) dates++;
83
+ else if (!isListLike(item) || !visit(item)) return false;
84
+ }
85
+ return true;
86
+ };
87
+ return visit(list) && dates > 0;
88
+ }
89
+ /**
90
+ * The statement's type for parameter `index` when it is a (nested) list or array of TIMESTAMPTZ,
91
+ * as nested LISTs (DuckDB casts a list into a fixed-size array); otherwise `undefined`.
92
+ */
93
+ function timestampTzListType(prepared, index) {
94
+ let type;
95
+ try {
96
+ type = prepared.parameterType(index);
97
+ } catch {
98
+ return;
99
+ }
100
+ const rebuild = (t) => {
101
+ if (t.typeId === DuckDBTypeId.LIST || t.typeId === DuckDBTypeId.ARRAY) {
102
+ const item = rebuild(t.valueType);
103
+ return item ? LIST(item) : void 0;
104
+ }
105
+ return t.typeId === DuckDBTypeId.TIMESTAMP_TZ ? TIMESTAMPTZ : void 0;
27
106
  };
107
+ return type.typeId === DuckDBTypeId.LIST || type.typeId === DuckDBTypeId.ARRAY ? rebuild(type) : void 0;
108
+ }
109
+ function parameterTypeId(prepared, index) {
110
+ try {
111
+ return prepared.parameterType(index).typeId;
112
+ } catch {
113
+ return;
114
+ }
115
+ }
116
+ /** Microseconds since the epoch; an invalid `Date` throws. */
117
+ function dateMicros(value) {
118
+ const millis = value.getTime();
119
+ if (Number.isNaN(millis)) throw new TypeError("Invalid Date passed as a query parameter.");
120
+ return BigInt(millis) * 1000n;
121
+ }
122
+ function listParameterType(prepared, index) {
123
+ try {
124
+ const type = prepared.parameterType(index);
125
+ return type.typeId === DuckDBTypeId.LIST ? type : void 0;
126
+ } catch {
127
+ return;
128
+ }
129
+ }
130
+ /** The LIST type of a JS list, or `undefined` when its items do not tell. */
131
+ function listType(list) {
132
+ const itemType = commonType(Array.from(list));
133
+ return itemType ? LIST(itemType) : void 0;
134
+ }
135
+ function commonType(items) {
136
+ const present = items.filter((item) => item !== null && item !== void 0);
137
+ if (present.length === 0) return void 0;
138
+ if (present.every((item) => typeof item === "number")) {
139
+ if (!present.every(Number.isInteger)) return DOUBLE;
140
+ return present.every((n) => n >= -2147483648 && n <= 2147483647) ? INTEGER : BIGINT;
141
+ }
142
+ if (present.every(isListLike)) {
143
+ const itemType = commonType(present.flatMap((list) => Array.from(list)));
144
+ return itemType ? LIST(itemType) : void 0;
145
+ }
146
+ if (present.every((item) => typeof item === "string")) return VARCHAR;
147
+ if (present.every((item) => typeof item === "boolean")) return BOOLEAN;
148
+ if (present.every((item) => typeof item === "bigint")) return HUGEINT;
149
+ if (present.every((item) => item instanceof Uint8Array)) return BLOB;
150
+ if (present.every((item) => item instanceof Date)) return TIMESTAMP;
151
+ }
152
+ function isListLike(value) {
153
+ return Array.isArray(value) || ArrayBuffer.isView(value) && !(value instanceof DataView) && !(value instanceof Uint8Array);
154
+ }
155
+ /**
156
+ * Map JS values DuckDB cannot type on its own: `Uint8Array` to BLOB, `Date`
157
+ * to TIMESTAMP (microseconds since the epoch, UTC; `bindParams` binds TIMESTAMPTZ
158
+ * where the statement expects one), arrays and non-byte typed
159
+ * arrays to LIST (recursively). Everything else is bound as is.
160
+ */
161
+ function toDuckDBValue(value, timestampTz = false) {
162
+ if (value instanceof Uint8Array) return blobValue(value);
163
+ if (value instanceof Date) {
164
+ const micros = dateMicros(value);
165
+ return timestampTz ? timestampTZValue(micros) : timestampValue(micros);
166
+ }
167
+ if (isListLike(value)) return listValue(Array.from(value, (item) => toDuckDBValue(item, timestampTz)));
168
+ return value;
28
169
  }
29
170
  //#endregion
30
171
  export { newNodeDuckDb };
@@ -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, 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":";;;;;;;;;;;AAmCA,eAAsB,cAAc,SAAkC;CACpE,MAAM,WAAW,MAAM,eAAe,OAAO,SAAS,QAAQ,UAAU;CACxE,MAAM,aAAa,MAAM,SAAS,QAAQ;CAE1C,OAAO,gBACL;EACE,MAAM,MAAM,KAAK,QAAQ;GACvB,MAAM,sBAAsB,YAAY,GAAG;GAC3C,IAAI,OAAO,SAAS,GAAG;IACrB,MAAM,WAAW,MAAM,WAAW,QAAQ,GAAG;IAC7C,IAAI;KACF,WAAW,UAAU,MAAM;KAE3B,QAAO,MADc,SAAS,cAAc,EAAA,CAC9B,gBAAgB;IAChC,UAAU;KACR,SAAS,YAAY;IACvB;GACF;GAEA,QAAO,MADc,WAAW,cAAc,GAAG,EAAA,CACnC,gBAAgB;EAChC;EACA,MAAM,KAAK,KAAK;GACd,MAAM,WAAW,IAAI,GAAG;EAC1B;EACA,QAAQ;GACN,WAAW,UAAU;GACrB,SAAS,UAAU;EACrB;CACF,GACA,EAAE,MAAM,iBAAiB,CAC3B;AACF;;;;;;;AAQA,eAAe,sBAAsB,YAA8B,KAA4B;CAC7F,IAAI;CACJ,IAAI;EACF,SAAS,MAAM,WAAW,kBAAkB,GAAG,EAAA,CAAG;CACpD,QAAQ;EACN;CACF;CACA,IAAI,QAAQ,GACV,MAAM,IAAI,MACR,iDAAiD,MAAM,qCACzD;AAEJ;AAEA,SAAS,WAAW,UAAmC,QAAyB;CAC9E,KAAK,IAAI,IAAI,GAAG,IAAI,OAAO,QAAQ,KAAK;EACtC,MAAM,QAAQ,OAAO;EACrB,MAAM,QAAQ,IAAI;EAClB,IAAI,WAAW,KAAK,GAAG;GAGrB,MAAM,SAAS,UAAU,KAAK,IAAI,oBAAoB,UAAU,KAAK,IAAI,KAAA;GACzE,IAAI,QAAQ;IACV,SAAS,UAAU,OAAO,cAAc,OAAO,IAAI,GAAG,MAAM;IAC5D;GACF;GAIA,MAAM,OAAO,SAAS,KAAK,KAAK,kBAAkB,UAAU,KAAK;GACjE,IAAI,MAAM;IACR,SAAS,UAAU,OAAO,cAAc,KAAK,GAAG,IAAI;IACpD;GACF;EACF;EACA,IAAI,iBAAiB,QAAQ,gBAAgB,UAAU,KAAK,MAAM,aAAa,cAAc;GAG3F,SAAS,UAAU,OAAO,iBAAiB,WAAW,KAAK,CAAC,GAAG,WAAW;GAC1E;EACF;EACA,SAAS,UAAU,OAAO,cAAc,KAAK,CAAC;CAChD;AACF;;AAGA,SAAS,UAAU,MAAyB;CAC1C,IAAI,QAAQ;CACZ,MAAM,SAAS,UAA6B;EAC1C,KAAK,MAAM,QAAQ,MAAM,KAAK,KAAK,GAAG;GACpC,IAAI,SAAS,QAAQ,SAAS,KAAA,GAAW;GACzC,IAAI,gBAAgB,MAAM;QACrB,IAAI,CAAC,WAAW,IAAI,KAAK,CAAC,MAAM,IAAI,GAAG,OAAO;EACrD;EACA,OAAO;CACT;CACA,OAAO,MAAM,IAAI,KAAK,QAAQ;AAChC;;;;;AAMA,SAAS,oBACP,UACA,OACwB;CACxB,IAAI;CACJ,IAAI;EACF,OAAO,SAAS,cAAc,KAAK;CACrC,QAAQ;EACN;CACF;CACA,MAAM,WAAW,MAA0C;EACzD,IAAI,EAAE,WAAW,aAAa,QAAQ,EAAE,WAAW,aAAa,OAAO;GACrE,MAAM,OAAO,QAAQ,EAAE,SAAS;GAChC,OAAO,OAAO,KAAK,IAAI,IAAI,KAAA;EAC7B;EACA,OAAO,EAAE,WAAW,aAAa,eAAe,cAAc,KAAA;CAChE;CACA,OAAO,KAAK,WAAW,aAAa,QAAQ,KAAK,WAAW,aAAa,QACrE,QAAQ,IAAI,IACZ,KAAA;AACN;AAEA,SAAS,gBAAgB,UAAmC,OAAe;CACzE,IAAI;EACF,OAAO,SAAS,cAAc,KAAK,CAAC,CAAC;CACvC,QAAQ;EACN;CACF;AACF;;AAGA,SAAS,WAAW,OAAqB;CACvC,MAAM,SAAS,MAAM,QAAQ;CAC7B,IAAI,OAAO,MAAM,MAAM,GACrB,MAAM,IAAI,UAAU,2CAA2C;CAEjE,OAAO,OAAO,MAAM,IAAI;AAC1B;AAEA,SAAS,kBAAkB,UAAmC,OAAe;CAC3E,IAAI;EACF,MAAM,OAAO,SAAS,cAAc,KAAK;EACzC,OAAO,KAAK,WAAW,aAAa,OAAO,OAAO,KAAA;CACpD,QAAQ;EACN;CACF;AACF;;AAGA,SAAS,SAAS,MAAwC;CACxD,MAAM,WAAW,WAAW,MAAM,KAAK,IAAI,CAAC;CAC5C,OAAO,WAAW,KAAK,QAAQ,IAAI,KAAA;AACrC;AAEA,SAAS,WAAW,OAA0C;CAC5D,MAAM,UAAU,MAAM,QAAQ,SAAS,SAAS,QAAQ,SAAS,KAAA,CAAS;CAC1E,IAAI,QAAQ,WAAW,GAAG,OAAO,KAAA;CACjC,IAAI,QAAQ,OAAO,SAAS,OAAO,SAAS,QAAQ,GAAG;EACrD,IAAI,CAAC,QAAQ,MAAM,OAAO,SAAS,GAAG,OAAO;EAC7C,OAAO,QAAQ,OAAO,MAAM,KAAK,eAAkB,KAAK,UAAa,IAAI,UAAU;CACrF;CACA,IAAI,QAAQ,MAAM,UAAU,GAAG;EAC7B,MAAM,WAAW,WAAW,QAAQ,SAAS,SAAS,MAAM,KAAK,IAAI,CAAC,CAAC;EACvE,OAAO,WAAW,KAAK,QAAQ,IAAI,KAAA;CACrC;CACA,IAAI,QAAQ,OAAO,SAAS,OAAO,SAAS,QAAQ,GAAG,OAAO;CAC9D,IAAI,QAAQ,OAAO,SAAS,OAAO,SAAS,SAAS,GAAG,OAAO;CAC/D,IAAI,QAAQ,OAAO,SAAS,OAAO,SAAS,QAAQ,GAAG,OAAO;CAC9D,IAAI,QAAQ,OAAO,SAAS,gBAAgB,UAAU,GAAG,OAAO;CAChE,IAAI,QAAQ,OAAO,SAAS,gBAAgB,IAAI,GAAG,OAAO;AAE5D;AAIA,SAAS,WAAW,OAAmC;CACrD,OACE,MAAM,QAAQ,KAAK,KAClB,YAAY,OAAO,KAAK,KAAK,EAAE,iBAAiB,aAAa,EAAE,iBAAiB;AAErF;;;;;;;AAQA,SAAS,cAAc,OAAgB,cAAc,OAAoB;CACvE,IAAI,iBAAiB,YACnB,OAAO,UAAU,KAAK;CAExB,IAAI,iBAAiB,MAAM;EACzB,MAAM,SAAS,WAAW,KAAK;EAC/B,OAAO,cAAc,iBAAiB,MAAM,IAAI,eAAe,MAAM;CACvE;CACA,IAAI,WAAW,KAAK,GAClB,OAAO,UAAU,MAAM,KAAK,QAAQ,SAAS,cAAc,MAAM,WAAW,CAAC,CAAC;CAEhF,OAAO;AACT"}
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.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.",
@@ -22,16 +22,19 @@
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.7",
37
+ "@statewalker/db-sqlite": "^0.1.3"
35
38
  },
36
39
  "devDependencies": {
37
40
  "@types/node": "^26.6.4",
@@ -1,9 +1,35 @@
1
- import type { DuckDBValue } from "@duckdb/node-api";
2
- import { DuckDBInstance } from "@duckdb/node-api";
3
- import type { Db, DbEntry, DbOptions } from "@statewalker/db-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";
25
+ import type { Db, DbOptions } from "@statewalker/db-api";
26
+ import { newSerialisedDb } from "@statewalker/db-sqlite";
4
27
 
5
28
  /**
6
- * 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).
7
33
  *
8
34
  * @param options.path File path for persistent storage. Omit for in-memory.
9
35
  */
@@ -11,25 +37,202 @@ export async function newNodeDuckDb(options?: DbOptions): Promise<Db> {
11
37
  const instance = await DuckDBInstance.create(options?.path ?? ":memory:");
12
38
  const connection = await instance.connect();
13
39
 
14
- return {
15
- async query<T = DbEntry>(sql: string, params?: unknown[]): Promise<T[]> {
16
- if (params && params.length > 0) {
17
- const prepared = await connection.prepare(sql);
18
- prepared.bind(params as DuckDBValue[]);
19
- const reader = await prepared.runAndReadAll();
20
- return reader.getRowObjectsJS() as T[];
21
- }
22
- const reader = await connection.runAndReadAll(sql);
23
- return reader.getRowObjectsJS() as T[];
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
+ }
53
+ }
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
+ },
24
64
  },
65
+ { name: "db-duckdb-node" },
66
+ );
67
+ }
25
68
 
26
- async exec(sql: string): Promise<void> {
27
- await connection.run(sql);
28
- },
69
+ /**
70
+ * `query` returns one result set, so it refuses SQL holding several
71
+ * statements (DuckDB would otherwise silently return the first one's rows).
72
+ * When extraction itself fails (empty SQL, a syntax error), the statement
73
+ * runs as usual and DuckDB reports its own result or error.
74
+ */
75
+ async function assertSingleStatement(connection: DuckDBConnection, sql: string): Promise<void> {
76
+ let count: number;
77
+ try {
78
+ count = (await connection.extractStatements(sql)).count;
79
+ } catch {
80
+ return;
81
+ }
82
+ if (count > 1) {
83
+ throw new Error(
84
+ `query() runs one statement, but the SQL holds ${count}; use exec() for several statements.`,
85
+ );
86
+ }
87
+ }
29
88
 
30
- async close(): Promise<void> {
31
- connection.closeSync();
32
- instance.closeSync();
33
- },
89
+ function bindParams(prepared: DuckDBPreparedStatement, params: unknown[]): void {
90
+ for (let i = 0; i < params.length; i++) {
91
+ const param = params[i];
92
+ const index = i + 1;
93
+ if (isListLike(param)) {
94
+ // Dates bound into TIMESTAMPTZ[] must be instants too, not TIMESTAMPs cast in the session
95
+ // time zone: bind with the statement's type and TIMESTAMPTZ items.
96
+ const tzType = onlyDates(param) ? timestampTzListType(prepared, index) : undefined;
97
+ if (tzType) {
98
+ prepared.bindValue(index, toDuckDBValue(param, true), tzType);
99
+ continue;
100
+ }
101
+ // DuckDB infers a list's type from its first item, so `[0, 0.5]` would
102
+ // become INTEGER[] and fail; infer it from all items instead. An empty
103
+ // list has no items: take its type from the statement when it is known.
104
+ const type = listType(param) ?? listParameterType(prepared, index);
105
+ if (type) {
106
+ prepared.bindValue(index, toDuckDBValue(param), type);
107
+ continue;
108
+ }
109
+ }
110
+ if (param instanceof Date && parameterTypeId(prepared, index) === DuckDBTypeId.TIMESTAMP_TZ) {
111
+ // A TIMESTAMP is cast to TIMESTAMPTZ in the session time zone, which would shift the
112
+ // instant by the local offset: bind the instant itself.
113
+ prepared.bindValue(index, timestampTZValue(dateMicros(param)), TIMESTAMPTZ);
114
+ continue;
115
+ }
116
+ prepared.bindValue(index, toDuckDBValue(param));
117
+ }
118
+ }
119
+
120
+ /** Whether a (nested) list holds at least one Date and nothing else but nulls. */
121
+ function onlyDates(list: ListLike): boolean {
122
+ let dates = 0;
123
+ const visit = (items: ListLike): boolean => {
124
+ for (const item of Array.from(items)) {
125
+ if (item === null || item === undefined) continue;
126
+ if (item instanceof Date) dates++;
127
+ else if (!isListLike(item) || !visit(item)) return false;
128
+ }
129
+ return true;
130
+ };
131
+ return visit(list) && dates > 0;
132
+ }
133
+
134
+ /**
135
+ * The statement's type for parameter `index` when it is a (nested) list or array of TIMESTAMPTZ,
136
+ * as nested LISTs (DuckDB casts a list into a fixed-size array); otherwise `undefined`.
137
+ */
138
+ function timestampTzListType(
139
+ prepared: DuckDBPreparedStatement,
140
+ index: number,
141
+ ): DuckDBType | undefined {
142
+ let type: DuckDBType;
143
+ try {
144
+ type = prepared.parameterType(index);
145
+ } catch {
146
+ return undefined;
147
+ }
148
+ const rebuild = (t: DuckDBType): DuckDBType | undefined => {
149
+ if (t.typeId === DuckDBTypeId.LIST || t.typeId === DuckDBTypeId.ARRAY) {
150
+ const item = rebuild(t.valueType);
151
+ return item ? LIST(item) : undefined;
152
+ }
153
+ return t.typeId === DuckDBTypeId.TIMESTAMP_TZ ? TIMESTAMPTZ : undefined;
34
154
  };
155
+ return type.typeId === DuckDBTypeId.LIST || type.typeId === DuckDBTypeId.ARRAY
156
+ ? rebuild(type)
157
+ : undefined;
158
+ }
159
+
160
+ function parameterTypeId(prepared: DuckDBPreparedStatement, index: number) {
161
+ try {
162
+ return prepared.parameterType(index).typeId;
163
+ } catch {
164
+ return undefined;
165
+ }
166
+ }
167
+
168
+ /** Microseconds since the epoch; an invalid `Date` throws. */
169
+ function dateMicros(value: Date): bigint {
170
+ const millis = value.getTime();
171
+ if (Number.isNaN(millis)) {
172
+ throw new TypeError("Invalid Date passed as a query parameter.");
173
+ }
174
+ return BigInt(millis) * 1000n;
175
+ }
176
+
177
+ function listParameterType(prepared: DuckDBPreparedStatement, index: number) {
178
+ try {
179
+ const type = prepared.parameterType(index);
180
+ return type.typeId === DuckDBTypeId.LIST ? type : undefined;
181
+ } catch {
182
+ return undefined;
183
+ }
184
+ }
185
+
186
+ /** The LIST type of a JS list, or `undefined` when its items do not tell. */
187
+ function listType(list: ListLike): DuckDBType | undefined {
188
+ const itemType = commonType(Array.from(list));
189
+ return itemType ? LIST(itemType) : undefined;
190
+ }
191
+
192
+ function commonType(items: unknown[]): DuckDBType | undefined {
193
+ const present = items.filter((item) => item !== null && item !== undefined);
194
+ if (present.length === 0) return undefined;
195
+ if (present.every((item) => typeof item === "number")) {
196
+ if (!present.every(Number.isInteger)) return DOUBLE;
197
+ return present.every((n) => n >= -2_147_483_648 && n <= 2_147_483_647) ? INTEGER : BIGINT;
198
+ }
199
+ if (present.every(isListLike)) {
200
+ const itemType = commonType(present.flatMap((list) => Array.from(list)));
201
+ return itemType ? LIST(itemType) : undefined;
202
+ }
203
+ if (present.every((item) => typeof item === "string")) return VARCHAR;
204
+ if (present.every((item) => typeof item === "boolean")) return BOOLEAN;
205
+ if (present.every((item) => typeof item === "bigint")) return HUGEINT;
206
+ if (present.every((item) => item instanceof Uint8Array)) return BLOB;
207
+ if (present.every((item) => item instanceof Date)) return TIMESTAMP;
208
+ return undefined;
209
+ }
210
+
211
+ type ListLike = ArrayLike<unknown> & Iterable<unknown>;
212
+
213
+ function isListLike(value: unknown): value is ListLike {
214
+ return (
215
+ Array.isArray(value) ||
216
+ (ArrayBuffer.isView(value) && !(value instanceof DataView) && !(value instanceof Uint8Array))
217
+ );
218
+ }
219
+
220
+ /**
221
+ * Map JS values DuckDB cannot type on its own: `Uint8Array` to BLOB, `Date`
222
+ * to TIMESTAMP (microseconds since the epoch, UTC; `bindParams` binds TIMESTAMPTZ
223
+ * where the statement expects one), arrays and non-byte typed
224
+ * arrays to LIST (recursively). Everything else is bound as is.
225
+ */
226
+ function toDuckDBValue(value: unknown, timestampTz = false): DuckDBValue {
227
+ if (value instanceof Uint8Array) {
228
+ return blobValue(value);
229
+ }
230
+ if (value instanceof Date) {
231
+ const micros = dateMicros(value);
232
+ return timestampTz ? timestampTZValue(micros) : timestampValue(micros);
233
+ }
234
+ if (isListLike(value)) {
235
+ return listValue(Array.from(value, (item) => toDuckDBValue(item, timestampTz)));
236
+ }
237
+ return value as DuckDBValue;
35
238
  }
@@ -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
- });