@avidian/duckdb-bun 0.0.0-stage → 1.0.1

package/src/bindings/runtime/dispatch.ts

@@ -0,0 +1,213 @@
+// The JavaScript side of the shim's threading (docs/adr/0001-blocking-calls-run-on-native-threads.md,
+// native/ABI.md): completes jobs that ran on native threads, runs function
+// callbacks DuckDB makes from its own threads, and releases ids DuckDB no longer
+// needs.
+//
+// The shim calls three thread-safe JSCallbacks from its threads. Bun marshals
+// each call onto the JS thread, so everything here runs on the JS thread, and a
+// job's completion always runs after the code that started the job has returned.
+import { CString, JSCallback, type Pointer, read } from "bun:ffi";
+import { isMainThread } from "node:worker_threads";
+import type { Handle } from "./handle.ts";
+import { shim, shimPath } from "./native.ts";
+import { jobOp, record } from "./ring.ts";
+import { type CallContext, traced } from "./trace.ts";
+
+// --- keeping the event loop alive -----------------------------------------------
+
+// A JSCallback that a native thread will call later does not keep the process
+// alive by itself, so one timer is ref'd while any job is in flight.
+const keepAlive = setInterval(() => {}, 2 ** 31 - 1);
+keepAlive.unref();
+let inFlight = 0;
+
+function begin(): void {
+  if (inFlight++ === 0) keepAlive.ref();
+}
+
+function end(): void {
+  if (--inFlight === 0) keepAlive.unref();
+}
+
+// --- jobs -----------------------------------------------------------------------
+
+interface PendingJob {
+  handles: readonly Handle[];
+  settle(job: Pointer): void;
+}
+
+const jobs = new Map<number, PendingJob>();
+
+function complete(job: Pointer): void {
+  const entry = jobs.get(job);
+  if (!entry) return;
+  jobs.delete(job);
+  end();
+  for (const handle of entry.handles) handle.release();
+  try {
+    entry.settle(job);
+  } finally {
+    shim.dbs_job_free(job);
+  }
+}
+
+/**
+ * Runs one blocking C call on a native thread and settles with `read(job)`, or
+ * rejects with the job's error text. `context` names the call for tracing. Each handle in `handles` counts the job as
+ * in flight until it completes, so an explicit destroy waits for it.
+ */
+export function runJob<T>(
+  context: CallContext,
+  handles: readonly Handle[],
+  start: () => Pointer | null,
+  read: (job: Pointer) => T,
+): Promise<T> {
+  return traced(context, () => startJob(context, handles, start, read));
+}
+
+function startJob<T>(
+  context: CallContext,
+  handles: readonly Handle[],
+  start: () => Pointer | null,
+  read: (job: Pointer) => T,
+): Promise<T> {
+  // The shim records the job's start and end; the SQL, when kept, goes in just before.
+  if (context.sql !== undefined) record(jobOp(context.op), null, 0, context.sql);
+  for (const handle of handles) handle.acquire();
+  const job = start();
+  if (job === null) {
+    for (const handle of handles) handle.release();
+    return Promise.reject(new Error("Failed to start a native thread"));
+  }
+  begin();
+  return new Promise<T>((resolve, reject) => {
+    jobs.set(job, {
+      handles,
+      settle(done) {
+        if (shim.dbs_job_failed(done)) {
+          const error = shim.dbs_job_error(done);
+          reject(new Error(error === null ? "Unknown error" : new CString(error).toString()));
+          return;
+        }
+        try {
+          resolve(read(done));
+        } catch (error) {
+          reject(error);
+        }
+      },
+    });
+  });
+}
+
+/** Native calls in flight on native threads, for diagnostics(). */
+export function jobsInFlight(): number {
+  return inFlight;
+}
+
+/** The pointer a job produced, or null. */
+export function jobOut0(job: Pointer): Pointer | null {
+  return shim.dbs_job_out0(job) as Pointer | null;
+}
+
+export function jobOut1(job: Pointer): number {
+  return Number(shim.dbs_job_out1(job));
+}
+
+// --- function callbacks -----------------------------------------------------------
+
+/** Call kinds from native/ABI.md. */
+export const CallKind = {
+  scalarBind: 1,
+  scalarInit: 2,
+  scalarMain: 3,
+  tableBind: 4,
+  tableInit: 5,
+  tableLocalInit: 6,
+  tableMain: 7,
+} as const;
+
+export type CallHandler = (kind: number, info: Pointer, input: Pointer | null, output: Pointer | null) => void;
+
+const handlers = new Map<number, CallHandler>();
+const released = new Map<number, () => void>();
+let nextId = 1;
+
+/** Ids carry this thread's shim context above bit 40 (2^40), so DuckDB threads call back into the right Worker. */
+const CONTEXT_SCALE = 2 ** 40;
+let contextBase = 0;
+
+/** Allocates a nonzero id for a function callback set, or for bind, init or state data. */
+export function allocateId(): number {
+  return contextBase + nextId++;
+}
+
+export function setCallHandler(id: number, handler: CallHandler): void {
+  handlers.set(id, handler);
+}
+
+/** Runs `onRelease` once DuckDB drops `id` (shim `on_release`). */
+export function onRelease(id: number, onRelease: () => void): void {
+  released.set(id, onRelease);
+}
+
+function dispatch(call: Pointer): void {
+  const kind = read.u32(call, 0);
+  const id = Number(read.u64(call, 8));
+  const info = read.ptr(call, 16) as Pointer;
+  const input = (read.ptr(call, 24) as Pointer) || null;
+  const output = (read.ptr(call, 32) as Pointer) || null;
+  const handler = handlers.get(id);
+  // The handler reports a thrown error through the C API's set-error function on
+  // `info`; an id without a handler is a shim bug, never reached by user code.
+  if (handler) handler(kind, info, input, output);
+}
+
+const onComplete = new JSCallback((job: Pointer) => complete(job), {
+  args: ["ptr"],
+  returns: "void",
+  threadsafe: true,
+});
+
+const onCall = new JSCallback(
+  (call: Pointer) => {
+    try {
+      dispatch(call);
+    } finally {
+      shim.dbs_call_done(call);
+    }
+  },
+  { args: ["ptr"], returns: "void", threadsafe: true },
+);
+
+const onCallSync = new JSCallback((call: Pointer) => dispatch(call), { args: ["ptr"], returns: "void" });
+
+const onReleaseCallback = new JSCallback(
+  (id: bigint) => {
+    const key = Number(id);
+    handlers.delete(key);
+    const release = released.get(key);
+    released.delete(key);
+    release?.();
+  },
+  { args: ["u64"], returns: "void", threadsafe: true },
+);
+
+// One shim context per JS thread: this one, or a Worker's (native/ABI.md, "Lifecycle").
+const context = shim.dbs_init(onComplete.ptr, onCall.ptr, onReleaseCallback.ptr);
+if (context < 1) throw new Error(`duckdb-bun: the native shim refused this thread (dbs_init returned ${context})`);
+contextBase = context * CONTEXT_SCALE;
+shim.dbs_set_sync_call(onCallSync.ptr);
+
+if (isMainThread) {
+  // After "exit" no more script runs, so the shim drops whatever arrives for this thread.
+  process.on("exit", () => shim.dbs_context_close());
+} else {
+  // A Worker stopped by terminate() emits no "exit" and runs no script, but Bun runs
+  // its Node-API cleanup hooks on the Worker's thread before its VM goes away. The
+  // shim, loaded as an addon here, adds one that closes this context and frees the
+  // handles it owns (docs/adr/0008-a-worker-closes-its-context-in-an-n-api-cleanup-hook.md).
+  process.dlopen({ exports: {} }, shimPath);
+  if (!shim.dbs_context_hooked()) {
+    throw new Error("duckdb-bun: the native shim could not add its Node-API cleanup hook in this Worker");
+  }
+}

