@avidian/duckdb-bun 0.0.0-stage → 1.0.0

package/src/bindings/api/appender.ts

@@ -0,0 +1,288 @@
+// Appender functions of the @duckdb/node-bindings contract. Semantics and
+// error text follow the official binding (bindings/src/duckdb_node_bindings.cpp
+// at the vendored tag): every failing call throws DuckDB's appender error.
+import type { Pointer } from "bun:ffi";
+import type {
+  Appender,
+  Connection,
+  DataChunk,
+  Date_,
+  Interval,
+  LogicalType,
+  Time,
+  Timestamp,
+  Value,
+} from "../generated/contract.ts";
+import {
+  dateFromObject,
+  expectBoolean,
+  expectNumber,
+  expectString,
+  hugeintFromBigInt,
+  type IntegerType,
+  int64FromBigInt,
+  integerFromNumber,
+  intervalFromObject,
+  throwIndexOutOfRange,
+  timeFromObject,
+  timestampFromObject,
+  uhugeintFromBigInt,
+  uint32FromNumber,
+  uint64FromBigInt,
+} from "../runtime/convert.ts";
+import { type Handle, unwrap } from "../runtime/handle.ts";
+import { own } from "../runtime/kinds.ts";
+import { cstr, encode, type LayoutName, readCString, slot, slotValue, utf8 } from "../runtime/marshal.ts";
+import { duckdb, shim } from "../runtime/native.ts";
+import { RingOp, record } from "../runtime/ring.ts";
+
+function asHandle<T>(handle: Handle): T {
+  return handle as unknown as T;
+}
+
+/** duckdb_appender_error is set whenever an appender call fails. */
+function appenderError(appender: Pointer | null): Error {
+  return new Error(readCString(duckdb.duckdb_appender_error(appender) as Pointer | null) ?? "Unknown appender error");
+}
+
+function check(appender: Pointer | null, failed: number): void {
+  if (failed) throw appenderError(appender);
+}
+
+// --- create ----------------------------------------------------------------------------------
+
+function connectionForAppender(connection: Connection): Pointer {
+  const ptr = unwrap(connection, "connection");
+  if (ptr === null) throw new Error("Failed to create appender: connection disconnected");
+  return ptr;
+}
+
+/** A nullable name as the C API takes it: null, or a NUL-terminated copy. */
+function optionalName(name: string | null): Buffer | null {
+  return name === null ? null : cstr(expectString(name));
+}
+
+/** Wraps the created appender, or throws its error after destroying it, as the official binding does. */
+function created(failed: number, out: BigUint64Array): Appender {
+  if (failed) {
+    const error = appenderError(slotValue(out));
+    duckdb.duckdb_appender_destroy(out);
+    throw error;
+  }
+  return asHandle(own("appender", slotValue(out) as Pointer));
+}
+
+export function appender_create(connection: Connection, schema: string | null, table: string): Appender {
+  const ptr = connectionForAppender(connection);
+  const schemaName = optionalName(schema);
+  const tableName = cstr(expectString(table));
+  const out = slot();
+  return created(duckdb.duckdb_appender_create(ptr, schemaName, tableName, out), out);
+}
+
+export function appender_create_ext(
+  connection: Connection,
+  catalog: string | null,
+  schema: string | null,
+  table: string,
+): Appender {
+  const ptr = connectionForAppender(connection);
+  const catalogName = optionalName(catalog);
+  const schemaName = optionalName(schema);
+  const tableName = cstr(expectString(table));
+  const out = slot();
+  return created(duckdb.duckdb_appender_create_ext(ptr, catalogName, schemaName, tableName, out), out);
+}
+
+// --- columns, flush, close -------------------------------------------------------------------
+
+export function appender_column_count(appender: Appender): number {
+  return Number(duckdb.duckdb_appender_column_count(unwrap(appender, "appender")));
+}
+
+export function appender_column_type(appender: Appender, column_index: number): LogicalType {
+  const ptr = unwrap(appender, "appender");
+  const index = uint32FromNumber(column_index);
+  const type = duckdb.duckdb_appender_column_type(ptr, index) as Pointer | null;
+  if (type === null) throwIndexOutOfRange(index, Number(duckdb.duckdb_appender_column_count(ptr)), "column");
+  return asHandle(own("logical type", type));
+}
+
+export function appender_flush_sync(appender: Appender): void {
+  const ptr = unwrap(appender, "appender");
+  record(RingOp.appenderFlush, ptr);
+  check(ptr, duckdb.duckdb_appender_flush(ptr));
+}
+
+export function appender_clear(appender: Appender): void {
+  const ptr = unwrap(appender, "appender");
+  check(ptr, duckdb.duckdb_appender_clear(ptr));
+}
+
+export function appender_close_sync(appender: Appender): void {
+  const ptr = unwrap(appender, "appender");
+  record(RingOp.appenderClose, ptr);
+  check(ptr, duckdb.duckdb_appender_close(ptr));
+}
+
+export function appender_end_row(appender: Appender): void {
+  const ptr = unwrap(appender, "appender");
+  check(ptr, duckdb.duckdb_appender_end_row(ptr));
+}
+
+// --- append ----------------------------------------------------------------------------------
+
+export function append_default(appender: Appender): void {
+  const ptr = unwrap(appender, "appender");
+  check(ptr, duckdb.duckdb_append_default(ptr));
+}
+
+export function append_bool(appender: Appender, bool: boolean): void {
+  const ptr = unwrap(appender, "appender");
+  check(ptr, duckdb.duckdb_append_bool(ptr, expectBoolean(bool)));
+}
+
+function appendInteger(
+  appender: Appender,
+  type: IntegerType,
+  value: unknown,
+  append: (ptr: Pointer | null, value: number) => number,
+): void {
+  const ptr = unwrap(appender, "appender");
+  check(ptr, append(ptr, integerFromNumber(value, type)));
+}
+
+/** Appends a by-value struct through the shim's pointer wrapper. */
+/**
+ * Appends a struct the C API takes by value. `value` converts the argument only
+ * after the appender is checked, so a bad appender is reported first, as the
+ * official binding reads its arguments in order.
+ */
+function appendStruct(
+  appender: Appender,
+  layout: LayoutName,
+  value: () => unknown,
+  append: (ptr: Pointer | null, value: Uint8Array) => number,
+): void {
+  const ptr = unwrap(appender, "appender");
+  check(ptr, append(ptr, encode(layout, value())));
+}
+
+export function append_int8(appender: Appender, int8: number): void {
+  appendInteger(appender, "int8", int8, (p, v) => duckdb.duckdb_append_int8(p, v));
+}
+
+export function append_int16(appender: Appender, int16: number): void {
+  appendInteger(appender, "int16", int16, (p, v) => duckdb.duckdb_append_int16(p, v));
+}
+
+export function append_int32(appender: Appender, int32: number): void {
+  appendInteger(appender, "int32", int32, (p, v) => duckdb.duckdb_append_int32(p, v));
+}
+
+export function append_int64(appender: Appender, int64: bigint): void {
+  const ptr = unwrap(appender, "appender");
+  check(ptr, duckdb.duckdb_append_int64(ptr, int64FromBigInt(int64, "bigint")));
+}
+
+export function append_hugeint(appender: Appender, hugeint: bigint): void {
+  const ptr = unwrap(appender, "appender");
+  check(ptr, shim.dbs_append_hugeint(ptr, encode("hugeint", hugeintFromBigInt(hugeint))));
+}
+
+export function append_uint8(appender: Appender, uint8: number): void {
+  appendInteger(appender, "uint8", uint8, (p, v) => duckdb.duckdb_append_uint8(p, v));
+}
+
+export function append_uint16(appender: Appender, uint16: number): void {
+  appendInteger(appender, "uint16", uint16, (p, v) => duckdb.duckdb_append_uint16(p, v));
+}
+
+export function append_uint32(appender: Appender, uint32: number): void {
+  appendInteger(appender, "uint32", uint32, (p, v) => duckdb.duckdb_append_uint32(p, v));
+}
+
+export function append_uint64(appender: Appender, uint64: bigint): void {
+  const ptr = unwrap(appender, "appender");
+  check(ptr, duckdb.duckdb_append_uint64(ptr, uint64FromBigInt(uint64, "bigint")));
+}
+
+export function append_uhugeint(appender: Appender, uhugeint: bigint): void {
+  const ptr = unwrap(appender, "appender");
+  check(ptr, shim.dbs_append_uhugeint(ptr, encode("uhugeint", uhugeintFromBigInt(uhugeint))));
+}
+
+export function append_float(appender: Appender, float: number): void {
+  const ptr = unwrap(appender, "appender");
+  check(ptr, duckdb.duckdb_append_float(ptr, expectNumber(float)));
+}
+
+export function append_double(appender: Appender, double: number): void {
+  const ptr = unwrap(appender, "appender");
+  check(ptr, duckdb.duckdb_append_double(ptr, expectNumber(double)));
+}
+
+export function append_date(appender: Appender, date: Date_): void {
+  appendStruct(
+    appender,
+    "date",
+    () => dateFromObject(date),
+    (p, v) => shim.dbs_append_date(p, v),
+  );
+}
+
+export function append_time(appender: Appender, time: Time): void {
+  appendStruct(
+    appender,
+    "time",
+    () => timeFromObject(time),
+    (p, v) => shim.dbs_append_time(p, v),
+  );
+}
+
+export function append_timestamp(appender: Appender, timestamp: Timestamp): void {
+  appendStruct(
+    appender,
+    "timestamp",
+    () => timestampFromObject(timestamp),
+    (p, v) => shim.dbs_append_timestamp(p, v),
+  );
+}
+
+export function append_interval(appender: Appender, interval: Interval): void {
+  appendStruct(
+    appender,
+    "interval",
+    () => intervalFromObject(interval),
+    (p, v) => shim.dbs_append_interval(p, v),
+  );
+}
+
+export function append_varchar(appender: Appender, varchar: string): void {
+  const ptr = unwrap(appender, "appender");
+  const { bytes, length } = utf8(expectString(varchar));
+  check(ptr, duckdb.duckdb_append_varchar_length(ptr, bytes, length));
+}
+
+export function append_blob(appender: Appender, data: Uint8Array): void {
+  const ptr = unwrap(appender, "appender");
+  if (!ArrayBuffer.isView(data) || data instanceof DataView) throw new Error("Invalid argument");
+  const bytes = new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+  // A zero-length view still needs a valid address; DuckDB reads none of it.
+  check(ptr, duckdb.duckdb_append_blob(ptr, bytes.byteLength === 0 ? new Uint8Array(1) : bytes, bytes.byteLength));
+}
+
+export function append_null(appender: Appender): void {
+  const ptr = unwrap(appender, "appender");
+  check(ptr, duckdb.duckdb_append_null(ptr));
+}
+
+export function append_value(appender: Appender, value: Value): void {
+  const ptr = unwrap(appender, "appender");
+  check(ptr, duckdb.duckdb_append_value(ptr, unwrap(value, "value")));
+}
+
+export function append_data_chunk(appender: Appender, chunk: DataChunk): void {
+  const ptr = unwrap(appender, "appender");
+  check(ptr, duckdb.duckdb_append_data_chunk(ptr, unwrap(chunk, "data chunk")));
+}

