@avidian/duckdb-bun 0.0.0-stage → 1.0.0

package/src/bindings/api/datetime.ts

@@ -0,0 +1,158 @@
+// Date, time, timestamp, hugeint and decimal helpers of the @duckdb/node-bindings
+// contract. Each one converts its argument as the official binding does
+// (bindings/src/duckdb_node_bindings.cpp and conversion_helpers.h at the vendored
+// tag), then calls the shim's by-value wrapper of the C function.
+import type {
+  Date_,
+  DateParts,
+  Decimal,
+  Time,
+  TimeParts,
+  Timestamp,
+  TimestampMilliseconds,
+  TimestampNanoseconds,
+  TimestampParts,
+  TimestampSeconds,
+  TimeTZ,
+  TimeTZParts,
+} from "../generated/contract.ts";
+import {
+  dateFromObject,
+  datePartsFromObject,
+  decimalFromObject,
+  expectNumber,
+  hugeintFromBigInt,
+  int32FromNumber,
+  int64FromNumber,
+  timeFromObject,
+  timePartsFromObject,
+  timestampFromObject,
+  timestampMillisecondsFromObject,
+  timestampNanosecondsFromObject,
+  timestampPartsFromObject,
+  timestampSecondsFromObject,
+  timeTzFromObject,
+  uhugeintFromBigInt,
+  uint32FromNumber,
+} from "../runtime/convert.ts";
+import { decode, encode, structBuffer } from "../runtime/marshal.ts";
+import { shim } from "../runtime/native.ts";
+
+// --- date and time ------------------------------------------------------------------
+
+export function from_date(date: Date_): DateParts {
+  const out = structBuffer("date_struct");
+  shim.dbs_from_date(encode("date", dateFromObject(date)), out);
+  return decode<DateParts>("date_struct", out);
+}
+
+export function to_date(parts: DateParts): Date_ {
+  const out = structBuffer("date");
+  shim.dbs_to_date(encode("date_struct", datePartsFromObject(parts)), out);
+  return decode<Date_>("date", out);
+}
+
+export function is_finite_date(date: Date_): boolean {
+  return shim.dbs_is_finite_date(encode("date", dateFromObject(date)));
+}
+
+export function from_time(time: Time): TimeParts {
+  const out = structBuffer("time_struct");
+  shim.dbs_from_time(encode("time", timeFromObject(time)), out);
+  return decode<TimeParts>("time_struct", out);
+}
+
+/** micros and offset go through Number::Int64Value and Number::Int32Value, which coerce rather than reject. */
+export function create_time_tz(micros: number, offset: number): TimeTZ {
+  const micros64 = int64FromNumber(micros);
+  const offset32 = int32FromNumber(offset);
+  const out = structBuffer("time_tz");
+  shim.dbs_create_time_tz(micros64, offset32, out);
+  return decode<TimeTZ>("time_tz", out);
+}
+
+export function from_time_tz(time_tz: TimeTZ): TimeTZParts {
+  const out = structBuffer("time_tz_struct");
+  shim.dbs_from_time_tz(encode("time_tz", timeTzFromObject(time_tz)), out);
+  return decode<TimeTZParts>("time_tz_struct", out);
+}
+
+export function to_time(parts: TimeParts): Time {
+  const out = structBuffer("time");
+  shim.dbs_to_time(encode("time_struct", timePartsFromObject(parts)), out);
+  return decode<Time>("time", out);
+}
+
+export function from_timestamp(timestamp: Timestamp): TimestampParts {
+  const out = structBuffer("timestamp_struct");
+  shim.dbs_from_timestamp(encode("timestamp", timestampFromObject(timestamp)), out);
+  return decode<TimestampParts>("timestamp_struct", out);
+}
+
+export function to_timestamp(parts: TimestampParts): Timestamp {
+  const out = structBuffer("timestamp");
+  shim.dbs_to_timestamp(encode("timestamp_struct", timestampPartsFromObject(parts)), out);
+  return decode<Timestamp>("timestamp", out);
+}
+
+export function is_finite_timestamp(timestamp: Timestamp): boolean {
+  return shim.dbs_is_finite_timestamp(encode("timestamp", timestampFromObject(timestamp)));
+}
+
+export function is_finite_timestamp_s(timestampSeconds: TimestampSeconds): boolean {
+  return shim.dbs_is_finite_timestamp_s(encode("timestamp_s", timestampSecondsFromObject(timestampSeconds)));
+}
+
+export function is_finite_timestamp_ms(timestampMilliseconds: TimestampMilliseconds): boolean {
+  return shim.dbs_is_finite_timestamp_ms(
+    encode("timestamp_ms", timestampMillisecondsFromObject(timestampMilliseconds)),
+  );
+}
+
+export function is_finite_timestamp_ns(timestampNanoseconds: TimestampNanoseconds): boolean {
+  return shim.dbs_is_finite_timestamp_ns(encode("timestamp_ns", timestampNanosecondsFromObject(timestampNanoseconds)));
+}
+
+// --- hugeint, uhugeint and decimal ------------------------------------------------------
+
+export function hugeint_to_double(hugeint: bigint): number {
+  return shim.dbs_hugeint_to_double(encode("hugeint", hugeintFromBigInt(hugeint)));
+}
+
+/** DuckDB returns 0 for a double outside the hugeint range. */
+export function double_to_hugeint(double: number): bigint {
+  const input = expectNumber(double);
+  const out = structBuffer("hugeint");
+  shim.dbs_double_to_hugeint(input, out);
+  return decode<bigint>("hugeint", out);
+}
+
+export function uhugeint_to_double(uhugeint: bigint): number {
+  return shim.dbs_uhugeint_to_double(encode("uhugeint", uhugeintFromBigInt(uhugeint)));
+}
+
+/** DuckDB returns 0 for a double outside the uhugeint range, negative ones included. */
+export function double_to_uhugeint(double: number): bigint {
+  const input = expectNumber(double);
+  const out = structBuffer("uhugeint");
+  shim.dbs_double_to_uhugeint(input, out);
+  return decode<bigint>("uhugeint", out);
+}
+
+/**
+ * width and scale go through Number::Uint32Value and then narrow to uint8_t, as
+ * in the official binding. DuckDB returns a zeroed decimal when the value does
+ * not fit.
+ */
+export function double_to_decimal(double: number, width: number, scale: number): Decimal {
+  const input = expectNumber(double);
+  const width8 = uint32FromNumber(width) & 0xff;
+  const scale8 = uint32FromNumber(scale) & 0xff;
+  const out = structBuffer("decimal");
+  shim.dbs_double_to_decimal(input, width8, scale8, out);
+  return decode<Decimal>("decimal", out);
+}
+
+export function decimal_to_double(decimal: Decimal): number {
+  return shim.dbs_decimal_to_double(encode("decimal", decimalFromObject(decimal)));
+}