package/src/bindings/runtime/exception.ts

@@ -0,0 +1,103 @@
+// The message of a C++ exception the shim's boundary caught (native/cpp/boundary.hpp),
+// built as DuckDB builds an error's message from one: ErrorData(const std::exception &)
+// and ErrorData::ConstructFinalMessage() in src/common/error_data.cpp at the pinned tag.
+//
+// A DuckDB exception's what() is a JSON object whose exception_type is the type's
+// display name, such as "Conversion", and whose exception_message is the text. Any
+// other what() is the text of an exception of type INVALID.
+
+/** ErrorData's text after an INTERNAL error's message; the stack trace it adds is left out. */
+const INTERNAL_SUFFIX =
+  "\nThis error signals an assertion failure within DuckDB. This usually occurs due to " +
+  "unexpected conditions or errors in the program's logic.\nFor more information, see " +
+  "https://duckdb.org/docs/current/dev/internal_errors";
+
+/** The display names of DuckDB's ExceptionType values (EXCEPTION_MAP in src/common/exception.cpp). */
+const EXCEPTION_TYPES = new Set([
+  "Invalid",
+  "Out of Range",
+  "Conversion",
+  "Unknown Type",
+  "Decimal",
+  "Mismatch Type",
+  "Divide by Zero",
+  "Object Size",
+  "Invalid type",
+  "Serialization",
+  "TransactionContext",
+  "Not implemented",
+  "Expression",
+  "Catalog",
+  "Parser",
+  "Binder",
+  "Planner",
+  "Scheduler",
+  "Executor",
+  "Constraint",
+  "Index",
+  "Stat",
+  "Connection",
+  "Syntax",
+  "Settings",
+  "Optimizer",
+  "NullPointer",
+  "IO",
+  "INTERRUPT",
+  "FATAL",
+  "INTERNAL",
+  "Invalid Input",
+  "Out of Memory",
+  "Permission",
+  "Parameter Not Resolved",
+  "Parameter Not Allowed",
+  "Dependency",
+  "Missing Extension",
+  "HTTP",
+  "Extension Autoloading",
+  "Sequence",
+  "Invalid Configuration",
+  "Data Corruption",
+  "Resource In Use",
+]);
+
+/** The what() of std::bad_alloc in libstdc++ and libc++. */
+const BAD_ALLOC = "std::bad_alloc";
+
+/**
+ * The error message DuckDB reports for an exception whose what() is `what`, or a
+ * generic one when the exception was not a std::exception (`what` null).
+ */
+export function exceptionMessage(what: string | null): string {
+  if (what === null) return "Error: a C++ exception that is not a std::exception";
+  let type = "Invalid";
+  let message = what;
+  if (what === BAD_ALLOC) {
+    type = "Out of Memory";
+    message = "Allocation failure";
+  } else if (what.startsWith("{")) {
+    const fields = parseFields(what);
+    if (fields) {
+      type = EXCEPTION_TYPES.has(fields.exception_type ?? "") ? (fields.exception_type as string) : "Invalid";
+      message = fields.exception_message ?? "";
+    }
+  }
+  message = message.replaceAll("\0", "\\0");
+  // UNKNOWN_TYPE, whose display name is "Unknown Type", gets no prefix.
+  const prefix = type === "Unknown Type" ? "" : `${type} `;
+  return `${prefix}Error: ${message}${type === "INTERNAL" ? INTERNAL_SUFFIX : ""}`;
+}
+
+/** The string fields of a JSON object, or null when `text` is not one. */
+function parseFields(text: string): Record<string, string | undefined> | null {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch (error) {
+    if (error instanceof SyntaxError) return null;
+    throw new Error("failed to parse a C++ exception message", { cause: error });
+  }
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+  const fields: Record<string, string | undefined> = {};
+  for (const [key, value] of Object.entries(parsed)) if (typeof value === "string") fields[key] = value;
+  return fields;
+}

