@avidian/duckdb-bun 0.0.0-stage → 1.0.0

package/src/errors.ts

@@ -0,0 +1,30 @@
+// A real Error subclass so callers can keep
+// using `err instanceof Error` and message regex checks (e.g. /Out of Memory/i).
+export class DuckDBError extends Error {
+  readonly duckdbMessage: string;
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = "DuckDBError";
+    this.duckdbMessage = message;
+  }
+}
+
+/** Runs `action`, rethrowing any error as a DuckDBError with the same message and the original as its cause. */
+export async function asDuckDBError<T>(action: () => Promise<T>): Promise<T> {
+  try {
+    return await action();
+  } catch (error) {
+    if (error instanceof DuckDBError) throw error;
+    throw new DuckDBError(error instanceof Error ? error.message : String(error), { cause: error });
+  }
+}
+
+/** The synchronous form of asDuckDBError. */
+export function asDuckDBErrorSync<T>(action: () => T): T {
+  try {
+    return action();
+  } catch (error) {
+    if (error instanceof DuckDBError) throw error;
+    throw new DuckDBError(error instanceof Error ? error.message : String(error), { cause: error });
+  }
+}

package/src/file-assets.d.ts

@@ -0,0 +1,10 @@
+// Files imported with `with { type: "file" }` resolve to their path at run time
+// (and to their /$bunfs/ path inside a `bun build --compile` executable).
+declare module "*.so" {
+  const path: string;
+  export default path;
+}
+declare module "*.dylib" {
+  const path: string;
+  export default path;
+}

package/src/index.ts

@@ -0,0 +1,17 @@
+// The native-JS binding: a narrow API over the same bindings as the main entry,
+// returning plain JavaScript values (README.md, "Native-JS binding").
+
+export { DuckDBConnection } from "./connection.ts";
+export { DuckDBInstance } from "./database.ts";
+export { DuckDBError } from "./errors.ts";
+export { Reader } from "./reader.ts";
+export { PreparedStatement } from "./statement.ts";
+export type { ColumnType, QueryResultShape } from "./types.ts";
+export { DuckDBType } from "./types.ts";
+
+import { version } from "../vendor/node-api/src/index.ts";
+
+/** The linked libduckdb version, e.g. "v2.0.0". */
+export function libraryVersion(): string {
+  return version();
+}

package/src/library.ts

@@ -0,0 +1,83 @@
+// Resolves the two native libraries: libduckdb and the Rust shim
+// (libduckdb_bun_shim), both shipped in the optional platform package for this
+// platform (@avidian/duckdb-bun-<platform>), the way @duckdb/node-api ships its
+// native addon.
+//
+// Resolution is synchronous so the bindings module has no top-level await and
+// stays loadable through require(), which worker_threads and CommonJS callers
+// use.
+//
+// The shim links libduckdb and finds it beside itself through its rpath
+// ($ORIGIN, @loader_path). Two cases copy both libraries side by side into a
+// fresh temporary directory, so the shim and JavaScript load one and the same
+// libduckdb: DUCKDB_BUN_LIBRARY_PATH, which overrides libduckdb with one of the
+// same DuckDB version, and a `bun build --compile` executable, whose files live
+// in Bun's virtual `/$bunfs/` filesystem that dlopen cannot read.
+import { mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, join } from "node:path";
+
+export interface NativePaths {
+  /** Absolute path to libduckdb. */
+  libPath: string;
+  /** Absolute path to the shim cdylib, built from native/. */
+  shimPath: string;
+}
+
+interface PlatformPackage {
+  default: string;
+  shimPath: string;
+}
+
+const SUPPORTED = "the supported platforms are linux-x64 (glibc), linux-arm64 (glibc) and darwin-arm64";
+
+function load(name: string, require: () => unknown): PlatformPackage {
+  try {
+    return require() as PlatformPackage;
+  } catch (cause) {
+    throw new Error(`duckdb-bun: the optional package ${name} is not installed. Reinstall without --no-optional.`, {
+      cause,
+    });
+  }
+}
+
+function platformPackage(): PlatformPackage {
+  // Each test reads process.platform and process.arch directly: `bun build --compile`
+  // folds them to constants, so it embeds the target's package and skips the others,
+  // whose native files are absent on this machine.
+  if (process.platform === "linux" && process.arch === "x64") {
+    return load("@avidian/duckdb-bun-linux-x64", () => require("@avidian/duckdb-bun-linux-x64"));
+  }
+  if (process.platform === "linux" && process.arch === "arm64") {
+    return load("@avidian/duckdb-bun-linux-arm64", () => require("@avidian/duckdb-bun-linux-arm64"));
+  }
+  if (process.platform === "darwin" && process.arch === "arm64") {
+    return load("@avidian/duckdb-bun-darwin-arm64", () => require("@avidian/duckdb-bun-darwin-arm64"));
+  }
+  throw new Error(`duckdb-bun: no native package for ${process.platform}-${process.arch}; ${SUPPORTED}.`);
+}
+
+function copyTo(dir: string, path: string, name = basename(path)): string {
+  const target = join(dir, name);
+  writeFileSync(target, readFileSync(path));
+  return target;
+}
+
+let cached: NativePaths | undefined;
+
+export function nativePaths(): NativePaths {
+  if (cached) return cached;
+  const pkg = platformPackage();
+  const override = process.env.DUCKDB_BUN_LIBRARY_PATH;
+  if (!override && !pkg.default.startsWith("/$bunfs/")) {
+    cached = { libPath: pkg.default, shimPath: pkg.shimPath };
+    return cached;
+  }
+  const dir = mkdtempSync(join(tmpdir(), "duckdb-bun-"));
+  cached = {
+    // Under the file name the shim links against, whatever the override is called.
+    libPath: copyTo(dir, override || pkg.default, basename(pkg.default)),
+    shimPath: copyTo(dir, pkg.shimPath),
+  };
+  return cached;
+}