package/src/bindings/api/index.ts

@@ -0,0 +1,13 @@
+// Every function, enum, constant and type of the @duckdb/node-bindings contract
+// (vendor/node-api/node-bindings.d.ts), gathered for src/bindings/index.ts.
+export * from "../generated/contract.ts";
+export * from "./appender.ts";
+export * from "./data-chunk.ts";
+export * from "./database.ts";
+export * from "./datetime.ts";
+export * from "./logical-types.ts";
+export * from "./query.ts";
+export * from "./scalar-function.ts";
+export * from "./table-function.ts";
+export * from "./values.ts";
+export * from "./vector.ts";

package/src/bindings/api/logical-types.ts

@@ -0,0 +1,227 @@
+// Logical type functions of the @duckdb/node-bindings contract. Semantics, error
+// text and index checks follow the official binding
+// (bindings/src/duckdb_node_bindings.cpp at the vendored tag).
+import { type Pointer, ptr } from "bun:ffi";
+import { type LogicalType, Type } from "../generated/contract.ts";
+import { checkIndexInRange, expectArray, expectString, uint32FromNumber } from "../runtime/convert.ts";
+import type { Handle } from "../runtime/handle.ts";
+import { unwrap } from "../runtime/handle.ts";
+import { own } from "../runtime/kinds.ts";
+import { cstr, takeCString } from "../runtime/marshal.ts";
+import { duckdb } from "../runtime/native.ts";
+
+function asLogicalType(handle: Handle): LogicalType {
+  return handle as unknown as LogicalType;
+}
+
+/** Wraps a logical type the caller owns; a null pointer stays null, as the official external does. */
+function ownLogicalType(pointer: Pointer | null): LogicalType {
+  return asLogicalType(own("logical type", pointer as Pointer));
+}
+
+function logicalTypePointer(logical_type: unknown): Pointer | null {
+  return unwrap(logical_type, "logical type");
+}
+
+/**
+ * A C string DuckDB allocated, freed after reading. A null pointer throws what
+ * Napi::String::New throws for one.
+ */
+function takeString(pointer: Pointer | null): string {
+  const text = takeCString(pointer);
+  if (text === null) throw new Error("Invalid argument");
+  return text;
+}
+
+/**
+ * A `const char **` array of `names` in one buffer: a pointer slot per name (at
+ * least one, as the official binding allocates) followed by the NUL-terminated
+ * UTF-8 names it points to. Passing the buffer to the C call keeps the names
+ * alive for exactly as long as it runs.
+ */
+function cStringArray(names: readonly string[]): Uint8Array {
+  const strings = names.map((name) => cstr(name));
+  const slots = Math.max(names.length, 1) * 8;
+  const buffer = new Uint8Array(slots + strings.reduce((total, bytes) => total + bytes.byteLength, 0));
+  const pointers = new BigUint64Array(buffer.buffer, 0, slots / 8);
+  const base = ptr(buffer);
+  let offset = slots;
+  strings.forEach((bytes, i) => {
+    buffer.set(bytes, offset);
+    pointers[i] = BigInt(base + offset);
+    offset += bytes.byteLength;
+  });
+  return buffer;
+}
+
+/** The member types and names of create_struct_type and create_union_type, read in the official order. */
+function members(
+  member_types: unknown,
+  member_names: unknown,
+): { types: BigUint64Array; names: Uint8Array; count: number } {
+  const typesArray = expectArray(member_types);
+  const namesArray = expectArray(member_names);
+  const count = Math.min(typesArray.length, namesArray.length);
+  const types = new BigUint64Array(Math.max(count, 1));
+  const names: string[] = [];
+  for (let i = 0; i < count; i++) {
+    types[i] = BigInt(logicalTypePointer(typesArray[i]) ?? 0);
+    names.push(expectString(namesArray[i]));
+  }
+  return { types, names: cStringArray(names), count };
+}
+
+// --- creation -----------------------------------------------------------------------
+
+export function create_logical_type(type: Type): LogicalType {
+  const id = uint32FromNumber(type);
+  // duckdb_create_logical_type returns a VARIANT without its child types, and
+  // using it crashes; see https://github.com/duckdb/duckdb/issues/24680.
+  if (id === Type.VARIANT) {
+    throw new Error("Cannot create a VARIANT logical type; see https://github.com/duckdb/duckdb/issues/24680");
+  }
+  return ownLogicalType(duckdb.duckdb_create_logical_type(id | 0) as Pointer | null);
+}
+
+export function logical_type_get_alias(logical_type: LogicalType): string | null {
+  return takeCString(duckdb.duckdb_logical_type_get_alias(logicalTypePointer(logical_type)) as Pointer | null);
+}
+
+export function logical_type_set_alias(logical_type: LogicalType, alias: string): void {
+  const pointer = logicalTypePointer(logical_type);
+  duckdb.duckdb_logical_type_set_alias(pointer, cstr(expectString(alias)));
+}
+
+export function create_list_type(logical_type: LogicalType): LogicalType {
+  return ownLogicalType(duckdb.duckdb_create_list_type(logicalTypePointer(logical_type)) as Pointer | null);
+}
+
+export function create_array_type(logical_type: LogicalType, array_size: number): LogicalType {
+  const child = logicalTypePointer(logical_type);
+  const size = uint32FromNumber(array_size);
+  return ownLogicalType(duckdb.duckdb_create_array_type(child, size) as Pointer | null);
+}
+
+export function create_map_type(key_type: LogicalType, value_type: LogicalType): LogicalType {
+  const key = logicalTypePointer(key_type);
+  const value = logicalTypePointer(value_type);
+  return ownLogicalType(duckdb.duckdb_create_map_type(key, value) as Pointer | null);
+}
+
+export function create_union_type(member_types: readonly LogicalType[], member_names: readonly string[]): LogicalType {
+  const { types, names, count } = members(member_types, member_names);
+  return ownLogicalType(duckdb.duckdb_create_union_type(types, names, count) as Pointer | null);
+}
+
+export function create_struct_type(member_types: readonly LogicalType[], member_names: readonly string[]): LogicalType {
+  const { types, names, count } = members(member_types, member_names);
+  return ownLogicalType(duckdb.duckdb_create_struct_type(types, names, count) as Pointer | null);
+}
+
+export function create_enum_type(member_names: readonly string[]): LogicalType {
+  const namesArray = expectArray(member_names);
+  const names = namesArray.map((name) => expectString(name));
+  return ownLogicalType(duckdb.duckdb_create_enum_type(cStringArray(names), names.length) as Pointer | null);
+}
+
+/** width and scale go through Number::Uint32Value and then narrow to uint8_t, as in the official binding. */
+export function create_decimal_type(width: number, scale: number): LogicalType {
+  const width8 = uint32FromNumber(width) & 0xff;
+  const scale8 = uint32FromNumber(scale) & 0xff;
+  return ownLogicalType(duckdb.duckdb_create_decimal_type(width8, scale8) as Pointer | null);
+}
+
+// --- accessors ----------------------------------------------------------------------
+
+export function get_type_id(logical_type: LogicalType): Type {
+  return duckdb.duckdb_get_type_id(logicalTypePointer(logical_type)) as Type;
+}
+
+export function decimal_width(logical_type: LogicalType): number {
+  return duckdb.duckdb_decimal_width(logicalTypePointer(logical_type));
+}
+
+export function decimal_scale(logical_type: LogicalType): number {
+  return duckdb.duckdb_decimal_scale(logicalTypePointer(logical_type));
+}
+
+export function decimal_internal_type(logical_type: LogicalType): Type {
+  return duckdb.duckdb_decimal_internal_type(logicalTypePointer(logical_type)) as Type;
+}
+
+export function enum_internal_type(logical_type: LogicalType): Type {
+  return duckdb.duckdb_enum_internal_type(logicalTypePointer(logical_type)) as Type;
+}
+
+export function enum_dictionary_size(logical_type: LogicalType): number {
+  return duckdb.duckdb_enum_dictionary_size(logicalTypePointer(logical_type));
+}
+
+/** duckdb_enum_dictionary_value reads out of bounds for a bad index, so it is checked first. */
+export function enum_dictionary_value(logical_type: LogicalType, index: number): string {
+  const pointer = logicalTypePointer(logical_type);
+  const position = uint32FromNumber(index);
+  checkIndexInRange(position, duckdb.duckdb_enum_dictionary_size(pointer), "enum value");
+  return takeString(duckdb.duckdb_enum_dictionary_value(pointer, position) as Pointer | null);
+}
+
+export function list_type_child_type(logical_type: LogicalType): LogicalType {
+  return ownLogicalType(duckdb.duckdb_list_type_child_type(logicalTypePointer(logical_type)) as Pointer | null);
+}
+
+export function array_type_child_type(logical_type: LogicalType): LogicalType {
+  return ownLogicalType(duckdb.duckdb_array_type_child_type(logicalTypePointer(logical_type)) as Pointer | null);
+}
+
+export function array_type_array_size(logical_type: LogicalType): number {
+  return Number(duckdb.duckdb_array_type_array_size(logicalTypePointer(logical_type)));
+}
+
+export function map_type_key_type(logical_type: LogicalType): LogicalType {
+  return ownLogicalType(duckdb.duckdb_map_type_key_type(logicalTypePointer(logical_type)) as Pointer | null);
+}
+
+export function map_type_value_type(logical_type: LogicalType): LogicalType {
+  return ownLogicalType(duckdb.duckdb_map_type_value_type(logicalTypePointer(logical_type)) as Pointer | null);
+}
+
+export function struct_type_child_count(logical_type: LogicalType): number {
+  return Number(duckdb.duckdb_struct_type_child_count(logicalTypePointer(logical_type)));
+}
+
+/** The struct accessors throw a C++ exception across the C boundary for a bad index, so it is checked first. */
+export function struct_type_child_name(logical_type: LogicalType, index: number): string {
+  const pointer = logicalTypePointer(logical_type);
+  const position = uint32FromNumber(index);
+  checkIndexInRange(position, Number(duckdb.duckdb_struct_type_child_count(pointer)), "struct entry");
+  return takeString(duckdb.duckdb_struct_type_child_name(pointer, position) as Pointer | null);
+}
+
+export function struct_type_child_type(logical_type: LogicalType, index: number): LogicalType {
+  const pointer = logicalTypePointer(logical_type);
+  const position = uint32FromNumber(index);
+  checkIndexInRange(position, Number(duckdb.duckdb_struct_type_child_count(pointer)), "struct entry");
+  return ownLogicalType(duckdb.duckdb_struct_type_child_type(pointer, position) as Pointer | null);
+}
+
+export function union_type_member_count(logical_type: LogicalType): number {
+  return Number(duckdb.duckdb_union_type_member_count(logicalTypePointer(logical_type)));
+}
+
+export function union_type_member_name(logical_type: LogicalType, index: number): string {
+  const pointer = logicalTypePointer(logical_type);
+  const position = uint32FromNumber(index);
+  checkIndexInRange(position, Number(duckdb.duckdb_union_type_member_count(pointer)), "union member");
+  return takeString(duckdb.duckdb_union_type_member_name(pointer, position) as Pointer | null);
+}
+
+export function union_type_member_type(logical_type: LogicalType, index: number): LogicalType {
+  const pointer = logicalTypePointer(logical_type);
+  const position = uint32FromNumber(index);
+  checkIndexInRange(position, Number(duckdb.duckdb_union_type_member_count(pointer)), "union member");
+  return ownLogicalType(duckdb.duckdb_union_type_member_type(pointer, position) as Pointer | null);
+}
+
+export function geometry_type_get_crs(logical_type: LogicalType): string | null {
+  return takeCString(duckdb.duckdb_geometry_type_get_crs(logicalTypePointer(logical_type)) as Pointer | null);
+}