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

package/lib/ToDuckDBValueConverters.js

@@ -0,0 +1,199 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.unwritableConverter = unwritableConverter;
+exports.nullFromNull = nullFromNull;
+exports.valueFromBoolean = valueFromBoolean;
+exports.valueFromNumber = valueFromNumber;
+exports.bigintFromNumeric = bigintFromNumeric;
+exports.valueFromString = valueFromString;
+exports.blobValueFromBytes = blobValueFromBytes;
+exports.bitValueFromBytes = bitValueFromBytes;
+exports.geometryValueFromBytes = geometryValueFromBytes;
+exports.dateValueFromDate = dateValueFromDate;
+exports.timeValueFromMicros = timeValueFromMicros;
+exports.timeNSValueFromNanos = timeNSValueFromNanos;
+exports.timeTZValueFromObject = timeTZValueFromObject;
+exports.timestampValueFromDate = timestampValueFromDate;
+exports.timestampTZValueFromDate = timestampTZValueFromDate;
+exports.timestampTZNanosValueFromDate = timestampTZNanosValueFromDate;
+exports.timestampSecondsValueFromDate = timestampSecondsValueFromDate;
+exports.timestampMillisValueFromDate = timestampMillisValueFromDate;
+exports.timestampNanosValueFromDate = timestampNanosValueFromDate;
+exports.intervalValueFromObject = intervalValueFromObject;
+exports.decimalValueFromNumeric = decimalValueFromNumeric;
+exports.uuidValueFromString = uuidValueFromString;
+exports.listValueFromArray = listValueFromArray;
+exports.arrayValueFromArray = arrayValueFromArray;
+exports.structValueFromObject = structValueFromObject;
+exports.mapValueFromEntries = mapValueFromEntries;
+exports.unionValueFromObject = unionValueFromObject;
+exports.variantValueFromJS = variantValueFromJS;
+const DuckDBType_1 = require("./DuckDBType");
+const values_1 = require("./values");
+const MILLIS_PER_DAY = 24 * 60 * 60 * 1000;
+/**
+ * The epoch milliseconds of `value`, refusing an Invalid Date.
+ *
+ * Without this, DATE turns NaN into a `DuckDBDateValue(NaN)` and hands it back,
+ * while the timestamps reach `BigInt(NaN)` and throw "The number NaN cannot be
+ * converted to a BigInt" — neither of which names the real problem.
+ */
+function millisFromDate(value) {
+    const millis = value.getTime();
+    if (Number.isNaN(millis)) {
+        throw new Error(`Cannot convert an Invalid Date`);
+    }
+    return millis;
+}
+function unwritableConverter(_, type) {
+    throw new Error(`Cannot write values of type: ${type}`);
+}
+function nullFromNull() {
+    return null;
+}
+function valueFromBoolean(value) {
+    return Boolean(value);
+}
+function valueFromNumber(value) {
+    return value;
+}
+function bigintFromNumeric(value) {
+    return typeof value === 'bigint' ? value : BigInt(value);
+}
+function valueFromString(value) {
+    return value;
+}
+function blobValueFromBytes(value) {
+    return new values_1.DuckDBBlobValue(value);
+}
+function bitValueFromBytes(value) {
+    return new values_1.DuckDBBitValue(value);
+}
+function geometryValueFromBytes(value) {
+    return new values_1.DuckDBGeometryValue(value);
+}
+function dateValueFromDate(value) {
+    // A DATE has no time component; the reader produces midnight UTC, so this is
+    // exact for a round trip and truncates toward the earlier day otherwise.
+    return new values_1.DuckDBDateValue(Math.floor(millisFromDate(value) / MILLIS_PER_DAY));
+}
+function timeValueFromMicros(value) {
+    return new values_1.DuckDBTimeValue(value);
+}
+function timeNSValueFromNanos(value) {
+    return new values_1.DuckDBTimeNSValue(value);
+}
+function timeTZValueFromObject(value) {
+    return values_1.DuckDBTimeTZValue.fromMicrosAndOffset(value.micros, value.offset);
+}
+function timestampValueFromDate(value) {
+    return new values_1.DuckDBTimestampValue(BigInt(millisFromDate(value)) * 1000n);
+}
+function timestampTZValueFromDate(value) {
+    return new values_1.DuckDBTimestampTZValue(BigInt(millisFromDate(value)) * 1000n);
+}
+function timestampTZNanosValueFromDate(value) {
+    return new values_1.DuckDBTimestampTZNanosecondsValue(BigInt(millisFromDate(value)) * 1000000n);
+}
+function timestampSecondsValueFromDate(value) {
+    return new values_1.DuckDBTimestampSecondsValue(BigInt(Math.floor(millisFromDate(value) / 1000)));
+}
+function timestampMillisValueFromDate(value) {
+    return new values_1.DuckDBTimestampMillisecondsValue(BigInt(millisFromDate(value)));
+}
+function timestampNanosValueFromDate(value) {
+    return new values_1.DuckDBTimestampNanosecondsValue(BigInt(millisFromDate(value)) * 1000000n);
+}
+function intervalValueFromObject(value) {
+    return new values_1.DuckDBIntervalValue(value.months, value.days, value.micros);
+}
+function decimalValueFromNumeric(value, type) {
+    if (!(type instanceof DuckDBType_1.DuckDBDecimalType)) {
+        throw new Error(`Expected DuckDBDecimalType`);
+    }
+    return typeof value === 'bigint'
+        ? new values_1.DuckDBDecimalValue(value, type.width, type.scale)
+        : values_1.DuckDBDecimalValue.fromDouble(value, type.width, type.scale);
+}
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function uuidValueFromString(value) {
+    if (!UUID_PATTERN.test(value)) {
+        throw new Error(`Not a UUID string: ${value}`);
+    }
+    return values_1.DuckDBUUIDValue.fromUint128(BigInt(`0x${value.replace(/-/g, '')}`));
+}
+function listValueFromArray(value, type, converter) {
+    if (!(type instanceof DuckDBType_1.DuckDBListType)) {
+        throw new Error(`Expected DuckDBListType`);
+    }
+    return (0, values_1.listValue)(value.map((item) => converter(item, type.valueType, converter)));
+}
+function arrayValueFromArray(value, type, converter) {
+    if (!(type instanceof DuckDBType_1.DuckDBArrayType)) {
+        throw new Error(`Expected DuckDBArrayType`);
+    }
+    if (value.length !== type.length) {
+        throw new Error(`Expected ${type.length} items for ${type}, got ${value.length}`);
+    }
+    return (0, values_1.arrayValue)(value.map((item) => converter(item, type.valueType, converter)));
+}
+/**
+ * Converts an object keyed by entry name to a named STRUCT value, or an array
+ * of items to a tuple value (see `DuckDBStructType.isTuple`).
+ */
+function structValueFromObject(value, type, converter) {
+    if (!(type instanceof DuckDBType_1.DuckDBStructType)) {
+        throw new Error(`Expected DuckDBStructType`);
+    }
+    if (type.isTuple) {
+        if (!Array.isArray(value)) {
+            throw new Error(`Expected an array for ${type}`);
+        }
+        if (value.length !== type.entryCount) {
+            throw new Error(`Expected ${type.entryCount} items for ${type}, got ${value.length}`);
+        }
+        return (0, values_1.tupleValue)(value.map((item, i) => converter(item, type.entryTypes[i], converter)));
+    }
+    if (Array.isArray(value)) {
+        throw new Error(`Expected an object for ${type}`);
+    }
+    const entryValues = value;
+    const entries = {};
+    for (const key of type.entryNames) {
+        if (!(key in entryValues)) {
+            throw new Error(`Missing entry for struct key: ${key}`);
+        }
+        entries[key] = converter(entryValues[key], type.typeForEntry(key), converter);
+    }
+    return (0, values_1.structValue)(entries);
+}
+function mapValueFromEntries(value, type, converter) {
+    if (!(type instanceof DuckDBType_1.DuckDBMapType)) {
+        throw new Error(`Expected DuckDBMapType`);
+    }
+    return (0, values_1.mapValue)(value.map((entry) => ({
+        key: converter(entry.key, type.keyType, converter),
+        value: converter(entry.value, type.valueType, converter),
+    })));
+}
+function unionValueFromObject(value, type, converter) {
+    if (!(type instanceof DuckDBType_1.DuckDBUnionType)) {
+        throw new Error(`Expected DuckDBUnionType`);
+    }
+    // memberTypeForTag indexes by tag and returns undefined for one it does not
+    // have, which would reach the dispatch as an undefined type. Unlike the read
+    // path, where the tag comes from a decoded value, here it is caller input.
+    if (!(value.tag in type.tagMemberIndexes)) {
+        throw new Error(`Tag ${JSON.stringify(value.tag)} is not a member of ${type}`);
+    }
+    return (0, values_1.unionValue)(value.tag, converter(value.value, type.memberTypeForTag(value.tag), converter));
+}
+/**
+ * A VARIANT carries the type of the value inside it, so writing one means
+ * saying what that type is. A `DuckDBVariantValue` already does — pass it
+ * through. A bare scalar does not, but is unambiguous enough for
+ * `typeForValue` to infer downstream, so wrap it.
+ */
+function variantValueFromJS(value) {
+    return value instanceof values_1.DuckDBVariantValue ? value : (0, values_1.variantValue)(value);
+}

