@avidian/duckdb-bun 0.0.0-stage → 1.0.1

package/vendor/node-api/src/DuckDBValueConverters.ts

@@ -0,0 +1,461 @@
+import {
+  DuckDBArrayType,
+  DuckDBListType,
+  DuckDBMapType,
+  DuckDBStructType,
+  DuckDBType,
+  DuckDBUnionType,
+} from './DuckDBType';
+import { DuckDBTypeId } from './DuckDBTypeId';
+import { DuckDBValueConverter } from './DuckDBValueConverter';
+import { typeForValue } from './typeForValue';
+import {
+  DuckDBArrayValue,
+  DuckDBBitValue,
+  DuckDBBlobValue,
+  DuckDBDateValue,
+  DuckDBDecimalValue,
+  DuckDBGeometryValue,
+  DuckDBIntervalValue,
+  DuckDBListValue,
+  DuckDBMapValue,
+  DuckDBStructValue,
+  DuckDBTimeTZValue,
+  DuckDBTimeNSValue,
+  DuckDBTimeValue,
+  DuckDBTimestampMillisecondsValue,
+  DuckDBTimestampNanosecondsValue,
+  DuckDBTimestampSecondsValue,
+  DuckDBTimestampTZValue,
+  DuckDBTimestampTZNanosecondsValue,
+  DuckDBTimestampValue,
+  DuckDBTupleValue,
+  DuckDBUnionValue,
+  DuckDBValue,
+  DuckDBVariantValue,
+} from './values';
+
+const MIN_DATE_DAYS = -100000000;
+const MAX_DATE_DAYS = 100000000;
+//                      -8640000000000
+const MIN_DATE_MILLIS = -8640000000000000;
+const MAX_DATE_MILLIS = 8640000000000000;
+
+/** Whether a TIMESTAMP_NS or TIMESTAMPTZ_NS value is not +/-infinity. */
+function isFiniteNanos(nanos: bigint): boolean {
+  return (
+    nanos !== DuckDBTimestampNanosecondsValue.PosInf.nanos &&
+    nanos !== DuckDBTimestampNanosecondsValue.NegInf.nanos
+  );
+}
+
+const MILLS_PER_DAY = 24 * 60 * 60 * 1000;
+
+export function unsupportedConverter(_: DuckDBValue, type: DuckDBType): null {
+  throw new Error(`Unsupported type: ${type}`);
+}
+
+export function nullConverter(_: DuckDBValue): null {
+  return null;
+}
+
+export function booleanFromValue(value: DuckDBValue): boolean {
+  return Boolean(value);
+}
+
+export function numberFromValue(value: DuckDBValue): number {
+  return Number(value);
+}
+
+export function jsonNumberFromValue(value: DuckDBValue): number | string {
+  if (Number.isFinite(value)) {
+    return Number(value);
+  }
+  return String(value);
+}
+
+export function bigintFromBigIntValue(
+  value: DuckDBValue,
+  type: DuckDBType
+): bigint {
+  if (typeof value === 'bigint') {
+    return value;
+  }
+  throw new Error(`Expected bigint value for type ${type}`);
+}
+
+export function stringFromValue(value: DuckDBValue): string {
+  return String(value);
+}
+
+export function bytesFromBlobValue(value: DuckDBValue): Uint8Array {
+  if (value instanceof DuckDBBlobValue) {
+    return value.bytes;
+  }
+  throw new Error(`Expected DuckDBBlobValue`);
+}
+
+export function bytesFromBitValue(value: DuckDBValue): Uint8Array {
+  if (value instanceof DuckDBBitValue) {
+    return value.data;
+  }
+  throw new Error(`Expected DuckDBBitValue`);
+}
+
+export function bytesFromGeometryValue(value: DuckDBValue): Uint8Array {
+  if (value instanceof DuckDBGeometryValue) {
+    return value.bytes;
+  }
+  throw new Error(`Expected DuckDBGeometryValue`);
+}
+
+export function dateFromDateValue(value: DuckDBValue): Date {
+  if (value instanceof DuckDBDateValue) {
+    if (MIN_DATE_DAYS <= value.days && value.days <= MAX_DATE_DAYS) {
+      return new Date(value.days * MILLS_PER_DAY);
+    }
+    throw new Error(`DATE value out of range for JS Date: ${value.days} days`);
+  }
+  throw new Error(`Expected DuckDBDateValue`);
+}
+
+export function bigintFromTimeValue(value: DuckDBValue): bigint {
+  if (value instanceof DuckDBTimeValue) {
+    return value.micros;
+  }
+  throw new Error(`Expected DuckDBTimeValue`);
+}
+
+export function bigintFromTimeNSValue(value: DuckDBValue): bigint {
+  if (value instanceof DuckDBTimeNSValue) {
+    return value.nanos;
+  }
+  throw new Error(`Expected DuckDBTimeNSValue`);
+}
+
+export function dateFromTimestampValue(value: DuckDBValue): Date {
+  if (value instanceof DuckDBTimestampValue) {
+    const millis = value.micros / 1000n;
+    if (MIN_DATE_MILLIS <= millis && millis <= MAX_DATE_MILLIS) {
+      return new Date(Number(millis));
+    }
+    throw new Error(
+      `TIMESTAMP value out of range for JS Date: ${value.micros} micros`
+    );
+  }
+  throw new Error(`Expected DuckDBTimestampValue`);
+}
+
+export function dateFromTimestampSecondsValue(value: DuckDBValue): Date {
+  if (value instanceof DuckDBTimestampSecondsValue) {
+    const millis = value.seconds * 1000n;
+    if (MIN_DATE_MILLIS <= millis && millis <= MAX_DATE_MILLIS) {
+      return new Date(Number(millis));
+    }
+    throw new Error(
+      `TIMESTAMP_S value out of range for JS Date: ${value.seconds} seconds`
+    );
+  }
+  throw new Error(`Expected DuckDBTimestampSecondsValue`);
+}
+
+export function dateFromTimestampMillisecondsValue(value: DuckDBValue): Date {
+  if (value instanceof DuckDBTimestampMillisecondsValue) {
+    const millis = value.millis;
+    if (MIN_DATE_MILLIS <= millis && millis <= MAX_DATE_MILLIS) {
+      return new Date(Number(millis));
+    }
+    throw new Error(
+      `TIMESTAMP_MS value out of range for JS Date: ${value.millis} millis`
+    );
+  }
+  throw new Error(`Expected DuckDBTimestampMillisecondsValue`);
+}
+
+export function dateFromTimestampNanosecondsValue(value: DuckDBValue): Date {
+  if (value instanceof DuckDBTimestampNanosecondsValue) {
+    const millis = value.nanos / 1000000n;
+    if (
+      isFiniteNanos(value.nanos) &&
+      MIN_DATE_MILLIS <= millis &&
+      millis <= MAX_DATE_MILLIS
+    ) {
+      return new Date(Number(millis));
+    }
+    throw new Error(
+      `TIMESTAMP_NS value out of range for JS Date: ${value.nanos} nanos`
+    );
+  }
+  throw new Error(`Expected DuckDBTimestampNanosecondsValue`);
+}
+
+export function objectFromTimeTZValue(value: DuckDBValue): {
+  micros: bigint;
+  offset: number;
+} {
+  if (value instanceof DuckDBTimeTZValue) {
+    return {
+      micros: value.micros,
+      offset: value.offset,
+    };
+  }
+  throw new Error(`Expected DuckDBTimeTZValue`);
+}
+
+export function dateFromTimestampTZValue(value: DuckDBValue): Date {
+  if (value instanceof DuckDBTimestampTZValue) {
+    const millis = value.micros / 1000n;
+    if (MIN_DATE_MILLIS <= millis && millis <= MAX_DATE_MILLIS) {
+      return new Date(Number(millis));
+    }
+    throw new Error(
+      `TIMESTAMPTZ value out of range for JS Date: ${value.micros} micros`
+    );
+  }
+  throw new Error(`Expected DuckDBTimestampTZValue`);
+}
+
+export function dateFromTimestampTZNanosecondsValue(value: DuckDBValue): Date {
+  if (value instanceof DuckDBTimestampTZNanosecondsValue) {
+    const millis = value.nanos / 1000000n;
+    if (
+      isFiniteNanos(value.nanos) &&
+      MIN_DATE_MILLIS <= millis &&
+      millis <= MAX_DATE_MILLIS
+    ) {
+      return new Date(Number(millis));
+    }
+    throw new Error(
+      `TIMESTAMP_TZ_NS value out of range for JS Date: ${value.nanos} nanos`
+    );
+  }
+  throw new Error(`Expected DuckDBTimestampTZNanosecondsValue`);
+}
+
+export function objectFromIntervalValue(value: DuckDBValue): {
+  months: number;
+  days: number;
+  micros: bigint;
+} {
+  if (value instanceof DuckDBIntervalValue) {
+    return {
+      months: value.months,
+      days: value.days,
+      micros: value.micros,
+    };
+  }
+  throw new Error(`Expected DuckDBIntervalValue`);
+}
+
+export function jsonObjectFromIntervalValue(value: DuckDBValue): {
+  months: number;
+  days: number;
+  micros: string;
+} {
+  if (value instanceof DuckDBIntervalValue) {
+    return {
+      months: value.months,
+      days: value.days,
+      micros: String(value.micros),
+    };
+  }
+  throw new Error(`Expected DuckDBIntervalValue`);
+}
+
+export function doubleFromDecimalValue(value: DuckDBValue): number {
+  if (value instanceof DuckDBDecimalValue) {
+    return value.toDouble();
+  }
+  throw new Error(`Expected DuckDBDecimalValue`);
+}
+
+export function arrayFromListValue<T>(
+  value: DuckDBValue,
+  type: DuckDBType,
+  converter: DuckDBValueConverter<T>
+): (T | null)[] {
+  if (value instanceof DuckDBListValue && type instanceof DuckDBListType) {
+    return value.items.map((v) => converter(v, type.valueType, converter));
+  }
+  throw new Error(`Expected DuckDBListValue and DuckDBListType`);
+}
+
+export function objectFromStructValue<T>(
+  value: DuckDBValue,
+  type: DuckDBType,
+  converter: DuckDBValueConverter<T>
+): { [key: string]: T | null } {
+  if (value instanceof DuckDBStructValue && type instanceof DuckDBStructType) {
+    const result: { [key: string]: T | null } = {};
+    for (const key in value.entries) {
+      result[key] = converter(
+        value.entries[key],
+        type.typeForEntry(key),
+        converter
+      );
+    }
+    return result;
+  }
+  throw new Error(`Expected DuckDBStructValue and DuckDBStructType`);
+}
+
+export function arrayFromTupleValue<T>(
+  value: DuckDBValue,
+  type: DuckDBType,
+  converter: DuckDBValueConverter<T>
+): (T | null)[] {
+  if (
+    value instanceof DuckDBTupleValue &&
+    type instanceof DuckDBStructType &&
+    type.isTuple
+  ) {
+    return value.items.map((item, i) =>
+      converter(item, type.entryTypes[i], converter)
+    );
+  }
+  throw new Error(`Expected DuckDBTupleValue and tuple DuckDBStructType`);
+}
+
+/**
+ * Converts a STRUCT value: a tuple (see `DuckDBStructType.isTuple`) to an
+ * array of its items, and a named struct to an object keyed by entry name.
+ */
+export function objectOrArrayFromStructValue<T>(
+  value: DuckDBValue,
+  type: DuckDBType,
+  converter: DuckDBValueConverter<T>
+): { [key: string]: T | null } | (T | null)[] {
+  if (value instanceof DuckDBTupleValue) {
+    return arrayFromTupleValue(value, type, converter);
+  }
+  return objectFromStructValue(value, type, converter);
+}
+
+export function objectArrayFromMapValue<T>(
+  value: DuckDBValue,
+  type: DuckDBType,
+  converter: DuckDBValueConverter<T>
+): { key: T | null; value: T | null }[] {
+  if (value instanceof DuckDBMapValue && type instanceof DuckDBMapType) {
+    return value.entries.map((entry) => ({
+      key: converter(entry.key, type.keyType, converter),
+      value: converter(entry.value, type.valueType, converter),
+    }));
+  }
+  throw new Error(`Expected DuckDBMapValue and DuckDBMapType`);
+}
+
+export function arrayFromArrayValue<T>(
+  value: DuckDBValue,
+  type: DuckDBType,
+  converter: DuckDBValueConverter<T>
+): (T | null)[] {
+  if (value instanceof DuckDBArrayValue && type instanceof DuckDBArrayType) {
+    return value.items.map((v) => converter(v, type.valueType, converter));
+  }
+  throw new Error(`Expected DuckDBArrayValue and DuckDBArrayType`);
+}
+
+export function objectFromUnionValue<T>(
+  value: DuckDBValue,
+  type: DuckDBType,
+  converter: DuckDBValueConverter<T>
+): { tag: string; value: T | null } {
+  if (value instanceof DuckDBUnionValue && type instanceof DuckDBUnionType) {
+    return {
+      tag: value.tag,
+      value: converter(
+        value.value,
+        type.memberTypeForTag(value.tag),
+        converter
+      ),
+    };
+  }
+  throw new Error(`Expected DuckDBUnionValue and DuckDBUnionType`);
+}
+
+/**
+ * Converter for VARIANT values: unwraps the `DuckDBVariantValue` wrapper
+ * and recursively walks the inner value, re-dispatching each scalar leaf
+ * through the supplied converter.
+ *
+ * A walker is needed (rather than just dispatching through the converter)
+ * because VARIANT containers are *heterogeneous* — items in a list or
+ * fields in a struct can have different types — while
+ * `arrayFromListValue` / `objectFromStructValue` / `objectArrayFromMapValue`
+ * assume a homogeneous element type pulled from the enclosing
+ * `DuckDBListType` / `DuckDBStructType` / `DuckDBMapType`. The walker
+ * emits the same output shape those converters do, and prefers the
+ * `DuckDBVariantValue.type` recorded by the decoder over `typeForValue`
+ * inference whenever a wrapper is encountered.
+ */
+export function fromVariantValue<T>(
+  value: DuckDBValue,
+  _type: DuckDBType,
+  converter: DuckDBValueConverter<T>
+): T | null {
+  if (!(value instanceof DuckDBVariantValue)) {
+    throw new Error(`Expected DuckDBVariantValue`);
+  }
+  return convertVariantInner(value.value, converter, value.type);
+}
+
+function convertVariantInner<T>(
+  value: DuckDBValue,
+  converter: DuckDBValueConverter<T>,
+  typeHint?: DuckDBType
+): T | null {
+  if (value === null) {
+    return null;
+  }
+  if (value instanceof DuckDBVariantValue) {
+    // Variant-of-variant (or a wrapped child inside a LIST(VARIANT)).
+    // Prefer the wrapper's exact type as the hint for further walking.
+    return convertVariantInner(value.value, converter, value.type ?? typeHint);
+  }
+  if (value instanceof DuckDBListValue || value instanceof DuckDBArrayValue) {
+    return value.items.map((item) =>
+      convertVariantInner(item, converter)
+    ) as unknown as T;
+  }
+  if (value instanceof DuckDBStructValue) {
+    const result: { [key: string]: T | null } = {};
+    for (const key in value.entries) {
+      result[key] = convertVariantInner(value.entries[key], converter);
+    }
+    return result as unknown as T;
+  }
+  if (value instanceof DuckDBTupleValue) {
+    return value.items.map((item) =>
+      convertVariantInner(item, converter)
+    ) as unknown as T;
+  }
+  if (value instanceof DuckDBMapValue) {
+    return value.entries.map((entry) => ({
+      key: convertVariantInner(entry.key, converter),
+      value: convertVariantInner(entry.value, converter),
+    })) as unknown as T;
+  }
+  if (value instanceof DuckDBUnionValue) {
+    return {
+      tag: value.tag,
+      value: convertVariantInner(value.value, converter),
+    } as unknown as T;
+  }
+  // Scalar (or non-recursable rich value like DECIMAL, BLOB, DATE, etc.):
+  // dispatch through the regular converter. Use `typeHint` (carried in
+  // from a wrapper) for type fidelity when available; fall back to
+  // `typeForValue` otherwise.
+  const inferredType = typeHint ?? typeForValue(value);
+  // `typeForValue` infers BIGINT for any JS integer number outside INT32
+  // range (e.g. a UINT32 VARIANT payload of 4_294_967_295). The BIGINT
+  // converters expect a `bigint`, not a `number`, and would otherwise
+  // throw. Coerce to bigint so the dispatch lands on a compatible reader.
+  if (
+    typeof value === 'number' &&
+    inferredType.typeId === DuckDBTypeId.BIGINT
+  ) {
+    return converter(BigInt(value), inferredType, converter);
+  }
+  return converter(value, inferredType, converter);
+}

