node-json-db is a lightweight, file-based database for Node.js, storing data directly in a JSON file. It is currently at stable version 2.6.0 and maintains an active release cadence, with several minor and patch releases occurring monthly or bi-monthly in the past year. Its primary differentiator is the use of a "DataPath" system, akin to XMLPath, for navigating and accessing nested data structures within the JSON file. All operations are asynchronous, leveraging `async/await`. It supports configurable database names, auto-save on push, human-readable file formats, custom separators, and since v2.6.0, serialization of complex JavaScript types like `Set`, `Map`, `Date`, `RegExp`, and `BigInt` via an `ISerializer` contract. This makes it suitable for simple, local data persistence where a full-fledged database system is overkill.
npm install node-json-dbVerified import paths — ran on the pinned version, not inferred.
Demonstrates initializing the database, pushing data (including merging objects), retrieving data, and handling errors for non-existent paths. Requires Node.js ESM support.
Always use `await` with `JsonDB` methods (e.g., `await db.push(...)`, `await db.getData(...)`), or handle promises explicitly with `.then()/.catch()`. Ensure your code is within an `async` function or a top-level `await` context.
Instantiate `JsonDB` with `new JsonDB(new Config('filename', autoSave, humanReadable, separator, syncWrites))`.To merge objects or arrays instead of overwriting, use `await db.push('/path', newData, false);`.Be aware that primitives cannot be merged; they are always replaced. Plan your data structures accordingly if deep merging is critical.
Wrap `getData` calls in `try-catch` blocks to gracefully handle missing data. Alternatively, use `db.getObjectDefault('/path', defaultValue)` (available since v2.2.0) if a default value is acceptable.Upgrade to `node-json-db@2.4.2` or higher to restore correct class exports and resolve import issues.
Check if the path exists before calling `getData()`, or wrap the call in a `try-catch` block. For convenience, use `db.getObjectDefault('/path', defaultValue)` (available since v2.2.0) to get a value or a fallback.Ensure your project is configured for ESM (`"type": "module"` in `package.json` or `.mjs` file extension) and use `import { JsonDB, Config } from 'node-json-db';`.Ensure all calls to `db.push()`, `db.getData()`, etc., are made from within an `async` function. For example, wrap your main logic in `async function main() { ... }` and call `main().catch(console.error);`.Always initialize `Config` with `new Config(...)` when passing it to `JsonDB`, for example: `new JsonDB(new Config('filename', true, false, '/'))`.No dependency data recorded yet.