@avidian/duckdb-bun 0.0.0-stage → 1.0.0

package/src/bindings/generated/contract.ts

@@ -0,0 +1,162 @@
+// Generated by scripts/gen-contract.ts from vendor/node-api/node-bindings.d.ts; do not edit.
+
+export const sizeof_bool: number = 1;
+
+export enum CatalogEntryType {
+  INVALID = 0,
+  TABLE = 1,
+  SCHEMA = 2,
+  VIEW = 3,
+  INDEX = 4,
+  PREPARED_STATEMENT = 5,
+  SEQUENCE = 6,
+  COLLATION = 7,
+  TYPE = 8,
+  DATABASE = 9,
+}
+
+export enum PendingState {
+  RESULT_READY = 0,
+  RESULT_NOT_READY = 1,
+  ERROR = 2,
+  NO_TASKS_AVAILABLE = 3,
+}
+
+export enum ResultType {
+  INVALID = 0,
+  CHANGED_ROWS = 1,
+  NOTHING = 2,
+  QUERY_RESULT = 3,
+}
+
+export enum StatementType {
+  INVALID = 0,
+  SELECT = 1,
+  INSERT = 2,
+  UPDATE = 3,
+  EXPLAIN = 4,
+  DELETE = 5,
+  PREPARE = 6,
+  CREATE = 7,
+  EXECUTE = 8,
+  ALTER = 9,
+  TRANSACTION = 10,
+  COPY = 11,
+  ANALYZE = 12,
+  VARIABLE_SET = 13,
+  CREATE_FUNC = 14,
+  DROP = 15,
+  EXPORT = 16,
+  PRAGMA = 17,
+  VACUUM = 18,
+  CALL = 19,
+  SET = 20,
+  LOAD = 21,
+  RELATION = 22,
+  EXTENSION = 23,
+  LOGICAL_PLAN = 24,
+  ATTACH = 25,
+  DETACH = 26,
+  MULTI = 27,
+  COPY_DATABASE = 28,
+  UPDATE_EXTENSIONS = 29,
+  MERGE_INTO = 30,
+}
+
+export enum Type {
+  INVALID = 0,
+  BOOLEAN = 1,
+  TINYINT = 2,
+  SMALLINT = 3,
+  INTEGER = 4,
+  BIGINT = 5,
+  UTINYINT = 6,
+  USMALLINT = 7,
+  UINTEGER = 8,
+  UBIGINT = 9,
+  FLOAT = 10,
+  DOUBLE = 11,
+  TIMESTAMP = 12,
+  DATE = 13,
+  TIME = 14,
+  INTERVAL = 15,
+  HUGEINT = 16,
+  UHUGEINT = 32,
+  VARCHAR = 17,
+  BLOB = 18,
+  DECIMAL = 19,
+  TIMESTAMP_S = 20,
+  TIMESTAMP_MS = 21,
+  TIMESTAMP_NS = 22,
+  ENUM = 23,
+  LIST = 24,
+  STRUCT = 25,
+  MAP = 26,
+  ARRAY = 33,
+  UUID = 27,
+  UNION = 28,
+  BIT = 29,
+  TIME_TZ = 30,
+  TIMESTAMP_TZ = 31,
+  ANY = 34,
+  BIGNUM = 35,
+  SQLNULL = 36,
+  STRING_LITERAL = 37,
+  INTEGER_LITERAL = 38,
+  TIME_NS = 39,
+  GEOMETRY = 40,
+  VARIANT = 41,
+  TIMESTAMP_TZ_NS = 42,
+}
+
+export type {
+  Appender,
+  BindInfo,
+  Catalog,
+  CatalogEntry,
+  ClientContext,
+  Config,
+  ConfigFlag,
+  Connection,
+  Database,
+  DataChunk,
+  Date_,
+  DateParts,
+  Decimal,
+  ExtractedStatements,
+  ExtractedStatementsAndCount,
+  FunctionInfo,
+  InstanceCache,
+  Interval,
+  LogicalType,
+  PendingResult,
+  PreparedStatement,
+  QueryProgress,
+  Result,
+  ScalarFunction,
+  ScalarFunctionBindFunction,
+  ScalarFunctionBindInfo,
+  ScalarFunctionInfo,
+  ScalarFunctionInitFunction,
+  ScalarFunctionInitInfo,
+  ScalarFunctionMainFunction,
+  TableFunction,
+  TableFunctionBindFunction,
+  TableFunctionBindInfo,
+  TableFunctionInfo,
+  TableFunctionInitFunction,
+  TableFunctionInitInfo,
+  TableFunctionMainFunction,
+  Time,
+  TimeNS,
+  TimeParts,
+  Timestamp,
+  TimestampMilliseconds,
+  TimestampNanoseconds,
+  TimestampParts,
+  TimestampSeconds,
+  TimeTZ,
+  TimeTZParts,
+  Value,
+  Vector,
+} from "../../../vendor/node-api/node-bindings.d.ts";