package/lib/conversion/dateTimeStringConversion.d.ts

@@ -12,9 +12,9 @@ export declare function getDuckDBTimeStringFromMicrosecondsInDay(microsecondsInD
 export declare function getDuckDBTimeStringFromNanosecondsInDay(nanosecondsInDay: bigint): string;
 export declare function getDuckDBTimeStringFromMicroseconds(microseconds: bigint): string;
 export declare function getDuckDBTimestampStringFromDaysAndMicroseconds(days: bigint, microsecondsInDay: bigint, timezonePart?: string): string;
-export declare function getDuckDBTimestampStringFromDaysAndNanoseconds(days: bigint, nanosecondsInDay: bigint): string;
+export declare function getDuckDBTimestampStringFromDaysAndNanoseconds(days: bigint, nanosecondsInDay: bigint, timezonePart?: string): string;
 export declare function getDuckDBTimestampStringFromMicroseconds(microseconds: bigint, timezoneOffsetInMinutes?: number): string;
 export declare function getDuckDBTimestampStringFromSeconds(seconds: bigint): string;
 export declare function getDuckDBTimestampStringFromMilliseconds(milliseconds: bigint): string;
-export declare function getDuckDBTimestampStringFromNanoseconds(nanoseconds: bigint): string;
+export declare function getDuckDBTimestampStringFromNanoseconds(nanoseconds: bigint, timezoneOffsetInMinutes?: number): string;
 export declare function getDuckDBIntervalString(months: number, days: number, microseconds: bigint): string;

package/lib/conversion/dateTimeStringConversion.js

@@ -53,7 +53,7 @@ function getDuckDBDateStringFromDays(days) {
     const millisecondsFromRemainingInterval = sign * absDaysFromRemainingInterval * MILLISECONDS_PER_DAY_NUM;
     const date = new Date(millisecondsFromRemainingInterval);
     let year = yearsFrom400YearIntervals + date.getUTCFullYear();
-    if (year < 0) {
+    if (year <= 0) {
         year--; // correct for non-existence of year zero
     }
     const month = date.getUTCMonth() + 1; // getUTCMonth returns zero-indexed month, but we want a one-index month for display
@@ -161,12 +161,12 @@ function getDuckDBTimestampStringFromDaysAndMicroseconds(days, microsecondsInDay
     const timeStr = getDuckDBTimeStringFromMicrosecondsInDay(microsecondsInDay);
     return `${dateStr} ${timeStr}${timezonePart ?? ''}`;
 }
-function getDuckDBTimestampStringFromDaysAndNanoseconds(days, nanosecondsInDay) {
+function getDuckDBTimestampStringFromDaysAndNanoseconds(days, nanosecondsInDay, timezonePart) {
     // This conversion of BigInt to Number is safe, because the largest absolute value that `days` can has is 106751
     // which fits without loss of precision in a JS Number. (106751 = (2^63-1) / NANOSECONDS_PER_DAY)
     const dateStr = getDuckDBDateStringFromDays(Number(days));
     const timeStr = getDuckDBTimeStringFromNanosecondsInDay(nanosecondsInDay);
-    return `${dateStr} ${timeStr}`;
+    return `${dateStr} ${timeStr}${timezonePart ?? ''}`;
 }
 function getDuckDBTimestampStringFromMicroseconds(microseconds, timezoneOffsetInMinutes) {
     // Note that -infinity and infinity are only representable in TIMESTAMP (and TIMESTAMPTZ), not the other timestamp
@@ -197,14 +197,27 @@ function getDuckDBTimestampStringFromSeconds(seconds) {
 function getDuckDBTimestampStringFromMilliseconds(milliseconds) {
     return getDuckDBTimestampStringFromMicroseconds(milliseconds * MICROSECONDS_PER_MILLISECOND);
 }
-function getDuckDBTimestampStringFromNanoseconds(nanoseconds) {
-    let days = nanoseconds / NANOSECONDS_PER_DAY;
-    let nanosecondsPart = nanoseconds % NANOSECONDS_PER_DAY;
+function getDuckDBTimestampStringFromNanoseconds(nanoseconds, timezoneOffsetInMinutes) {
+    // TIMESTAMP_NS and TIMESTAMPTZ_NS use the same infinity values as TIMESTAMP.
+    if (nanoseconds === NEGATIVE_INFINITY_TIMESTAMP) {
+        return '-infinity';
+    }
+    if (nanoseconds === POSITIVE_INFINITY_TIMESTAMP) {
+        return 'infinity';
+    }
+    const offsetNanoseconds = timezoneOffsetInMinutes !== undefined
+        ? nanoseconds +
+            BigInt(timezoneOffsetInMinutes) *
+                NANOSECONDS_PER_SECOND *
+                SECONDS_PER_MINUTE
+        : nanoseconds;
+    let days = offsetNanoseconds / NANOSECONDS_PER_DAY;
+    let nanosecondsPart = offsetNanoseconds % NANOSECONDS_PER_DAY;
     if (nanosecondsPart < 0) {
         days--;
         nanosecondsPart += NANOSECONDS_PER_DAY;
     }
-    return getDuckDBTimestampStringFromDaysAndNanoseconds(days, nanosecondsPart);
+    return getDuckDBTimestampStringFromDaysAndNanoseconds(days, nanosecondsPart, getTimezoneOffsetString(timezoneOffsetInMinutes));
 }
 // Assumes baseUnit can be pluralized by adding an 's'.
 function numberAndUnit(value, baseUnit) {

package/lib/conversion/varintDecode.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Decodes an unsigned LEB128 (little-endian base-128) varint at
+ * `view[offset]`. Each byte contributes 7 bits of payload; the high bit is
+ * a continuation flag.
+ *
+ * Returns the decoded `value` and the byte position `nextOffset` immediately
+ * after the varint. Throws if the varint:
+ *   - reads past the end of `view` (truncated),
+ *   - exceeds 2**32-1 (overflow).
+ *
+ * Uses arithmetic (not bitwise) accumulation so values up to 2**32-1
+ * round-trip correctly — JS bitwise operators coerce to signed int32 and
+ * would turn 0xffffffff into -1.
+ */
+export declare function varintDecode(view: DataView, offset: number): {
+    value: number;
+    nextOffset: number;
+};

package/lib/conversion/varintDecode.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.varintDecode = varintDecode;
+/**
+ * Decodes an unsigned LEB128 (little-endian base-128) varint at
+ * `view[offset]`. Each byte contributes 7 bits of payload; the high bit is
+ * a continuation flag.
+ *
+ * Returns the decoded `value` and the byte position `nextOffset` immediately
+ * after the varint. Throws if the varint:
+ *   - reads past the end of `view` (truncated),
+ *   - exceeds 2**32-1 (overflow).
+ *
+ * Uses arithmetic (not bitwise) accumulation so values up to 2**32-1
+ * round-trip correctly — JS bitwise operators coerce to signed int32 and
+ * would turn 0xffffffff into -1.
+ */
+function varintDecode(view, offset) {
+    let value = 0;
+    let multiplier = 1;
+    let cur = offset;
+    while (true) {
+        if (cur >= view.byteLength) {
+            throw new Error('varint truncated');
+        }
+        const byte = view.getUint8(cur++);
+        value += (byte & 0x7f) * multiplier;
+        if ((byte & 0x80) === 0) {
+            break;
+        }
+        multiplier *= 128;
+        if (multiplier > 0x80000000) {
+            // multiplier == 128**5 means we're about to process a 6th byte —
+            // even a single payload bit beyond would push past 2**32-1.
+            throw new Error('varint overflow');
+        }
+    }
+    if (value > 0xffffffff) {
+        throw new Error('varint overflow');
+    }
+    return { value, nextOffset: cur };
+}

package/lib/convertColumnsFromChunks.d.ts

@@ -1,3 +1,3 @@
 import { DuckDBDataChunk } from './DuckDBDataChunk';
 import { DuckDBValueConverter } from './DuckDBValueConverter';
-export declare function convertColumnsFromChunks<T>(chunks: readonly DuckDBDataChunk[], converter: DuckDBValueConverter<T>): (T | null)[][];
+export declare function convertColumnsFromChunks<T>(chunks: readonly DuckDBDataChunk[], columnCount: number, converter: DuckDBValueConverter<T>): (T | null)[][];

package/lib/convertColumnsFromChunks.js

@@ -1,9 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.convertColumnsFromChunks = convertColumnsFromChunks;
-function convertColumnsFromChunks(chunks, converter) {
+function convertColumnsFromChunks(chunks, columnCount, converter) {
     if (chunks.length === 0) {
-        return [];
+        return Array.from({ length: columnCount }, () => []);
     }
     const convertedColumns = chunks[0].convertColumns(converter);
     for (let chunkIndex = 1; chunkIndex < chunks.length; chunkIndex++) {

package/lib/createResult.d.ts

@@ -1,3 +1,4 @@
 import duckdb from '@haybarn/node-bindings';
 import { DuckDBResult } from './DuckDBResult';
-export declare function createResult(result: duckdb.Result): DuckDBResult;
+import { StatementType } from './enums';
+export declare function createResult(result: duckdb.Result, preparedStatementType?: StatementType): DuckDBResult;

package/lib/createResult.js

@@ -7,11 +7,11 @@ exports.createResult = createResult;
 const node_bindings_1 = __importDefault(require("@haybarn/node-bindings"));
 const DuckDBMaterializedResult_1 = require("./DuckDBMaterializedResult");
 const DuckDBResult_1 = require("./DuckDBResult");
-function createResult(result) {
+function createResult(result, preparedStatementType) {
     if (node_bindings_1.default.result_is_streaming(result)) {
-        return new DuckDBResult_1.DuckDBResult(result);
+        return new DuckDBResult_1.DuckDBResult(result, preparedStatementType);
     }
     else {
-        return new DuckDBMaterializedResult_1.DuckDBMaterializedResult(result);
+        return new DuckDBMaterializedResult_1.DuckDBMaterializedResult(result, preparedStatementType);
     }
 }

package/lib/createValue.js

@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.createValue = createValue;
 const node_bindings_1 = __importDefault(require("@haybarn/node-bindings"));
 const DuckDBTypeId_1 = require("./DuckDBTypeId");
+const typeForValue_1 = require("./typeForValue");
 const values_1 = require("./values");
 function createValue(type, input) {
     if (input === null) {
@@ -34,8 +35,8 @@ function createValue(type, input) {
             }
             throw new Error(`input is not a number`);
         case DuckDBTypeId_1.DuckDBTypeId.BIGINT:
-            if (typeof input === 'bigint') {
-                return node_bindings_1.default.create_int64(input);
+            if (typeof input === 'bigint' || typeof input === 'number') {
+                return node_bindings_1.default.create_int64(BigInt(input));
             }
             throw new Error(`input is not a bigint`);
         case DuckDBTypeId_1.DuckDBTypeId.UTINYINT:
@@ -54,8 +55,8 @@ function createValue(type, input) {
             }
             throw new Error(`input is not a number`);
         case DuckDBTypeId_1.DuckDBTypeId.UBIGINT:
-            if (typeof input === 'bigint') {
-                return node_bindings_1.default.create_uint64(input);
+            if (typeof input === 'bigint' || typeof input === 'number') {
+                return node_bindings_1.default.create_uint64(BigInt(input));
             }
             throw new Error(`input is not a bigint`);
         case DuckDBTypeId_1.DuckDBTypeId.FLOAT:
@@ -142,11 +143,32 @@ function createValue(type, input) {
             }
             throw new Error(`input is not a DuckDBListValue`);
         case DuckDBTypeId_1.DuckDBTypeId.STRUCT:
+            if (type.isTuple) {
+                if (input instanceof values_1.DuckDBTupleValue) {
+                    if (type.entryTypes.find((entryType) => entryType.typeId === DuckDBTypeId_1.DuckDBTypeId.ANY)) {
+                        throw new Error('Cannot create tuples with an entry type of ANY. Specify a specific type.');
+                    }
+                    if (input.items.length !== type.entryCount) {
+                        throw new Error(`Expected ${type.entryCount} items for ${type}, got ${input.items.length}`);
+                    }
+                    return node_bindings_1.default.create_struct_value(type.toLogicalType().logical_type, input.items.map((item, i) => createValue(type.entryTypes[i], item)));
+                }
+                throw new Error(`input is not a DuckDBTupleValue`);
+            }
             if (input instanceof values_1.DuckDBStructValue) {
                 if (type.entryTypes.find((entryType) => entryType.typeId === DuckDBTypeId_1.DuckDBTypeId.ANY)) {
                     throw new Error('Cannot create structs with an entry type of ANY. Specify a specific type.');
                 }
-                return node_bindings_1.default.create_struct_value(type.toLogicalType().logical_type, Object.values(input.entries).map((value, i) => createValue(type.entryTypes[i], value)));
+                // Pair entries by name rather than positionally so that
+                // `structValue({b: 'x', a: 1})` against `STRUCT({a: INTEGER, b:
+                // VARCHAR})` doesn't silently mispair when the value's insertion
+                // order differs from the type's declared field order.
+                return node_bindings_1.default.create_struct_value(type.toLogicalType().logical_type, type.entryNames.map((name, i) => {
+                    if (!(name in input.entries)) {
+                        throw new Error(`STRUCT entry '${name}' is missing from input`);
+                    }
+                    return createValue(type.entryTypes[i], input.entries[name]);
+                }));
             }
             throw new Error(`input is not a DuckDBStructValue`);
         case DuckDBTypeId_1.DuckDBTypeId.MAP:
@@ -198,6 +220,11 @@ function createValue(type, input) {
                 return node_bindings_1.default.create_timestamp_tz(input);
             }
             throw new Error(`input is not a DuckDBTimestampTZValue`);
+        case DuckDBTypeId_1.DuckDBTypeId.TIMESTAMP_TZ_NS:
+            if (input instanceof values_1.DuckDBTimestampTZNanosecondsValue) {
+                return node_bindings_1.default.create_timestamp_tz_ns(input);
+            }
+            throw new Error(`input is not a DuckDBTimestampTZNanosecondsValue`);
         case DuckDBTypeId_1.DuckDBTypeId.ANY:
             throw new Error(`Cannot create values of type ANY. Specify a specific type.`);
         case DuckDBTypeId_1.DuckDBTypeId.BIGNUM:
@@ -216,6 +243,37 @@ function createValue(type, input) {
                 return node_bindings_1.default.create_time_ns(input);
             }
             throw new Error(`input is not a DuckDBTimeNSValue`);
+        case DuckDBTypeId_1.DuckDBTypeId.GEOMETRY:
+            if (input instanceof values_1.DuckDBGeometryValue) {
+                throw new Error(`Creating values of type GEOMETRY is not yet supported.`);
+                // TODO: create_geometry doesn't exist; create_blob results in Failed to cast value: Unimplemented type for cast (BLOB -> GEOMETRY)
+                // return duckdb.create_blob(input.bytes);
+            }
+            throw new Error(`input is not a DuckDBGeometryValue`);
+        case DuckDBTypeId_1.DuckDBTypeId.VARIANT: {
+            // VARIANT has no direct create primitive in the C API; DuckDB
+            // implicitly casts from any compatible type when the target column
+            // or parameter is VARIANT. Recurse on the input's natural type so
+            // we hand DuckDB a Value it can cast.
+            //
+            // If the input is a DuckDBVariantValue, prefer its embedded `.type`
+            // (set by the decoder from the on-disk variant tag) so heterogeneous
+            // content round-trips faithfully. Fall back to `typeForValue` when
+            // no type hint is attached. The recursion is wrapped so a
+            // mismatched wrapper (e.g. `variantValue('hello', INTEGER)`)
+            // surfaces a VARIANT-flavored error rather than a confusing
+            // `input is not a number` from a sibling case.
+            const inner = input instanceof values_1.DuckDBVariantValue ? input.value : input;
+            const innerType = input instanceof values_1.DuckDBVariantValue && input.type
+                ? input.type
+                : (0, typeForValue_1.typeForValue)(inner);
+            try {
+                return createValue(innerType, inner);
+            }
+            catch (err) {
+                throw new Error(`Failed to create VARIANT value (inner type ${innerType}): ${err.message}`);
+            }
+        }
         default:
             throw new Error(`unrecognized type id ${typeId}`);
     }

package/lib/duckdb.d.ts

@@ -2,12 +2,11 @@ export { double_to_hugeint, double_to_uhugeint, hugeint_to_double, uhugeint_to_d
 export * from './configurationOptionDescriptions';
 export * from './createDuckDBValueConverter';
 export * from './DuckDBAppender';
-export * from './DuckDBBindInfo';
 export * from './DuckDBClientContext';
 export * from './DuckDBConnection';
 export * from './DuckDBDataChunk';
+export * from './DuckDBDataChunkWriter';
 export * from './DuckDBExtractedStatements';
-export * from './DuckDBFunctionInfo';
 export * from './DuckDBInstance';
 export * from './DuckDBInstanceCache';
 export * from './DuckDBLogicalType';
@@ -18,16 +17,30 @@ export * from './DuckDBPreparedStatementCollection';
 export * from './DuckDBResult';
 export * from './DuckDBResultReader';
 export * from './DuckDBScalarFunction';
+export * from './DuckDBScalarFunctionBindInfo';
+export * from './DuckDBScalarFunctionInfo';
+export * from './DuckDBScalarFunctionInitInfo';
+export * from './DuckDBTableFunction';
+export * from './DuckDBTableFunctionBindInfo';
+export * from './DuckDBTableFunctionInfo';
+export * from './DuckDBTableFunctionInitInfo';
 export * from './DuckDBType';
 export * from './DuckDBTypeId';
 export * from './DuckDBValueConverter';
 export * from './DuckDBValueConverters';
 export * from './DuckDBVector';
+export * from './ToDuckDBValueConverter';
+export * from './ToDuckDBValueConverters';
 export * from './enums';
 export * from './JS';
 export * from './JSDuckDBValueConverter';
+export * from './JSInputTypeForTypeId';
+export * from './JSToDuckDBValueConverter';
+export * from './JSTypeForTypeId';
 export * from './Json';
 export * from './JsonDuckDBValueConverter';
+export * from './JsonTypeForTypeId';
+export * from './readValue';
 export * from './sql';
 export * from './values';
 export * from './version';

package/lib/duckdb.js

@@ -23,12 +23,11 @@ Object.defineProperty(exports, "uhugeint_to_double", { enumerable: true, get: fu
 __exportStar(require("./configurationOptionDescriptions"), exports);
 __exportStar(require("./createDuckDBValueConverter"), exports);
 __exportStar(require("./DuckDBAppender"), exports);
-__exportStar(require("./DuckDBBindInfo"), exports);
 __exportStar(require("./DuckDBClientContext"), exports);
 __exportStar(require("./DuckDBConnection"), exports);
 __exportStar(require("./DuckDBDataChunk"), exports);
+__exportStar(require("./DuckDBDataChunkWriter"), exports);
 __exportStar(require("./DuckDBExtractedStatements"), exports);
-__exportStar(require("./DuckDBFunctionInfo"), exports);
 __exportStar(require("./DuckDBInstance"), exports);
 __exportStar(require("./DuckDBInstanceCache"), exports);
 __exportStar(require("./DuckDBLogicalType"), exports);
@@ -39,16 +38,30 @@ __exportStar(require("./DuckDBPreparedStatementCollection"), exports);
 __exportStar(require("./DuckDBResult"), exports);
 __exportStar(require("./DuckDBResultReader"), exports);
 __exportStar(require("./DuckDBScalarFunction"), exports);
+__exportStar(require("./DuckDBScalarFunctionBindInfo"), exports);
+__exportStar(require("./DuckDBScalarFunctionInfo"), exports);
+__exportStar(require("./DuckDBScalarFunctionInitInfo"), exports);
+__exportStar(require("./DuckDBTableFunction"), exports);
+__exportStar(require("./DuckDBTableFunctionBindInfo"), exports);
+__exportStar(require("./DuckDBTableFunctionInfo"), exports);
+__exportStar(require("./DuckDBTableFunctionInitInfo"), exports);
 __exportStar(require("./DuckDBType"), exports);
 __exportStar(require("./DuckDBTypeId"), exports);
 __exportStar(require("./DuckDBValueConverter"), exports);
 __exportStar(require("./DuckDBValueConverters"), exports);
 __exportStar(require("./DuckDBVector"), exports);
+__exportStar(require("./ToDuckDBValueConverter"), exports);
+__exportStar(require("./ToDuckDBValueConverters"), exports);
 __exportStar(require("./enums"), exports);
 __exportStar(require("./JS"), exports);
 __exportStar(require("./JSDuckDBValueConverter"), exports);
+__exportStar(require("./JSInputTypeForTypeId"), exports);
+__exportStar(require("./JSToDuckDBValueConverter"), exports);
+__exportStar(require("./JSTypeForTypeId"), exports);
 __exportStar(require("./Json"), exports);
 __exportStar(require("./JsonDuckDBValueConverter"), exports);
+__exportStar(require("./JsonTypeForTypeId"), exports);
+__exportStar(require("./readValue"), exports);
 __exportStar(require("./sql"), exports);
 __exportStar(require("./values"), exports);
 __exportStar(require("./version"), exports);

package/lib/getColumnsFromChunks.d.ts

@@ -1,3 +1,3 @@
 import { DuckDBDataChunk } from './DuckDBDataChunk';
 import { DuckDBValue } from './values';
-export declare function getColumnsFromChunks(chunks: readonly DuckDBDataChunk[]): DuckDBValue[][];
+export declare function getColumnsFromChunks(chunks: readonly DuckDBDataChunk[], columnCount: number): DuckDBValue[][];

package/lib/getColumnsFromChunks.js

@@ -1,8 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getColumnsFromChunks = getColumnsFromChunks;
-function getColumnsFromChunks(chunks) {
-    const columns = [];
+function getColumnsFromChunks(chunks, columnCount) {
+    const columns = Array.from({ length: columnCount }, () => []);
     for (const chunk of chunks) {
         chunk.appendToColumns(columns);
     }

package/lib/getColumnsObjectFromChunks.js

@@ -3,6 +3,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.getColumnsObjectFromChunks = getColumnsObjectFromChunks;
 function getColumnsObjectFromChunks(chunks, columnNames) {
     const columnsObject = {};
+    for (const columnName of columnNames) {
+        columnsObject[columnName] = [];
+    }
     for (const chunk of chunks) {
         chunk.appendToColumnsObject(columnNames, columnsObject);
     }

package/lib/readValue.d.ts

@@ -0,0 +1,22 @@
+import { Value } from '@haybarn/node-bindings';
+import { DuckDBValue } from './values';
+/**
+ * Converts a `duckdb.Value` into a `DuckDBValue`.
+ *
+ * Results normally arrive as vectors rather than values, so this is for the
+ * places that hand back a value instead: table function parameters, and
+ * `duckdb_get_table_names`.
+ *
+ * It works by referencing the value into a vector of its own and reading the one
+ * element back, which reuses the vector reading path rather than duplicating it.
+ * That matters for more than tidiness: the value accessors cannot reach inside an
+ * ARRAY or a UNION at all, because `duckdb_get_list_child` and
+ * `duckdb_get_struct_child` guard on the exact logical type id and return null
+ * for both. Going through a vector covers every type, and leaves one
+ * implementation of how each type is represented rather than two that can drift.
+ *
+ * The cost is roughly an extra microsecond per scalar value, which is fine here
+ * and would not be in a per-row path. Per-row data already arrives as vectors and
+ * never comes through here.
+ */
+export declare function readValue(value: Value): DuckDBValue;