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

package/lib/JSDuckDBValueConverter.d.ts

@@ -1,3 +1,2 @@
-import { DuckDBValueConverter } from './DuckDBValueConverter';
 import { JS } from './JS';
-export declare const JSDuckDBValueConverter: DuckDBValueConverter<JS>;
+export declare const JSDuckDBValueConverter: import("./DuckDBValueConverter").DuckDBValueConverter<JS>;

package/lib/JSDuckDBValueConverter.js

@@ -31,7 +31,7 @@ const JSConvertersByTypeId = {
     [DuckDBTypeId_1.DuckDBTypeId.TIMESTAMP_NS]: DuckDBValueConverters_1.dateFromTimestampNanosecondsValue,
     [DuckDBTypeId_1.DuckDBTypeId.ENUM]: DuckDBValueConverters_1.stringFromValue,
     [DuckDBTypeId_1.DuckDBTypeId.LIST]: DuckDBValueConverters_1.arrayFromListValue,
-    [DuckDBTypeId_1.DuckDBTypeId.STRUCT]: DuckDBValueConverters_1.objectFromStructValue,
+    [DuckDBTypeId_1.DuckDBTypeId.STRUCT]: DuckDBValueConverters_1.objectOrArrayFromStructValue,
     [DuckDBTypeId_1.DuckDBTypeId.MAP]: DuckDBValueConverters_1.objectArrayFromMapValue,
     [DuckDBTypeId_1.DuckDBTypeId.ARRAY]: DuckDBValueConverters_1.arrayFromArrayValue,
     [DuckDBTypeId_1.DuckDBTypeId.UUID]: DuckDBValueConverters_1.stringFromValue,
@@ -44,6 +44,9 @@ const JSConvertersByTypeId = {
     [DuckDBTypeId_1.DuckDBTypeId.SQLNULL]: DuckDBValueConverters_1.nullConverter,
     [DuckDBTypeId_1.DuckDBTypeId.STRING_LITERAL]: DuckDBValueConverters_1.unsupportedConverter,
     [DuckDBTypeId_1.DuckDBTypeId.INTEGER_LITERAL]: DuckDBValueConverters_1.unsupportedConverter,
-    [DuckDBTypeId_1.DuckDBTypeId.TIME_NS]: DuckDBValueConverters_1.bigintFromTimeValue,
+    [DuckDBTypeId_1.DuckDBTypeId.TIME_NS]: DuckDBValueConverters_1.bigintFromTimeNSValue,
+    [DuckDBTypeId_1.DuckDBTypeId.GEOMETRY]: DuckDBValueConverters_1.bytesFromGeometryValue,
+    [DuckDBTypeId_1.DuckDBTypeId.VARIANT]: DuckDBValueConverters_1.fromVariantValue,
+    [DuckDBTypeId_1.DuckDBTypeId.TIMESTAMP_TZ_NS]: DuckDBValueConverters_1.dateFromTimestampTZNanosecondsValue,
 };
 exports.JSDuckDBValueConverter = (0, createDuckDBValueConverter_1.createDuckDBValueConverter)(JSConvertersByTypeId);

package/lib/JSInputTypeForTypeId.d.ts

@@ -0,0 +1,104 @@
+import type { DuckDBType } from './DuckDBType';
+import { DuckDBTypeId } from './DuckDBTypeId';
+import type { JS } from './JS';
+import type { DuckDBVariantValue } from './values';
+/**
+ * The JS type accepted by `jsToDuckDBValue` for each DuckDB type id: the write
+ * counterpart of `JSTypeForTypeId`.
+ *
+ * Everything `JSTypeForTypeId` produces, this table accepts — see the
+ * round-trip assertion in `test/js-writes.test.ts` — but not the reverse.
+ * Writes are deliberately wider where a second spelling is unambiguous: the
+ * 64-bit and wider integers take `number` as well as `bigint`, and DECIMAL
+ * takes either a double or a raw scaled `bigint`. VARIANT is the one
+ * exception in the other direction; see below.
+ *
+ * NULL is not in the table: `createToDuckDBValueConverter` maps `null` to
+ * `null` for every type, so a nullable value is `JSInputTypeForTypeId[Id] |
+ * null`.
+ *
+ * Type ids that cannot be written map to `never`: `INVALID`, `ANY`,
+ * `STRING_LITERAL` and `INTEGER_LITERAL`, none of which can appear in a result
+ * either.
+ *
+ * VARIANT is the one place the write side is *narrower* than the read side. A
+ * VARIANT holds its own type, so writing one means saying what that type is.
+ * A `DuckDBVariantValue` carries it — either explicitly, as
+ * `variantValue(structValue({k: 'n'}), STRUCT({k: VARCHAR}))`, or inferred by
+ * `typeForValue` from a wrapped inner value — and a bare boolean, number,
+ * bigint or string is unambiguous enough to infer on its own. A bare `Date`,
+ * `Uint8Array`, array or object is not: each maps to several DuckDB types, so
+ * `typeForValue` yields ANY and the write fails. Wrap those to say which.
+ *
+ * Reading a VARIANT discards that type, which is why the round-trip
+ * containment the other ids satisfy does not hold here: the read table gives
+ * `JS | null`, and JS alone is not enough to write back.
+ *
+ * This interface is exhaustive over `DuckDBTypeId`, and is the annotation
+ * source for the converter map in `jsToDuckDBValue`; adding a type id without
+ * adding it here is a compile error.
+ */
+export interface JSInputTypeForTypeId {
+    [DuckDBTypeId.INVALID]: never;
+    [DuckDBTypeId.BOOLEAN]: boolean;
+    [DuckDBTypeId.TINYINT]: number;
+    [DuckDBTypeId.SMALLINT]: number;
+    [DuckDBTypeId.INTEGER]: number;
+    [DuckDBTypeId.BIGINT]: bigint | number;
+    [DuckDBTypeId.UTINYINT]: number;
+    [DuckDBTypeId.USMALLINT]: number;
+    [DuckDBTypeId.UINTEGER]: number;
+    [DuckDBTypeId.UBIGINT]: bigint | number;
+    [DuckDBTypeId.FLOAT]: number;
+    [DuckDBTypeId.DOUBLE]: number;
+    [DuckDBTypeId.TIMESTAMP]: Date;
+    [DuckDBTypeId.DATE]: Date;
+    [DuckDBTypeId.TIME]: bigint;
+    [DuckDBTypeId.INTERVAL]: {
+        months: number;
+        days: number;
+        micros: bigint;
+    };
+    [DuckDBTypeId.HUGEINT]: bigint | number;
+    [DuckDBTypeId.UHUGEINT]: bigint | number;
+    [DuckDBTypeId.VARCHAR]: string;
+    [DuckDBTypeId.BLOB]: Uint8Array;
+    [DuckDBTypeId.DECIMAL]: number | bigint;
+    [DuckDBTypeId.TIMESTAMP_S]: Date;
+    [DuckDBTypeId.TIMESTAMP_MS]: Date;
+    [DuckDBTypeId.TIMESTAMP_NS]: Date;
+    [DuckDBTypeId.ENUM]: string;
+    [DuckDBTypeId.LIST]: readonly (JS | null)[];
+    [DuckDBTypeId.STRUCT]: Readonly<Record<string, JS | null>> | readonly (JS | null)[];
+    [DuckDBTypeId.MAP]: readonly {
+        key: JS | null;
+        value: JS | null;
+    }[];
+    [DuckDBTypeId.ARRAY]: readonly (JS | null)[];
+    [DuckDBTypeId.UUID]: string;
+    [DuckDBTypeId.UNION]: {
+        tag: string;
+        value: JS | null;
+    };
+    [DuckDBTypeId.BIT]: Uint8Array;
+    [DuckDBTypeId.TIME_TZ]: {
+        micros: bigint;
+        offset: number;
+    };
+    [DuckDBTypeId.TIMESTAMP_TZ]: Date;
+    [DuckDBTypeId.ANY]: never;
+    [DuckDBTypeId.BIGNUM]: bigint | number;
+    [DuckDBTypeId.SQLNULL]: null;
+    [DuckDBTypeId.STRING_LITERAL]: never;
+    [DuckDBTypeId.INTEGER_LITERAL]: never;
+    [DuckDBTypeId.TIME_NS]: bigint;
+    [DuckDBTypeId.GEOMETRY]: Uint8Array;
+    [DuckDBTypeId.VARIANT]: DuckDBVariantValue | boolean | number | bigint | string;
+    [DuckDBTypeId.TIMESTAMP_TZ_NS]: Date;
+}
+/**
+ * The JS type accepted by `jsToDuckDBValue` for a given `DuckDBType`.
+ *
+ * Excludes NULL; use `JSInputTypeFor<T> | null` for a nullable value.
+ */
+export type JSInputTypeFor<T extends DuckDBType> = JSInputTypeForTypeId[T['typeId']];

package/lib/JSInputTypeForTypeId.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const DuckDBTypeId_1 = require("./DuckDBTypeId");

package/lib/JSToDuckDBValueConverter.d.ts

@@ -0,0 +1,30 @@
+import { DuckDBType } from './DuckDBType';
+import { JS } from './JS';
+import { JSInputTypeFor } from './JSInputTypeForTypeId';
+import { DuckDBValue } from './values';
+/**
+ * Converts a JS value into the `DuckDBValue` representation for a DuckDB type:
+ * the inverse of `JSDuckDBValueConverter`.
+ *
+ * Pass this to `DuckDBDataChunk.setRowsConverted` and friends to fill a chunk
+ * from JS values. `jsToDuckDBValue` below is the single-value form, and checks
+ * its input against a statically known type.
+ */
+export declare const JSToDuckDBValueConverter: import("./ToDuckDBValueConverter").ToDuckDBValueConverter<JS>;
+/**
+ * Converts a JS value into the `DuckDBValue` representation for `type`.
+ *
+ * The inverse of `JSDuckDBValueConverter`. Accepts what
+ * `JSInputTypeForTypeId` declares for the type's id, plus `null` for any type.
+ * Generic over the type, so a statically known one checks its input exactly:
+ * `jsToDuckDBValue(new Date(), TIMESTAMP)` is accepted and
+ * `jsToDuckDBValue(new Date(), INTEGER)` is not. Passing a `DuckDBType` that
+ * is only known as the union widens the input to the union of every entry,
+ * which is as precise as the type information allows.
+ *
+ * Pure TypeScript: it constructs no `duckdb_value` and needs no connection, so
+ * it composes with every write entry point — `DuckDBAppender.appendValue`,
+ * `DuckDBPreparedStatement.bindValue`, and `DuckDBDataChunk.setRows` all take
+ * a `DuckDBValue`.
+ */
+export declare function jsToDuckDBValue<T extends DuckDBType>(value: JSInputTypeFor<T> | null, type: T): DuckDBValue;

package/lib/JSToDuckDBValueConverter.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JSToDuckDBValueConverter = void 0;
+exports.jsToDuckDBValue = jsToDuckDBValue;
+const DuckDBTypeId_1 = require("./DuckDBTypeId");
+const ToDuckDBValueConverter_1 = require("./ToDuckDBValueConverter");
+const ToDuckDBValueConverters_1 = require("./ToDuckDBValueConverters");
+const JSInputConvertersByTypeId = {
+    [DuckDBTypeId_1.DuckDBTypeId.INVALID]: ToDuckDBValueConverters_1.unwritableConverter,
+    [DuckDBTypeId_1.DuckDBTypeId.BOOLEAN]: ToDuckDBValueConverters_1.valueFromBoolean,
+    [DuckDBTypeId_1.DuckDBTypeId.TINYINT]: ToDuckDBValueConverters_1.valueFromNumber,
+    [DuckDBTypeId_1.DuckDBTypeId.SMALLINT]: ToDuckDBValueConverters_1.valueFromNumber,
+    [DuckDBTypeId_1.DuckDBTypeId.INTEGER]: ToDuckDBValueConverters_1.valueFromNumber,
+    [DuckDBTypeId_1.DuckDBTypeId.BIGINT]: ToDuckDBValueConverters_1.bigintFromNumeric,
+    [DuckDBTypeId_1.DuckDBTypeId.UTINYINT]: ToDuckDBValueConverters_1.valueFromNumber,
+    [DuckDBTypeId_1.DuckDBTypeId.USMALLINT]: ToDuckDBValueConverters_1.valueFromNumber,
+    [DuckDBTypeId_1.DuckDBTypeId.UINTEGER]: ToDuckDBValueConverters_1.valueFromNumber,
+    [DuckDBTypeId_1.DuckDBTypeId.UBIGINT]: ToDuckDBValueConverters_1.bigintFromNumeric,
+    [DuckDBTypeId_1.DuckDBTypeId.FLOAT]: ToDuckDBValueConverters_1.valueFromNumber,
+    [DuckDBTypeId_1.DuckDBTypeId.DOUBLE]: ToDuckDBValueConverters_1.valueFromNumber,
+    [DuckDBTypeId_1.DuckDBTypeId.TIMESTAMP]: ToDuckDBValueConverters_1.timestampValueFromDate,
+    [DuckDBTypeId_1.DuckDBTypeId.DATE]: ToDuckDBValueConverters_1.dateValueFromDate,
+    [DuckDBTypeId_1.DuckDBTypeId.TIME]: ToDuckDBValueConverters_1.timeValueFromMicros,
+    [DuckDBTypeId_1.DuckDBTypeId.INTERVAL]: ToDuckDBValueConverters_1.intervalValueFromObject,
+    [DuckDBTypeId_1.DuckDBTypeId.HUGEINT]: ToDuckDBValueConverters_1.bigintFromNumeric,
+    [DuckDBTypeId_1.DuckDBTypeId.UHUGEINT]: ToDuckDBValueConverters_1.bigintFromNumeric,
+    [DuckDBTypeId_1.DuckDBTypeId.VARCHAR]: ToDuckDBValueConverters_1.valueFromString,
+    [DuckDBTypeId_1.DuckDBTypeId.BLOB]: ToDuckDBValueConverters_1.blobValueFromBytes,
+    [DuckDBTypeId_1.DuckDBTypeId.DECIMAL]: ToDuckDBValueConverters_1.decimalValueFromNumeric,
+    [DuckDBTypeId_1.DuckDBTypeId.TIMESTAMP_S]: ToDuckDBValueConverters_1.timestampSecondsValueFromDate,
+    [DuckDBTypeId_1.DuckDBTypeId.TIMESTAMP_MS]: ToDuckDBValueConverters_1.timestampMillisValueFromDate,
+    [DuckDBTypeId_1.DuckDBTypeId.TIMESTAMP_NS]: ToDuckDBValueConverters_1.timestampNanosValueFromDate,
+    [DuckDBTypeId_1.DuckDBTypeId.ENUM]: ToDuckDBValueConverters_1.valueFromString,
+    [DuckDBTypeId_1.DuckDBTypeId.LIST]: ToDuckDBValueConverters_1.listValueFromArray,
+    [DuckDBTypeId_1.DuckDBTypeId.STRUCT]: ToDuckDBValueConverters_1.structValueFromObject,
+    [DuckDBTypeId_1.DuckDBTypeId.MAP]: ToDuckDBValueConverters_1.mapValueFromEntries,
+    [DuckDBTypeId_1.DuckDBTypeId.ARRAY]: ToDuckDBValueConverters_1.arrayValueFromArray,
+    [DuckDBTypeId_1.DuckDBTypeId.UUID]: ToDuckDBValueConverters_1.uuidValueFromString,
+    [DuckDBTypeId_1.DuckDBTypeId.UNION]: ToDuckDBValueConverters_1.unionValueFromObject,
+    [DuckDBTypeId_1.DuckDBTypeId.BIT]: ToDuckDBValueConverters_1.bitValueFromBytes,
+    [DuckDBTypeId_1.DuckDBTypeId.TIME_TZ]: ToDuckDBValueConverters_1.timeTZValueFromObject,
+    [DuckDBTypeId_1.DuckDBTypeId.TIMESTAMP_TZ]: ToDuckDBValueConverters_1.timestampTZValueFromDate,
+    [DuckDBTypeId_1.DuckDBTypeId.ANY]: ToDuckDBValueConverters_1.unwritableConverter,
+    [DuckDBTypeId_1.DuckDBTypeId.BIGNUM]: ToDuckDBValueConverters_1.bigintFromNumeric,
+    [DuckDBTypeId_1.DuckDBTypeId.SQLNULL]: ToDuckDBValueConverters_1.nullFromNull,
+    [DuckDBTypeId_1.DuckDBTypeId.STRING_LITERAL]: ToDuckDBValueConverters_1.unwritableConverter,
+    [DuckDBTypeId_1.DuckDBTypeId.INTEGER_LITERAL]: ToDuckDBValueConverters_1.unwritableConverter,
+    [DuckDBTypeId_1.DuckDBTypeId.TIME_NS]: ToDuckDBValueConverters_1.timeNSValueFromNanos,
+    [DuckDBTypeId_1.DuckDBTypeId.GEOMETRY]: ToDuckDBValueConverters_1.geometryValueFromBytes,
+    [DuckDBTypeId_1.DuckDBTypeId.VARIANT]: ToDuckDBValueConverters_1.variantValueFromJS,
+    [DuckDBTypeId_1.DuckDBTypeId.TIMESTAMP_TZ_NS]: ToDuckDBValueConverters_1.timestampTZNanosValueFromDate,
+};
+/**
+ * Converts a JS value into the `DuckDBValue` representation for a DuckDB type:
+ * the inverse of `JSDuckDBValueConverter`.
+ *
+ * Pass this to `DuckDBDataChunk.setRowsConverted` and friends to fill a chunk
+ * from JS values. `jsToDuckDBValue` below is the single-value form, and checks
+ * its input against a statically known type.
+ */
+exports.JSToDuckDBValueConverter = (0, ToDuckDBValueConverter_1.createToDuckDBValueConverter)(JSInputConvertersByTypeId);
+/**
+ * Converts a JS value into the `DuckDBValue` representation for `type`.
+ *
+ * The inverse of `JSDuckDBValueConverter`. Accepts what
+ * `JSInputTypeForTypeId` declares for the type's id, plus `null` for any type.
+ * Generic over the type, so a statically known one checks its input exactly:
+ * `jsToDuckDBValue(new Date(), TIMESTAMP)` is accepted and
+ * `jsToDuckDBValue(new Date(), INTEGER)` is not. Passing a `DuckDBType` that
+ * is only known as the union widens the input to the union of every entry,
+ * which is as precise as the type information allows.
+ *
+ * Pure TypeScript: it constructs no `duckdb_value` and needs no connection, so
+ * it composes with every write entry point — `DuckDBAppender.appendValue`,
+ * `DuckDBPreparedStatement.bindValue`, and `DuckDBDataChunk.setRows` all take
+ * a `DuckDBValue`.
+ */
+function jsToDuckDBValue(value, type) {
+    // The converter chain is typed against JS, which the input table exceeds for
+    // VARIANT alone (a DuckDBVariantValue is not a JS value). Narrowed back at
+    // the same boundary the factory documents.
+    return (0, exports.JSToDuckDBValueConverter)(value, type, exports.JSToDuckDBValueConverter);
+}

package/lib/JSTypeForTypeId.d.ts

@@ -0,0 +1,91 @@
+import type { DuckDBType } from './DuckDBType';
+import { DuckDBTypeId } from './DuckDBTypeId';
+import type { JS } from './JS';
+/**
+ * The JS type produced by `JSDuckDBValueConverter` for each DuckDB type id.
+ *
+ * Values are non-NULL results only: SQL NULL is handled by
+ * `createDuckDBValueConverter`, which yields `null` for any type. Callers
+ * representing a nullable value should use `JSTypeForTypeId[Id] | null`.
+ *
+ * Type ids that cannot appear in a result (`INVALID`, `ANY`,
+ * `STRING_LITERAL`, `INTEGER_LITERAL`) map to `never`, since their
+ * converters throw.
+ *
+ * Nested types bottom out at `JS`, because `DuckDBListType`,
+ * `DuckDBArrayType`, `DuckDBStructType`, `DuckDBMapType`, and
+ * `DuckDBUnionType` do not carry their child types at the type level.
+ *
+ * STRUCT is an object keyed by entry name, except for a tuple (see
+ * `DuckDBStructType.isTuple`), which is an array of its items.
+ *
+ * This interface is exhaustive over `DuckDBTypeId`, and is the annotation
+ * source for the converter map in `JSDuckDBValueConverter`; adding a type id
+ * without adding it here is a compile error.
+ */
+export interface JSTypeForTypeId {
+    [DuckDBTypeId.INVALID]: never;
+    [DuckDBTypeId.BOOLEAN]: boolean;
+    [DuckDBTypeId.TINYINT]: number;
+    [DuckDBTypeId.SMALLINT]: number;
+    [DuckDBTypeId.INTEGER]: number;
+    [DuckDBTypeId.BIGINT]: bigint;
+    [DuckDBTypeId.UTINYINT]: number;
+    [DuckDBTypeId.USMALLINT]: number;
+    [DuckDBTypeId.UINTEGER]: number;
+    [DuckDBTypeId.UBIGINT]: bigint;
+    [DuckDBTypeId.FLOAT]: number;
+    [DuckDBTypeId.DOUBLE]: number;
+    [DuckDBTypeId.TIMESTAMP]: Date;
+    [DuckDBTypeId.DATE]: Date;
+    [DuckDBTypeId.TIME]: bigint;
+    [DuckDBTypeId.INTERVAL]: {
+        months: number;
+        days: number;
+        micros: bigint;
+    };
+    [DuckDBTypeId.HUGEINT]: bigint;
+    [DuckDBTypeId.UHUGEINT]: bigint;
+    [DuckDBTypeId.VARCHAR]: string;
+    [DuckDBTypeId.BLOB]: Uint8Array;
+    [DuckDBTypeId.DECIMAL]: number;
+    [DuckDBTypeId.TIMESTAMP_S]: Date;
+    [DuckDBTypeId.TIMESTAMP_MS]: Date;
+    [DuckDBTypeId.TIMESTAMP_NS]: Date;
+    [DuckDBTypeId.ENUM]: string;
+    [DuckDBTypeId.LIST]: (JS | null)[];
+    [DuckDBTypeId.STRUCT]: {
+        [key: string]: JS | null;
+    } | (JS | null)[];
+    [DuckDBTypeId.MAP]: {
+        key: JS | null;
+        value: JS | null;
+    }[];
+    [DuckDBTypeId.ARRAY]: (JS | null)[];
+    [DuckDBTypeId.UUID]: string;
+    [DuckDBTypeId.UNION]: {
+        tag: string;
+        value: JS | null;
+    };
+    [DuckDBTypeId.BIT]: Uint8Array;
+    [DuckDBTypeId.TIME_TZ]: {
+        micros: bigint;
+        offset: number;
+    };
+    [DuckDBTypeId.TIMESTAMP_TZ]: Date;
+    [DuckDBTypeId.ANY]: never;
+    [DuckDBTypeId.BIGNUM]: bigint;
+    [DuckDBTypeId.SQLNULL]: null;
+    [DuckDBTypeId.STRING_LITERAL]: never;
+    [DuckDBTypeId.INTEGER_LITERAL]: never;
+    [DuckDBTypeId.TIME_NS]: bigint;
+    [DuckDBTypeId.GEOMETRY]: Uint8Array;
+    [DuckDBTypeId.VARIANT]: JS | null;
+    [DuckDBTypeId.TIMESTAMP_TZ_NS]: Date;
+}
+/**
+ * The JS type produced by `JSDuckDBValueConverter` for a given `DuckDBType`.
+ *
+ * Excludes NULL; use `JSTypeFor<T> | null` for a nullable value.
+ */
+export type JSTypeFor<T extends DuckDBType> = JSTypeForTypeId[T['typeId']];

package/lib/JSTypeForTypeId.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const DuckDBTypeId_1 = require("./DuckDBTypeId");

package/lib/JsonDuckDBValueConverter.d.ts

@@ -1,3 +1,2 @@
-import { DuckDBValueConverter } from './DuckDBValueConverter';
 import { Json } from './Json';
-export declare const JsonDuckDBValueConverter: DuckDBValueConverter<Json>;
+export declare const JsonDuckDBValueConverter: import("./DuckDBValueConverter").DuckDBValueConverter<Json>;

package/lib/JsonDuckDBValueConverter.js

@@ -31,7 +31,7 @@ const JsonConvertersByTypeId = {
     [DuckDBTypeId_1.DuckDBTypeId.TIMESTAMP_NS]: DuckDBValueConverters_1.stringFromValue,
     [DuckDBTypeId_1.DuckDBTypeId.ENUM]: DuckDBValueConverters_1.stringFromValue,
     [DuckDBTypeId_1.DuckDBTypeId.LIST]: DuckDBValueConverters_1.arrayFromListValue,
-    [DuckDBTypeId_1.DuckDBTypeId.STRUCT]: DuckDBValueConverters_1.objectFromStructValue,
+    [DuckDBTypeId_1.DuckDBTypeId.STRUCT]: DuckDBValueConverters_1.objectOrArrayFromStructValue,
     [DuckDBTypeId_1.DuckDBTypeId.MAP]: DuckDBValueConverters_1.objectArrayFromMapValue,
     [DuckDBTypeId_1.DuckDBTypeId.ARRAY]: DuckDBValueConverters_1.arrayFromArrayValue,
     [DuckDBTypeId_1.DuckDBTypeId.UUID]: DuckDBValueConverters_1.stringFromValue,
@@ -45,5 +45,8 @@ const JsonConvertersByTypeId = {
     [DuckDBTypeId_1.DuckDBTypeId.STRING_LITERAL]: DuckDBValueConverters_1.unsupportedConverter,
     [DuckDBTypeId_1.DuckDBTypeId.INTEGER_LITERAL]: DuckDBValueConverters_1.unsupportedConverter,
     [DuckDBTypeId_1.DuckDBTypeId.TIME_NS]: DuckDBValueConverters_1.stringFromValue,
+    [DuckDBTypeId_1.DuckDBTypeId.GEOMETRY]: DuckDBValueConverters_1.stringFromValue,
+    [DuckDBTypeId_1.DuckDBTypeId.VARIANT]: DuckDBValueConverters_1.fromVariantValue,
+    [DuckDBTypeId_1.DuckDBTypeId.TIMESTAMP_TZ_NS]: DuckDBValueConverters_1.stringFromValue,
 };
 exports.JsonDuckDBValueConverter = (0, createDuckDBValueConverter_1.createDuckDBValueConverter)(JsonConvertersByTypeId);

package/lib/JsonTypeForTypeId.d.ts

@@ -0,0 +1,96 @@
+import type { DuckDBType } from './DuckDBType';
+import { DuckDBTypeId } from './DuckDBTypeId';
+import type { Json } from './Json';
+/**
+ * The JSON-compatible type produced by `JsonDuckDBValueConverter` for each
+ * DuckDB type id.
+ *
+ * Values are non-NULL results only: SQL NULL is handled by
+ * `createDuckDBValueConverter`, which yields `null` for any type. Callers
+ * representing a nullable value should use `JsonTypeForTypeId[Id] | null`.
+ *
+ * This differs from `JSTypeForTypeId` wherever a DuckDB value has no lossless
+ * JSON representation: 64-bit and wider integers, temporal types, DECIMAL,
+ * BLOB, BIT, and GEOMETRY are rendered as strings rather than as `bigint`,
+ * `Date`, or `Uint8Array`, and FLOAT and DOUBLE widen to `number | string` so
+ * that Infinity and NaN survive as strings.
+ *
+ * Type ids that cannot appear in a result (`INVALID`, `ANY`,
+ * `STRING_LITERAL`, `INTEGER_LITERAL`) map to `never`, since their
+ * converters throw.
+ *
+ * Nested types bottom out at `Json`, because `DuckDBListType`,
+ * `DuckDBArrayType`, `DuckDBStructType`, `DuckDBMapType`, and
+ * `DuckDBUnionType` do not carry their child types at the type level.
+ *
+ * STRUCT is an object keyed by entry name, except for a tuple (see
+ * `DuckDBStructType.isTuple`), which is an array of its items.
+ *
+ * This interface is exhaustive over `DuckDBTypeId`, and is the annotation
+ * source for the converter map in `JsonDuckDBValueConverter`; adding a type id
+ * without adding it here is a compile error.
+ */
+export interface JsonTypeForTypeId {
+    [DuckDBTypeId.INVALID]: never;
+    [DuckDBTypeId.BOOLEAN]: boolean;
+    [DuckDBTypeId.TINYINT]: number;
+    [DuckDBTypeId.SMALLINT]: number;
+    [DuckDBTypeId.INTEGER]: number;
+    [DuckDBTypeId.BIGINT]: string;
+    [DuckDBTypeId.UTINYINT]: number;
+    [DuckDBTypeId.USMALLINT]: number;
+    [DuckDBTypeId.UINTEGER]: number;
+    [DuckDBTypeId.UBIGINT]: string;
+    [DuckDBTypeId.FLOAT]: number | string;
+    [DuckDBTypeId.DOUBLE]: number | string;
+    [DuckDBTypeId.TIMESTAMP]: string;
+    [DuckDBTypeId.DATE]: string;
+    [DuckDBTypeId.TIME]: string;
+    [DuckDBTypeId.INTERVAL]: {
+        months: number;
+        days: number;
+        micros: string;
+    };
+    [DuckDBTypeId.HUGEINT]: string;
+    [DuckDBTypeId.UHUGEINT]: string;
+    [DuckDBTypeId.VARCHAR]: string;
+    [DuckDBTypeId.BLOB]: string;
+    [DuckDBTypeId.DECIMAL]: string;
+    [DuckDBTypeId.TIMESTAMP_S]: string;
+    [DuckDBTypeId.TIMESTAMP_MS]: string;
+    [DuckDBTypeId.TIMESTAMP_NS]: string;
+    [DuckDBTypeId.ENUM]: string;
+    [DuckDBTypeId.LIST]: (Json | null)[];
+    [DuckDBTypeId.STRUCT]: {
+        [key: string]: Json | null;
+    } | (Json | null)[];
+    [DuckDBTypeId.MAP]: {
+        key: Json | null;
+        value: Json | null;
+    }[];
+    [DuckDBTypeId.ARRAY]: (Json | null)[];
+    [DuckDBTypeId.UUID]: string;
+    [DuckDBTypeId.UNION]: {
+        tag: string;
+        value: Json | null;
+    };
+    [DuckDBTypeId.BIT]: string;
+    [DuckDBTypeId.TIME_TZ]: string;
+    [DuckDBTypeId.TIMESTAMP_TZ]: string;
+    [DuckDBTypeId.ANY]: never;
+    [DuckDBTypeId.BIGNUM]: string;
+    [DuckDBTypeId.SQLNULL]: null;
+    [DuckDBTypeId.STRING_LITERAL]: never;
+    [DuckDBTypeId.INTEGER_LITERAL]: never;
+    [DuckDBTypeId.TIME_NS]: string;
+    [DuckDBTypeId.GEOMETRY]: string;
+    [DuckDBTypeId.VARIANT]: Json | null;
+    [DuckDBTypeId.TIMESTAMP_TZ_NS]: string;
+}
+/**
+ * The JSON-compatible type produced by `JsonDuckDBValueConverter` for a given
+ * `DuckDBType`.
+ *
+ * Excludes NULL; use `JsonTypeFor<T> | null` for a nullable value.
+ */
+export type JsonTypeFor<T extends DuckDBType> = JsonTypeForTypeId[T['typeId']];

package/lib/JsonTypeForTypeId.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const DuckDBTypeId_1 = require("./DuckDBTypeId");

package/lib/ToDuckDBValueConverter.d.ts

@@ -0,0 +1,41 @@
+import { DuckDBType } from './DuckDBType';
+import { DuckDBTypeId } from './DuckDBTypeId';
+import { DuckDBValue } from './values';
+/**
+ * Converts a `T` into the `DuckDBValue` representation for a DuckDB type: the
+ * inverse of `DuckDBValueConverter<T>`, which converts the other way.
+ *
+ * `T` is whatever representation a given converter accepts — see
+ * `JSToDuckDBValueConverter` for the JS one. `DuckDBValue` is itself a
+ * TypeScript representation, plain JS for the scalars and the value wrapper
+ * classes, which hold nothing but data, for the rest. So a conversion of this
+ * shape touches no C API, which is what lets it survive the move to the V2 C
+ * API, where constructing a `duckdb_value` requires a connection or context.
+ * Nothing here constructs one.
+ */
+export type ToDuckDBValueConverter<T> = (value: T, type: DuckDBType, converter: ToDuckDBValueConverter<T>) => DuckDBValue;
+/**
+ * A converter for a single DuckDB type id, whose accepted input `In` is
+ * narrower than the `Nested` the top-level converter it recurses through
+ * accepts.
+ *
+ * The write-side counterpart of `DuckDBValueConverterFor`, and narrowing for
+ * the same reason: in a per-type-id map only the accepted input varies by id,
+ * while the `converter` argument is always the map's top-level converter.
+ */
+export type ToDuckDBValueConverterFor<In, Nested> = (value: In, type: DuckDBType, converter: ToDuckDBValueConverter<Nested>) => DuckDBValue;
+/**
+ * Assembles a per-type-id converter map into a single converter.
+ *
+ * `InputTable` is the type table the map was annotated from — one entry per
+ * type id — so each entry may accept a type narrower than `T`. That narrowing
+ * is contravariant, so unlike the read direction it cannot be checked through
+ * to the dispatch: the type id is only known at runtime, and the compiler
+ * cannot relate `type.typeId` to the static type of `value`. The one unchecked
+ * cast that closes the gap lives here rather than at each call site — callers
+ * get a checked signature, and the mismatch surfaces as the converter's own
+ * `Expected ...` error.
+ */
+export declare function createToDuckDBValueConverter<T, InputTable extends Record<DuckDBTypeId, unknown>>(convertersByTypeId: {
+    [Id in DuckDBTypeId]: ToDuckDBValueConverterFor<InputTable[Id], T>;
+}): ToDuckDBValueConverter<T>;

package/lib/ToDuckDBValueConverter.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createToDuckDBValueConverter = createToDuckDBValueConverter;
+/**
+ * Assembles a per-type-id converter map into a single converter.
+ *
+ * `InputTable` is the type table the map was annotated from — one entry per
+ * type id — so each entry may accept a type narrower than `T`. That narrowing
+ * is contravariant, so unlike the read direction it cannot be checked through
+ * to the dispatch: the type id is only known at runtime, and the compiler
+ * cannot relate `type.typeId` to the static type of `value`. The one unchecked
+ * cast that closes the gap lives here rather than at each call site — callers
+ * get a checked signature, and the mismatch surfaces as the converter's own
+ * `Expected ...` error.
+ */
+function createToDuckDBValueConverter(convertersByTypeId) {
+    return (value, type, converter) => {
+        if (value == null) {
+            return null;
+        }
+        const converterForTypeId = convertersByTypeId[type.typeId];
+        if (!converterForTypeId) {
+            throw new Error(`No converter for typeId: ${type.typeId}`);
+        }
+        return converterForTypeId(value, type, converter);
+    };
+}

package/lib/ToDuckDBValueConverters.d.ts

@@ -0,0 +1,54 @@
+import { DuckDBType } from './DuckDBType';
+import { ToDuckDBValueConverter } from './ToDuckDBValueConverter';
+import { DuckDBBitValue, DuckDBBlobValue, DuckDBDateValue, DuckDBDecimalValue, DuckDBGeometryValue, DuckDBIntervalValue, DuckDBTimeNSValue, DuckDBTimeTZValue, DuckDBTimeValue, DuckDBTimestampMillisecondsValue, DuckDBTimestampNanosecondsValue, DuckDBTimestampSecondsValue, DuckDBTimestampTZValue, DuckDBTimestampTZNanosecondsValue, DuckDBTimestampValue, DuckDBUUIDValue, DuckDBValue, DuckDBVariantValue } from './values';
+export declare function unwritableConverter(_: unknown, type: DuckDBType): never;
+export declare function nullFromNull(): null;
+export declare function valueFromBoolean(value: boolean): boolean;
+export declare function valueFromNumber(value: number): number;
+export declare function bigintFromNumeric(value: bigint | number): bigint;
+export declare function valueFromString(value: string): string;
+export declare function blobValueFromBytes(value: Uint8Array): DuckDBBlobValue;
+export declare function bitValueFromBytes(value: Uint8Array): DuckDBBitValue;
+export declare function geometryValueFromBytes(value: Uint8Array): DuckDBGeometryValue;
+export declare function dateValueFromDate(value: Date): DuckDBDateValue;
+export declare function timeValueFromMicros(value: bigint): DuckDBTimeValue;
+export declare function timeNSValueFromNanos(value: bigint): DuckDBTimeNSValue;
+export declare function timeTZValueFromObject(value: {
+    micros: bigint;
+    offset: number;
+}): DuckDBTimeTZValue;
+export declare function timestampValueFromDate(value: Date): DuckDBTimestampValue;
+export declare function timestampTZValueFromDate(value: Date): DuckDBTimestampTZValue;
+export declare function timestampTZNanosValueFromDate(value: Date): DuckDBTimestampTZNanosecondsValue;
+export declare function timestampSecondsValueFromDate(value: Date): DuckDBTimestampSecondsValue;
+export declare function timestampMillisValueFromDate(value: Date): DuckDBTimestampMillisecondsValue;
+export declare function timestampNanosValueFromDate(value: Date): DuckDBTimestampNanosecondsValue;
+export declare function intervalValueFromObject(value: {
+    months: number;
+    days: number;
+    micros: bigint;
+}): DuckDBIntervalValue;
+export declare function decimalValueFromNumeric(value: number | bigint, type: DuckDBType): DuckDBDecimalValue;
+export declare function uuidValueFromString(value: string): DuckDBUUIDValue;
+export declare function listValueFromArray<T>(value: readonly T[], type: DuckDBType, converter: ToDuckDBValueConverter<T>): DuckDBValue;
+export declare function arrayValueFromArray<T>(value: readonly T[], type: DuckDBType, converter: ToDuckDBValueConverter<T>): DuckDBValue;
+/**
+ * Converts an object keyed by entry name to a named STRUCT value, or an array
+ * of items to a tuple value (see `DuckDBStructType.isTuple`).
+ */
+export declare function structValueFromObject<T>(value: Readonly<Record<string, T>> | readonly T[], type: DuckDBType, converter: ToDuckDBValueConverter<T>): DuckDBValue;
+export declare function mapValueFromEntries<T>(value: readonly {
+    key: T;
+    value: T;
+}[], type: DuckDBType, converter: ToDuckDBValueConverter<T>): DuckDBValue;
+export declare function unionValueFromObject<T>(value: {
+    tag: string;
+    value: T;
+}, type: DuckDBType, converter: ToDuckDBValueConverter<T>): DuckDBValue;
+/**
+ * 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.
+ */
+export declare function variantValueFromJS(value: DuckDBVariantValue | boolean | number | bigint | string): DuckDBVariantValue;