package/src/bindings/api/data-chunk.ts

@@ -0,0 +1,58 @@
+// Data chunk functions of the @duckdb/node-bindings contract. Semantics and
+// error text follow the official binding (bindings/src/duckdb_node_bindings.cpp
+// at the vendored tag).
+import type { Pointer } from "bun:ffi";
+import type { DataChunk, LogicalType, Vector } from "../generated/contract.ts";
+import { expectArray, throwIndexOutOfRange, uint32FromNumber } from "../runtime/convert.ts";
+import { type Handle, handleOf, unwrap } from "../runtime/handle.ts";
+import { borrow, own } from "../runtime/kinds.ts";
+import { duckdb } from "../runtime/native.ts";
+import { derived } from "../runtime/scope.ts";
+
+function asHandle<T>(handle: Handle): T {
+  return handle as unknown as T;
+}
+
+export function create_data_chunk(logical_types: readonly LogicalType[]): DataChunk {
+  const array = expectArray(logical_types);
+  const count = array.length;
+  // duckdb_create_data_chunk needs a valid array pointer even for zero columns.
+  const types = new BigUint64Array(Math.max(count, 1));
+  for (let i = 0; i < count; i++) types[i] = BigInt(unwrap(array[i], "logical type") ?? 0);
+  const chunk = duckdb.duckdb_create_data_chunk(types, count) as Pointer | null;
+  // DuckDB returns null for a column type it will not accept (ANY, for one)
+  // rather than reporting the refusal.
+  if (chunk === null) {
+    throw new Error("Failed to create data chunk. One or more column types are not supported.");
+  }
+  return asHandle(own("data chunk", chunk));
+}
+
+export function data_chunk_reset(chunk: DataChunk): void {
+  duckdb.duckdb_data_chunk_reset(unwrap(chunk, "data chunk"));
+}
+
+export function data_chunk_get_column_count(chunk: DataChunk): number {
+  return Number(duckdb.duckdb_data_chunk_get_column_count(unwrap(chunk, "data chunk")));
+}
+
+export function data_chunk_get_vector(chunk: DataChunk, column_index: number): Vector {
+  const handle = handleOf(chunk, "data chunk");
+  const ptr = handle.ptr;
+  const index = uint32FromNumber(column_index);
+  const vector = duckdb.duckdb_data_chunk_get_vector(ptr, index) as Pointer | null;
+  if (vector === null) {
+    throwIndexOutOfRange(index, Number(duckdb.duckdb_data_chunk_get_column_count(ptr)), "column");
+  }
+  // The vector belongs to the chunk, which the handle keeps alive.
+  return asHandle(derived(handle, borrow("vector", vector, handle)));
+}
+
+export function data_chunk_get_size(chunk: DataChunk): number {
+  return Number(duckdb.duckdb_data_chunk_get_size(unwrap(chunk, "data chunk")));
+}
+
+export function data_chunk_set_size(chunk: DataChunk, size: number): void {
+  const ptr = unwrap(chunk, "data chunk");
+  duckdb.duckdb_data_chunk_set_size(ptr, uint32FromNumber(size));
+}

