@avidian/duckdb-bun 0.0.0-stage → 1.0.0

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

@@ -0,0 +1,303 @@
+import {
+  DuckDBArrayType,
+  DuckDBDecimalType,
+  DuckDBListType,
+  DuckDBMapType,
+  DuckDBStructType,
+  DuckDBType,
+  DuckDBUnionType,
+} 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,
+  arrayValue,
+  listValue,
+  mapValue,
+  structValue,
+  tupleValue,
+  unionValue,
+  variantValue,
+} from './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: Date): number {
+  const millis = value.getTime();
+  if (Number.isNaN(millis)) {
+    throw new Error(`Cannot convert an Invalid Date`);
+  }
+  return millis;
+}
+
+export function unwritableConverter(_: unknown, type: DuckDBType): never {
+  throw new Error(`Cannot write values of type: ${type}`);
+}
+
+export function nullFromNull(): null {
+  return null;
+}
+
+export function valueFromBoolean(value: boolean): boolean {
+  return Boolean(value);
+}
+
+export function valueFromNumber(value: number): number {
+  return value;
+}
+
+export function bigintFromNumeric(value: bigint | number): bigint {
+  return typeof value === 'bigint' ? value : BigInt(value);
+}
+
+export function valueFromString(value: string): string {
+  return value;
+}
+
+export function blobValueFromBytes(value: Uint8Array): DuckDBBlobValue {
+  return new DuckDBBlobValue(value);
+}
+
+export function bitValueFromBytes(value: Uint8Array): DuckDBBitValue {
+  return new DuckDBBitValue(value);
+}
+
+export function geometryValueFromBytes(value: Uint8Array): DuckDBGeometryValue {
+  return new DuckDBGeometryValue(value);
+}
+
+export function dateValueFromDate(value: Date): DuckDBDateValue {
+  // 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 DuckDBDateValue(Math.floor(millisFromDate(value) / MILLIS_PER_DAY));
+}
+
+export function timeValueFromMicros(value: bigint): DuckDBTimeValue {
+  return new DuckDBTimeValue(value);
+}
+
+export function timeNSValueFromNanos(value: bigint): DuckDBTimeNSValue {
+  return new DuckDBTimeNSValue(value);
+}
+
+export function timeTZValueFromObject(value: {
+  micros: bigint;
+  offset: number;
+}): DuckDBTimeTZValue {
+  return DuckDBTimeTZValue.fromMicrosAndOffset(value.micros, value.offset);
+}
+
+export function timestampValueFromDate(value: Date): DuckDBTimestampValue {
+  return new DuckDBTimestampValue(BigInt(millisFromDate(value)) * 1000n);
+}
+
+export function timestampTZValueFromDate(value: Date): DuckDBTimestampTZValue {
+  return new DuckDBTimestampTZValue(BigInt(millisFromDate(value)) * 1000n);
+}
+
+export function timestampTZNanosValueFromDate(
+  value: Date
+): DuckDBTimestampTZNanosecondsValue {
+  return new DuckDBTimestampTZNanosecondsValue(
+    BigInt(millisFromDate(value)) * 1000000n
+  );
+}
+
+export function timestampSecondsValueFromDate(
+  value: Date
+): DuckDBTimestampSecondsValue {
+  return new DuckDBTimestampSecondsValue(
+    BigInt(Math.floor(millisFromDate(value) / 1000))
+  );
+}
+
+export function timestampMillisValueFromDate(
+  value: Date
+): DuckDBTimestampMillisecondsValue {
+  return new DuckDBTimestampMillisecondsValue(BigInt(millisFromDate(value)));
+}
+
+export function timestampNanosValueFromDate(
+  value: Date
+): DuckDBTimestampNanosecondsValue {
+  return new DuckDBTimestampNanosecondsValue(
+    BigInt(millisFromDate(value)) * 1000000n
+  );
+}
+
+export function intervalValueFromObject(value: {
+  months: number;
+  days: number;
+  micros: bigint;
+}): DuckDBIntervalValue {
+  return new DuckDBIntervalValue(value.months, value.days, value.micros);
+}
+
+export function decimalValueFromNumeric(
+  value: number | bigint,
+  type: DuckDBType
+): DuckDBDecimalValue {
+  if (!(type instanceof DuckDBDecimalType)) {
+    throw new Error(`Expected DuckDBDecimalType`);
+  }
+  return typeof value === 'bigint'
+    ? new DuckDBDecimalValue(value, type.width, type.scale)
+    : 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;
+
+export function uuidValueFromString(value: string): DuckDBUUIDValue {
+  if (!UUID_PATTERN.test(value)) {
+    throw new Error(`Not a UUID string: ${value}`);
+  }
+  return DuckDBUUIDValue.fromUint128(BigInt(`0x${value.replace(/-/g, '')}`));
+}
+
+export function listValueFromArray<T>(
+  value: readonly T[],
+  type: DuckDBType,
+  converter: ToDuckDBValueConverter<T>
+): DuckDBValue {
+  if (!(type instanceof DuckDBListType)) {
+    throw new Error(`Expected DuckDBListType`);
+  }
+  return listValue(
+    value.map((item) => converter(item, type.valueType, converter))
+  );
+}
+
+export function arrayValueFromArray<T>(
+  value: readonly T[],
+  type: DuckDBType,
+  converter: ToDuckDBValueConverter<T>
+): DuckDBValue {
+  if (!(type instanceof DuckDBArrayType)) {
+    throw new Error(`Expected DuckDBArrayType`);
+  }
+  if (value.length !== type.length) {
+    throw new Error(
+      `Expected ${type.length} items for ${type}, got ${value.length}`
+    );
+  }
+  return 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`).
+ */
+export function structValueFromObject<T>(
+  value: Readonly<Record<string, T>> | readonly T[],
+  type: DuckDBType,
+  converter: ToDuckDBValueConverter<T>
+): DuckDBValue {
+  if (!(type instanceof 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 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 as Readonly<Record<string, T>>;
+  const entries: Record<string, DuckDBValue> = {};
+  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 structValue(entries);
+}
+
+export function mapValueFromEntries<T>(
+  value: readonly { key: T; value: T }[],
+  type: DuckDBType,
+  converter: ToDuckDBValueConverter<T>
+): DuckDBValue {
+  if (!(type instanceof DuckDBMapType)) {
+    throw new Error(`Expected DuckDBMapType`);
+  }
+  return mapValue(
+    value.map((entry) => ({
+      key: converter(entry.key, type.keyType, converter),
+      value: converter(entry.value, type.valueType, converter),
+    }))
+  );
+}
+
+export function unionValueFromObject<T>(
+  value: { tag: string; value: T },
+  type: DuckDBType,
+  converter: ToDuckDBValueConverter<T>
+): DuckDBValue {
+  if (!(type instanceof 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 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.
+ */
+export function variantValueFromJS(
+  value: DuckDBVariantValue | boolean | number | bigint | string
+): DuckDBVariantValue {
+  return value instanceof DuckDBVariantValue ? value : variantValue(value);
+}

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

@@ -0,0 +1,13 @@
+import duckdb from "../../../src/bindings/index.ts";
+
+export function configurationOptionDescriptions(): Readonly<
+  Record<string, string>
+> {
+  const descriptions: Record<string, string> = {};
+  const count = duckdb.config_count();
+  for (let i = 0; i < count; i++) {
+    const { name, description } = duckdb.get_config_flag(i);
+    descriptions[name] = description;
+  }
+  return descriptions;
+}

package/vendor/node-api/src/conversion/bytesFromString.ts

@@ -0,0 +1,5 @@
+const textEncoder = new TextEncoder();
+
+export function bytesFromString(str: string): Uint8Array {
+  return textEncoder.encode(str);
+}

package/vendor/node-api/src/conversion/dateTimeStringConversion.ts

@@ -0,0 +1,343 @@
+const DAYS_IN_400_YEARS = 146097; // (((365 * 4 + 1) * 25) - 1) * 4 + 1
+const MILLISECONDS_PER_DAY_NUM = 86400000; // 1000 * 60 * 60 * 24
+
+const MICROSECONDS_PER_SECOND = 1000000n;
+const MICROSECONDS_PER_MILLISECOND = 1000n;
+const NANOSECONDS_PER_SECOND = 1000000000n;
+const SECONDS_PER_MINUTE = 60n;
+const MINUTES_PER_HOUR = 60n;
+const MICROSECONDS_PER_DAY = 86400000000n; // 24 * 60 * 60 * 1000000
+const NANOSECONDS_PER_DAY = 86400000000000n; // 24 * 60 * 60 * 1000000000
+
+const NEGATIVE_INFINITY_TIMESTAMP = -9223372036854775807n; // -(2^63-1)
+const POSITIVE_INFINITY_TIMESTAMP = 9223372036854775807n; // 2^63-1
+
+export function getDuckDBDateStringFromYearMonthDay(
+  year: number,
+  month: number,
+  dayOfMonth: number
+): string {
+  const yearStr = String(Math.abs(year)).padStart(4, '0');
+  const monthStr = String(month).padStart(2, '0');
+  const dayOfMonthStr = String(dayOfMonth).padStart(2, '0');
+  return `${yearStr}-${monthStr}-${dayOfMonthStr}${year < 0 ? ' (BC)' : ''}`;
+}
+
+export function getDuckDBDateStringFromDays(days: number): string {
+  const absDays = Math.abs(days);
+  const sign = days < 0 ? -1 : 1;
+  // 400 years is the shortest interval with a fixed number of days. (Leap years and different length months can result
+  // in shorter intervals having different number of days.) By separating the number of 400 year intervals from the
+  // interval covered by the remaining days, we can guarantee that the date resulting from shifting the epoch by the
+  // remaining interval is within the valid range of the JS Date object. This allows us to use JS Date to calculate the
+  // year, month, and day of month for the date represented by the remaining interval, thus accounting for leap years
+  // and different length months. We can then safely add back the years from the 400 year intervals, because the month
+  // and day of month won't change when a date is shifted by a whole number of such intervals.
+  const num400YearIntervals = Math.floor(absDays / DAYS_IN_400_YEARS);
+  const yearsFrom400YearIntervals = sign * num400YearIntervals * 400;
+  const absDaysFromRemainingInterval = absDays % DAYS_IN_400_YEARS;
+  const millisecondsFromRemainingInterval =
+    sign * absDaysFromRemainingInterval * MILLISECONDS_PER_DAY_NUM;
+  const date = new Date(millisecondsFromRemainingInterval);
+  let year = yearsFrom400YearIntervals + date.getUTCFullYear();
+  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
+  const dayOfMonth = date.getUTCDate(); // getUTCDate returns one-indexed day-of-month
+  return getDuckDBDateStringFromYearMonthDay(year, month, dayOfMonth);
+}
+
+export function getTimezoneOffsetString(
+  timezoneOffsetInMinutes?: number
+): string | undefined {
+  if (timezoneOffsetInMinutes === undefined) {
+    return undefined;
+  }
+  const negative = timezoneOffsetInMinutes < 0;
+  const positiveMinutes = Math.abs(timezoneOffsetInMinutes);
+  const minutesPart = positiveMinutes % 60;
+  const hoursPart = Math.floor(positiveMinutes / 60);
+  const minutesStr =
+    minutesPart !== 0 ? String(minutesPart).padStart(2, '0') : '';
+  const hoursStr = String(hoursPart).padStart(2, '0');
+  return `${negative ? '-' : '+'}${hoursStr}${
+    minutesStr ? `:${minutesStr}` : ''
+  }`;
+}
+
+export function getAbsoluteOffsetStringFromParts(
+  hoursPart: number,
+  minutesPart: number,
+  secondsPart: number
+): string {
+  const hoursStr = String(hoursPart).padStart(2, '0');
+  const minutesStr =
+    minutesPart !== 0 || secondsPart !== 0
+      ? String(minutesPart).padStart(2, '0')
+      : '';
+  const secondsStr =
+    secondsPart !== 0 ? String(secondsPart).padStart(2, '0') : '';
+  let result = hoursStr;
+  if (minutesStr) {
+    result += `:${minutesStr}`;
+    if (secondsStr) {
+      result += `:${secondsStr}`;
+    }
+  }
+  return result;
+}
+
+export function getOffsetStringFromAbsoluteSeconds(
+  absoluteOffsetInSeconds: number
+): string {
+  const secondsPart = absoluteOffsetInSeconds % 60;
+  const minutes = Math.floor(absoluteOffsetInSeconds / 60);
+  const minutesPart = minutes % 60;
+  const hoursPart = Math.floor(minutes / 60);
+  return getAbsoluteOffsetStringFromParts(hoursPart, minutesPart, secondsPart);
+}
+
+export function getOffsetStringFromSeconds(offsetInSeconds: number): string {
+  const negative = offsetInSeconds < 0;
+  const absoluteOffsetInSeconds = negative ? -offsetInSeconds : offsetInSeconds;
+  const absoluteString = getOffsetStringFromAbsoluteSeconds(
+    absoluteOffsetInSeconds
+  );
+  return `${negative ? '-' : '+'}${absoluteString}`;
+}
+
+export function getDuckDBTimeStringFromParts(
+  hoursPart: bigint,
+  minutesPart: bigint,
+  secondsPart: bigint,
+  microsecondsPart: bigint
+): string {
+  const hoursStr = String(hoursPart).padStart(2, '0');
+  const minutesStr = String(minutesPart).padStart(2, '0');
+  const secondsStr = String(secondsPart).padStart(2, '0');
+  const microsecondsStr = String(microsecondsPart)
+    .padStart(6, '0')
+    .replace(/0+$/, '');
+  return `${hoursStr}:${minutesStr}:${secondsStr}${
+    microsecondsStr.length > 0 ? `.${microsecondsStr}` : ''
+  }`;
+}
+
+export function getDuckDBTimeStringFromPartsNS(
+  hoursPart: bigint,
+  minutesPart: bigint,
+  secondsPart: bigint,
+  nanosecondsPart: bigint
+): string {
+  const hoursStr = String(hoursPart).padStart(2, '0');
+  const minutesStr = String(minutesPart).padStart(2, '0');
+  const secondsStr = String(secondsPart).padStart(2, '0');
+  const nanosecondsStr = String(nanosecondsPart)
+    .padStart(9, '0')
+    .replace(/0+$/, '');
+  return `${hoursStr}:${minutesStr}:${secondsStr}${
+    nanosecondsStr.length > 0 ? `.${nanosecondsStr}` : ''
+  }`;
+}
+
+export function getDuckDBTimeStringFromPositiveMicroseconds(
+  positiveMicroseconds: bigint
+): string {
+  const microsecondsPart = positiveMicroseconds % MICROSECONDS_PER_SECOND;
+  const seconds = positiveMicroseconds / MICROSECONDS_PER_SECOND;
+  const secondsPart = seconds % SECONDS_PER_MINUTE;
+  const minutes = seconds / SECONDS_PER_MINUTE;
+  const minutesPart = minutes % MINUTES_PER_HOUR;
+  const hoursPart = minutes / MINUTES_PER_HOUR;
+  return getDuckDBTimeStringFromParts(
+    hoursPart,
+    minutesPart,
+    secondsPart,
+    microsecondsPart
+  );
+}
+
+export function getDuckDBTimeStringFromPositiveNanoseconds(
+  positiveNanoseconds: bigint
+): string {
+  const nanosecondsPart = positiveNanoseconds % NANOSECONDS_PER_SECOND;
+  const seconds = positiveNanoseconds / NANOSECONDS_PER_SECOND;
+  const secondsPart = seconds % SECONDS_PER_MINUTE;
+  const minutes = seconds / SECONDS_PER_MINUTE;
+  const minutesPart = minutes % MINUTES_PER_HOUR;
+  const hoursPart = minutes / MINUTES_PER_HOUR;
+  return getDuckDBTimeStringFromPartsNS(
+    hoursPart,
+    minutesPart,
+    secondsPart,
+    nanosecondsPart
+  );
+}
+
+export function getDuckDBTimeStringFromMicrosecondsInDay(
+  microsecondsInDay: bigint
+): string {
+  const positiveMicroseconds =
+    microsecondsInDay < 0
+      ? microsecondsInDay + MICROSECONDS_PER_DAY
+      : microsecondsInDay;
+  return getDuckDBTimeStringFromPositiveMicroseconds(positiveMicroseconds);
+}
+
+export function getDuckDBTimeStringFromNanosecondsInDay(
+  nanosecondsInDay: bigint
+): string {
+  const positiveNanoseconds =
+    nanosecondsInDay < 0
+      ? nanosecondsInDay + NANOSECONDS_PER_DAY
+      : nanosecondsInDay;
+  return getDuckDBTimeStringFromPositiveNanoseconds(positiveNanoseconds);
+}
+
+export function getDuckDBTimeStringFromMicroseconds(
+  microseconds: bigint
+): string {
+  const negative = microseconds < 0;
+  const positiveMicroseconds = negative ? -microseconds : microseconds;
+  const positiveString =
+    getDuckDBTimeStringFromPositiveMicroseconds(positiveMicroseconds);
+  return negative ? `-${positiveString}` : positiveString;
+}
+
+export function getDuckDBTimestampStringFromDaysAndMicroseconds(
+  days: bigint,
+  microsecondsInDay: bigint,
+  timezonePart?: string
+): string {
+  // This conversion of BigInt to Number is safe, because the largest absolute value that `days` can has is 106751991,
+  // which fits without loss of precision in a JS Number. (106751991 = (2^63-1) / MICROSECONDS_PER_DAY)
+  const dateStr = getDuckDBDateStringFromDays(Number(days));
+  const timeStr = getDuckDBTimeStringFromMicrosecondsInDay(microsecondsInDay);
+  return `${dateStr} ${timeStr}${timezonePart ?? ''}`;
+}
+
+export function getDuckDBTimestampStringFromDaysAndNanoseconds(
+  days: bigint,
+  nanosecondsInDay: bigint,
+  timezonePart?: string
+): string {
+  // 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}${timezonePart ?? ''}`;
+}
+
+export function getDuckDBTimestampStringFromMicroseconds(
+  microseconds: bigint,
+  timezoneOffsetInMinutes?: number
+): string {
+  // Note that -infinity and infinity are only representable in TIMESTAMP (and TIMESTAMPTZ), not the other timestamp
+  // variants. This is by-design and matches DuckDB.
+  if (microseconds === NEGATIVE_INFINITY_TIMESTAMP) {
+    return '-infinity';
+  }
+  if (microseconds === POSITIVE_INFINITY_TIMESTAMP) {
+    return 'infinity';
+  }
+  const offsetMicroseconds =
+    timezoneOffsetInMinutes !== undefined
+      ? microseconds +
+        BigInt(timezoneOffsetInMinutes) *
+          MICROSECONDS_PER_SECOND *
+          SECONDS_PER_MINUTE
+      : microseconds;
+  let days = offsetMicroseconds / MICROSECONDS_PER_DAY;
+  let microsecondsPart = offsetMicroseconds % MICROSECONDS_PER_DAY;
+  if (microsecondsPart < 0) {
+    days--;
+    microsecondsPart += MICROSECONDS_PER_DAY;
+  }
+  return getDuckDBTimestampStringFromDaysAndMicroseconds(
+    days,
+    microsecondsPart,
+    getTimezoneOffsetString(timezoneOffsetInMinutes)
+  );
+}
+
+export function getDuckDBTimestampStringFromSeconds(seconds: bigint): string {
+  return getDuckDBTimestampStringFromMicroseconds(
+    seconds * MICROSECONDS_PER_SECOND
+  );
+}
+
+export function getDuckDBTimestampStringFromMilliseconds(
+  milliseconds: bigint
+): string {
+  return getDuckDBTimestampStringFromMicroseconds(
+    milliseconds * MICROSECONDS_PER_MILLISECOND
+  );
+}
+
+export function getDuckDBTimestampStringFromNanoseconds(
+  nanoseconds: bigint,
+  timezoneOffsetInMinutes?: number
+): string {
+  // 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,
+    getTimezoneOffsetString(timezoneOffsetInMinutes)
+  );
+}
+
+// Assumes baseUnit can be pluralized by adding an 's'.
+function numberAndUnit(value: number, baseUnit: string): string {
+  return `${value} ${baseUnit}${Math.abs(value) !== 1 ? 's' : ''}`;
+}
+
+export function getDuckDBIntervalString(
+  months: number,
+  days: number,
+  microseconds: bigint
+): string {
+  const parts: string[] = [];
+  if (months !== 0) {
+    const sign = months < 0 ? -1 : 1;
+    const absMonths = Math.abs(months);
+    const absYears = Math.floor(absMonths / 12);
+    const years = sign * absYears;
+    const extraMonths = sign * (absMonths - absYears * 12);
+    if (years !== 0) {
+      parts.push(numberAndUnit(years, 'year'));
+    }
+    if (extraMonths !== 0) {
+      parts.push(numberAndUnit(extraMonths, 'month'));
+    }
+  }
+  if (days !== 0) {
+    parts.push(numberAndUnit(days, 'day'));
+  }
+  if (microseconds !== 0n) {
+    parts.push(getDuckDBTimeStringFromMicroseconds(microseconds));
+  }
+  if (parts.length > 0) {
+    return parts.join(' ');
+  }
+  return '00:00:00';
+}

package/vendor/node-api/src/conversion/displayStringForDuckDBValue.ts

@@ -0,0 +1,12 @@
+import { quotedString } from '../sql';
+import { DuckDBValue } from '../values';
+
+export function displayStringForDuckDBValue(value: DuckDBValue): string {
+  if (value == null) {
+    return 'NULL';
+  }
+  if (typeof value === 'string') {
+    return quotedString(value);
+  }
+  return value.toString();
+}