Registry / database / jdb

jdb

JSON →
library1.0jsnpmunverified

JDB is a lightweight, file-append-only, in-memory, non-blocking I/O database inspired by NeDB. It allows users to manipulate data directly using standard JavaScript code, eliminating the need for a separate query language. The current stable version is 0.5.5, indicating a relatively mature but perhaps slower-paced development cycle without explicit release cadence information. Key differentiators include its lightweight core (approx. 200 lines), direct JavaScript data manipulation, promise support, and both standalone server and in-application library modes. It operates by appending JavaScript commands to a file, which are then re-executed on startup to reconstruct the database's in-memory state. Periodically, the database file can be compacted into a single JSON object to optimize storage and startup time.

database
npm install jdb
github ↗package ↗
INSTALL
IMPORT
SIG · JDB
J
jdb
databasejavascriptv1.0
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

jdb
✓ const jdb = require('jdb')();
✗ import jdb from 'jdb'; const jdb = require('jdb');
The `jdb` package exports a factory function that must be immediately invoked `()` to get the database instance. It is primarily a CommonJS module.
init
✓ await jdb.init();
✗ jdb.init((err) => { /* ... */ });
The `init` method initializes the database and returns a Promise by default (since `promise` option defaults to `true`). Callback-style is also supported but Promise is preferred for modern async/await patterns.
exec
✓ await jdb.exec({ data: someData, command: (db, data) => db.doc.myKey = data });
✗ jdb.exec((db) => { db.doc.myKey = outerScopeVar; });
The `exec` method takes an options object or data + command function. The `command` function is executed in an isolated scope, requiring all necessary data to be passed via the `data` option.

This quickstart demonstrates initializing a JDB instance, saving complex JavaScript objects using both callback and promise-based `exec` methods, accessing the saved data directly from the in-memory document, and finally simulating a restart to confirm data persistence by re-initializing from the saved file. It also includes cleanup of the temporary database file.

const jdb = require('jdb')(); const path = require('path'); const fs = require('fs'); const dbFilePath = path.join(__dirname, 'temp.jdb'); const some_data = { "name": { "first": "Yad", "last": "Smood" }, "fav_color": "blue", "languages": [ { "name": "Chinese", "level": 10 }, { "name": "English", "level": 8, "preferred": true }, { "name": "Japanese", "level": 6 } ], "height": 180, "weight": 68 }; async function runQuickstart() { // Clean up previous runs if (fs.existsSync(dbFilePath)) { fs.unlinkSync(dbFilePath); } try { // Initialize JDB with a specific file path await jdb.init({ dbPath: dbFilePath }); console.log('Database initialized at:', dbFilePath); // Set data using exec with callback (converted to promise for sequential execution) await new Promise((resolve, reject) => { jdb.exec( { data: some_data, command: (jdbInstance, data) => { jdbInstance.doc.ys = data; jdbInstance.save('saved_data'); // Save with a return value }, callback: (err, result) => { if (err) return reject(err); console.log('Exec with callback result:', result); // Expected: 'saved_data' resolve(result); } } ); }); // Simple way to save data using exec with promise await jdb.exec(some_data, (jdbInstance, data) => { jdbInstance.doc.arr = data.languages.map((el) => el.name); jdbInstance.save(); // Default save returns undefined on success }); console.log('Second data save completed.'); // Get the value after operations complete from the current instance console.log('Current instance: jdb.doc.ys.name:', jdb.doc.ys.name); console.log('Current instance: jdb.doc.arr:', jdb.doc.arr); // Simulate restart by creating a new JDB instance and initializing from the same file const jdb2 = require('jdb')(); await jdb2.init({ dbPath: dbFilePath }); console.log('\n--- After simulated restart ---'); console.log('New instance: jdb2.doc.ys.name:', jdb2.doc.ys.name); console.log('New instance: jdb2.doc.arr:', jdb2.doc.arr); } catch (err) { console.error('An error occurred:', err); } finally { // Clean up the database file if (fs.existsSync(dbFilePath)) { fs.unlinkSync(dbFilePath); console.log('\nCleaned up database file:', dbFilePath); } } } runQuickstart();
Debug
Known issues
breakingJDB's core mechanism involves persisting database operations as executable JavaScript code, which is re-evaluated on startup. This design inherently means that if the database file (.jdb) is tampered with or contains untrusted code, arbitrary code execution can occur in the Node.js process. This poses a significant security risk for applications that might receive database files from untrusted sources or operate in environments where the file system is not secured.
fix
Only use JDB with database files from trusted sources and ensure strict file system permissions for database files. Avoid using JDB in multi-tenant environments where users can submit arbitrary JavaScript code for data manipulation without stringent validation.
affects: >=0.1.0
gotchaWhen defining the `command` function for `jdb.exec`, direct access to variables from the outer scope (closure) is not permitted. The command function is serialized and executed in its own isolated context, receiving only `jdbInstance` and `data` arguments.
fix
Pass any necessary external data into the `exec` call via the `data` option, and access it within the command function through the `data` argument: `jdb.exec({ data: myExternalData, command: (jdb, receivedData) => { jdb.doc.myKey = receivedData; jdb.save(); } });`
affects: >=0.1.0
gotchaFor databases with a very large number of operations (many `jdb.exec` calls), startup time can be significantly affected. JDB rebuilds its in-memory state by re-executing every JavaScript command ever appended to the database file. While compaction helps reduce file size, the entire command history still needs to be replayed.
fix
Regularly use `jdb.compactDBFile()` (or enable `compactDBFile: true` in `init` options) to reduce the number of commands that need to be replayed. Consider alternative database solutions if extremely fast startup for very large, highly mutable datasets is a critical requirement.
affects: >=0.1.0
Errors
Common errors & fixes
ReferenceError: [variable_name] is not defined at command (eval at <anonymous> (...))
Attempting to access an outer-scope variable directly within the `command` function passed to `jdb.exec`. The command function executes in an isolated scope.
fix
Pass the required data via the `data` property of the `exec` options object and access it as the second argument to your command function: `jdb.exec({ data: myValue, command: (db, receivedValue) => { db.doc.someKey = receivedValue; db.save(); } });`
TypeError: require(...) is not a function
The `jdb` package exports a factory function, not a direct database instance. It must be called to instantiate the database.
fix
Ensure you invoke the required module by adding `()` after the `require` call: `const jdb = require('jdb')();`
Upgrade
Version history
1.0latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
7 hits · last 30 days
node
6
Resources
githubhttps://github.com/ysmood/jdb ↗
packagehttps://www.npmjs.com/package/jdb ↗
jdb — npm install jdb · libregistry