@avidian/duckdb-bun 1.0.0 → 1.0.1

package/README.md

@@ -47,6 +47,7 @@ Every release is a stable version, so a range such as `^1.0.0` takes every compa
 | `@avidian/duckdb-bun` | DuckDB | `@duckdb/node-api` it matches |
 | --- | --- | --- |
 | 1.0.0 | 2.0.0 | 2.0.0-r.1 |
+| 1.0.1 | 2.0.0 | 2.0.0-r.1 |
 
 At run time, `DUCKDB_VERSION` holds the bundled DuckDB version, and `diagnostics().versions` holds all of them:
 
@@ -186,6 +187,7 @@ Include the report when you open an issue.
   It runs every blocking call (open, connect, query, prepare, execute, fetch) on a native thread, so the JS thread never waits for a query.
   It installs the crash handler.
 - Every native pointer is owned by a handle object, freed by a `FinalizationRegistry` or by an explicit close, and never while a native call is using it.
+- A Worker that ends, including through `terminate()` in the middle of a query, interrupts its queries and frees its databases, connections and other handles; the main thread's databases keep working ([ADR 0008](docs/adr/0008-a-worker-closes-its-context-in-an-n-api-cleanup-hook.md)).
 
 The design decisions are recorded in [`docs/adr/`](docs/adr/).
 
@@ -217,10 +219,10 @@ Each CI run uploads its full tables as the `bench-<platform>` artifact.
 
 ## Known issues
 
-- Terminating a Bun `Worker` with `worker.terminate()` while that Worker runs a query crashes the process with SIGSEGV.
-  Bun runs no exit handler in a terminated Worker, so the binding never learns that the Worker's JavaScript is gone, and the finished query calls back into it.
-  The official `@duckdb/node-api` crashes on the same sequence under Bun 1.4.4, on the first termination.
-  Until a fix ships, let a Worker's queries settle, or close its connections, before terminating it.
+- In a `bun build --compile` binary, each Worker that loads the package copies libduckdb and the shim into a new temporary folder and loads its own copy.
+  Starting many Workers leaves those folders behind, and the main thread's `diagnostics()` does not count the Workers' native work.
+- A Worker terminated in the few microseconds between a query's native thread starting and DuckDB beginning that query does not interrupt it.
+  The query runs to its end before the Worker's handles are freed; nothing crashes or leaks.
 - One process can load the package in at most 4094 Workers over its whole life, because each JS thread takes a context id that is never reused (`native/ABI.md`, `dbs_init`).
   A Worker past that limit throws when it loads the package.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avidian/duckdb-bun",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Bun-native, drop-in reimplementation of @duckdb/node-api via bun:ffi over the libduckdb C API. Embeds libduckdb so `bun build --compile` yields a self-contained binary.",
   "author": "John Michael Manlupig",
   "license": "MIT",
@@ -49,6 +49,7 @@
     "soak": "bun run scripts/soak.ts",
     "test:crash": "bun test tests/heavy/crash-report.test.ts",
     "test:issue-3060": "bun test tests/heavy/issue-3060.test.ts",
+    "test:worker-terminate": "bun test tests/heavy/worker-terminate.test.ts",
     "test:unit": "bun test --path-ignore-patterns 'tests/official/**' --path-ignore-patterns 'tests/heavy/**' --path-ignore-patterns 'tests/compile/**' --path-ignore-patterns tests/parity.test.ts --path-ignore-patterns 'tests/parity/**' --path-ignore-patterns 'tests/fuzz/**'",
     "coverage": "bun run scripts/coverage.ts",
     "check-version": "bun run scripts/check-version.ts",