package/src/bindings/api/database.ts

@@ -0,0 +1,232 @@
+// Instance cache, database, config, connection, client context and catalog
+// functions of the @duckdb/node-bindings contract. Semantics and error text
+// follow the official binding (bindings/src/duckdb_node_bindings.cpp and
+// promise_workers.h at the vendored tag).
+import type { Pointer } from "bun:ffi";
+import type {
+  Catalog,
+  CatalogEntry,
+  CatalogEntryType,
+  ClientContext,
+  Config,
+  ConfigFlag,
+  Connection,
+  Database,
+  InstanceCache,
+  QueryProgress,
+  Value,
+} from "../generated/contract.ts";
+import { expectBoolean, expectString, integerFromNumber, uint32FromNumber } from "../runtime/convert.ts";
+import { jobOut0, runJob } from "../runtime/dispatch.ts";
+import { type Handle, handleOf, unwrap } from "../runtime/handle.ts";
+import { own } from "../runtime/kinds.ts";
+import { cstr, decode, readCString, slot, slotValue, structBuffer, utf8 } from "../runtime/marshal.ts";
+import { duckdb, shim } from "../runtime/native.ts";
+import { RingOp, record } from "../runtime/ring.ts";
+import { callContext } from "../runtime/trace.ts";
+
+/** The `duckdb_api` value the official binding sets on every config it creates. */
+const DEFAULT_DUCKDB_API = "node-neo-bindings";
+
+function asHandle<T>(handle: Handle): T {
+  return handle as unknown as T;
+}
+
+function databaseFrom(job: Pointer): Database {
+  return asHandle<Database>(own("database", jobOut0(job) as Pointer));
+}
+
+// --- instance cache and open ---------------------------------------------------------
+
+export function create_instance_cache(): InstanceCache {
+  return asHandle(own("instance cache", duckdb.duckdb_create_instance_cache() as Pointer));
+}
+
+// The official binding's async workers read the path before the handles.
+
+export function get_or_create_from_cache(cache: InstanceCache, path?: string, config?: Config): Promise<Database> {
+  const { bytes, length } = utf8(path === undefined ? "" : expectString(path));
+  const cacheHandle = handleOf(cache, "instance cache");
+  const configHandle = config === undefined ? undefined : handleOf(config, "config");
+  const handles = configHandle ? [cacheHandle, configHandle] : [cacheHandle];
+  return runJob(
+    callContext("get_or_create_from_cache"),
+    handles,
+    () =>
+      shim.dbs_job_get_or_create_from_cache(
+        cacheHandle.ptr,
+        bytes,
+        length,
+        path !== undefined,
+        configHandle?.ptr ?? null,
+      ) as Pointer | null,
+    databaseFrom,
+  );
+}
+
+export function open(path?: string, config?: Config): Promise<Database> {
+  const { bytes, length } = utf8(path === undefined ? "" : expectString(path));
+  const configHandle = config === undefined ? undefined : handleOf(config, "config");
+  return runJob(
+    callContext("open"),
+    configHandle ? [configHandle] : [],
+    () => shim.dbs_job_open(bytes, length, path !== undefined, configHandle?.ptr ?? null) as Pointer | null,
+    databaseFrom,
+  );
+}
+
+export function close_sync(database: Database): void {
+  const handle = handleOf(database, "database");
+  record(RingOp.close, handle.ptr);
+  handle.requestDestroy();
+}
+
+export function library_version(): string {
+  return readCString(duckdb.duckdb_library_version() as Pointer) ?? "";
+}
+
+// --- config -------------------------------------------------------------------------
+
+export function create_config(): Config {
+  const out = slot();
+  if (duckdb.duckdb_create_config(out)) {
+    duckdb.duckdb_destroy_config(out);
+    throw new Error("Failed to create config");
+  }
+  const config = own("config", slotValue(out) as Pointer);
+  if (duckdb.duckdb_set_config(config.ptr, cstr("duckdb_api"), cstr(DEFAULT_DUCKDB_API))) {
+    throw new Error("Failed to set duckdb_api");
+  }
+  return asHandle(config);
+}
+
+export function config_count(): number {
+  return Number(duckdb.duckdb_config_count());
+}
+
+export function get_config_flag(index: number): ConfigFlag {
+  // Read as Number::Uint32Value, as the official binding does.
+  const flag = uint32FromNumber(index);
+  const name = slot();
+  const description = slot();
+  if (duckdb.duckdb_get_config_flag(flag, name, description)) throw new Error("Config option not found");
+  return { name: readCString(slotValue(name)) ?? "", description: readCString(slotValue(description)) ?? "" };
+}
+
+export function set_config(config: Config, name: string, option: string): void {
+  const ptr = unwrap(config, "config");
+  if (duckdb.duckdb_set_config(ptr, cstr(expectString(name)), cstr(expectString(option)))) {
+    throw new Error("Failed to set config");
+  }
+}
+
+// --- connection ---------------------------------------------------------------------
+
+export function connect(database: Database): Promise<Connection> {
+  const handle = handleOf(database, "database");
+  return runJob(
+    callContext("connect"),
+    [handle],
+    () => shim.dbs_job_connect(handle.destroyRequested ? null : handle.ptr) as Pointer | null,
+    (job) => asHandle<Connection>(own("connection", jobOut0(job) as Pointer)),
+  );
+}
+
+export function interrupt(connection: Connection): void {
+  const ptr = unwrap(connection, "connection");
+  record(RingOp.interrupt, ptr);
+  duckdb.duckdb_interrupt(ptr);
+}
+
+export function query_progress(connection: Connection): QueryProgress {
+  const out = structBuffer("query_progress_type");
+  shim.dbs_query_progress(unwrap(connection, "connection"), out);
+  return decode<QueryProgress>("query_progress_type", out);
+}
+
+export function disconnect_sync(connection: Connection): void {
+  const handle = handleOf(connection, "connection");
+  record(RingOp.disconnect, handle.ptr);
+  handle.requestDestroy();
+}
+
+export function connection_get_client_context(connection: Connection): ClientContext {
+  const out = slot();
+  duckdb.duckdb_connection_get_client_context(unwrap(connection, "connection"), out);
+  const context = slotValue(out);
+  if (context === null) throw new Error("Failed to get client context");
+  return asHandle(own("client context", context));
+}
+
+export function client_context_get_connection_id(client_context: ClientContext): number {
+  return Number(duckdb.duckdb_client_context_get_connection_id(unwrap(client_context, "client context")));
+}
+
+export function get_table_names(connection: Connection, query: string, qualified: boolean): Value {
+  const ptr = unwrap(connection, "connection");
+  const text = cstr(expectString(query));
+  const value = duckdb.duckdb_get_table_names(ptr, text, expectBoolean(qualified)) as Pointer;
+  return asHandle(own("value", value));
+}
+
+// --- catalog ------------------------------------------------------------------------
+
+/** DUCKDB_CATALOG_ENTRY_TYPE_DATABASE, the highest catalog entry type. */
+const CATALOG_ENTRY_TYPE_DATABASE = 9;
+
+/** Entry types the built-in duckdb catalog cannot look up, by duckdb_catalog_entry_type value. */
+const UNSUPPORTED_DUCKDB_CATALOG_ENTRY_TYPES: Readonly<Record<number, string>> = {
+  0: "INVALID",
+  2: "SCHEMA",
+  5: "PREPARED_STATEMENT",
+  9: "DATABASE",
+};
+
+export function client_context_get_catalog(context: ClientContext, catalog_name: string): Catalog | null {
+  const ptr = unwrap(context, "client context");
+  const catalog = duckdb.duckdb_client_context_get_catalog(ptr, cstr(expectString(catalog_name))) as Pointer | null;
+  return catalog === null ? null : asHandle(own("catalog", catalog));
+}
+
+export function catalog_get_type_name(catalog: Catalog): string {
+  return readCString(duckdb.duckdb_catalog_get_type_name(unwrap(catalog, "catalog")) as Pointer | null) ?? "";
+}
+
+export function catalog_get_entry(
+  catalog: Catalog,
+  context: ClientContext,
+  entry_type: CatalogEntryType,
+  schema_name: string,
+  entry_name: string,
+): CatalogEntry | null {
+  const catalogPtr = unwrap(catalog, "catalog");
+  const contextPtr = unwrap(context, "client context");
+  const type = integerFromNumber(entry_type, "uint32", "entry_type");
+  if (type > CATALOG_ENTRY_TYPE_DATABASE) throw new RangeError("Invalid catalog entry type");
+  const schema = expectString(schema_name);
+  const name = expectString(entry_name);
+  if (schema.includes("\0") || name.includes("\0")) {
+    throw new Error("Catalog entry names must not contain null bytes");
+  }
+  // Extension catalogs may support different lookup categories.
+  const unsupported = UNSUPPORTED_DUCKDB_CATALOG_ENTRY_TYPES[type];
+  if (unsupported && catalog_get_type_name(catalog) === "duckdb") {
+    throw new Error(`Catalog entry type ${unsupported} is not supported by duckdb catalog lookups`);
+  }
+  const entry = duckdb.duckdb_catalog_get_entry(
+    catalogPtr,
+    contextPtr,
+    type,
+    cstr(schema),
+    cstr(name),
+  ) as Pointer | null;
+  return entry === null ? null : asHandle(own("catalog entry", entry));
+}
+
+export function catalog_entry_get_type(entry: CatalogEntry): CatalogEntryType {
+  return duckdb.duckdb_catalog_entry_get_type(unwrap(entry, "catalog entry")) as CatalogEntryType;
+}
+
+export function catalog_entry_get_name(entry: CatalogEntry): string {
+  return readCString(duckdb.duckdb_catalog_entry_get_name(unwrap(entry, "catalog entry")) as Pointer | null) ?? "";
+}