@duckdb/node-api 1.2.1-alpha.17 → 1.2.2-alpha.19

package/README.md

@@ -4,26 +4,26 @@ An API for using [DuckDB](https://duckdb.org/) in [Node](https://nodejs.org/).
 
 This is a high-level API meant for applications.
 It depends on low-level bindings that adhere closely to [DuckDB's C API](https://duckdb.org/docs/api/c/overview),
-available separately as [@duckdb/duckdb-bindings](https://www.npmjs.com/package/@duckdb/node-bindings).
+available separately as [@duckdb/node-bindings](https://www.npmjs.com/package/@duckdb/node-bindings).
 
 ## Features
 
-### Main differences from [duckdb-node](https://www.npmjs.com/package/duckdb)
-- Native support for Promises; no need for separate [duckdb-async](https://www.npmjs.com/package/duckdb-async) wrapper.
-- DuckDB-specific API; not based on the [SQLite Node API](https://www.npmjs.com/package/sqlite3).
-- Lossless & efficent support for values of all [DuckDB data types](https://duckdb.org/docs/sql/data_types/overview).
-- Wraps [released DuckDB binaries](https://github.com/duckdb/duckdb/releases) instead of rebuilding DuckDB.
-- Built on [DuckDB's C API](https://duckdb.org/docs/api/c/overview); exposes more functionality.
+### Main Differences from [duckdb-node](https://www.npmjs.com/package/duckdb)
+* Native support for Promises; no need for separate [duckdb-async](https://www.npmjs.com/package/duckdb-async) wrapper.
+* DuckDB-specific API; not based on the [SQLite Node API](https://www.npmjs.com/package/sqlite3).
+* Lossless & efficent support for values of all [DuckDB data types](https://duckdb.org/docs/sql/data_types/overview).
+* Wraps [released DuckDB binaries](https://github.com/duckdb/duckdb/releases) instead of rebuilding DuckDB.
+* Built on [DuckDB's C API](https://duckdb.org/docs/api/c/overview); exposes more functionality.
 
 ### Roadmap
 
 Some features are not yet complete:
-- Binding and appending the MAP and UNION data types
-- Appending default values row-by-row
-- User-defined types & functions
-- Profiling info
-- Table description
-- APIs for Arrow
+* Binding and appending the MAP and UNION data types
+* Appending default values row-by-row
+* User-defined types & functions
+* Profiling info
+* Table description
+* APIs for Arrow
 
 See the [issues list on GitHub](https://github.com/duckdb/duckdb-node-neo/issues)
 for the most up-to-date roadmap.
@@ -118,13 +118,13 @@ Connections will be disconnected automatically soon after their reference
 is dropped, but you can also disconnect explicitly if and when you want:
 
 ```ts
-connection.disconnect();
+connection.disconnectSync();
 ```
 
 or, equivalently:
 
 ```ts
-connection.close();
+connection.closeSync();
 ```
 
 ### Run SQL
@@ -140,6 +140,7 @@ 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));
+// OR, with type inference: prepared.bindList(3, [10, 11, 12]);
 const result = await prepared.run();
 ```
 
@@ -847,13 +848,13 @@ appender.appendInteger(123);
 appender.appendVarchar('mallard');
 appender.endRow();
 
-appender.flush();
+appender.flushSync();
 
 appender.appendInteger(17);
 appender.appendVarchar('goose');
 appender.endRow();
 
-appender.close(); // also flushes
+appender.closeSync(); // also flushes
 ```
 
 ### Append Data Chunk
@@ -878,7 +879,7 @@ chunk.setColumns([
 // ]);
 
 appender.appendDataChunk(chunk);
-appender.flush();
+appender.flushSync();
 ```
 
 See "Specifying Values" above for how to supply values to the appender.

package/lib/DuckDBAppender.d.ts

@@ -37,13 +37,13 @@ export declare class DuckDBAppender {
     appendVarchar(value: string): void;
     appendBlob(value: Uint8Array): void;
     appendEnum(value: string, type: DuckDBEnumType): void;
-    appendList(value: DuckDBListValue, type: DuckDBListType): void;
-    appendStruct(value: DuckDBStructValue, type: DuckDBStructType): void;
-    appendArray(value: DuckDBArrayValue, type: DuckDBArrayType): void;
+    appendList(value: DuckDBListValue | readonly DuckDBValue[], type?: DuckDBListType): void;
+    appendStruct(value: DuckDBStructValue | Readonly<Record<string, DuckDBValue>>, type?: DuckDBStructType): void;
+    appendArray(value: DuckDBArrayValue | readonly DuckDBValue[], type?: DuckDBArrayType): void;
     appendUUID(value: DuckDBUUIDValue): void;
     appendBit(value: DuckDBBitValue): void;
     appendVarInt(value: bigint): void;
     appendNull(): void;
-    appendValue(value: DuckDBValue, type: DuckDBType): void;
+    appendValue(value: DuckDBValue, type?: DuckDBType): void;
     appendDataChunk(dataChunk: DuckDBDataChunk): void;
 }

package/lib/DuckDBAppender.js

@@ -8,6 +8,8 @@ const node_bindings_1 = __importDefault(require("@duckdb/node-bindings"));
 const createValue_1 = require("./createValue");
 const DuckDBLogicalType_1 = require("./DuckDBLogicalType");
 const DuckDBType_1 = require("./DuckDBType");
+const typeForValue_1 = require("./typeForValue");
+const values_1 = require("./values");
 class DuckDBAppender {
     appender;
     constructor(appender) {
@@ -111,14 +113,14 @@ class DuckDBAppender {
         this.appendValue(value, type);
     }
     appendList(value, type) {
-        this.appendValue(value, type);
+        this.appendValue(value instanceof values_1.DuckDBListValue ? value : (0, values_1.listValue)(value), type);
     }
     appendStruct(value, type) {
-        this.appendValue(value, type);
+        this.appendValue(value instanceof values_1.DuckDBStructValue ? value : (0, values_1.structValue)(value), type);
     }
     // TODO: MAP (when DuckDB C API supports creating MAP values)
     appendArray(value, type) {
-        this.appendValue(value, type);
+        this.appendValue(value instanceof values_1.DuckDBArrayValue ? value : (0, values_1.arrayValue)(value), type);
     }
     // TODO: UNION (when DuckDB C API supports creating UNION values)
     appendUUID(value) {
@@ -134,7 +136,7 @@ class DuckDBAppender {
         node_bindings_1.default.append_null(this.appender);
     }
     appendValue(value, type) {
-        node_bindings_1.default.append_value(this.appender, (0, createValue_1.createValue)(type, value));
+        node_bindings_1.default.append_value(this.appender, (0, createValue_1.createValue)(type ? type : (0, typeForValue_1.typeForValue)(value), value));
     }
     appendDataChunk(dataChunk) {
         node_bindings_1.default.append_data_chunk(this.appender, dataChunk.chunk);

package/lib/DuckDBConnection.d.ts

@@ -11,6 +11,7 @@ import { DuckDBType } from './DuckDBType';
 import { DuckDBValue } from './values';
 export declare class DuckDBConnection {
     private readonly connection;
+    private readonly preparedStatements;
     constructor(connection: duckdb.Connection);
     static create(instance?: DuckDBInstance): Promise<DuckDBConnection>;
     /** Same as disconnectSync. */
@@ -29,6 +30,7 @@ export declare class DuckDBConnection {
     start(sql: string, values?: DuckDBValue[] | Record<string, DuckDBValue>, types?: DuckDBType[] | Record<string, DuckDBType | undefined>): Promise<DuckDBPendingResult>;
     startStream(sql: string, values?: DuckDBValue[] | Record<string, DuckDBValue>, types?: DuckDBType[] | Record<string, DuckDBType | undefined>): Promise<DuckDBPendingResult>;
     prepare(sql: string): Promise<DuckDBPreparedStatement>;
+    private createPrepared;
     extractStatements(sql: string): Promise<DuckDBExtractedStatements>;
     createAppender(table: string, schema?: string | null, catalog?: string | null): Promise<DuckDBAppender>;
 }

package/lib/DuckDBConnection.js

@@ -10,11 +10,14 @@ const DuckDBExtractedStatements_1 = require("./DuckDBExtractedStatements");
 const DuckDBInstance_1 = require("./DuckDBInstance");
 const DuckDBMaterializedResult_1 = require("./DuckDBMaterializedResult");
 const DuckDBPreparedStatement_1 = require("./DuckDBPreparedStatement");
+const DuckDBPreparedStatementWeakRefCollection_1 = require("./DuckDBPreparedStatementWeakRefCollection");
 const DuckDBResultReader_1 = require("./DuckDBResultReader");
 class DuckDBConnection {
     connection;
+    preparedStatements;
     constructor(connection) {
         this.connection = connection;
+        this.preparedStatements = new DuckDBPreparedStatementWeakRefCollection_1.DuckDBPreparedStatementWeakRefCollection();
     }
     static async create(instance) {
         if (instance) {
@@ -27,6 +30,7 @@ class DuckDBConnection {
         return this.disconnectSync();
     }
     disconnectSync() {
+        this.preparedStatements.destroySync();
         return node_bindings_1.default.disconnect_sync(this.connection);
     }
     interrupt() {
@@ -37,9 +41,14 @@ class DuckDBConnection {
     }
     async run(sql, values, types) {
         if (values) {
-            const prepared = await this.prepare(sql);
-            prepared.bind(values, types);
-            return prepared.run();
+            const prepared = await this.createPrepared(sql);
+            try {
+                prepared.bind(values, types);
+                return prepared.run();
+            }
+            finally {
+                prepared.destroySync();
+            }
         }
         else {
             return new DuckDBMaterializedResult_1.DuckDBMaterializedResult(await node_bindings_1.default.query(this.connection, sql));
@@ -59,11 +68,16 @@ class DuckDBConnection {
         return reader;
     }
     async stream(sql, values, types) {
-        const prepared = await this.prepare(sql);
-        if (values) {
-            prepared.bind(values, types);
+        const prepared = await this.createPrepared(sql);
+        try {
+            if (values) {
+                prepared.bind(values, types);
+            }
+            return prepared.stream();
+        }
+        finally {
+            prepared.destroySync();
         }
-        return prepared.stream();
     }
     async streamAndRead(sql, values, types) {
         return new DuckDBResultReader_1.DuckDBResultReader(await this.stream(sql, values, types));
@@ -79,20 +93,35 @@ class DuckDBConnection {
         return reader;
     }
     async start(sql, values, types) {
-        const prepared = await this.prepare(sql);
-        if (values) {
-            prepared.bind(values, types);
+        const prepared = await this.createPrepared(sql);
+        try {
+            if (values) {
+                prepared.bind(values, types);
+            }
+            return prepared.start();
+        }
+        finally {
+            prepared.destroySync();
         }
-        return prepared.start();
     }
     async startStream(sql, values, types) {
-        const prepared = await this.prepare(sql);
-        if (values) {
-            prepared.bind(values, types);
+        const prepared = await this.createPrepared(sql);
+        try {
+            if (values) {
+                prepared.bind(values, types);
+            }
+            return prepared.startStream();
+        }
+        finally {
+            prepared.destroySync();
         }
-        return prepared.startStream();
     }
     async prepare(sql) {
+        const prepared = await this.createPrepared(sql);
+        this.preparedStatements.add(prepared);
+        return prepared;
+    }
+    async createPrepared(sql) {
         return new DuckDBPreparedStatement_1.DuckDBPreparedStatement(await node_bindings_1.default.prepare(this.connection, sql));
     }
     async extractStatements(sql) {
@@ -100,7 +129,7 @@ class DuckDBConnection {
         if (statement_count === 0) {
             throw new Error(`Failed to extract statements: ${node_bindings_1.default.extract_statements_error(extracted_statements)}`);
         }
-        return new DuckDBExtractedStatements_1.DuckDBExtractedStatements(this.connection, extracted_statements, statement_count);
+        return new DuckDBExtractedStatements_1.DuckDBExtractedStatements(this.connection, extracted_statements, statement_count, this.preparedStatements);
     }
     async createAppender(table, schema, catalog) {
         return new DuckDBAppender_1.DuckDBAppender(node_bindings_1.default.appender_create_ext(this.connection, catalog ?? null, schema ?? null, table));

package/lib/DuckDBDataChunk.js

@@ -29,6 +29,10 @@ class DuckDBDataChunk {
         return node_bindings_1.default.data_chunk_get_size(this.chunk);
     }
     set rowCount(count) {
+        const maxRowCount = node_bindings_1.default.vector_size();
+        if (count > maxRowCount) {
+            throw new Error(`A data chunk cannot have more than ${maxRowCount} rows`);
+        }
         node_bindings_1.default.data_chunk_set_size(this.chunk, count);
     }
     getColumnVector(columnIndex) {

package/lib/DuckDBExtractedStatements.d.ts

@@ -1,10 +1,12 @@
 import duckdb from '@duckdb/node-bindings';
 import { DuckDBPreparedStatement } from './DuckDBPreparedStatement';
+import { DuckDBPreparedStatementCollection } from './DuckDBPreparedStatementCollection';
 export declare class DuckDBExtractedStatements {
     private readonly connection;
     private readonly extracted_statements;
     private readonly statement_count;
-    constructor(connection: duckdb.Connection, extracted_statements: duckdb.ExtractedStatements, statement_count: number);
+    private readonly preparedStatements?;
+    constructor(connection: duckdb.Connection, extracted_statements: duckdb.ExtractedStatements, statement_count: number, preparedStatements?: DuckDBPreparedStatementCollection);
     get count(): number;
     prepare(index: number): Promise<DuckDBPreparedStatement>;
 }

package/lib/DuckDBExtractedStatements.js

@@ -10,16 +10,22 @@ class DuckDBExtractedStatements {
     connection;
     extracted_statements;
     statement_count;
-    constructor(connection, extracted_statements, statement_count) {
+    preparedStatements;
+    constructor(connection, extracted_statements, statement_count, preparedStatements) {
         this.connection = connection;
         this.extracted_statements = extracted_statements;
         this.statement_count = statement_count;
+        this.preparedStatements = preparedStatements;
     }
     get count() {
         return this.statement_count;
     }
     async prepare(index) {
-        return new DuckDBPreparedStatement_1.DuckDBPreparedStatement(await node_bindings_1.default.prepare_extracted_statement(this.connection, this.extracted_statements, index));
+        const prepared = new DuckDBPreparedStatement_1.DuckDBPreparedStatement(await node_bindings_1.default.prepare_extracted_statement(this.connection, this.extracted_statements, index));
+        if (this.preparedStatements) {
+            this.preparedStatements.add(prepared);
+        }
+        return prepared;
     }
 }
 exports.DuckDBExtractedStatements = DuckDBExtractedStatements;

package/lib/DuckDBPreparedStatement.d.ts

@@ -10,6 +10,7 @@ import { DuckDBArrayValue, DuckDBBitValue, DuckDBDateValue, DuckDBDecimalValue,
 export declare class DuckDBPreparedStatement {
     private readonly prepared_statement;
     constructor(prepared_statement: duckdb.PreparedStatement);
+    destroySync(): void;
     get statementType(): StatementType;
     get parameterCount(): number;
     parameterName(parameterIndex: number): string;
@@ -44,13 +45,13 @@ export declare class DuckDBPreparedStatement {
     bindVarchar(parameterIndex: number, value: string): void;
     bindBlob(parameterIndex: number, value: Uint8Array): void;
     bindEnum(parameterIndex: number, value: string, type: DuckDBEnumType): 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;
+    bindArray(parameterIndex: number, value: DuckDBArrayValue | readonly DuckDBValue[], type?: DuckDBArrayType): void;
+    bindList(parameterIndex: number, value: DuckDBListValue | readonly DuckDBValue[], type?: DuckDBListType): void;
+    bindStruct(parameterIndex: number, value: DuckDBStructValue | Readonly<Record<string, DuckDBValue>>, type?: DuckDBStructType): void;
     bindUUID(parameterIndex: number, value: DuckDBUUIDValue): void;
     bindBit(parameterIndex: number, value: DuckDBBitValue): void;
     bindNull(parameterIndex: number): void;
-    bindValue(parameterIndex: number, value: DuckDBValue, type: DuckDBType): void;
+    bindValue(parameterIndex: number, value: DuckDBValue, type?: DuckDBType): void;
     bind(values: DuckDBValue[] | Record<string, DuckDBValue>, types?: DuckDBType[] | Record<string, DuckDBType | undefined>): void;
     run(): Promise<DuckDBMaterializedResult>;
     runAndRead(): Promise<DuckDBResultReader>;

package/lib/DuckDBPreparedStatement.js

@@ -13,11 +13,15 @@ const DuckDBResult_1 = require("./DuckDBResult");
 const DuckDBResultReader_1 = require("./DuckDBResultReader");
 const DuckDBType_1 = require("./DuckDBType");
 const typeForValue_1 = require("./typeForValue");
+const values_1 = require("./values");
 class DuckDBPreparedStatement {
     prepared_statement;
     constructor(prepared_statement) {
         this.prepared_statement = prepared_statement;
     }
+    destroySync() {
+        return node_bindings_1.default.destroy_prepare_sync(this.prepared_statement);
+    }
     get statementType() {
         return node_bindings_1.default.prepared_statement_type(this.prepared_statement);
     }
@@ -121,13 +125,13 @@ class DuckDBPreparedStatement {
         this.bindValue(parameterIndex, value, type);
     }
     bindArray(parameterIndex, value, type) {
-        this.bindValue(parameterIndex, value, type);
+        this.bindValue(parameterIndex, value instanceof values_1.DuckDBArrayValue ? value : (0, values_1.arrayValue)(value), type);
     }
     bindList(parameterIndex, value, type) {
-        this.bindValue(parameterIndex, value, type);
+        this.bindValue(parameterIndex, value instanceof values_1.DuckDBListValue ? value : (0, values_1.listValue)(value), type);
     }
     bindStruct(parameterIndex, value, type) {
-        this.bindValue(parameterIndex, value, type);
+        this.bindValue(parameterIndex, value instanceof values_1.DuckDBStructValue ? value : (0, values_1.structValue)(value), type);
     }
     // TODO: bind MAP, UNION
     bindUUID(parameterIndex, value) {
@@ -140,24 +144,19 @@ class DuckDBPreparedStatement {
         node_bindings_1.default.bind_null(this.prepared_statement, parameterIndex);
     }
     bindValue(parameterIndex, value, type) {
-        node_bindings_1.default.bind_value(this.prepared_statement, parameterIndex, (0, createValue_1.createValue)(type, value));
+        node_bindings_1.default.bind_value(this.prepared_statement, parameterIndex, (0, createValue_1.createValue)(type ? type : (0, typeForValue_1.typeForValue)(value), 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]));
+                this.bindValue(i + 1, values[i], typesIsArray ? types[i] : undefined);
             }
         }
         else {
             const typesIsRecord = types && !Array.isArray(types);
             for (const key in values) {
-                const index = this.parameterIndex(key);
-                let type = typesIsRecord ? types[key] : undefined;
-                if (type === undefined) {
-                    type = (0, typeForValue_1.typeForValue)(values[key]);
-                }
-                this.bindValue(index, values[key], type);
+                this.bindValue(this.parameterIndex(key), values[key], typesIsRecord ? types[key] : undefined);
             }
         }
     }

package/lib/DuckDBPreparedStatementCollection.d.ts

@@ -0,0 +1,4 @@
+import { DuckDBPreparedStatement } from './DuckDBPreparedStatement';
+export interface DuckDBPreparedStatementCollection {
+    add(prepared: DuckDBPreparedStatement): void;
+}

package/lib/DuckDBPreparedStatementCollection.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/DuckDBPreparedStatementWeakRefCollection.d.ts

@@ -0,0 +1,8 @@
+import { DuckDBPreparedStatement } from './DuckDBPreparedStatement';
+import { DuckDBPreparedStatementCollection } from './DuckDBPreparedStatementCollection';
+export declare class DuckDBPreparedStatementWeakRefCollection implements DuckDBPreparedStatementCollection {
+    preparedStatements: WeakRef<DuckDBPreparedStatement>[];
+    add(prepared: DuckDBPreparedStatement): void;
+    destroySync(): void;
+    private prune;
+}

package/lib/DuckDBPreparedStatementWeakRefCollection.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DuckDBPreparedStatementWeakRefCollection = void 0;
+class DuckDBPreparedStatementWeakRefCollection {
+    preparedStatements = [];
+    add(prepared) {
+        this.prune();
+        this.preparedStatements.push(new WeakRef(prepared));
+    }
+    destroySync() {
+        for (const preparedRef of this.preparedStatements) {
+            const prepared = preparedRef.deref();
+            if (prepared) {
+                prepared.destroySync();
+            }
+        }
+        this.preparedStatements = [];
+    }
+    prune() {
+        this.preparedStatements = this.preparedStatements.filter((ref) => !!ref.deref());
+    }
+}
+exports.DuckDBPreparedStatementWeakRefCollection = DuckDBPreparedStatementWeakRefCollection;

package/lib/duckdb.d.ts

@@ -10,6 +10,7 @@ export * from './DuckDBLogicalType';
 export * from './DuckDBMaterializedResult';
 export * from './DuckDBPendingResult';
 export * from './DuckDBPreparedStatement';
+export * from './DuckDBPreparedStatementCollection';
 export * from './DuckDBResult';
 export * from './DuckDBType';
 export * from './DuckDBTypeId';

package/lib/duckdb.js

@@ -31,6 +31,7 @@ __exportStar(require("./DuckDBLogicalType"), exports);
 __exportStar(require("./DuckDBMaterializedResult"), exports);
 __exportStar(require("./DuckDBPendingResult"), exports);
 __exportStar(require("./DuckDBPreparedStatement"), exports);
+__exportStar(require("./DuckDBPreparedStatementCollection"), exports);
 __exportStar(require("./DuckDBResult"), exports);
 __exportStar(require("./DuckDBType"), exports);
 __exportStar(require("./DuckDBTypeId"), exports);

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@duckdb/node-api",
-  "version": "1.2.1-alpha.17",
+  "version": "1.2.2-alpha.19",
   "license": "MIT",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
   "dependencies": {
-    "@duckdb/node-bindings": "1.2.1-alpha.17"
+    "@duckdb/node-bindings": "1.2.2-alpha.19"
   },
   "repository": {
     "type": "git",