package/src/neo.ts

@@ -0,0 +1,16 @@
+// Public entry for the drop-in `@duckdb/node-api` replacement. Re-exports the full
+// vendored official TypeScript API (running over our bun:ffi bindings), so:
+//
+//   import { DuckDBInstance } from "@avidian/duckdb-bun";
+//
+// behaves like `@duckdb/node-api`, with the same classes and value objects, but
+// embeds libduckdb, so `bun build --compile` yields a self-contained binary.
+//
+// It adds diagnostics(), DUCKDB_VERSION and the "duckdb-bun:call" tracing channel (README.md).
+// The narrow, native-JS binding is still available at `@avidian/duckdb-bun/native-js`.
+export * from "../vendor/node-api/src/index.ts";
+export { default } from "../vendor/node-api/src/index.ts";
+export { type Diagnostics, diagnostics } from "./bindings/runtime/diagnostics.ts";
+export type { CallContext } from "./bindings/runtime/trace.ts";
+/** The DuckDB version this package bundles, such as "2.0.0". */
+export { DUCKDB_VERSION } from "./version.ts";

package/src/reader.ts

@@ -0,0 +1,47 @@
+// The native-JS value mapping over the vendored @duckdb/node-api reader: the
+// official JS converter, except that DATE, TIME, TIME_TZ, TIME_NS and BIT come
+// back as their SQL text (DATE as YYYY-MM-DD). Nested values use the same mapping.
+import {
+  type DuckDBResultReader,
+  DuckDBTypeId,
+  type DuckDBValueConverter,
+  JSDuckDBValueConverter,
+} from "../vendor/node-api/src/index.ts";
+
+const AS_TEXT = new Set<DuckDBTypeId>([
+  DuckDBTypeId.DATE,
+  DuckDBTypeId.TIME,
+  DuckDBTypeId.TIME_TZ,
+  DuckDBTypeId.TIME_NS,
+  DuckDBTypeId.BIT,
+]);
+
+const nativeJsConverter: DuckDBValueConverter<unknown> = (value, type, converter) => {
+  if (value === null) return null;
+  if (AS_TEXT.has(type.typeId)) return String(value);
+  return JSDuckDBValueConverter(value, type, converter as never);
+};
+
+/** A materialized query result. Mirrors the slice of @duckdb/node-api's reader used downstream. */
+export class Reader {
+  #columns: string[];
+  #rows: Record<string, unknown>[];
+  constructor(columns: string[], rows: Record<string, unknown>[]) {
+    this.#columns = columns;
+    this.#rows = rows;
+  }
+  columnNames(): string[] {
+    return this.#columns;
+  }
+  getRowObjects(): Record<string, unknown>[] {
+    return this.#rows;
+  }
+  get rowCount(): number {
+    return this.#rows.length;
+  }
+}
+
+/** Converts a fully read official reader into a native-JS Reader. */
+export function readerFrom(reader: DuckDBResultReader): Reader {
+  return new Reader(reader.columnNames(), reader.convertRowObjects(nativeJsConverter) as Record<string, unknown>[]);
+}

package/src/statement.ts