package/src/bindings/index.ts

@@ -0,0 +1,10 @@
+// Our reimplementation of the `@duckdb/node-bindings` contract
+// (vendor/node-api/node-bindings.d.ts) over the libduckdb C API, through bun:ffi
+// and the Rust shim. The vendored `@duckdb/node-api` imports it as a default
+// (`import duckdb from ...`), a namespace and by name, so it exports all three.
+// The default export is a namespace, so `duckdb.Database` and the other contract
+// types resolve through it as they do through the official module.
+import * as duckdb from "./api/index.ts";
+
+export * from "./api/index.ts";
+export default duckdb;

package/src/bindings/runtime/convert.ts

@@ -0,0 +1,307 @@
+// JavaScript argument checks and conversions, ported from the official binding's
+// bindings/src/conversion_helpers.h (vendored tag), with the same error text.
+// Where the official binding gets a JS value through a node-addon-api cast, a
+// value of the wrong JS type fails with N-API's own message, such as
+// "A number was expected", and these helpers throw the same. node-addon-api
+// raises the number, string, boolean, and object expectations as a TypeError and
+// every other N-API status, "A bigint was expected" included, as an Error.
+
+// --- N-API type expectations ----------------------------------------------------------
+
+export function expectNumber(value: unknown): number {
+  if (typeof value !== "number") throw new TypeError("A number was expected");
+  return value;
+}
+
+export function expectBigInt(value: unknown): bigint {
+  if (typeof value !== "bigint") throw new Error("A bigint was expected");
+  return value;
+}
+
+export function expectString(value: unknown): string {
+  if (typeof value !== "string") throw new TypeError("A string was expected");
+  return value;
+}
+
+export function expectBoolean(value: unknown): boolean {
+  if (typeof value !== "boolean") throw new TypeError("A boolean was expected");
+  return value;
+}
+
+/**
+ * An object argument whose properties the official binding reads with
+ * node-addon-api's Object::Get. N-API converts the value with ToObject first, so
+ * a primitive other than null and undefined reads as its wrapper object, whose
+ * fields are missing, and the field's own check is what fails. For null and
+ * undefined, the official binding under Bun throws Bun's own TypeError, such as
+ * "null is not an object (evaluating '...')", whose text quotes the caller's
+ * source; this throws N-API's object expectation instead.
+ */
+export function expectObject(value: unknown): Record<string, unknown> {
+  if (value === null || value === undefined) throw new TypeError("An object was expected");
+  return Object(value) as Record<string, unknown>;
+}
+
+/**
+ * A value the official binding keeps with napi_create_reference: extra info,
+ * bind data, init data, and scalar function state. The runtime refuses a
+ * reference to null or to a number, string, boolean, or bigint with
+ * napi_invalid_arg, which node-addon-api reports as "Invalid argument".
+ */
+export function expectReferenceable<T>(value: T): T {
+  if (value === null || ["number", "string", "boolean", "bigint"].includes(typeof value)) {
+    throw new Error("Invalid argument");
+  }
+  return value;
+}
+
+export function expectArray(value: unknown): readonly unknown[] {
+  if (!Array.isArray(value)) throw new Error("An array was expected");
+  return value;
+}
+
+// --- N-API number coercions ------------------------------------------------------------
+// The official binding reads some numbers with node-addon-api's lossy accessors
+// rather than GetIntegerFromNumber; these reproduce what each accessor returns.
+
+/** Number::Int32Value: ToInt32, so fractions truncate, values wrap modulo 2^32, and NaN and infinities read as 0. */
+export function int32FromNumber(value: unknown): number {
+  return expectNumber(value) | 0;
+}
+
+/** Number::Uint32Value: ToUint32, so a negative index arrives as a large unsigned one. */
+export function uint32FromNumber(value: unknown): number {
+  return expectNumber(value) >>> 0;
+}
+
+const INT64_MAX = 2n ** 63n - 1n;
+const INT64_MIN = -(2n ** 63n);
+
+/** Number::Int64Value: truncates, saturates at the int64 bounds, and reads NaN and infinities as 0. */
+export function int64FromNumber(value: unknown): bigint {
+  const number = expectNumber(value);
+  if (!Number.isFinite(number)) return 0n;
+  if (number >= 2 ** 63) return INT64_MAX;
+  if (number <= -(2 ** 63)) return INT64_MIN;
+  return BigInt(Math.trunc(number));
+}
+
+/** node-addon-api's Function cast, as the official binding makes before it stores a callback. */
+export function expectFunction<T>(value: T): T {
+  if (typeof value !== "function") throw new Error("A function was expected");
+  return value;
+}
+
+// --- bounds -------------------------------------------------------------------------------
+
+export function throwIndexOutOfRange(index: number | bigint, count: number | bigint, what: string): never {
+  throw new RangeError(`${what} index ${index} is out of range (count: ${count})`);
+}
+
+export function checkIndexInRange(index: number, count: number, what: string): void {
+  if (index >= count) throwIndexOutOfRange(index, count, what);
+}
+
+export function checkOneBasedIndexInRange(index: number, count: number, what: string): void {
+  if (index < 1 || index > count) throwIndexOutOfRange(index, count, what);
+}
+
+/** Call before handing a row index to a duckdb_validity_* function, which indexes the mask unchecked. */
+export function checkValidityRowInRange(mask: Uint8Array, rowIndex: number): void {
+  const rowCount = mask.byteLength * 8;
+  if (rowIndex >= rowCount) {
+    throw new RangeError(
+      `row index ${rowIndex} is out of range for a validity mask of ${mask.byteLength} bytes (${rowCount} rows)`,
+    );
+  }
+}
+
+// --- fixed-width integers from JS numbers ---------------------------------------------
+
+const INTEGER_RANGES = {
+  int8: [-128, 127],
+  int16: [-32768, 32767],
+  int32: [-2147483648, 2147483647],
+  uint8: [0, 255],
+  uint16: [0, 65535],
+  uint32: [0, 4294967295],
+} as const;
+
+export type IntegerType = keyof typeof INTEGER_RANGES;
+
+/** Rejects any number that does not fit `type` exactly, as GetIntegerFromNumber does. */
+export function integerFromNumber(value: unknown, type: IntegerType, valueName = "number"): number {
+  const number = expectNumber(value);
+  if (!Number.isFinite(number) || number !== Math.trunc(number)) throw new Error(`${valueName} is not an integer`);
+  const [min, max] = INTEGER_RANGES[type];
+  if (number < min || number > max) throw new Error(`${valueName} out of ${type} range`);
+  return number;
+}
+
+/**
+ * An unsigned 64-bit index or count from a JS number, as node-addon-api's
+ * Number::Int64Value then a cast to idx_t: fractions truncate and a negative
+ * value wraps, so callers range-check the result against a count.
+ */
+export function indexFromNumber(value: unknown): number {
+  const number = Math.trunc(expectNumber(value));
+  return Number.isFinite(number) ? number : 0;
+}
+
+// --- 64-bit and wider integers from BigInts -----------------------------------------------
+
+/** An int64 from a BigInt, rejecting a lossy conversion with `${name} out of int64 range`. */
+export function int64FromBigInt(value: unknown, name: string): bigint {
+  const big = expectBigInt(value);
+  if (BigInt.asIntN(64, big) !== big) throw new Error(`${name} out of int64 range`);
+  return big;
+}
+
+export function uint64FromBigInt(value: unknown, name: string): bigint {
+  const big = expectBigInt(value);
+  if (BigInt.asUintN(64, big) !== big) throw new Error(`${name} out of uint64 range`);
+  return big;
+}
+
+const TWO_128 = 1n << 128n;
+
+/**
+ * A hugeint from a BigInt. Like GetHugeIntFromBigInt, it rejects a magnitude
+ * wider than 128 bits and wraps anything narrower into the 128-bit two's
+ * complement range.
+ */
+export function hugeintFromBigInt(value: unknown): bigint {
+  const big = expectBigInt(value);
+  if ((big < 0n ? -big : big) >= TWO_128) throw new Error("bigint out of hugeint range");
+  return BigInt.asIntN(128, big);
+}
+
+export function uhugeintFromBigInt(value: unknown): bigint {
+  const big = expectBigInt(value);
+  if (big < 0n || big >= TWO_128) throw new Error("bigint out of uhugeint range");
+  return big;
+}
+
+// --- struct objects ------------------------------------------------------------------------
+
+export interface DateParts {
+  year: number;
+  month: number;
+  day: number;
+}
+
+export interface TimeParts {
+  hour: number;
+  min: number;
+  sec: number;
+  micros: number;
+}
+
+export function dateFromObject(value: unknown): { days: number } {
+  return { days: integerFromNumber(expectObject(value).days, "int32", "days") };
+}
+
+export function datePartsFromObject(value: unknown): DateParts {
+  const object = expectObject(value);
+  return {
+    year: integerFromNumber(object.year, "int32", "year"),
+    month: integerFromNumber(object.month, "int8", "month"),
+    day: integerFromNumber(object.day, "int8", "day"),
+  };
+}
+
+export function timeFromObject(value: unknown): { micros: bigint } {
+  return { micros: int64FromBigInt(expectObject(value).micros, "micros") };
+}
+
+export function timePartsFromObject(value: unknown): TimeParts {
+  const object = expectObject(value);
+  return {
+    hour: integerFromNumber(object.hour, "int8", "hour"),
+    min: integerFromNumber(object.min, "int8", "min"),
+    sec: integerFromNumber(object.sec, "int8", "sec"),
+    micros: integerFromNumber(object.micros, "int32", "micros"),
+  };
+}
+
+export function timeNsFromObject(value: unknown): { nanos: bigint } {
+  return { nanos: int64FromBigInt(expectObject(value).nanos, "nanos") };
+}
+
+export function timeTzFromObject(value: unknown): { bits: bigint } {
+  return { bits: uint64FromBigInt(expectObject(value).bits, "bits") };
+}
+
+export function timestampFromObject(value: unknown): { micros: bigint } {
+  return { micros: int64FromBigInt(expectObject(value).micros, "micros") };
+}
+
+export function timestampSecondsFromObject(value: unknown): { seconds: bigint } {
+  return { seconds: int64FromBigInt(expectObject(value).seconds, "seconds") };
+}
+
+export function timestampMillisecondsFromObject(value: unknown): { millis: bigint } {
+  return { millis: int64FromBigInt(expectObject(value).millis, "millis") };
+}
+
+export function timestampNanosecondsFromObject(value: unknown): { nanos: bigint } {
+  return { nanos: int64FromBigInt(expectObject(value).nanos, "nanos") };
+}
+
+export function timestampPartsFromObject(value: unknown): { date: DateParts; time: TimeParts } {
+  const object = expectObject(value);
+  return { date: datePartsFromObject(object.date), time: timePartsFromObject(object.time) };
+}
+
+export function intervalFromObject(value: unknown): { months: number; days: number; micros: bigint } {
+  const object = expectObject(value);
+  return {
+    months: integerFromNumber(object.months, "int32", "months"),
+    days: integerFromNumber(object.days, "int32", "days"),
+    micros: int64FromBigInt(object.micros, "micros"),
+  };
+}
+
+export function decimalFromObject(value: unknown): { width: number; scale: number; value: bigint } {
+  const object = expectObject(value);
+  return {
+    width: integerFromNumber(object.width, "uint8", "width"),
+    scale: integerFromNumber(object.scale, "uint8", "scale"),
+    value: hugeintFromBigInt(object.value),
+  };
+}
+
+// --- bignum ----------------------------------------------------------------------------------
+
+/**
+ * The big-endian magnitude bytes and sign of a BigInt, padded to whole 64-bit
+ * words as GetBigNumFromBigInt does. Zero is one zero byte rather than the
+ * official binding's empty array: DuckDB's Bignum::FromByteArray throws a C++
+ * exception for an empty array, which aborts the process.
+ */
+export function bignumFromBigInt(value: unknown): { bytes: Uint8Array; isNegative: boolean } {
+  const big = expectBigInt(value);
+  if (big === 0n) return { bytes: new Uint8Array(1), isNegative: false };
+  const isNegative = big < 0n;
+  let magnitude = isNegative ? -big : big;
+  let wordCount = 0;
+  for (let rest = magnitude; rest > 0n; rest >>= 64n) wordCount++;
+  const bytes = new Uint8Array(wordCount * 8);
+  for (let i = bytes.length - 1; i >= 0; i--) {
+    bytes[i] = Number(magnitude & 0xffn);
+    magnitude >>= 8n;
+  }
+  return { bytes, isNegative };
+}
+
+/**
+ * The BigInt for big-endian magnitude bytes of any length. The official
+ * MakeBigIntFromBigNum reads only size / 8 whole words, so it returns a wrong
+ * value for every bignum whose byte count is not a multiple of 8, which is
+ * every bignum DuckDB produces itself (`1::BIGNUM` has one byte).
+ */
+export function bigIntFromBignum(bytes: Uint8Array, isNegative: boolean): bigint {
+  let magnitude = 0n;
+  for (const byte of bytes) magnitude = (magnitude << 8n) | BigInt(byte);
+  return isNegative ? -magnitude : magnitude;
+}

