JDB File-Append-Only Database

Common errors

• ReferenceError: [variable_name] is not defined at command (eval at <anonymous> (...))

  cause 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

  cause 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')();`

Warnings

• breaking JDB'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.
• gotcha When 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(); } });`
• gotcha For 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.

Install

• npm install jdb npm
• yarn add jdb yarn
• pnpm add jdb pnpm

Imports

• jdb
  wrong:

  import jdb from 'jdb';
  const jdb = require('jdb');

  correct:

  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
  wrong:

  jdb.init((err) => { /* ... */ });

  correct:

  await jdb.init();

  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
  wrong:

  jdb.exec((db) => { db.doc.myKey = outerScopeVar; });

  correct:

  await jdb.exec({ data: someData, command: (db, data) => db.doc.myKey = data });

  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.

Quickstart

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();