@haybarn/node-api 1.5.6-rc1 → 2.0.0-rc3

package/README.md

@@ -1,6 +1,13 @@
+<p align="center">
+  <a href="https://query.farm/products/haybarn/"><img src="https://raw.githubusercontent.com/Query-farm-haybarn/.github/haybarn/profile/assets/haybarn-icon.png" alt="Haybarn" width="120" height="120"></a>
+</p>
+<p align="center">
+  <a href="https://query.farm"><img src="https://query.farm/media-kit/logo/wordmark-light.png" alt="Query.Farm" height="28"></a>
+</p>
+
 # Haybarn Node API
 
-A high-level Node API for [Haybarn](https://github.com/Query-farm-haybarn/haybarn),
+A high-level Node API for [Haybarn](https://query.farm/products/haybarn/),
 a derived distribution of [DuckDB](https://duckdb.org/) (powered by DuckDB),
 published by Query Farm LLC.
 
@@ -213,16 +220,50 @@ These are:
 | `LIST` | `listValue` |
 | `MAP` | `mapValue` |
 | `STRUCT` | `structValue` |
+| `STRUCT` (unnamed, a tuple) | `tupleValue` |
 | `TIME` | `timeValue` |
 | `TIMETZ` | `timeTZValue` |
 | `TIMESTAMP` | `timestampValue` |
 | `TIMESTAMPTZ` | `timestampTZValue` |
+| `TIMESTAMPTZ_NS` | `timestampTZNanosValue` |
 | `TIMESTAMP_S` | `timestampSecondsValue` |
 | `TIMESTAMP_MS` | `timestampMillisValue` |
 | `TIMESTAMP_NS` | `timestampNanosValue` |
 | `UNION` | `unionValue` |
 | `UUID` | `uuidValue` |
 
+Alternatively, `jsToDuckDBValue` converts a plain JS value to the form
+a given DuckDB type expects, so these functions need not be called
+directly:
+
+```ts
+import { jsToDuckDBValue, DATE, TIMESTAMP_MS } from '@haybarn/node-api';
+
+jsToDuckDBValue(new Date('2024-01-15T12:34:56.789Z'), TIMESTAMP_MS);
+// same as timestampMillisValue(1705322096789n)
+
+jsToDuckDBValue(new Date('2024-01-15T00:00:00.000Z'), DATE);
+// same as dateValue(19737)
+
+jsToDuckDBValue(null, DATE); // null, for any type
+```
+
+It is generic over the type, so a statically known one checks its input:
+
+```ts
+jsToDuckDBValue(new Date(), TIMESTAMP); // ok
+jsToDuckDBValue(new Date(), INTEGER);   // rejected at compile time
+```
+
+What each type accepts is given by `JSInputTypeForTypeId`, and by
+`JSInputTypeFor` when keyed by a `DuckDBType`. These are wider than
+what is read back where a second spelling is unambiguous: `BIGINT` and
+the wider integers accept `number` as well as `bigint`, and `DECIMAL`
+accepts either a double or a raw scaled `bigint`.
+
+The result is a `DuckDBValue`, which is what `appendValue`,
+`bindValue`, and `setRows` all accept.
+
 ### Stream Results
 
 Streaming results evaluate lazily when rows are read.
@@ -231,6 +272,38 @@ Streaming results evaluate lazily when rows are read.
 const result = await connection.stream('from range(10_000)');
 ```
 
+### Close Results
+
+Results are destroyed automatically soon after their reference is
+dropped, but you can also close them explicitly to free their memory:
+
+```ts
+result.closeSync();
+```
+
+From DuckDB 2.0, a streaming result that hasn't been read to the end, or
+a pending result that hasn't been executed, blocks its connection: the
+next statement on it fails until the result is closed. A result reader
+or pending result can be closed the same way:
+
+```ts
+const reader = await connection.streamAndReadUntil(sql, 100);
+reader.closeSync();
+const rows = reader.getRows(); // rows already read stay available
+```
+
+Column names and types also stay available after closing; reading more
+rows throws.
+
+The same applies to appenders: from DuckDB 2.0, an appender can't flush
+while its connection has such a result. Appenders flush on `flushSync()`
+and `closeSync()`, and automatically about every 204,800 rows, so with a
+streaming result open, appending fails at the next flush, and the rows
+appended since the last successful flush are lost. Read the result to the
+end or close it before appending, or append on a separate connection.
+Close appenders explicitly too: one that is flushed when it's garbage
+collected can't report a failure.
+
 ### Inspect Result Metadata
 
 Get column names and types:
@@ -577,6 +650,45 @@ const columnNameAndTypeObjects = reader.columnNameAndTypeObjectsJson();
 // ]
 ```
 
+### Infer JS Types from DuckDB Types
+
+The mapping each converter applies is also available at the type level.
+`JSTypeFor` gives the JS type that `getRowsJS` and the other `JS` methods
+produce for a given DuckDB type; `JsonTypeFor` does the same for the `Json`
+methods.
+
+```ts
+import {
+  JSTypeFor,
+  JsonTypeFor,
+  DuckDBBigIntType,
+  DuckDBIntegerType,
+  DuckDBTimestampTZType,
+} from '@haybarn/node-api';
+
+type A = JSTypeFor<DuckDBIntegerType>;     // number
+type B = JSTypeFor<DuckDBBigIntType>;      // bigint
+type C = JSTypeFor<DuckDBTimestampTZType>; // Date
+
+type D = JsonTypeFor<DuckDBBigIntType>;      // string
+type E = JsonTypeFor<DuckDBTimestampTZType>; // string
+```
+
+The two differ wherever a value has no lossless JSON form: 64-bit and
+wider integers, temporal types, `DECIMAL`, `BLOB`, `BIT` and `GEOMETRY`
+render as strings, and `FLOAT` and `DOUBLE` widen to `number | string`
+so that Infinity and NaN survive.
+
+Both are also available keyed by type id, as `JSTypeForTypeId` and
+`JsonTypeForTypeId`, which is the form to use when the id is what you have:
+
+```ts
+type F = JSTypeForTypeId[DuckDBTypeId.INTEGER]; // number
+```
+
+These describe non-NULL values. Since any column can be NULL, a value read
+from one is `JSTypeFor<T> | null`.
+
 ### Fetch Chunks
 
 Fetch all chunks:
@@ -611,7 +723,8 @@ Get chunk data:
 ```ts
 const rows = chunk.getRows();
 
-const rowObjects = chunk.getRowObjects(result.deduplicatedColumnNames());
+const rowObjects =
+  chunk.getRowObjects(result.deduplicatedColumnNames());
 
 const columns = chunk.getColumns();
 
@@ -740,8 +853,13 @@ if (columnType.typeId === DuckDBTypeId.MAP) {
 }
 
 if (columnType.typeId === DuckDBTypeId.STRUCT) {
-  // { name1: value1, name2: value2, ... }
-  const structEntries = columnValue.entries;
+  if (columnType.isTuple) {
+    // An unnamed struct, such as (1, 'a'): items in entry order
+    const tupleItems = columnValue.items; // array of values
+  } else {
+    // { name1: value1, name2: value2, ... }
+    const structEntries = columnValue.entries;
+  }
   const structString = columnValue.toString();
 }
 
@@ -810,9 +928,9 @@ if (columnType.typeId === DuckDBTypeId.UUID) {
 
 ### Displaying Timezones
 
-Converting a TIMESTAMP_TZ value to a string depends on a timezone offset.
-By default, this is set to the offset for the local timezone when the Node
-process is started.
+Converting a TIMESTAMP_TZ or TIMESTAMPTZ_NS value to a string depends on
+a timezone offset. By default, this is set to the offset for the local
+timezone when the Node process is started.
 
 To change it, set the `timezoneOffsetInMinutes`
 property of `DuckDBTimestampTZValue`:
@@ -827,6 +945,9 @@ const cet = DuckDBTimestampTZValue.Epoch.toString();
 // 1970-01-01 01:00:00+01
 ```
 
+`DuckDBTimestampTZNanosecondsValue` (TIMESTAMPTZ_NS) uses the same
+`DuckDBTimestampTZValue.timezoneOffsetInMinutes` setting.
+
 Note that the timezone offset used for this string
 conversion is distinct from the `TimeZone` setting of DuckDB.
 
@@ -853,11 +974,13 @@ appender.appendInteger(42);
 appender.appendVarchar('duck');
 appender.endRow();
 
+appender.flushSync();
+
 appender.appendInteger(123);
 appender.appendVarchar('mallard');
 appender.endRow();
 
-appender.flushSync();
+appender.clear(); // discards the unflushed 'mallard' row
 
 appender.appendInteger(17);
 appender.appendVarchar('goose');
@@ -893,6 +1016,87 @@ appender.flushSync();
 
 See "Specifying Values" above for how to supply values to the appender.
 
+### Append Data Chunk of JS Values
+
+`setRowsConverted` and `setColumnsConverted` fill a data chunk from
+values in another representation, converting on the way in.
+`JSToDuckDBValueConverter` converts from plain JS, so a `Date` can be
+written to a `TIMESTAMP` column without constructing a
+`DuckDBTimestampValue` first:
+
+```ts
+import {
+  DuckDBDataChunk,
+  JSToDuckDBValueConverter,
+  INTEGER,
+  TIMESTAMP,
+  VARCHAR,
+} from '@haybarn/node-api';
+
+await connection.run(
+  `create or replace table target_table(
+    i integer, v varchar, t timestamp
+  )`
+);
+
+const appender = await connection.createAppender('target_table');
+
+const chunk = DuckDBDataChunk.create([INTEGER, VARCHAR, TIMESTAMP]);
+chunk.setRowsConverted(
+  [
+    [42, 'duck', new Date('2024-01-15T12:34:56.000Z')],
+    [123, 'mallard', null],
+  ],
+  JSToDuckDBValueConverter
+);
+
+appender.appendDataChunk(chunk);
+appender.flushSync();
+```
+
+The column types come from the chunk, so no types are passed to the
+converter. `setColumnValuesConverted` does the same for a single
+column.
+
+### Buffer Rows Into Data Chunks
+
+`DuckDBDataChunkWriter` accumulates rows and emits them as filled data
+chunks, for callers producing a row at a time. `forAppender` takes the
+column types from the appender:
+
+```ts
+import {
+  DuckDBDataChunkWriter,
+  JSToDuckDBValueConverter,
+} from '@haybarn/node-api';
+
+await connection.run(
+  `create or replace table target_table(i integer, v varchar)`
+);
+
+const appender = await connection.createAppender('target_table');
+
+const writer = DuckDBDataChunkWriter.forAppender(appender, {
+  converter: JSToDuckDBValueConverter,
+});
+
+writer.appendRow([42, 'duck']);
+writer.appendRow([123, 'mallard']);
+writer.appendRow([17, 'goose']);
+
+// Emits the buffered rows. The last chunk is usually a partial one.
+writer.flush();
+appender.closeSync();
+```
+
+A chunk is emitted every `rowsPerDataChunk` rows, which defaults to the
+DuckDB vector size. Omit the converter to write `DuckDBValue`s instead.
+Rows are copied as they are appended, so the same array can be reused
+across calls.
+
+Callers who already have rows in chunk-sized batches do not need a writer;
+filling a data chunk directly, as above, avoids the buffering.
+
 ### Scalar Functions
 
 ```ts
@@ -919,6 +1123,93 @@ const rows = reader.getRows();
 // [ [ 5 ] ]
 ```
 
+An optional `initFunction` runs once per DuckDB worker thread, giving each thread
+its own state:
+
+```ts
+connection.registerScalarFunction(
+  DuckDBScalarFunction.create({
+    name: 'my_counter',
+    initFunction: (initInfo) => {
+      initInfo.setState({ next: 0 });
+    },
+    mainFunction: (functionInfo, input, output) => {
+      const state = functionInfo.state as { next: number };
+      for (let rowIndex = 0; rowIndex < input.rowCount; rowIndex++) {
+        output.setItem(rowIndex, state.next++);
+      }
+      output.flush();
+    },
+    returnType: INTEGER,
+    volatile: true,
+  })
+);
+const reader = await connection.runAndReadAll(
+  'select my_counter() from range(3)'
+);
+const rows = reader.getRows();
+// [ [ 0 ], [ 1 ], [ 2 ] ]
+```
+
+Marking the function `volatile` is required whenever its result depends on init
+state rather than only on its arguments: without it, DuckDB may treat the call as
+constant and evaluate it just once.
+
+Note that this is per-thread state, unlike a table function's `initData`, which is
+shared across the scan. Init info also exposes the client context, bind data, and
+extra info, and reports errors with `setError`. Callbacks are always run on the JS
+thread, so they are serialized even when DuckDB evaluates in parallel.
+
+### Table Functions
+
+```ts
+connection.registerTableFunction(
+  DuckDBTableFunction.create({
+    name: 'my_range',
+    parameterTypes: [INTEGER],
+    bindFunction: (info) => {
+      const count = info.getParameter(0) as number;
+      info.addResultColumn('n', INTEGER);
+      info.setBindData({ count });
+    },
+    initFunction: (info) => {
+      info.setInitData({ nextRow: 0 });
+    },
+    mainFunction: (info, output) => {
+      const { count } = info.bindData as { count: number };
+      const initData = info.initData as { nextRow: number };
+      const chunkSize = Math.min(2048, count - initData.nextRow);
+      // Set the row count before writing: that is what sizes the
+      // vectors.
+      // A row count of zero reports that the scan is finished.
+      output.rowCount = chunkSize;
+      if (chunkSize > 0) {
+        const column = output.getColumnVector(0);
+        for (let i = 0; i < chunkSize; i++) {
+          column.setItem(i, initData.nextRow + i);
+        }
+        column.flush();
+        initData.nextRow += chunkSize;
+      }
+    },
+  })
+);
+const reader =
+  await connection.runAndReadAll('select * from my_range(3)');
+const rows = reader.getRows();
+// [ [ 0 ], [ 1 ], [ 2 ] ]
+```
+
+The main function is called repeatedly until it reports a row count of zero.
+Bind data is read-only during the scan; use init data to track progress. Setting
+`supportsProjectionPushdown: true` makes DuckDB report the columns actually
+selected, which init can read with `getColumnIndexes`.
+
+For a scan that runs on several threads, set `maxThreads` from the init function
+and give each thread its own state with `localInitFunction`; the main function
+reads it with `localInitData`. Callbacks are always run on the JS thread, so they
+are serialized even when DuckDB scans in parallel.
+
 ### Extract Statements
 
 ```ts
@@ -1032,8 +1323,9 @@ const reader = await connection.streamAndReadAll(sql, values, types);
 const reader = await connection.streamAndReadUntil(sql, targetRowCount);
 const reader =
   await connection.streamAndReadUntil(sql, targetRowCount, values);
-const reader =
-  await connection.streamAndReadUntil(sql, targetRowCount, values, types);
+const reader = await connection.streamAndReadUntil(
+  sql, targetRowCount, values, types
+);
 
 // Prepared Statements
 
@@ -1044,7 +1336,8 @@ const prepared = await connection.prepare(sql);
 prepared.bind(values);
 prepared.bind(values, types);
 
-// Run the prepared statement. These mirror the methods on the connection.
+// Run the prepared statement. These mirror the methods on the
+// connection.
 const result = prepared.run();
 
 const reader = prepared.runAndRead();
@@ -1064,11 +1357,11 @@ const pending = await connection.start(sql);
 const pending = await connection.start(sql, values);
 const pending = await connection.start(sql, values, types);
 
-// The methods beginning with "startThenRead" provide some, but not full,
-// cooperative multithreading. They use pending results to split processing
-// into short tasks, but they fully materialize the result, which can
-// take some time (and memory). For full cooperative multithreading,
-// see the "startStreamThenRead" methods below.
+// The methods beginning with "startThenRead" provide some, but not
+// full, cooperative multithreading. They use pending results to split
+// processing into short tasks, but they fully materialize the result,
+// which can take some time (and memory). For full cooperative
+// multithreading, see the "startStreamThenRead" methods below.
 const reader = await connection.startThenRead(sql);
 const reader = await connection.startThenRead(sql, values);
 const reader = await connection.startThenRead(sql, values, types);
@@ -1080,8 +1373,9 @@ const reader = await connection.startThenReadAll(sql, values, types);
 const reader = await connection.startThenReadUntil(sql, targetRowCount);
 const reader =
   await connection.startThenReadUntil(sql, targetRowCount, values);
-const reader =
-  await connection.startThenReadUntil(sql, targetRowCount, values, types);
+const reader = await connection.startThenReadUntil(
+  sql, targetRowCount, values, types
+);
 
 // Create a pending, streaming result.
 const pending = await connection.startStream(sql);
@@ -1104,8 +1398,9 @@ const reader =
 
 const reader =
   await connection.startStreamThenReadUntil(sql, targetRowCount);
-const reader =
-  await connection.startStreamThenReadUntil(sql, targetRowCount, values);
+const reader = await connection.startStreamThenReadUntil(
+  sql, targetRowCount, values
+);
 const reader = await connection.startStreamThenReadUntil(
   sql, targetRowCount, values, types);
 

package/lib/DuckDBAppender.d.ts

@@ -1,12 +1,15 @@
 import duckdb from '@haybarn/node-bindings';
+import { DuckDBConnection } from './DuckDBConnection';
 import { DuckDBDataChunk } from './DuckDBDataChunk';
 import { DuckDBArrayType, DuckDBEnumType, DuckDBListType, DuckDBMapType, DuckDBStructType, DuckDBType, DuckDBUnionType } from './DuckDBType';
-import { DuckDBArrayValue, DuckDBBitValue, DuckDBDateValue, DuckDBDecimalValue, DuckDBIntervalValue, DuckDBListValue, DuckDBMapValue, DuckDBStructValue, DuckDBTimestampMillisecondsValue, DuckDBTimestampNanosecondsValue, DuckDBTimestampSecondsValue, DuckDBTimestampTZValue, DuckDBTimestampValue, DuckDBTimeTZValue, DuckDBTimeValue, DuckDBUnionValue, DuckDBUUIDValue, DuckDBValue } from './values';
+import { DuckDBArrayValue, DuckDBBitValue, DuckDBDateValue, DuckDBDecimalValue, DuckDBIntervalValue, DuckDBListValue, DuckDBMapValue, DuckDBStructValue, DuckDBTimestampMillisecondsValue, DuckDBTimestampNanosecondsValue, DuckDBTimestampSecondsValue, DuckDBTimestampTZValue, DuckDBTimestampTZNanosecondsValue, DuckDBTimestampValue, DuckDBTimeTZValue, DuckDBTimeValue, DuckDBTupleValue, DuckDBUnionValue, DuckDBUUIDValue, DuckDBValue, DuckDBVariantValue } from './values';
 export declare class DuckDBAppender {
+    readonly connection: DuckDBConnection;
     private readonly appender;
-    constructor(appender: duckdb.Appender);
+    constructor(connection: DuckDBConnection, appender: duckdb.Appender);
     closeSync(): void;
     flushSync(): void;
+    clear(): void;
     get columnCount(): number;
     columnType(columnIndex: number): DuckDBType;
     endRow(): void;
@@ -30,6 +33,7 @@ export declare class DuckDBAppender {
     appendTimeTZ(value: DuckDBTimeTZValue): void;
     appendTimestamp(value: DuckDBTimestampValue): void;
     appendTimestampTZ(value: DuckDBTimestampTZValue): void;
+    appendTimestampTZNanoseconds(value: DuckDBTimestampTZNanosecondsValue): void;
     appendTimestampSeconds(value: DuckDBTimestampSecondsValue): void;
     appendTimestampMilliseconds(value: DuckDBTimestampMillisecondsValue): void;
     appendTimestampNanoseconds(value: DuckDBTimestampNanosecondsValue): void;
@@ -39,12 +43,14 @@ export declare class DuckDBAppender {
     appendEnum(value: string, type: DuckDBEnumType): void;
     appendList(value: DuckDBListValue | readonly DuckDBValue[], type?: DuckDBListType): void;
     appendStruct(value: DuckDBStructValue | Readonly<Record<string, DuckDBValue>>, type?: DuckDBStructType): void;
+    appendTuple(value: DuckDBTupleValue | readonly DuckDBValue[], type?: DuckDBStructType): void;
     appendMap(value: DuckDBMapValue, type?: DuckDBMapType): void;
     appendArray(value: DuckDBArrayValue | readonly DuckDBValue[], type?: DuckDBArrayType): void;
     appendUnion(value: DuckDBUnionValue, type?: DuckDBUnionType): void;
     appendUUID(value: DuckDBUUIDValue): void;
     appendBit(value: DuckDBBitValue): void;
     appendBigNum(value: bigint): void;
+    appendVariant(value: DuckDBVariantValue | null): void;
     appendNull(): void;
     appendValue(value: DuckDBValue, type?: DuckDBType): void;
     appendDataChunk(dataChunk: DuckDBDataChunk): void;

package/lib/DuckDBAppender.js

@@ -11,8 +11,10 @@ const DuckDBType_1 = require("./DuckDBType");
 const typeForValue_1 = require("./typeForValue");
 const values_1 = require("./values");
 class DuckDBAppender {
+    connection;
     appender;
-    constructor(appender) {
+    constructor(connection, appender) {
+        this.connection = connection;
         this.appender = appender;
     }
     closeSync() {
@@ -21,6 +23,9 @@ class DuckDBAppender {
     flushSync() {
         node_bindings_1.default.appender_flush_sync(this.appender);
     }
+    clear() {
+        node_bindings_1.default.appender_clear(this.appender);
+    }
     get columnCount() {
         return node_bindings_1.default.appender_column_count(this.appender);
     }
@@ -91,6 +96,9 @@ class DuckDBAppender {
     appendTimestampTZ(value) {
         this.appendValue(value, DuckDBType_1.TIMESTAMPTZ);
     }
+    appendTimestampTZNanoseconds(value) {
+        this.appendValue(value, DuckDBType_1.TIMESTAMPTZ_NS);
+    }
     appendTimestampSeconds(value) {
         this.appendValue(value, DuckDBType_1.TIMESTAMP_S);
     }
@@ -118,6 +126,9 @@ class DuckDBAppender {
     appendStruct(value, type) {
         this.appendValue(value instanceof values_1.DuckDBStructValue ? value : (0, values_1.structValue)(value), type);
     }
+    appendTuple(value, type) {
+        this.appendValue(value instanceof values_1.DuckDBTupleValue ? value : (0, values_1.tupleValue)(value), type);
+    }
     appendMap(value, type) {
         this.appendValue(value, type);
     }
@@ -136,6 +147,13 @@ class DuckDBAppender {
     appendBigNum(value) {
         this.appendValue(value, DuckDBType_1.BIGNUM);
     }
+    appendVariant(value) {
+        if (value === null) {
+            this.appendNull();
+            return;
+        }
+        this.appendValue(value, DuckDBType_1.VARIANT);
+    }
     appendNull() {
         node_bindings_1.default.append_null(this.appender);
     }

package/lib/DuckDBConnection.d.ts

@@ -9,6 +9,7 @@ import { DuckDBPreparedStatement } from './DuckDBPreparedStatement';
 import { DuckDBResult } from './DuckDBResult';
 import { DuckDBResultReader } from './DuckDBResultReader';
 import { DuckDBScalarFunction } from './DuckDBScalarFunction';
+import { DuckDBTableFunction } from './DuckDBTableFunction';
 import { DuckDBType } from './DuckDBType';
 import { DuckDBValue } from './values';
 export declare class DuckDBConnection {
@@ -45,5 +46,6 @@ export declare class DuckDBConnection {
     private runUntilLast;
     getTableNames(query: string, qualified: boolean): readonly string[];
     createAppender(table: string, schema?: string | null, catalog?: string | null): Promise<DuckDBAppender>;
+    registerTableFunction(tableFunction: DuckDBTableFunction): void;
     registerScalarFunction(scalarFunction: DuckDBScalarFunction): void;
 }

package/lib/DuckDBConnection.js

@@ -199,7 +199,10 @@ class DuckDBConnection {
         return names;
     }
     async createAppender(table, schema, catalog) {
-        return new DuckDBAppender_1.DuckDBAppender(node_bindings_1.default.appender_create_ext(this.connection, catalog ?? null, schema ?? null, table));
+        return new DuckDBAppender_1.DuckDBAppender(this, node_bindings_1.default.appender_create_ext(this.connection, catalog ?? null, schema ?? null, table));
+    }
+    registerTableFunction(tableFunction) {
+        node_bindings_1.default.register_table_function(this.connection, tableFunction.table_function);
     }
     registerScalarFunction(scalarFunction) {
         node_bindings_1.default.register_scalar_function(this.connection, scalarFunction.scalar_function);

package/lib/DuckDBDataChunk.d.ts

@@ -1,6 +1,7 @@
 import duckdb from '@haybarn/node-bindings';
 import { DuckDBType } from './DuckDBType';
 import { DuckDBValueConverter } from './DuckDBValueConverter';
+import { ToDuckDBValueConverter } from './ToDuckDBValueConverter';
 import { DuckDBVector } from './DuckDBVector';
 import { DuckDBValue } from './values';
 export declare class DuckDBDataChunk {
@@ -12,17 +13,38 @@ export declare class DuckDBDataChunk {
     get columnCount(): number;
     get rowCount(): number;
     set rowCount(count: number);
+    /**
+     * Refuses a column count that does not match the chunk's.
+     *
+     * A short array would leave the remaining vectors never written and never
+     * flushed while the chunk reports a non-zero row count, and reading or
+     * appending it then crashes the process instead of raising.
+     */
+    private assertColumnCount;
     getColumnVector(columnIndex: number): DuckDBVector;
     visitColumnValues(columnIndex: number, visitValue: (value: DuckDBValue, rowIndex: number, columnIndex: number, type: DuckDBType) => void): void;
     appendColumnValues(columnIndex: number, values: DuckDBValue[]): void;
     getColumnValues(columnIndex: number): DuckDBValue[];
     convertColumnValues<T>(columnIndex: number, converter: DuckDBValueConverter<T>): (T | null)[];
     setColumnValues(columnIndex: number, values: readonly DuckDBValue[]): void;
+    /**
+     * `setColumnValues` with each value converted on the way in: the write
+     * counterpart of `convertColumnValues`.
+     *
+     * The column's type comes from its vector, so the converter is the only
+     * thing the caller supplies.
+     */
+    setColumnValuesConverted<T>(columnIndex: number, values: readonly (T | null)[], converter: ToDuckDBValueConverter<T>): void;
     visitColumns(visitColumn: (column: DuckDBValue[], columnIndex: number, type: DuckDBType) => void): void;
     appendToColumns(columns: (DuckDBValue[] | undefined)[]): void;
     getColumns(): DuckDBValue[][];
     convertColumns<T>(converter: DuckDBValueConverter<T>): (T | null)[][];
     setColumns(columns: readonly (readonly DuckDBValue[])[]): void;
+    /**
+     * `setColumns` with each value converted on the way in: the write
+     * counterpart of `convertColumns`.
+     */
+    setColumnsConverted<T>(columns: readonly (readonly (T | null)[])[], converter: ToDuckDBValueConverter<T>): void;
     appendToColumnsObject(columnNames: readonly string[], columnsObject: Record<string, DuckDBValue[] | undefined>): void;
     getColumnsObject(columnNames: readonly string[]): Record<string, DuckDBValue[]>;
     visitColumnMajor(visitValue: (value: DuckDBValue, rowIndex: number, columnIndex: number, type: DuckDBType) => void): void;
@@ -35,6 +57,14 @@ export declare class DuckDBDataChunk {
     getRows(): DuckDBValue[][];
     convertRows<T>(converter: DuckDBValueConverter<T>): (T | null)[][];
     setRows(rows: readonly (readonly DuckDBValue[])[]): void;
+    /**
+     * `setRows` with each value converted on the way in: the write counterpart
+     * of `convertRows`.
+     *
+     * Each column's type comes from its vector, so the converter is the only
+     * thing the caller supplies.
+     */
+    setRowsConverted<T>(rows: readonly (readonly (T | null)[])[], converter: ToDuckDBValueConverter<T>): void;
     appendToRowObjects(columnNames: readonly string[], rowObjects: Record<string, DuckDBValue>[]): void;
     getRowObjects(columnNames: readonly string[]): Record<string, DuckDBValue>[];
     visitRowMajor(visitValue: (value: DuckDBValue, rowIndex: number, columnIndex: number, type: DuckDBType) => void): void;