package/src/bindings/runtime/diagnostics.ts

@@ -0,0 +1,45 @@
+// diagnostics(): a snapshot of the binding's native state, for leak hunting,
+// support requests and health checks. README.md documents every field.
+import { toArrayBuffer } from "bun:ffi";
+import { jobsInFlight } from "./dispatch.ts";
+import { flags } from "./flags.ts";
+import { liveHandles } from "./handle.ts";
+import { crashHandler, libraryPath, shim, shimPath, versions } from "./native.ts";
+import { CALL_CHANNEL } from "./trace.ts";
+
+export interface Diagnostics {
+  versions: { package: string; duckdb: string; bun: string; shim: string };
+  paths: { libduckdb: string; shim: string };
+  crashHandler: string;
+  flags: { debug: boolean; traceSql: boolean; crashHandler: boolean };
+  tracingChannel: string;
+  /** Native threads running blocking calls now, and the most at once. */
+  nativeThreads: { running: number; peak: number };
+  /** Blocking calls run on native threads: started, completed, and awaited by JavaScript now. */
+  jobs: { started: number; completed: number; inFlight: number };
+  /** Scalar and table function callbacks DuckDB made: posted from its threads, completed, and run inline. */
+  callbacks: { posted: number; completed: number; inline: number };
+  /** Entries written to the crash-report ring buffer. */
+  ringEntries: number;
+  /** Owned native handles not yet freed, by kind. */
+  liveHandles: Record<string, number>;
+}
+
+const COUNTERS = 8;
+
+export function diagnostics(): Diagnostics {
+  const counters = new BigUint64Array(toArrayBuffer(shim.dbs_counters() as never, 0, COUNTERS * 8));
+  const at = (index: number) => Number(counters[index]);
+  return {
+    versions: { ...versions },
+    paths: { libduckdb: libraryPath, shim: shimPath },
+    crashHandler,
+    flags: { ...flags },
+    tracingChannel: CALL_CHANNEL,
+    nativeThreads: { running: at(0), peak: at(1) },
+    jobs: { started: at(2), completed: at(3), inFlight: jobsInFlight() },
+    callbacks: { posted: at(4), completed: at(5), inline: at(6) },
+    ringEntries: at(7),
+    liveHandles: liveHandles(),
+  };
+}