@@ -71,9 +72,9 @@
     "analytics"
   ],
   "optionalDependencies": {
-    "@avidian/duckdb-bun-darwin-arm64": "1.0.0",
-    "@avidian/duckdb-bun-linux-arm64": "1.0.0",
-    "@avidian/duckdb-bun-linux-x64": "1.0.0"
+    "@avidian/duckdb-bun-darwin-arm64": "1.0.1",
+    "@avidian/duckdb-bun-linux-arm64": "1.0.1",
+    "@avidian/duckdb-bun-linux-x64": "1.0.1"
   },
   "devDependencies": {
     "@biomejs/biome": "2.6.7",

package/src/bindings/runtime/dispatch.ts

@@ -7,8 +7,9 @@
 // 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 } from "./native.ts";
+import { shim, shimPath } from "./native.ts";
 import { jobOp, record } from "./ring.ts";
 import { type CallContext, traced } from "./trace.ts";
 
@@ -196,5 +197,17 @@ 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);
-// A Worker's callbacks die with it, so the shim drops whatever arrives for it afterwards.
-process.on("exit", () => shim.dbs_context_close());
+
+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/kinds.ts

@@ -1,44 +1,44 @@
-// One constructor per handle kind, pairing each owned pointer with the C
-// function that frees it, as the official binding's externals.h does.
+// 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 { slot } from "./marshal.ts";
-import { duckdb } from "./native.ts";
+import { shim } from "./native.ts";
 
-/** Calls a `duckdb_destroy_x(T *handle)` style function with the address of `ptr`. */
-function viaSlot(destroy: (address: BigUint64Array) => void): (ptr: Pointer) => void {
-  return (ptr) => destroy(slot(ptr));
-}
+/** 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>>;
 
-const DESTROY = {
-  appender: viaSlot((a) => duckdb.duckdb_appender_destroy(a)),
-  catalog: viaSlot((a) => duckdb.duckdb_destroy_catalog(a)),
-  "catalog entry": viaSlot((a) => duckdb.duckdb_destroy_catalog_entry(a)),
-  "client context": viaSlot((a) => duckdb.duckdb_destroy_client_context(a)),
-  config: viaSlot((a) => duckdb.duckdb_destroy_config(a)),
-  connection: viaSlot((a) => duckdb.duckdb_disconnect(a)),
-  "data chunk": viaSlot((a) => duckdb.duckdb_destroy_data_chunk(a)),
-  database: viaSlot((a) => duckdb.duckdb_close(a)),
-  "extracted statements": viaSlot((a) => duckdb.duckdb_destroy_extracted(a)),
-  "instance cache": viaSlot((a) => duckdb.duckdb_destroy_instance_cache(a)),
-  "logical type": viaSlot((a) => duckdb.duckdb_destroy_logical_type(a)),
-  "pending result": viaSlot((a) => duckdb.duckdb_destroy_pending(a)),
-  "prepared statement": viaSlot((a) => duckdb.duckdb_destroy_prepare(a)),
-  // A result is a `duckdb_result *` the shim allocated with duckdb_malloc.
-  result: (ptr: Pointer) => {
-    duckdb.duckdb_destroy_result(ptr);
-    duckdb.duckdb_free(ptr);
-  },
-  "scalar function": viaSlot((a) => duckdb.duckdb_destroy_scalar_function(a)),
-  "table function": viaSlot((a) => duckdb.duckdb_destroy_table_function(a)),
-  value: viaSlot((a) => duckdb.duckdb_destroy_value(a)),
-  vector: viaSlot((a) => duckdb.duckdb_destroy_vector(a)),
-} as const satisfies Partial<Record<Kind, (ptr: Pointer) => void>>;
+export type OwnedKind = keyof typeof KIND_CODE;
 
-export type OwnedKind = keyof typeof DESTROY;
+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]);
 }
 

package/src/bindings/runtime/native.ts

@@ -16,6 +16,9 @@ const shimAbi = {
   dbs_init: { args: ["ptr", "ptr", "ptr"], returns: "i32" },
   dbs_set_sync_call: { args: ["ptr"], returns: "void" },
   dbs_context_close: { args: [], returns: "void" },
+  dbs_context_hooked: { args: [], returns: "bool" },
+  dbs_own: { args: ["u32", "ptr"], returns: "void" },
+  dbs_destroy: { args: ["u32", "ptr"], returns: "void" },
   dbs_counters: { args: [], returns: "ptr" },
   dbs_version: { args: [], returns: "cstring" },
   dbs_capi_table: { args: ["ptr"], returns: "ptr" },