@@ -0,0 +1,61 @@
+import type { DuckDBPreparedStatement } from "../vendor/node-api/src/index.ts";
+import { asDuckDBError, asDuckDBErrorSync } from "./errors.ts";
+import { type Reader, readerFrom } from "./reader.ts";
+
+const INT64_MIN = -9_223_372_036_854_775_808n;
+const INT64_MAX = 9_223_372_036_854_775_807n;
+
+/** A prepared statement with 1-based parameter binding. */
+export class PreparedStatement {
+  #statement: DuckDBPreparedStatement;
+  #closed = false;
+
+  constructor(statement: DuckDBPreparedStatement) {
+    this.#statement = statement;
+  }
+
+  /** Number of `?` parameters in the statement. */
+  get paramCount(): number {
+    return this.#statement.parameterCount;
+  }
+
+  /** Bind a single 1-based parameter, dispatching by JS type. */
+  bind(index: number, value: unknown): this {
+    const statement = this.#statement;
+    asDuckDBErrorSync(() => {
+      if (value === null || value === undefined) statement.bindNull(index);
+      else if (typeof value === "boolean") statement.bindBoolean(index, value);
+      else if (typeof value === "bigint") {
+        if (value >= INT64_MIN && value <= INT64_MAX) statement.bindBigInt(index, value);
+        else statement.bindVarchar(index, value.toString());
+      } else if (typeof value === "number") {
+        if (Number.isSafeInteger(value)) statement.bindBigInt(index, BigInt(value));
+        else statement.bindDouble(index, value);
+      } else if (value instanceof Date) statement.bindVarchar(index, value.toISOString());
+      else statement.bindVarchar(index, String(value));
+    });
+    return this;
+  }
+
+  /** Bind all parameters positionally (1-based under the hood). */
+  bindAll(values: unknown[]): this {
+    for (let i = 0; i < values.length; i++) this.bind(i + 1, values[i]);
+    return this;
+  }
+
+  /** Execute and discard the result. */
+  async run(): Promise<void> {
+    await asDuckDBError(() => this.#statement.run());
+  }
+
+  /** Execute and read every row. */
+  async readAll(): Promise<Reader> {
+    return readerFrom(await asDuckDBError(() => this.#statement.runAndReadAll()));
+  }
+
+  close(): void {
+    if (this.#closed) return;
+    this.#statement.destroySync();
+    this.#closed = true;
+  }
+}

package/src/types.ts

@@ -0,0 +1,52 @@
+// Mirror of the `DUCKDB_TYPE` enum from vendor/duckdb.h.
+export const DuckDBType = {
+  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,
+  VARCHAR: 17,
+  BLOB: 18,
+  DECIMAL: 19,
+  TIMESTAMP_S: 20,
+  TIMESTAMP_MS: 21,
+  TIMESTAMP_NS: 22,
+  ENUM: 23,
+  LIST: 24,
+  STRUCT: 25,
+  MAP: 26,
+  UUID: 27,
+  BIT: 29,
+  TIME_TZ: 30,
+  TIMESTAMP_TZ: 31,
+  UHUGEINT: 32,
+  ARRAY: 33,
+  BIGNUM: 35,
+  SQLNULL: 36,
+} as const;
+
+// Metadata needed to decode a result column: its type id plus (for DECIMAL) the
+// scale and the integer storage type the decimal is stored as.
+export interface ColumnType {
+  id: number;
+  scale?: number;
+  internal?: number;
+}
+
+export interface QueryResultShape {
+  columns: string[];
+  rows: Record<string, unknown>[];
+  rowCount: number;
+}

package/src/version.ts

@@ -0,0 +1,6 @@
+// Single source of truth for the DuckDB version this binding targets. Bump this
+// when upgrading, then re-run `bun run fetch-lib`. See MAINTENANCE.md.
+export const DUCKDB_VERSION = "2.0.0";
+
+/** The version tag as it appears on GitHub releases and from duckdb_library_version(). */
+export const DUCKDB_VERSION_TAG = `v${DUCKDB_VERSION}`;

package/vendor/node-api/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2018-2025 Stichting DuckDB Foundation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/vendor/node-api/PROVENANCE.md

@@ -0,0 +1,54 @@
+# Vendored `@duckdb/node-api` and `@duckdb/node-bindings` tests
+
+These trees are copied **verbatim** from the official DuckDB Node "Neo" monorepo.
+We reimplement the bindings over `bun:ffi` and prove parity against the official test suites.
+
+|                                 |                                                                       |
+| ------------------------------- | --------------------------------------------------------------------- |
+| Upstream repo                   | https://github.com/duckdb/duckdb-node-neo                             |
+| Tag                             | `v2.0.0-r.1`                                                          |
+| Commit                          | `769e55196b7e68c953c72618adbce553d54b777d`                            |
+| `@duckdb/node-api` version      | `2.0.0-r.1`                                                           |
+| `@duckdb/node-bindings` version | `2.0.0-r.1` (DuckDB core v2.0.0)                                      |
+| License                         | MIT, see `./LICENSE` and `../node-bindings/LICENSE`                   |
+
+## Layout
+
+- `src/` is copied from `api/src/`.
+  It is the full TypeScript API layer, **unmodified on disk** except for the import rewrite described below.
+- `test/` is copied from `api/test/`.
+  It is the official `@duckdb/node-api` Vitest suite, with `util/` and `bench/`; we do not run `bench/`.
+  It is **unmodified on disk**.
+- `node-bindings.d.ts` is copied from `bindings/pkgs/@duckdb/node-bindings/duckdb.d.ts`.
+  It is the exact interface contract that our `src/bindings/` reimplements, and the source of truth for `scripts/gen-contract.ts`.
+- `../node-bindings/test/` is copied from `bindings/test/`.
+  It is the official `@duckdb/node-bindings` Vitest suite, with `utils/`, `fixtures/` and `stress/`.
+  It is **unmodified on disk**.
+- `../node-bindings/LICENSE` is the upstream license that covers the bindings tests.
+
+## How it's wired
+
+- The `@duckdb/node-bindings` imports in `src/` are rewritten **on disk** to a relative import of our `src/bindings/` by `scripts/vendor-rewrite-bindings.ts`.
+  That is the only modification against upstream; every other line is byte-identical.
+  It makes the published package a plugin-free drop-in: consumers `import { DuckDBInstance } from '@avidian/duckdb-bun'`, and the vendored layer loads our `bun:ffi` bindings directly, with nothing else in the resolution path.
+- The `vitest` imports in both test suites can't be rewritten on disk the same way, because they would need `vitest` installed for the editor and the type checker.
+  `bun test` also hard-remaps `vitest` to `bun:test`, which lacks an `assert` export, before tsconfig `paths` or a plugin `onResolve` run.
+  So `tests/preload.ts` uses an **`onLoad`** plugin, scoped to the two `test/` directories, that rewrites `vitest` to `tests/vitest-shim.ts` at load time.
+  The shim re-exports the `bun:test` runner primitives and chai's `assert`, which is what vitest's `assert` is.
+- The same `onLoad` plugin rewrites the bindings suite's ESM `@duckdb/node-bindings` imports to our `src/bindings/`.
+- The bindings suite also resolves `@duckdb/node-bindings` through CommonJS: `worker_threads.test.ts` calls `createRequire(...).resolve()`, and `scalar_function_exit.test.ts` spawns `bun` on `fixtures/scalarFunctionExit.cjs`, which calls `require()`.
+  `tests/node-bindings-resolve.ts` overrides `Module._resolveFilename` for requests from `../node-bindings/test/`, and `tests/preload.ts` loads it in the test process and adds it to `BUN_OPTIONS` for every spawned `bun` process.
+- `tests/official/api.test.ts` (`bun run test:official`) and `tests/official/bindings.test.ts` (`bun run test:bindings`) import every test file of the respective suite.
+  `bindings.test.ts` leaves out `stress/`, which is heavy and runs one file at a time.
+
+## Updating (on a DuckDB version bump)
+
+`scripts/upgrade-duckdb.ts` (`bun run upgrade-duckdb`) does steps 1 to 5 and updates the table above; MAINTENANCE.md "Upgrading DuckDB" describes when it runs.
+
+1. Check out the upstream tag `v<version>` whose `api/pkgs/@duckdb/node-api/package.json` carries the new `@duckdb/node-api` version, built on the new `DUCKDB_VERSION` pin (`src/version.ts`).
+2. Re-copy `api/src` to `src/`, `api/test` to `test/`, `bindings/test` to `../node-bindings/test/`, `LICENSE` to both `LICENSE` files, and the bindings `duckdb.d.ts` to `node-bindings.d.ts`.
+3. Run `bun run scripts/vendor-rewrite-bindings.ts` to rewrite the `@duckdb/node-bindings` imports to our bindings; it is idempotent.
+4. Add any new bindings test file to `tests/official/bindings.test.ts`, and any new API test file to `tests/official/api.test.ts`.
+5. Run `bun run gen:contract` to regenerate `src/bindings/generated/contract.ts` from `node-bindings.d.ts`.
+6. Implement any newly added binding functions.
+   Verify with `bun run test:official` and `bun run test:bindings`.