@avidian/duckdb-bun 0.0.0-stage → 1.0.0

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

@@ -0,0 +1,136 @@
+import { DuckDBType } from './DuckDBType';
+import { DuckDBTypeId } from './DuckDBTypeId';
+import { JS } from './JS';
+import {
+  JSInputTypeFor,
+  JSInputTypeForTypeId,
+} from './JSInputTypeForTypeId';
+import {
+  ToDuckDBValueConverterFor,
+  createToDuckDBValueConverter,
+} from './ToDuckDBValueConverter';
+import {
+  arrayValueFromArray,
+  bigintFromNumeric,
+  bitValueFromBytes,
+  blobValueFromBytes,
+  dateValueFromDate,
+  decimalValueFromNumeric,
+  geometryValueFromBytes,
+  intervalValueFromObject,
+  listValueFromArray,
+  mapValueFromEntries,
+  nullFromNull,
+  structValueFromObject,
+  timeNSValueFromNanos,
+  timeTZValueFromObject,
+  timeValueFromMicros,
+  timestampMillisValueFromDate,
+  timestampNanosValueFromDate,
+  timestampSecondsValueFromDate,
+  timestampTZValueFromDate,
+  timestampTZNanosValueFromDate,
+  timestampValueFromDate,
+  unionValueFromObject,
+  unwritableConverter,
+  uuidValueFromString,
+  valueFromBoolean,
+  valueFromNumber,
+  valueFromString,
+  variantValueFromJS,
+} from './ToDuckDBValueConverters';
+import { DuckDBValue } from './values';
+
+const JSInputConvertersByTypeId: {
+  [Id in DuckDBTypeId]: ToDuckDBValueConverterFor<
+    JSInputTypeForTypeId[Id],
+    JS
+  >;
+} = {
+  [DuckDBTypeId.INVALID]: unwritableConverter,
+  [DuckDBTypeId.BOOLEAN]: valueFromBoolean,
+  [DuckDBTypeId.TINYINT]: valueFromNumber,
+  [DuckDBTypeId.SMALLINT]: valueFromNumber,
+  [DuckDBTypeId.INTEGER]: valueFromNumber,
+  [DuckDBTypeId.BIGINT]: bigintFromNumeric,
+  [DuckDBTypeId.UTINYINT]: valueFromNumber,
+  [DuckDBTypeId.USMALLINT]: valueFromNumber,
+  [DuckDBTypeId.UINTEGER]: valueFromNumber,
+  [DuckDBTypeId.UBIGINT]: bigintFromNumeric,
+  [DuckDBTypeId.FLOAT]: valueFromNumber,
+  [DuckDBTypeId.DOUBLE]: valueFromNumber,
+  [DuckDBTypeId.TIMESTAMP]: timestampValueFromDate,
+  [DuckDBTypeId.DATE]: dateValueFromDate,
+  [DuckDBTypeId.TIME]: timeValueFromMicros,
+  [DuckDBTypeId.INTERVAL]: intervalValueFromObject,
+  [DuckDBTypeId.HUGEINT]: bigintFromNumeric,
+  [DuckDBTypeId.UHUGEINT]: bigintFromNumeric,
+  [DuckDBTypeId.VARCHAR]: valueFromString,
+  [DuckDBTypeId.BLOB]: blobValueFromBytes,
+  [DuckDBTypeId.DECIMAL]: decimalValueFromNumeric,
+  [DuckDBTypeId.TIMESTAMP_S]: timestampSecondsValueFromDate,
+  [DuckDBTypeId.TIMESTAMP_MS]: timestampMillisValueFromDate,
+  [DuckDBTypeId.TIMESTAMP_NS]: timestampNanosValueFromDate,
+  [DuckDBTypeId.ENUM]: valueFromString,
+  [DuckDBTypeId.LIST]: listValueFromArray,
+  [DuckDBTypeId.STRUCT]: structValueFromObject,
+  [DuckDBTypeId.MAP]: mapValueFromEntries,
+  [DuckDBTypeId.ARRAY]: arrayValueFromArray,
+  [DuckDBTypeId.UUID]: uuidValueFromString,
+  [DuckDBTypeId.UNION]: unionValueFromObject,
+  [DuckDBTypeId.BIT]: bitValueFromBytes,
+  [DuckDBTypeId.TIME_TZ]: timeTZValueFromObject,
+  [DuckDBTypeId.TIMESTAMP_TZ]: timestampTZValueFromDate,
+  [DuckDBTypeId.ANY]: unwritableConverter,
+  [DuckDBTypeId.BIGNUM]: bigintFromNumeric,
+  [DuckDBTypeId.SQLNULL]: nullFromNull,
+  [DuckDBTypeId.STRING_LITERAL]: unwritableConverter,
+  [DuckDBTypeId.INTEGER_LITERAL]: unwritableConverter,
+  [DuckDBTypeId.TIME_NS]: timeNSValueFromNanos,
+  [DuckDBTypeId.GEOMETRY]: geometryValueFromBytes,
+  [DuckDBTypeId.VARIANT]: variantValueFromJS,
+  [DuckDBTypeId.TIMESTAMP_TZ_NS]: 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.
+ */
+export const JSToDuckDBValueConverter = createToDuckDBValueConverter<
+  JS,
+  JSInputTypeForTypeId
+>(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`.
+ */
+export function jsToDuckDBValue<T extends DuckDBType>(
+  value: JSInputTypeFor<T> | null,
+  type: T
+): DuckDBValue {
+  // 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 JSToDuckDBValueConverter(
+    value as JS,
+    type,
+    JSToDuckDBValueConverter
+  );
+}

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

@@ -0,0 +1,78 @@
+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/vendor/node-api/src/Json.ts

@@ -0,0 +1,7 @@
+export type Json =
+  | null
+  | boolean
+  | number
+  | string
+  | Json[]
+  | { [key: string]: Json };

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

@@ -0,0 +1,72 @@
+import { createDuckDBValueConverter } from './createDuckDBValueConverter';
+import { DuckDBTypeId } from './DuckDBTypeId';
+import { DuckDBValueConverterFor } from './DuckDBValueConverter';
+import {
+  arrayFromArrayValue,
+  arrayFromListValue,
+  booleanFromValue,
+  fromVariantValue,
+  jsonNumberFromValue,
+  jsonObjectFromIntervalValue,
+  nullConverter,
+  numberFromValue,
+  objectArrayFromMapValue,
+  objectOrArrayFromStructValue,
+  objectFromUnionValue,
+  stringFromValue,
+  unsupportedConverter,
+} from './DuckDBValueConverters';
+import { Json } from './Json';
+import { JsonTypeForTypeId } from './JsonTypeForTypeId';
+
+const JsonConvertersByTypeId: {
+  [Id in DuckDBTypeId]: DuckDBValueConverterFor<JsonTypeForTypeId[Id], Json>;
+} = {
+  [DuckDBTypeId.INVALID]: unsupportedConverter,
+  [DuckDBTypeId.BOOLEAN]: booleanFromValue,
+  [DuckDBTypeId.TINYINT]: numberFromValue,
+  [DuckDBTypeId.SMALLINT]: numberFromValue,
+  [DuckDBTypeId.INTEGER]: numberFromValue,
+  [DuckDBTypeId.BIGINT]: stringFromValue,
+  [DuckDBTypeId.UTINYINT]: numberFromValue,
+  [DuckDBTypeId.USMALLINT]: numberFromValue,
+  [DuckDBTypeId.UINTEGER]: numberFromValue,
+  [DuckDBTypeId.UBIGINT]: stringFromValue,
+  [DuckDBTypeId.FLOAT]: jsonNumberFromValue,
+  [DuckDBTypeId.DOUBLE]: jsonNumberFromValue,
+  [DuckDBTypeId.TIMESTAMP]: stringFromValue,
+  [DuckDBTypeId.DATE]: stringFromValue,
+  [DuckDBTypeId.TIME]: stringFromValue,
+  [DuckDBTypeId.INTERVAL]: jsonObjectFromIntervalValue,
+  [DuckDBTypeId.HUGEINT]: stringFromValue,
+  [DuckDBTypeId.UHUGEINT]: stringFromValue,
+  [DuckDBTypeId.VARCHAR]: stringFromValue,
+  [DuckDBTypeId.BLOB]: stringFromValue,
+  [DuckDBTypeId.DECIMAL]: stringFromValue,
+  [DuckDBTypeId.TIMESTAMP_S]: stringFromValue,
+  [DuckDBTypeId.TIMESTAMP_MS]: stringFromValue,
+  [DuckDBTypeId.TIMESTAMP_NS]: stringFromValue,
+  [DuckDBTypeId.ENUM]: stringFromValue,
+  [DuckDBTypeId.LIST]: arrayFromListValue,
+  [DuckDBTypeId.STRUCT]: objectOrArrayFromStructValue,
+  [DuckDBTypeId.MAP]: objectArrayFromMapValue,
+  [DuckDBTypeId.ARRAY]: arrayFromArrayValue,
+  [DuckDBTypeId.UUID]: stringFromValue,
+  [DuckDBTypeId.UNION]: objectFromUnionValue,
+  [DuckDBTypeId.BIT]: stringFromValue,
+  [DuckDBTypeId.TIME_TZ]: stringFromValue,
+  [DuckDBTypeId.TIMESTAMP_TZ]: stringFromValue,
+  [DuckDBTypeId.ANY]: unsupportedConverter,
+  [DuckDBTypeId.BIGNUM]: stringFromValue,
+  [DuckDBTypeId.SQLNULL]: nullConverter,
+  [DuckDBTypeId.STRING_LITERAL]: unsupportedConverter,
+  [DuckDBTypeId.INTEGER_LITERAL]: unsupportedConverter,
+  [DuckDBTypeId.TIME_NS]: stringFromValue,
+  [DuckDBTypeId.GEOMETRY]: stringFromValue,
+  [DuckDBTypeId.VARIANT]: fromVariantValue,
+  [DuckDBTypeId.TIMESTAMP_TZ_NS]: stringFromValue,
+};
+
+export const JsonDuckDBValueConverter = createDuckDBValueConverter<Json>(
+  JsonConvertersByTypeId
+);

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

@@ -0,0 +1,86 @@
+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/vendor/node-api/src/ToDuckDBValueConverter.ts

@@ -0,0 +1,68 @@
+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 function createToDuckDBValueConverter<
+  T,
+  InputTable extends Record<DuckDBTypeId, unknown>,
+>(convertersByTypeId: {
+  [Id in DuckDBTypeId]: ToDuckDBValueConverterFor<InputTable[Id], T>;
+}): ToDuckDBValueConverter<T> {
+  return (value, type, converter) => {
+    if (value == null) {
+      return null;
+    }
+    const converterForTypeId = convertersByTypeId[type.typeId] as
+      | ToDuckDBValueConverter<T>
+      | undefined;
+    if (!converterForTypeId) {
+      throw new Error(`No converter for typeId: ${type.typeId}`);
+    }
+    return converterForTypeId(value, type, converter);
+  };
+}