JSON Filesystem Database

Common errors

• TypeError: JSONDBFSDriver is not a constructor

  cause Attempting to instantiate the module export with `new` when it exports an object, not a class/constructor.
  fix The `jsondbfs` module exports an object. Use its `connect` method directly: `const jsondbfs = require('jsondbfs'); jsondbfs.connect(...)`.

• Error: EACCES: permission denied, open '/path/to/store/collections/Users.json'

  cause The specified `path` for storing collections is not writable by the Node.js process.
  fix Ensure the directory specified in the `path` option for `jsondbfs.connect()` exists and has appropriate write permissions for the user running the Node.js application.

• ReferenceError: database is not defined

  cause Trying to access the `database` object or its collections outside the `connect` callback, before the asynchronous connection process has completed.
  fix All operations on the `database` object must be performed inside the `connect` callback or in code executed only after the `connect` callback has successfully resolved and assigned the `db` instance.

• Error: Collection 'NonExistentCollection' not found

  cause Attempting to access a collection that was not specified in the `collections` array during the `jsondbfs.connect()` call.
  fix Ensure all collections intended for use are included in the `collections` array passed to `jsondbfs.connect()`.

Warnings

• breaking Version 0.4.0 introduced a significant API overhaul, changing how database connections are established and how collections are accessed and manipulated. Code written for versions prior to 0.4.0 will not be compatible with newer versions.
  Fix: Refer to the `0.4.0` release notes or the latest README for the updated API usage, particularly the `connect` method and collection interaction.
• gotcha Prior to version 0.4.3, the 'memory' driver had a critical bug where data flushes to disk could fail, potentially leading to data loss upon application restart or unexpected termination, even when configured for persistence.
  Fix: Upgrade to version `0.4.3` or newer to ensure reliable data persistence with the 'memory' driver.
• gotcha The 'disk' driver implements pessimistic transaction locking, which can lead to performance bottlenecks or deadlocks under high concurrency if not properly managed. This is by design to ensure data integrity, but users should be aware of its implications.
  Fix: For high-concurrency write operations, consider the 'memory' driver with configured persistence, or carefully manage concurrent access patterns when using the 'disk' driver. Implement robust error handling for lock acquisition failures.
• gotcha All `jsondbfs` methods are callback-based, adhering to the Node.js error-first callback pattern. There is no native support for Promises or async/await syntax, requiring manual promisification or wrapper libraries for modern asynchronous codeflows.
  Fix: Wrap `jsondbfs` methods with `util.promisify` (Node.js built-in) or a custom Promise wrapper if using async/await syntax is desired. Ensure error handling is consistently applied in callbacks.

Install

• npm install jsondbfs npm
• yarn add jsondbfs yarn
• pnpm add jsondbfs pnpm

Imports

• jsondbfs
  wrong:

  import jsondbfs from 'jsondbfs';

  correct:

  const jsondbfs = require('jsondbfs');

  The module exports an object containing the `connect` method. For ESM environments, dynamic import or a bundler's CJS interop is required.
• connect
  wrong:

  import { connect } from 'jsondbfs';

  correct:

  const { connect } = require('jsondbfs');

  `connect` is a named property of the object exported by the `jsondbfs` module.
• Database Instance
  wrong:

  const Database = require('jsondbfs').Database;

  correct:

  jsondbfs.connect(['Users'], { driver: 'memory' }, (err, db) => { /* db is the Database instance */ });

  The `Database` instance is asynchronously returned via the callback of the `connect` method; it's not a direct export from the module.

Quickstart

This quickstart demonstrates how to connect to a JSON DB FS instance, create/access collections, and perform common CRUD operations (insert, count, update, find, remove) using the asynchronous callback API.

const jsondbfs = require('jsondbfs');
let database;

// Connect to the database, specifying collections and configuration
jsondbfs.connect(['Users', 'Products'], { path: './data', driver: 'memory' }, function(err, db){
  if (err) return console.error('Connection error:', err);
  database = db;
  console.log('Database connected. Current collections:', Object.keys(database));

  // Insert a document into the 'Users' collection
  database.Users.insert({ name: 'Alice', email: 'alice@example.com', roles: ['User'] }, function(err, document){
    if (err) return console.error('Insert error:', err);
    console.log('Inserted document:', document);

    // Count documents in 'Users' collection
    database.Users.count(function(err, count){
      if (err) return console.error('Count error:', err);
      console.log('Total users:', count);

      // Update a document
      database.Users.update({ name: 'Alice' }, { email: 'alice.updated@example.com' }, function(err, result){
        if (err) return console.error('Update error:', err);
        console.log('Update result:', result);

        // Find all documents matching a criteria
        database.Users.find({ email: 'alice.updated@example.com' }, function(err, documents){
          if (err) return console.error('Find error:', err);
          console.log('Found documents:', documents);

          // Remove a document
          database.Users.remove({ name: 'Alice' }, function(err, success){
            if (err) return console.error('Remove error:', err);
            console.log('Document removed:', success);

            // Count again after removal
            database.Users.count(function(err, finalCount){
              if (err) return console.error('Final count error:', err);
              console.log('Users after removal:', finalCount);
            });
          });
        });
      });
    });
  });
});