{"id":16404,"library":"jsondbfs","title":"JSON Filesystem Database","description":"JSON FileSystem Database (jsondbfs) is a NoSQL document database, analogous to MongoDB, designed for Node.js environments. The latest version, 1.0.3, was released in 2017, and the project appears to be no longer actively maintained. It offers fully asynchronous data operations, leveraging the `async` library for parallel execution of accessing and filtering data. It supports two primary drivers: a high-performance 'Memory' driver, which can be configured to periodically flush data to disk for persistence, and a 'Disk' driver that stores all data directly on the filesystem and implements pessimistic transaction locking for data integrity. The package provides a lightweight, file-based database solution with Mongo-style query capabilities via `json-criteria`, but its lack of ongoing development means it may not be suitable for new projects or environments requiring up-to-date dependencies or security patches.","status":"abandoned","version":"1.0.3","language":"javascript","source_language":"en","source_url":"git://github.com/mcmartins/jsondbfs","tags":["javascript","json","jsonfs","jsondb","jsondbfs","db","database","nosql","memory"],"install":[{"cmd":"npm install jsondbfs","lang":"bash","label":"npm"},{"cmd":"yarn add jsondbfs","lang":"bash","label":"yarn"},{"cmd":"pnpm add jsondbfs","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Internal unique ID generation.","package":"node-uuid","optional":false},{"reason":"Object utility functions.","package":"underscore","optional":false},{"reason":"Asynchronous and parallel method execution strategies.","package":"async","optional":false},{"reason":"Pessimistic transaction locking for the 'disk' driver.","package":"lockfile","optional":false},{"reason":"Mongo-style criteria queries on JSON objects.","package":"json-criteria","optional":false}],"imports":[{"note":"The module exports an object containing the `connect` method. For ESM environments, dynamic import or a bundler's CJS interop is required.","wrong":"import jsondbfs from 'jsondbfs';","symbol":"jsondbfs","correct":"const jsondbfs = require('jsondbfs');"},{"note":"`connect` is a named property of the object exported by the `jsondbfs` module.","wrong":"import { connect } from 'jsondbfs';","symbol":"connect","correct":"const { connect } = require('jsondbfs');"},{"note":"The `Database` instance is asynchronously returned via the callback of the `connect` method; it's not a direct export from the module.","wrong":"const Database = require('jsondbfs').Database;","symbol":"Database Instance","correct":"jsondbfs.connect(['Users'], { driver: 'memory' }, (err, db) => { /* db is the Database instance */ });"}],"quickstart":{"code":"const jsondbfs = require('jsondbfs');\nlet database;\n\n// Connect to the database, specifying collections and configuration\njsondbfs.connect(['Users', 'Products'], { path: './data', driver: 'memory' }, function(err, db){\n  if (err) return console.error('Connection error:', err);\n  database = db;\n  console.log('Database connected. Current collections:', Object.keys(database));\n\n  // Insert a document into the 'Users' collection\n  database.Users.insert({ name: 'Alice', email: 'alice@example.com', roles: ['User'] }, function(err, document){\n    if (err) return console.error('Insert error:', err);\n    console.log('Inserted document:', document);\n\n    // Count documents in 'Users' collection\n    database.Users.count(function(err, count){\n      if (err) return console.error('Count error:', err);\n      console.log('Total users:', count);\n\n      // Update a document\n      database.Users.update({ name: 'Alice' }, { email: 'alice.updated@example.com' }, function(err, result){\n        if (err) return console.error('Update error:', err);\n        console.log('Update result:', result);\n\n        // Find all documents matching a criteria\n        database.Users.find({ email: 'alice.updated@example.com' }, function(err, documents){\n          if (err) return console.error('Find error:', err);\n          console.log('Found documents:', documents);\n\n          // Remove a document\n          database.Users.remove({ name: 'Alice' }, function(err, success){\n            if (err) return console.error('Remove error:', err);\n            console.log('Document removed:', success);\n\n            // Count again after removal\n            database.Users.count(function(err, finalCount){\n              if (err) return console.error('Final count error:', err);\n              console.log('Users after removal:', finalCount);\n            });\n          });\n        });\n      });\n    });\n  });\n});","lang":"javascript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=0.4.0"},{"fix":"Upgrade to version `0.4.3` or newer to ensure reliable data persistence with the 'memory' driver.","message":"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.","severity":"gotcha","affected_versions":"<0.4.3"},{"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.","message":"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.","severity":"gotcha","affected_versions":"*"},{"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.","message":"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.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"The `jsondbfs` module exports an object. Use its `connect` method directly: `const jsondbfs = require('jsondbfs'); jsondbfs.connect(...)`.","cause":"Attempting to instantiate the module export with `new` when it exports an object, not a class/constructor.","error":"TypeError: JSONDBFSDriver is not a constructor"},{"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.","cause":"The specified `path` for storing collections is not writable by the Node.js process.","error":"Error: EACCES: permission denied, open '/path/to/store/collections/Users.json'"},{"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.","cause":"Trying to access the `database` object or its collections outside the `connect` callback, before the asynchronous connection process has completed.","error":"ReferenceError: database is not defined"},{"fix":"Ensure all collections intended for use are included in the `collections` array passed to `jsondbfs.connect()`.","cause":"Attempting to access a collection that was not specified in the `collections` array during the `jsondbfs.connect()` call.","error":"Error: Collection 'NonExistentCollection' not found"}],"ecosystem":"npm"}