low-json-db

A lightweight, zero-dependency, file-based document database for Node.js. It gives you a familiar MongoDB-style API while storing everything as plain JSON files.

Perfect for: prototypes, small backends, CLI tools, Electron apps, local configuration stores, and learning how document databases work.

Why low-json-db?

Most projects don’t need a full database server. Sometimes you just want to store structured data in a simple, readable format without installing Redis, MongoDB, or SQLite.

low-json-db solves this by giving you a clean document-oriented API on top of the file system. Each collection becomes a single .json file. Indexes are stored in separate .idx.json files for fast lookups.

Key Features

MongoDB-style API

insert, find, update, delete, aggregation – the methods you already know.

Atomic Writes

Data is first written to a temporary file then renamed, protecting against crashes.

Indexes

Optional indexes stored in separate files for fast equality lookups.

Sync + Async

Every method has both a synchronous and an asynchronous version.

Transactions

Simple snapshot-based transactions with commit and rollback.

Zero Dependencies

Only uses Node.js built-in modules. No external packages required.

TypeScript Ready

Full type declarations included out of the box.

Events

Built on EventEmitter so you can listen to inserts, updates, saves, etc.

Quick Example

const { JSONDB } = require('low-json-db');

const db = new JSONDB('./data');

const users = db.collection({
  name: 'users',
  autoId: true,
  indexes: ['email']
});

// Insert a document
const user = users.insert({
  name: 'Alice',
  email: 'alice@example.com',
  age: 28
});

// Find by indexed field (very fast)
const found = users.findOne({ email: 'alice@example.com' });

// Update
users.updateOne(
  { name: 'Alice' },
  { $set: { age: 29 }, $push: { tags: 'admin' } }
);

// Async version
await users.insertAsync({
  name: 'Bob',
  email: 'bob@example.com'
});

How it stores data

When you create a collection called users, the library creates:

users.json – the actual documents
users.idx.json – the index file (only if you defined indexes)

Both files are written atomically. If the process crashes while writing, the original file remains intact.

When to use it

Good fit:

Prototypes and MVPs
CLI tools and local scripts
Electron / desktop applications
Small backends with low concurrency
Configuration and cache storage
Learning document database concepts

Not recommended for:

High-concurrency production servers
Very large datasets (hundreds of thousands of documents)
Multi-process writes without external locking

Next step: Go to the Installation page or jump straight to the Quick Start guide.

License & Contributing

low-json-db is released under the MIT License. Contributions are welcome — feel free to open issues or pull requests.