bunostrdb

Bun FFI bindings for nostrdb — the unfairly fast embedded nostr database backed by LMDB.

Linux x86_64 only. This package does not support macOS, Windows, or non-x64 Linux. The native library is built from vendored C sources and loaded via bun:ffi dlopen().

npm consumers: prebuilt binaries. bun add bunostrdb gives you prebuilt Linux x86_64 shared objects — no C toolchain required. The npm tarball intentionally does not include the full vendored dependency tree needed to rebuild libnostrdb.so from source. To rebuild, clone the monorepo (git clone --recursive) and build from the repository root.

This package has a single runtime dependency (flatbuffers). The command-line interface lives in bunostrdb-cli at the repository root and depends on this package — installing the CLI never forces argument-parsing dependencies onto library consumers.

Docs: bunostrdb docs — getting started, resource management, architecture.

Prerequisites

• Bun v1.4.0+ (required for FFI; tested on 1.4.0)
• Linux x86_64 (enforced at load time — process.platform === "linux" and process.arch === "x64")
• A working C toolchain (build-essential or equivalent), make, and GNU coreutils (file, grep, find) — source builds only; npm consumers skip this

Native toolchain assumptions (source builds only)

• Compiler: GCC or Clang with C11 support (-fPIC is applied by the Makefile)
• Make: GNU Make (not BSD Make)
• The struct sizes in src/ffi.ts are hard-coded for the Linux x86_64 layout. (The vendored Makefile contains Darwin branches for byteswap.h portability, but this project never produces non-Linux artifacts.)

glibc compatibility note: The native binaries are dynamically linked against glibc. Systems with glibc < 2.38 (Debian 11 "bullseye", Ubuntu 20.04 "focal", RHEL 8, and older) are not supported even if they run Linux x86_64. The error at dlopen() time will be: libnostrdb.so: cannot open shared object file: GLIBC_2.38 not found.

Install

bun add bunostrdb
# or
pnpm add bunostrdb
# or
npm install bunostrdb

Source build (monorepo)

# 1. Clone and install (from the repository root)
git clone --recursive https://relay.ngit.dev/npub1m0std0zlg4d9gldykfjys342lz85ve2rvpqnpk86vcnzts02m68sl502vt/bunostrdb.git
cd bunostrdb
bun install

# 2. Build the native libraries (upstream lib + Bun shim)
bun run build:native

# 3. Build the TypeScript sources
bun run build:all

# 4. Run tests (from the repository root)
bun test

For npm consumers

bun add bunostrdb gives you the prebuilt Linux x86_64 binaries (see the callout at the top).

Continuous integration. Because the package ships ABI-sensitive native binaries, downstream consumers should still pin a known-good version and re-validate before upgrading Bun, glibc, or the vendored nostrdb commit.

License

Distributed under the BSD-3 license.

Support

If bunostrdb is useful, support development with any amount using Monero:

8AfaZJa3HRnS4F9yRzRK9iDcVPm17WA33EEZjWfREkkoUGWbLfA79aeSWoAj21B7swMW9bb8iWdgw8mtjJ5y4yMT7z6AmCc