package/vendor/node-api/src/DuckDBVector.ts

@@ -0,0 +1 @@
+export * from './vectors';

package/vendor/node-api/src/JS.ts

@@ -0,0 +1,11 @@
+export type JS =
+  | null
+  | boolean
+  | number
+  | bigint
+  | string
+  | Uint8Array
+  | Date
+  | JS[]
+  | { [key: string]: JS };
+  

package/vendor/node-api/src/JSDuckDBValueConverter.ts

@@ -0,0 +1,85 @@
+import { createDuckDBValueConverter } from './createDuckDBValueConverter';
+import { DuckDBTypeId } from './DuckDBTypeId';
+import { DuckDBValueConverterFor } from './DuckDBValueConverter';
+import {
+  arrayFromArrayValue,
+  arrayFromListValue,
+  bigintFromBigIntValue,
+  bigintFromTimeNSValue,
+  bigintFromTimeValue,
+  booleanFromValue,
+  bytesFromBitValue,
+  bytesFromBlobValue,
+  bytesFromGeometryValue,
+  dateFromDateValue,
+  dateFromTimestampMillisecondsValue,
+  dateFromTimestampNanosecondsValue,
+  dateFromTimestampSecondsValue,
+  dateFromTimestampTZValue,
+  dateFromTimestampTZNanosecondsValue,
+  dateFromTimestampValue,
+  doubleFromDecimalValue,
+  fromVariantValue,
+  nullConverter,
+  numberFromValue,
+  objectArrayFromMapValue,
+  objectFromIntervalValue,
+  objectOrArrayFromStructValue,
+  objectFromTimeTZValue,
+  objectFromUnionValue,
+  stringFromValue,
+  unsupportedConverter,
+} from './DuckDBValueConverters';
+import { JS } from './JS';
+import { JSTypeForTypeId } from './JSTypeForTypeId';
+
+const JSConvertersByTypeId: {
+  [Id in DuckDBTypeId]: DuckDBValueConverterFor<JSTypeForTypeId[Id], JS>;
+} = {
+  [DuckDBTypeId.INVALID]: unsupportedConverter,
+  [DuckDBTypeId.BOOLEAN]: booleanFromValue,
+  [DuckDBTypeId.TINYINT]: numberFromValue,
+  [DuckDBTypeId.SMALLINT]: numberFromValue,
+  [DuckDBTypeId.INTEGER]: numberFromValue,
+  [DuckDBTypeId.BIGINT]: bigintFromBigIntValue,
+  [DuckDBTypeId.UTINYINT]: numberFromValue,
+  [DuckDBTypeId.USMALLINT]: numberFromValue,
+  [DuckDBTypeId.UINTEGER]: numberFromValue,
+  [DuckDBTypeId.UBIGINT]: bigintFromBigIntValue,
+  [DuckDBTypeId.FLOAT]: numberFromValue,
+  [DuckDBTypeId.DOUBLE]: numberFromValue,
+  [DuckDBTypeId.TIMESTAMP]: dateFromTimestampValue,
+  [DuckDBTypeId.DATE]: dateFromDateValue,
+  [DuckDBTypeId.TIME]: bigintFromTimeValue,
+  [DuckDBTypeId.INTERVAL]: objectFromIntervalValue,
+  [DuckDBTypeId.HUGEINT]: bigintFromBigIntValue,
+  [DuckDBTypeId.UHUGEINT]: bigintFromBigIntValue,
+  [DuckDBTypeId.VARCHAR]: stringFromValue,
+  [DuckDBTypeId.BLOB]: bytesFromBlobValue,
+  [DuckDBTypeId.DECIMAL]: doubleFromDecimalValue,
+  [DuckDBTypeId.TIMESTAMP_S]: dateFromTimestampSecondsValue,
+  [DuckDBTypeId.TIMESTAMP_MS]: dateFromTimestampMillisecondsValue,
+  [DuckDBTypeId.TIMESTAMP_NS]: dateFromTimestampNanosecondsValue,
+  [DuckDBTypeId.ENUM]: stringFromValue,
+  [DuckDBTypeId.LIST]: arrayFromListValue,
+  [DuckDBTypeId.STRUCT]: objectOrArrayFromStructValue,
+  [DuckDBTypeId.MAP]: objectArrayFromMapValue,
+  [DuckDBTypeId.ARRAY]: arrayFromArrayValue,
+  [DuckDBTypeId.UUID]: stringFromValue,
+  [DuckDBTypeId.UNION]: objectFromUnionValue,
+  [DuckDBTypeId.BIT]: bytesFromBitValue,
+  [DuckDBTypeId.TIME_TZ]: objectFromTimeTZValue,
+  [DuckDBTypeId.TIMESTAMP_TZ]: dateFromTimestampTZValue,
+  [DuckDBTypeId.ANY]: unsupportedConverter,
+  [DuckDBTypeId.BIGNUM]: bigintFromBigIntValue,
+  [DuckDBTypeId.SQLNULL]: nullConverter,
+  [DuckDBTypeId.STRING_LITERAL]: unsupportedConverter,
+  [DuckDBTypeId.INTEGER_LITERAL]: unsupportedConverter,
+  [DuckDBTypeId.TIME_NS]: bigintFromTimeNSValue,
+  [DuckDBTypeId.GEOMETRY]: bytesFromGeometryValue,
+  [DuckDBTypeId.VARIANT]: fromVariantValue,
+  [DuckDBTypeId.TIMESTAMP_TZ_NS]: dateFromTimestampTZNanosecondsValue,
+};
+
+export const JSDuckDBValueConverter =
+  createDuckDBValueConverter<JS>(JSConvertersByTypeId);

package/vendor/node-api/src/JSInputTypeForTypeId.ts

@@ -0,0 +1,101 @@
+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']];