@duckdb/node-api 1.1.3-alpha.8 → 1.1.3-alpha.9

package/LICENSE

@@ -1,4 +1,4 @@
-Copyright 2018-2023 Stichting DuckDB Foundation
+Copyright 2018-2025 Stichting DuckDB Foundation
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 

package/README.md

@@ -18,8 +18,8 @@ available separately as [@duckdb/duckdb-bindings](https://www.npmjs.com/package/
 ### Roadmap
 
 Some features are not yet complete:
-- Appending and binding advanced data types. (Additional DuckDB C API support needed.)
-- Writing to data chunk vectors. (Needs special handling in Node.)
+- Binding advanced data types. (Additional DuckDB C API support needed.)
+- Appending advanced data types row-by-row. Appending data chunks recommended instead.
 - User-defined types & functions. (Support for this was added to the DuckDB C API in v1.1.0.)
 - Profiling info (Added in v1.1.0)
 - Table description (Added in v1.1.0)
@@ -103,12 +103,43 @@ const result = await connection.run('from test_all_types()');
 ### Parameterize SQL
 
 ```ts
-const prepared = await connection.prepare('select $1, $2');
+const prepared = await connection.prepare('select $1, $2, $3');
 prepared.bindVarchar(1, 'duck');
 prepared.bindInteger(2, 42);
+prepared.bindList(3, listValue([10, 11, 12]), LIST(INTEGER));
 const result = await prepared.run();
 ```
 
+or:
+
+```ts
+const prepared = await connection.prepare('select $a, $b, $c');
+prepared.bind({
+  'a': 'duck',
+  'b': 42,
+  'c': listValue([10, 11, 12]),
+}, {
+  'a': VARCHAR,
+  'b': INTEGER,
+  'c': LIST(INTEGER),
+});
+const result = await prepared.run();
+```
+
+or even:
+
+```ts
+const result = await connection.run('select $a, $b, $c', {
+  'a': 'duck',
+  'b': 42,
+  'c': listValue([10, 11, 12]),
+}, {
+  'a': VARCHAR,
+  'b': INTEGER,
+  'c': LIST(INTEGER),
+});
+```
+
 ### Stream Results
 
 Streaming results evaluate lazily when rows are read.
@@ -412,6 +443,31 @@ appender.endRow();
 appender.close(); // also flushes
 ```
 
+### Append Data Chunk
+
+```ts
+await connection.run(
+  `create or replace table target_table(i integer, v varchar)`
+);
+
+const appender = await connection.createAppender('main', 'target_table');
+
+const chunk = DuckDBDataChunk.create([INTEGER, VARCHAR]);
+chunk.setColumns([
+  [42, 123, 17],
+  ['duck', 'mallad', 'goose'],
+]);
+// OR:
+// chunk.setRows([
+//   [42, 'duck'],
+//   [123, 'mallard'],
+//   [17, 'goose'],
+// ]);
+
+appender.appendDataChunk(chunk);
+appender.flush();
+```
+
 ### Extract Statements
 
 ```ts

package/lib/DuckDBConnection.d.ts

@@ -3,10 +3,12 @@ import { DuckDBAppender } from './DuckDBAppender';
 import { DuckDBExtractedStatements } from './DuckDBExtractedStatements';
 import { DuckDBInstance } from './DuckDBInstance';
 import { DuckDBMaterializedResult } from './DuckDBMaterializedResult';
+import { DuckDBPendingResult } from './DuckDBPendingResult';
 import { DuckDBPreparedStatement } from './DuckDBPreparedStatement';
 import { DuckDBResult } from './DuckDBResult';
 import { DuckDBResultReader } from './DuckDBResultReader';
-import { DuckDBPendingResult } from './DuckDBPendingResult';
+import { DuckDBType } from './DuckDBType';
+import { DuckDBValue } from './values';
 export declare class DuckDBConnection {
     private readonly connection;
     constructor(connection: duckdb.Connection);
@@ -16,16 +18,16 @@ export declare class DuckDBConnection {
     disconnect(): void;
     interrupt(): void;
     get progress(): duckdb.QueryProgress;
-    run(sql: string): Promise<DuckDBMaterializedResult>;
-    runAndRead(sql: string): Promise<DuckDBResultReader>;
-    runAndReadAll(sql: string): Promise<DuckDBResultReader>;
-    runAndReadUntil(sql: string, targetRowCount: number): Promise<DuckDBResultReader>;
-    stream(sql: string): Promise<DuckDBResult>;
-    streamAndRead(sql: string): Promise<DuckDBResultReader>;
-    streamAndReadAll(sql: string): Promise<DuckDBResultReader>;
-    streamAndReadUntil(sql: string, targetRowCount: number): Promise<DuckDBResultReader>;
-    start(sql: string): Promise<DuckDBPendingResult>;
-    startStream(sql: string): Promise<DuckDBPendingResult>;
+    run(sql: string, values?: DuckDBValue[] | Record<string, DuckDBValue>, types?: DuckDBType[] | Record<string, DuckDBType>): Promise<DuckDBMaterializedResult>;
+    runAndRead(sql: string, values?: DuckDBValue[] | Record<string, DuckDBValue>, types?: DuckDBType[] | Record<string, DuckDBType>): Promise<DuckDBResultReader>;
+    runAndReadAll(sql: string, values?: DuckDBValue[] | Record<string, DuckDBValue>, types?: DuckDBType[] | Record<string, DuckDBType>): Promise<DuckDBResultReader>;
+    runAndReadUntil(sql: string, targetRowCount: number, values?: DuckDBValue[] | Record<string, DuckDBValue>, types?: DuckDBType[] | Record<string, DuckDBType>): Promise<DuckDBResultReader>;
+    stream(sql: string, values?: DuckDBValue[] | Record<string, DuckDBValue>, types?: DuckDBType[] | Record<string, DuckDBType>): Promise<DuckDBResult>;
+    streamAndRead(sql: string, values?: DuckDBValue[] | Record<string, DuckDBValue>, types?: DuckDBType[] | Record<string, DuckDBType>): Promise<DuckDBResultReader>;
+    streamAndReadAll(sql: string, values?: DuckDBValue[] | Record<string, DuckDBValue>, types?: DuckDBType[] | Record<string, DuckDBType>): Promise<DuckDBResultReader>;
+    streamAndReadUntil(sql: string, targetRowCount: number, values?: DuckDBValue[] | Record<string, DuckDBValue>, types?: DuckDBType[] | Record<string, DuckDBType>): Promise<DuckDBResultReader>;
+    start(sql: string, values?: DuckDBValue[] | Record<string, DuckDBValue>, types?: DuckDBType[] | Record<string, DuckDBType>): Promise<DuckDBPendingResult>;
+    startStream(sql: string, values?: DuckDBValue[] | Record<string, DuckDBValue>, types?: DuckDBType[] | Record<string, DuckDBType>): Promise<DuckDBPendingResult>;
     prepare(sql: string): Promise<DuckDBPreparedStatement>;
     extractStatements(sql: string): Promise<DuckDBExtractedStatements>;
     createAppender(schema: string, table: string): Promise<DuckDBAppender>;

package/lib/DuckDBConnection.js

@@ -31,45 +31,61 @@ class DuckDBConnection {
     get progress() {
         return node_bindings_1.default.query_progress(this.connection);
     }
-    async run(sql) {
-        return new DuckDBMaterializedResult_1.DuckDBMaterializedResult(await node_bindings_1.default.query(this.connection, sql));
+    async run(sql, values, types) {
+        if (values) {
+            const prepared = await this.prepare(sql);
+            prepared.bind(values, types);
+            return prepared.run();
+        }
+        else {
+            return new DuckDBMaterializedResult_1.DuckDBMaterializedResult(await node_bindings_1.default.query(this.connection, sql));
+        }
     }
-    async runAndRead(sql) {
-        return new DuckDBResultReader_1.DuckDBResultReader(await this.run(sql));
+    async runAndRead(sql, values, types) {
+        return new DuckDBResultReader_1.DuckDBResultReader(await this.run(sql, values, types));
     }
-    async runAndReadAll(sql) {
-        const reader = new DuckDBResultReader_1.DuckDBResultReader(await this.run(sql));
+    async runAndReadAll(sql, values, types) {
+        const reader = new DuckDBResultReader_1.DuckDBResultReader(await this.run(sql, values, types));
         await reader.readAll();
         return reader;
     }
-    async runAndReadUntil(sql, targetRowCount) {
-        const reader = new DuckDBResultReader_1.DuckDBResultReader(await this.run(sql));
+    async runAndReadUntil(sql, targetRowCount, values, types) {
+        const reader = new DuckDBResultReader_1.DuckDBResultReader(await this.run(sql, values, types));
         await reader.readUntil(targetRowCount);
         return reader;
     }
-    async stream(sql) {
+    async stream(sql, values, types) {
         const prepared = await this.prepare(sql);
+        if (values) {
+            prepared.bind(values, types);
+        }
         return prepared.stream();
     }
-    async streamAndRead(sql) {
-        return new DuckDBResultReader_1.DuckDBResultReader(await this.stream(sql));
+    async streamAndRead(sql, values, types) {
+        return new DuckDBResultReader_1.DuckDBResultReader(await this.stream(sql, values, types));
     }
-    async streamAndReadAll(sql) {
-        const reader = new DuckDBResultReader_1.DuckDBResultReader(await this.stream(sql));
+    async streamAndReadAll(sql, values, types) {
+        const reader = new DuckDBResultReader_1.DuckDBResultReader(await this.stream(sql, values, types));
         await reader.readAll();
         return reader;
     }
-    async streamAndReadUntil(sql, targetRowCount) {
-        const reader = new DuckDBResultReader_1.DuckDBResultReader(await this.stream(sql));
+    async streamAndReadUntil(sql, targetRowCount, values, types) {
+        const reader = new DuckDBResultReader_1.DuckDBResultReader(await this.stream(sql, values, types));
         await reader.readUntil(targetRowCount);
         return reader;
     }
-    async start(sql) {
+    async start(sql, values, types) {
         const prepared = await this.prepare(sql);
+        if (values) {
+            prepared.bind(values, types);
+        }
         return prepared.start();
     }
-    async startStream(sql) {
+    async startStream(sql, values, types) {
         const prepared = await this.prepare(sql);
+        if (values) {
+            prepared.bind(values, types);
+        }
         return prepared.startStream();
     }
     async prepare(sql) {

package/lib/DuckDBDataChunk.d.ts

@@ -1,17 +1,21 @@
 import duckdb from '@duckdb/node-bindings';
+import { DuckDBType } from './DuckDBType';
 import { DuckDBVector } from './DuckDBVector';
 import { DuckDBValue } from './values';
 export declare class DuckDBDataChunk {
     readonly chunk: duckdb.DataChunk;
     private readonly vectors;
     constructor(chunk: duckdb.DataChunk);
-    static create(logical_types: duckdb.LogicalType[]): DuckDBDataChunk;
+    static create(types: readonly DuckDBType[], rowCount?: number): DuckDBDataChunk;
     reset(): void;
     get columnCount(): number;
     getColumnVector(columnIndex: number): DuckDBVector;
     getColumnValues(columnIndex: number): DuckDBValue[];
+    setColumnValues(columnIndex: number, values: readonly DuckDBValue[]): void;
     getColumns(): DuckDBValue[][];
+    setColumns(columns: readonly (readonly DuckDBValue[])[]): void;
     getRows(): DuckDBValue[][];
+    setRows(rows: readonly (readonly DuckDBValue[])[]): void;
     get rowCount(): number;
     set rowCount(count: number);
 }

package/lib/DuckDBDataChunk.js

@@ -12,8 +12,12 @@ class DuckDBDataChunk {
     constructor(chunk) {
         this.chunk = chunk;
     }
-    static create(logical_types) {
-        return new DuckDBDataChunk(node_bindings_1.default.create_data_chunk(logical_types));
+    static create(types, rowCount) {
+        const chunk = new DuckDBDataChunk(node_bindings_1.default.create_data_chunk(types.map(t => t.toLogicalType().logical_type)));
+        if (rowCount != undefined) {
+            chunk.rowCount = rowCount;
+        }
+        return chunk;
     }
     reset() {
         node_bindings_1.default.data_chunk_reset(this.chunk);
@@ -32,6 +36,16 @@ class DuckDBDataChunk {
     getColumnValues(columnIndex) {
         return this.getColumnVector(columnIndex).toArray();
     }
+    setColumnValues(columnIndex, values) {
+        const vector = this.getColumnVector(columnIndex);
+        if (vector.itemCount !== values.length) {
+            throw new Error(`number of values must equal chunk row count`);
+        }
+        for (let i = 0; i < values.length; i++) {
+            vector.setItem(i, values[i]);
+        }
+        vector.flush();
+    }
     getColumns() {
         const columns = [];
         const columnCount = this.columnCount;
@@ -40,6 +54,14 @@ class DuckDBDataChunk {
         }
         return columns;
     }
+    setColumns(columns) {
+        if (columns.length > 0) {
+            this.rowCount = columns[0].length;
+        }
+        for (let columnIndex = 0; columnIndex < columns.length; columnIndex++) {
+            this.setColumnValues(columnIndex, columns[columnIndex]);
+        }
+    }
     getRows() {
         const rows = [];
         const vectors = [];
@@ -57,6 +79,17 @@ class DuckDBDataChunk {
         }
         return rows;
     }
+    setRows(rows) {
+        this.rowCount = rows.length;
+        const columnCount = this.columnCount;
+        for (let columnIndex = 0; columnIndex < columnCount; columnIndex++) {
+            const vector = this.getColumnVector(columnIndex);
+            for (let rowIndex = 0; rowIndex < rows.length; rowIndex++) {
+                vector.setItem(rowIndex, rows[rowIndex][columnIndex]);
+            }
+            vector.flush();
+        }
+    }
     get rowCount() {
         return node_bindings_1.default.data_chunk_get_size(this.chunk);
     }

package/lib/DuckDBPreparedStatement.d.ts

@@ -3,9 +3,10 @@ import { DuckDBMaterializedResult } from './DuckDBMaterializedResult';
 import { DuckDBPendingResult } from './DuckDBPendingResult';
 import { DuckDBResult } from './DuckDBResult';
 import { DuckDBResultReader } from './DuckDBResultReader';
+import { DuckDBArrayType, DuckDBListType, DuckDBStructType, DuckDBType } from './DuckDBType';
 import { DuckDBTypeId } from './DuckDBTypeId';
 import { StatementType } from './enums';
-import { DuckDBDateValue, DuckDBDecimalValue, DuckDBIntervalValue, DuckDBTimestampValue, DuckDBTimeValue } from './values';
+import { DuckDBArrayValue, DuckDBDateValue, DuckDBDecimalValue, DuckDBIntervalValue, DuckDBListValue, DuckDBStructValue, DuckDBTimestampTZValue, DuckDBTimestampValue, DuckDBTimeTZValue, DuckDBTimeValue, DuckDBValue } from './values';
 export declare class DuckDBPreparedStatement {
     private readonly prepared_statement;
     constructor(prepared_statement: duckdb.PreparedStatement);
@@ -31,11 +32,18 @@ export declare class DuckDBPreparedStatement {
     bindDouble(parameterIndex: number, value: number): void;
     bindDate(parameterIndex: number, value: DuckDBDateValue): void;
     bindTime(parameterIndex: number, value: DuckDBTimeValue): void;
+    bindTimeTZ(parameterIndex: number, value: DuckDBTimeTZValue): void;
     bindTimestamp(parameterIndex: number, value: DuckDBTimestampValue): void;
+    bindTimestampTZ(parameterIndex: number, value: DuckDBTimestampTZValue): void;
     bindInterval(parameterIndex: number, value: DuckDBIntervalValue): void;
     bindVarchar(parameterIndex: number, value: string): void;
     bindBlob(parameterIndex: number, value: Uint8Array): void;
+    bindArray(parameterIndex: number, value: DuckDBArrayValue, type: DuckDBArrayType): void;
+    bindList(parameterIndex: number, value: DuckDBListValue, type: DuckDBListType): void;
+    bindStruct(parameterIndex: number, value: DuckDBStructValue, type: DuckDBStructType): void;
     bindNull(parameterIndex: number): void;
+    bindValue(parameterIndex: number, value: DuckDBValue, type: DuckDBType): void;
+    bind(values: DuckDBValue[] | Record<string, DuckDBValue>, types?: DuckDBType[] | Record<string, DuckDBType>): void;
     run(): Promise<DuckDBMaterializedResult>;
     runAndRead(): Promise<DuckDBResultReader>;
     runAndReadAll(): Promise<DuckDBResultReader>;

package/lib/DuckDBPreparedStatement.js

@@ -5,10 +5,13 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DuckDBPreparedStatement = void 0;
 const node_bindings_1 = __importDefault(require("@duckdb/node-bindings"));
+const createValue_1 = require("./createValue");
 const DuckDBMaterializedResult_1 = require("./DuckDBMaterializedResult");
 const DuckDBPendingResult_1 = require("./DuckDBPendingResult");
 const DuckDBResult_1 = require("./DuckDBResult");
 const DuckDBResultReader_1 = require("./DuckDBResultReader");
+const DuckDBType_1 = require("./DuckDBType");
+const typeForValue_1 = require("./typeForValue");
 class DuckDBPreparedStatement {
     prepared_statement;
     constructor(prepared_statement) {
@@ -80,11 +83,16 @@ class DuckDBPreparedStatement {
     bindTime(parameterIndex, value) {
         node_bindings_1.default.bind_time(this.prepared_statement, parameterIndex, value);
     }
+    bindTimeTZ(parameterIndex, value) {
+        this.bindValue(parameterIndex, value, DuckDBType_1.TIMETZ);
+    }
     bindTimestamp(parameterIndex, value) {
         node_bindings_1.default.bind_timestamp(this.prepared_statement, parameterIndex, value);
     }
-    // TODO: bind TIMESTAMPS_S/_MS/_NS?
-    // TODO: bind TIME_TZ/TIMESTAMP_TZ?
+    bindTimestampTZ(parameterIndex, value) {
+        this.bindValue(parameterIndex, value, DuckDBType_1.TIMESTAMPTZ);
+    }
+    // TODO: bind TIMESTAMPS_S/_MS/_NS
     bindInterval(parameterIndex, value) {
         node_bindings_1.default.bind_interval(this.prepared_statement, parameterIndex, value);
     }
@@ -94,17 +102,40 @@ class DuckDBPreparedStatement {
     bindBlob(parameterIndex, value) {
         node_bindings_1.default.bind_blob(this.prepared_statement, parameterIndex, value);
     }
-    // TODO: bind ENUM?
-    // TODO: bind nested types? (ARRAY, LIST, STRUCT, MAP, UNION) (using bindValue?)
-    // TODO: bind UUID?
-    // TODO: bind BIT?
+    // TODO: bind ENUM
+    bindArray(parameterIndex, value, type) {
+        this.bindValue(parameterIndex, value, type);
+    }
+    bindList(parameterIndex, value, type) {
+        this.bindValue(parameterIndex, value, type);
+    }
+    bindStruct(parameterIndex, value, type) {
+        this.bindValue(parameterIndex, value, type);
+    }
+    // TODO: bind MAP, UNION
+    // TODO: bind UUID
+    // TODO: bind BIT
     bindNull(parameterIndex) {
         node_bindings_1.default.bind_null(this.prepared_statement, parameterIndex);
     }
-    // TODO: expose bindValue, or implement bindList, bindStruct, etc.?
-    // public bindValue(parameterIndex: number, value: Value) {
-    //   duckdb.bind_value(this.prepared_statement, parameterIndex, value);
-    // }
+    bindValue(parameterIndex, value, type) {
+        node_bindings_1.default.bind_value(this.prepared_statement, parameterIndex, (0, createValue_1.createValue)(type, value));
+    }
+    bind(values, types) {
+        if (Array.isArray(values)) {
+            const typesIsArray = Array.isArray(types);
+            for (let i = 0; i < values.length; i++) {
+                this.bindValue(i + 1, values[i], typesIsArray ? types[i] : (0, typeForValue_1.typeForValue)(values[i]));
+            }
+        }
+        else {
+            const typesIsRecord = types && !Array.isArray(types);
+            for (const key in values) {
+                const index = this.parameterIndex(key);
+                this.bindValue(index, values[key], typesIsRecord ? types[key] : (0, typeForValue_1.typeForValue)(values[key]));
+            }
+        }
+    }
     async run() {
         return new DuckDBMaterializedResult_1.DuckDBMaterializedResult(await node_bindings_1.default.execute_prepared(this.prepared_statement));
     }