EJDB - Embedded JSON Database

1.2.12-44 verified Thu Apr 23 auth: no javascript deprecated

EJDB (Embedded JSON Database) is a lightweight, embedded NoSQL database engine for Node.js, providing a MongoDB-like query language for local JSON document storage. The `ejdb` npm package specifically provides the Node.js bindings for the first generation EJDB engine. This version, `1.2.12-44`, is stable but officially discontinued and has not been updated in over seven years. The project has entirely transitioned to its successor, `ejdb2_node`, which is a complete rewrite. Users should migrate to `ejdb2_node` for active development, maintenance, and new features, including security updates. EJDB v1.x was designed for Node.js versions >=4.0.0 and focused on providing fast, self-contained, file-based JSON document storage with indexing, without requiring a separate server process. Its release cadence was sporadic, with its last publish seven years ago. Its key differentiator was being a high-performance embedded JSON store suitable for small to medium-scale applications where a full-fledged database server was considered overkill.

Common errors

error Error: `node-gyp` failed to rebuild... ↓

cause Installation failed because required C++ build tools are missing or incompatible with your Node.js version/OS.

fix

Install node-gyp prerequisites (e.g., npm install -g node-gyp, then follow its setup instructions for your OS). For long-term stability, migrate to ejdb2_node.

error TypeError: require is not a function ↓

cause Attempting to use `require()` in an ES module context (`type: "module"` in `package.json` or `.mjs` file).

fix

Change your file to use CommonJS (.js file without type: "module") or refactor your project to use ejdb2_node which may offer better ESM compatibility.

error Error: Cannot find module 'ejdb' ↓

cause The package was not installed successfully, or Node.js cannot locate the native binding.

fix

Run npm install ejdb again. Check the console output for node-gyp errors. If errors persist, ensure build tools are configured or consider migrating to ejdb2_node.

Warnings

breaking The `ejdb` package is officially discontinued and deprecated. All new development, maintenance, and support efforts have shifted to its successor, `ejdb2_node`. Users should plan to migrate to `ejdb2_node` as soon as possible for continued functionality and security. ↓

fix Migrate your application to use the `ejdb2_node` package (https://www.npmjs.com/package/ejdb2_node). This will involve code changes as EJDB2 is a complete rewrite.

gotcha As a native Node.js add-on, `ejdb` requires `node-gyp` to compile C++ source code during installation. This process can frequently fail on modern Node.js versions or certain operating systems due to missing build tools (e.g., C++ compilers, Python) or ABI incompatibilities. The package has not been updated in seven years. ↓

fix Ensure you have the necessary build tools installed for `node-gyp` (e.g., Python 2.7, Visual C++ Build Tools on Windows, `build-essential` on Linux). However, due to deprecation, migration to `ejdb2_node` is the recommended long-term solution, as some versions of `ejdb2_node` offer pre-compiled binaries.

gotcha This package receives no active maintenance, bug fixes, or security updates. Using it in production environments may expose applications to unpatched vulnerabilities or unexpected behavior with newer Node.js versions. ↓

fix Expeditiously migrate to the `ejdb2_node` package, which is actively maintained and supported by the developers.

Install

npm install ejdb

yarn add ejdb

pnpm add ejdb

Imports

EJDB
wrong
```
import EJDB from 'ejdb'
```
correct
```
const EJDB = require('ejdb')
```
This package exclusively uses CommonJS modules. ESM 'import' syntax is not supported for this version of EJDB.
EJDB.QL
wrong
```
import { QL } from 'ejdb'
```
correct
```
const QL = EJDB.QL
```
The Query Language (QL) utility is a static method accessed directly from the main EJDB object after it has been required.
EJDB.DEFAULT_OPEN_MODE
wrong
```
import { DEFAULT_OPEN_MODE } from 'ejdb'
```
correct
```
const { DEFAULT_OPEN_MODE } = EJDB
```
Constants like DEFAULT_OPEN_MODE are properties of the main EJDB object.

Quickstart

Demonstrates how to initialize EJDB, open a database file, insert a JSON document, and query for data using a MongoDB-like syntax.

const EJDB = require('ejdb');
const db = new EJDB();

async function run() {
    try {
        // Open/create a database file named 'my_database.ejdb'
        // EJDB.DEFAULT_OPEN_MODE includes read/write, create if not exists, and truncate on open if specified.
        await db.open('my_database.ejdb', EJDB.DEFAULT_OPEN_MODE);
        console.log('Database opened successfully.');

        // Insert a document into the 'users' collection
        const userDoc = {
            name: 'John Doe',
            age: 42,
            city: 'Sampleville',
            interests: ['coding', 'reading', 'hiking']
        };
        const oid = await db.insert('users', userDoc);
        console.log(`Document inserted with OID: ${oid}`);

        // Find documents in the 'users' collection where age is greater than 30
        // EJDB.QL is used to construct MongoDB-like queries.
        const query = EJDB.QL('{"age": {"$gt": 30}}');
        const cursor = await db.find('users', query);
        const results = await cursor.toArray();
        console.log('Found documents:', results);

        // Close the database connection
        await db.close();
        console.log('Database closed.');
    } catch (err) {
        console.error('An error occurred:', err);
    }
}

run();