simple-json-db

library2.0.0jsnpmunverified

A minimal, no-frills JSON key-value storage engine for Node.js, version 2.0.0. It provides synchronous and asynchronous writes, optional sync-on-write, and customizable JSON serialization. Unlike full-fledged databases, Simple JSONdb stores the entire data in a single JSON file, making it ideal for small projects, prototypes, or configurations. Supports Node >=10.0, ships TypeScript definitions, and has 100% test coverage. Releases are infrequent, with v2 being the current stable.

database storage

npm install simple-json-db

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SIMPLE-JSON-DB

simple-json-db

databasejavascriptv2.0.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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

JSONdb

✓ import JSONdb from 'simple-json-db'

✗ const JSONdb = require('simple-json-db')

Package is ESM-only since v2, use import statement. Default export.

JSONdb (CommonJS)

✓ const JSONdb = require('simple-json-db').default

✗ const JSONdb = require('simple-json-db')

If using CommonJS, you must use .default because it's an ESM default export.

JSONdb type

✓ import type JSONdb from 'simple-json-db'

✗ import { JSONdb } from 'simple-json-db'

Type import uses default, not named export. For TypeScript only.

Basic CRUD operations: set, get, has, delete, JSON access, and sync.

import JSONdb from 'simple-json-db'; // Create a new database (or open existing) const db = new JSONdb('./data.json', { asyncWrite: true, syncOnWrite: true, jsonSpaces: 2 }); // Set values db.set('user', { name: 'Alice', age: 30 }); db.set('config', { theme: 'dark' }); // Get a value const user = db.get('user'); console.log(user); // { name: 'Alice', age: 30 } // Check existence console.log(db.has('config')); // true // Delete a key db.delete('config'); console.log(db.has('config')); // false // Access entire JSON stored (copy) const allData = db.JSON(); console.log(allData); // { user: { name: 'Alice', age: 30 } } // Replace entire stored object (careful, overwrites) db.JSON({ newKey: 'newData' }); // Manually sync to disk if asyncWrite is true await db.sync();

Debug

Known issues

breakingv2 is ESM-only. CommonJS require() without .default will not work.

fix

Use import JSONdb from 'simple-json-db' or CommonJS require('simple-json-db').default.

affects: >=2.0.0

breakingv2 changed constructor signature; options object is second parameter, no longer accepts string for path as first argument? (Check docs)

fix

Use new JSONdb(path, options) as documented.

affects: >=2.0.0

deprecateddb.JSON() as getter returns a copy; modifying it does not affect stored data. This can be a footgun.

fix

Use db.JSON(newObject) to replace the entire store, or db.set(key, value) for individual keys.

affects: *

gotchaKeys must be strings; non-string keys will be coerced to strings.

fix

Always use string keys.

affects: *

gotchaasyncWrite: true does not automatically sync after every set; you must call sync() manually or set syncOnWrite: true.

fix

Set syncOnWrite: true in options to auto-sync after each modification.

affects: *

gotchadb.JSON({...}) overwrites the entire storage object; previous data is lost unless you merged it manually.

fix

Always read current data first (get JSON), merge, then write back.

affects: *

Errors

Common errors & fixes

TypeError: JSONdb is not a constructor

Using require('simple-json-db') in CommonJS without .default

fix

Use const JSONdb = require('simple-json-db').default

SyntaxError: Unexpected identifier 'JSONdb'

Using const JSONdb = require('simple-json-db') in ESM context

fix

Use import JSONdb from 'simple-json-db'

ENOENT: no such file or directory, open '...'

The specified file path does not exist. Package does not auto-create directories.

fix

Ensure the directory exists before creating the db instance.

TypeError: db.JSON is not a function

Calling db.JSON() without parentheses in some contexts? (e.g., db.JSON) or using wrong import

fix

Use db.JSON() with parentheses. Ensure you imported JSONdb correctly.

Upgrade

Version history

2.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

34 hits · last 30 days

node