FoundationDB Node.js Bindings

Common errors

• Error: The FoundationDB C client library could not be loaded. Please ensure FoundationDB is installed and libfdb_c is in your dynamic library path.

  cause The native FoundationDB client library (`libfdb_c.so`, `.dylib`, or `.dll`) is not installed on the system, or its location is not included in the operating system's dynamic library search path.
  fix Install the FoundationDB client library for your OS and architecture from foundationdb.org/download/. On Linux, ensure `libfdb_c.so` is in a standard path like `/usr/local/lib` or `LD_LIBRARY_PATH` is set. On macOS, check `DYLD_LIBRARY_PATH`. On Windows, ensure `fdb_c.dll` is in a directory listed in your system's `PATH` environment variable.

• Error: API version may be set only once

  cause Attempted to call `fdb.setAPIVersion()` more than once in the application's lifecycle, or after other FoundationDB operations have already initialized the API.
  fix Identify all calls to `fdb.setAPIVersion()` and consolidate them into a single invocation at the absolute entry point of your application before any other FoundationDB API usage.

• TypeError: fdb.open is not a function

  cause Incorrect import statement used in an ESM context. When a CommonJS module is imported with `import fdb from 'module';` in ESM, the default export may not contain all expected properties.
  fix In an ESM context, use `import * as fdb from 'foundationdb';` to correctly import all exports from the CommonJS module. If using CommonJS, `const fdb = require('foundationdb');` is correct.

Warnings

• breaking The `foundationdb` Node.js package requires the FoundationDB C client library (`libfdb_c`) to be installed system-wide on the machine where the application runs. This library is not bundled with the npm package and must be downloaded separately from the official FoundationDB website.
  Fix: Download and install the appropriate FoundationDB client library for your operating system and architecture from foundationdb.org/download/. Ensure the library is discoverable by your system's dynamic linker (e.g., in PATH on Windows, LD_LIBRARY_PATH on Linux, DYLD_LIBRARY_PATH on macOS).
• gotcha You MUST call `fdb.setAPIVersion(version)` exactly once, and it must be the very first FoundationDB-related operation in your application. Calling it after `fdb.open()` or attempting to call it multiple times (even with the same version) can lead to errors or unexpected behavior.
  Fix: Ensure `fdb.setAPIVersion(version)` is placed at the absolute start of your application's bootstrap logic, prior to any `fdb.open()` calls or other API interactions. If you have multiple calls from different parts of your code, consolidate them.
• gotcha Windows support for `node-foundationdb` is currently disabled due to a known missing header file (`fdb_c_types.h`) in the FoundationDB Windows MSI installer, which prevents the native bindings from compiling correctly.
  Fix: Windows users should currently avoid this library or use a Linux/macOS environment. Monitor the FoundationDB forums and GitHub issues for updates on Windows support.
• gotcha On macOS, due to binary sandboxing, you may need to explicitly add `export DYLD_LIBRARY_PATH=/usr/local/lib` to your shell profile (`.zshrc` or `.bash_profile`) to help the system locate the `libfdb_c` dynamic library.
  Fix: Add `export DYLD_LIBRARY_PATH=/usr/local/lib` to your shell configuration file and restart your terminal or shell session for changes to take effect.
• gotcha This library only supports FoundationDB server versions 6.2.0 or later. Using it with older server versions may lead to unexpected errors or incompatible API behavior. Additionally, the `setAPIVersion` argument must be less than or equal to the FoundationDB cluster's actual API version.
  Fix: Ensure your FoundationDB cluster is running version 6.2.0 or newer. Verify that the `setAPIVersion` call matches a supported client API version for your specific server version.

Install

• npm install foundationdb npm
• yarn add foundationdb yarn
• pnpm add foundationdb pnpm

Imports

• fdb
  wrong:

  import fdb from 'foundationdb';

  correct:

  const fdb = require('foundationdb');

  The `foundationdb` package primarily uses CommonJS exports as shown in the quickstart. For ESM environments, `import * as fdb from 'foundationdb';` is the correct pattern for importing CommonJS modules to access all exports. Using `import fdb from 'foundationdb';` typically only works for modules with a default ESM export or specific `exports` map in `package.json`.
• fdb.setAPIVersion
  wrong:

  const dbRoot = fdb.open();
  fdb.setAPIVersion(700); // Incorrect order, will throw an error.

  correct:

  fdb.setAPIVersion(700); // Must be called before fdb.open()

  This function MUST be called once, at the very start of your application, before any other FoundationDB operations, including `fdb.open()`. The API version chosen (`700` in the example) must be less than or equal to the FoundationDB cluster's major/minor API version.
• Database (TypeScript Type)

  import type { Database, Transaction, Directory } from 'foundationdb';

  The package ships with TypeScript types. Import specific types explicitly for better type checking and IntelliSense.

Quickstart

Demonstrates connecting to FoundationDB, creating a directory, configuring key/value encoding, performing a transactional write, and reading data using the promise-based API.

const fdb = require('foundationdb');
fdb.setAPIVersion(700); // Must be called before database is opened

(async () => {
  const dbRoot = fdb.open(); // or open('/path/to/fdb.cluster')

  // Scope all of your application's data inside the 'myapp' directory in your database
  const db = dbRoot.at(await fdb.directory.createOrOpen(dbRoot, 'myapp'))
    .withKeyEncoding(fdb.encoders.tuple) // automatically encode & decode keys using tuples
    .withValueEncoding(fdb.encoders.json); // and values using JSON

  await db.doTransaction(async tn => {
    console.log('Book 123 is', await tn.get(['books', 123])); // Book 123 is undefined

    tn.set(['books', 123], {
      title: 'Reinventing Organizations',
      author: 'Laloux'
    });
  });
  
  console.log('now book 123 is', await db.get(['books', 123])); // shorthand for db.doTransaction(...)
})().catch(err => {
  console.error('An error occurred:', err);
  process.exit(1);
});