package/src/bindings/runtime/flags.ts

@@ -0,0 +1,19 @@
+// The environment flags the bindings read once at load. README.md documents them.
+
+function enabled(name: string): boolean {
+  return process.env[name] === "1";
+}
+
+export const flags = {
+  /** DUCKDB_BUN_DEBUG=1: one stderr line per native call, plus the loaded library paths. */
+  debug: enabled("DUCKDB_BUN_DEBUG"),
+  /** DUCKDB_BUN_TRACE_SQL=1: redacted SQL in the tracing channel, debug lines and crash reports. */
+  traceSql: enabled("DUCKDB_BUN_TRACE_SQL"),
+  /** DUCKDB_BUN_CRASH_HANDLER=0 leaves the fatal-signal handler uninstalled. */
+  crashHandler: process.env.DUCKDB_BUN_CRASH_HANDLER !== "0",
+} as const;
+
+/** Writes one diagnostic line to stderr when DUCKDB_BUN_DEBUG=1. */
+export function debug(line: string): void {
+  if (flags.debug) process.stderr.write(`[duckdb-bun] ${line}\n`);
+}

package/src/bindings/runtime/handle.ts

@@ -0,0 +1,217 @@
+// Typed handle objects for every native pointer the bindings hand to JavaScript
+// (docs/adr/0002-handles-are-objects-freed-by-a-finalization-registry.md).
+//
+// Each handle mirrors one N-API external of the official binding
+// (bindings/src/externals.h at the vendored tag): it carries a kind that plays
+// the role of the external's type tag, so passing the wrong handle throws the
+// same "Invalid <kind> argument" error, and a destroy function that a
+// FinalizationRegistry runs once the handle is unreachable.
+//
+// A native call that uses a handle counts itself in `inFlight` for as long as it
+// runs. An explicit destroy (close_sync, disconnect_sync, destroy_*_sync) during
+// that time only sets `destroyRequested`, and the last call to finish destroys
+// the pointer. The official binding does this for results and pending results;
+// here every handle a native thread can use follows the rule, so close_sync and
+// disconnect_sync during a query never free memory a native thread is using.
+
+import type { Pointer } from "bun:ffi";
+
+export type Kind =
+  | "appender"
+  | "catalog"
+  | "catalog entry"
+  | "client context"
+  | "config"
+  | "connection"
+  | "data chunk"
+  | "database"
+  | "extracted statements"
+  | "instance cache"
+  | "logical type"
+  | "pending result"
+  | "prepared statement"
+  | "result"
+  | "scalar function"
+  | "scalar function bind info"
+  | "scalar function info"
+  | "scalar function init info"
+  | "table function"
+  | "table function bind info"
+  | "table function info"
+  | "table function init info"
+  | "value"
+  | "vector";
+
+/** Kinds whose explicit destroy makes later use throw, as in the official binding. */
+const DESTROYED_MESSAGE: Partial<Record<Kind, string>> = {
+  result: "Result destroyed",
+  "pending result": "Pending result destroyed",
+};
+
+type Destroy = (ptr: Pointer) => void;
+
+/** The native state of one handle, shared with the FinalizationRegistry. It
+ * never references the Handle itself, so it does not keep it alive. */
+interface Cell {
+  readonly kind: Kind;
+  ptr: Pointer | null;
+  readonly destroy: Destroy | null;
+  inFlight: number;
+  destroyRequested: boolean;
+}
+
+/** Owned handles whose pointer is not yet freed, by kind, for diagnostics(). */
+const live = new Map<Kind, number>();
+
+/** A snapshot of the owned handles not yet freed, by kind. */
+export function liveHandles(): Record<string, number> {
+  return Object.fromEntries([...live].filter(([, count]) => count > 0));
+}
+
+function destroyCell(cell: Cell): void {
+  const { ptr, destroy } = cell;
+  cell.ptr = null;
+  if (ptr !== null && destroy) {
+    live.set(cell.kind, (live.get(cell.kind) ?? 1) - 1);
+    destroy(ptr);
+  }
+}
+
+// --- native memory pressure (docs/adr/0007-native-memory-pressure-requests-garbage-collection.md) ---
+//
+// The garbage collector sees only the JS heap, not the native memory a handle
+// owns, so unreachable results and data chunks pile up between collections: a
+// loop of small queries held about 1000 of them, against about 500 for the
+// official binding. Every `pressureLimit` results and data chunks created and not
+// destroyed explicitly, the binding asks for an asynchronous collection, as N-API's
+// napi_adjust_external_memory lets V8 do. The limit grows with the live count, so
+// a program that keeps many results alive is not collected more often.
+
+const PRESSURE_KINDS: ReadonlySet<Kind> = new Set<Kind>(["result", "data chunk"]);
+/** The fewest results and data chunks created between two requested collections. */
+export const MIN_PRESSURE_LIMIT = 256;
+let pressureCount = 0;
+let pressureLimit = MIN_PRESSURE_LIMIT;
+
+function addPressure(kind: Kind): void {
+  if (!PRESSURE_KINDS.has(kind) || ++pressureCount < pressureLimit) return;
+  pressureCount = 0;
+  let liveCount = 0;
+  for (const pressured of PRESSURE_KINDS) liveCount += live.get(pressured) ?? 0;
+  pressureLimit = Math.max(MIN_PRESSURE_LIMIT, liveCount);
+  Bun.gc(false);
+}
+
+function relievePressure(kind: Kind): void {
+  if (PRESSURE_KINDS.has(kind) && pressureCount > 0) pressureCount--;
+}
+
+/** Collections requested so far and the current limit, for tests. */
+export function pressureState(): { count: number; limit: number } {
+  return { count: pressureCount, limit: pressureLimit };
+}
+
+const registry = new FinalizationRegistry<Cell>((cell) => {
+  // A native call holds a strong reference to its handles until it completes,
+  // so a collected handle has no call in flight; the check is defensive.
+  if (cell.inFlight === 0) destroyCell(cell);
+});
+
+export class Handle<K extends Kind = Kind> {
+  readonly kind: K;
+  readonly #cell: Cell;
+  /** Keeps the handle this one borrows from (a data chunk for its vectors) alive. */
+  readonly #owner: object | undefined;
+
+  constructor(kind: K, ptr: Pointer | null, destroy: Destroy | null, owner?: object) {
+    this.kind = kind;
+    this.#cell = { kind, ptr, destroy, inFlight: 0, destroyRequested: false };
+    this.#owner = owner;
+    if (destroy && ptr !== null) {
+      live.set(kind, (live.get(kind) ?? 0) + 1);
+      registry.register(this, this.#cell, this.#cell);
+      addPressure(kind);
+    }
+  }
+
+  /** The native pointer, or null once destroyed. */
+  get ptr(): Pointer | null {
+    return this.#cell.ptr;
+  }
+
+  get owner(): object | undefined {
+    return this.#owner;
+  }
+
+  get destroyRequested(): boolean {
+    return this.#cell.destroyRequested;
+  }
+
+  /** True for a pointer owned elsewhere, which this handle never frees. */
+  get borrowed(): boolean {
+    return this.#cell.destroy === null;
+  }
+
+  /** Marks a native call as using this handle until `release` is called. */
+  acquire(): void {
+    this.#cell.inFlight++;
+  }
+
+  release(): void {
+    const cell = this.#cell;
+    cell.inFlight--;
+    if (cell.destroyRequested && cell.inFlight === 0) this.#finish();
+  }
+
+  /** Explicit destroy: now, or when the last native call using the handle completes. */
+  requestDestroy(): void {
+    const cell = this.#cell;
+    cell.destroyRequested = true;
+    if (cell.inFlight === 0) this.#finish();
+  }
+
+  /** Invalidates a borrowed handle, such as a callback's info once the callback returns. */
+  invalidate(): void {
+    this.#cell.ptr = null;
+    this.#cell.destroyRequested = true;
+  }
+
+  #finish(): void {
+    if (this.#cell.ptr !== null && this.#cell.destroy) relievePressure(this.kind);
+    registry.unregister(this.#cell);
+    destroyCell(this.#cell);
+  }
+}
+
+/** Wraps an owned pointer, freed by `destroy` when collected or explicitly destroyed. */
+export function owned<K extends Kind>(kind: K, ptr: Pointer, destroy: Destroy): Handle<K> {
+  return new Handle(kind, ptr, destroy);
+}
+
+/** Wraps a pointer owned elsewhere (a vector of a data chunk, a callback's info). */
+export function borrowed<K extends Kind>(kind: K, ptr: Pointer | null, owner?: object): Handle<K> {
+  return new Handle(kind, ptr, null, owner);
+}
+
+/**
+ * The pointer behind `value`, checked like the official binding's type tags.
+ *
+ * After an explicit destroy, a result or pending result throws the official
+ * "... destroyed" error, an invalidated borrowed handle throws the type error,
+ * and any other handle reads as null, the pointer the official binding's
+ * destroy leaves behind (so a query on it fails with "connection disconnected").
+ */
+export function unwrap(value: unknown, kind: Kind): Pointer | null {
+  if (!(value instanceof Handle) || value.kind !== kind) throw new Error(`Invalid ${kind} argument`);
+  if (!value.destroyRequested) return value.ptr;
+  const destroyed = DESTROYED_MESSAGE[kind];
+  if (destroyed) throw new Error(destroyed);
+  if (value.borrowed) throw new Error(`Invalid ${kind} argument`);
+  return null;
+}
+
+/** Like `unwrap`, but returns the Handle itself, for calls that must acquire it. */
+export function handleOf<K extends Kind>(value: unknown, kind: K): Handle<K> {
+  unwrap(value, kind);
+  return value as Handle<K>;
+}

package/src/bindings/runtime/kinds.ts

@@ -0,0 +1,53 @@
+// One constructor per handle kind. The shim frees each owned pointer with the C
+// function the official binding's externals.h pairs with its kind, and records it
+// in this JS thread's context, so a Worker that ends without running script
+// still frees it (native/ABI.md, "Handle ownership").
+import type { Pointer } from "bun:ffi";
+import "./dispatch.ts"; // Opens this JS thread's shim context before the first handle.
+import { borrowed, type Handle, type Kind, owned } from "./handle.ts";
+import { shim } from "./native.ts";
+
+/** Handle kind codes from native/ABI.md. */
+const KIND_CODE = {
+  appender: 1,
+  catalog: 2,
+  "catalog entry": 3,
+  "client context": 4,
+  config: 5,
+  connection: 6,
+  "data chunk": 7,
+  database: 8,
+  "extracted statements": 9,
+  "instance cache": 10,
+  "logical type": 11,
+  "pending result": 12,
+  "prepared statement": 13,
+  // A `duckdb_result *` the shim allocated with duckdb_malloc.
+  result: 14,
+  "scalar function": 15,
+  "table function": 16,
+  value: 17,
+  vector: 18,
+} as const satisfies Partial<Record<Kind, number>>;
+
+export type OwnedKind = keyof typeof KIND_CODE;
+
+const DESTROY = Object.fromEntries(
+  Object.entries(KIND_CODE).map(([kind, code]) => [kind, (ptr: Pointer) => shim.dbs_destroy(code, ptr)]),
+) as Record<OwnedKind, (ptr: Pointer) => void>;
+
+/** Wraps a pointer the caller now owns; it is freed when collected or explicitly destroyed. */
+export function own<K extends OwnedKind>(kind: K, ptr: Pointer): Handle<K> {
+  shim.dbs_own(KIND_CODE[kind], ptr);
+  return owned(kind, ptr, DESTROY[kind]);
+}
+
+/** Wraps a pointer owned elsewhere: a data chunk's vector, a callback's info, a chunk passed to a callback. */
+export function borrow<K extends Kind>(kind: K, ptr: Pointer | null, owner?: object): Handle<K> {
+  return borrowed(kind, ptr, owner);
+}
+
+/** The destroy function for a kind, for the explicit `*_sync` destroy entry points. */
+export function destroyerOf(kind: OwnedKind): (ptr: Pointer) => void {
+  return DESTROY[kind];
+}