file-json-db
A resilient, zero-dependency, MongoDB-style JSON document database for Node.js.
- Search API –
collection.search({ keyword, fields, exclude, caseInsensitive }) - Improved project – proper inclusion / exclusion / mixed (exclusion wins),
_idkept by default - keepIdIndex option (default
false) for lower memory with auto IDs - Better TypeScript definitions with full JSDoc
file-json-db lets you store structured documents on the local filesystem while giving you a familiar document-database API. There is no separate database server to install, no external dependencies to manage, and the data remains human-readable JSON files.
What problem does it solve?
Most applications eventually need persistent structured data. Reaching for MongoDB, PostgreSQL,
or even SQLite is often overkill for small projects, scripts, or desktop applications.
At the same time, hand-rolling fs.readFile / JSON.parse becomes
painful the moment you need queries, indexes, concurrent writes, or recovery from partial writes.
file-json-db sits in the sweet spot: it gives you a real document API
(insert, find, update, delete, aggregation, transactions) while storing everything as plain
JSON files on disk. Collections are directories. Large collections are automatically split
into multiple part-XXXX.json files so a single file never grows unboundedly.
Core ideas
- A database is a directory on the filesystem.
- A collection is a subdirectory inside that database.
- Collection data is stored in one or more
part-XXXX.jsonfiles. - An in-memory index (
index.json) tracks which part contains which document and maintains secondary indexes. - Every write is atomic: data is written to a temporary file, then renamed into place.
- Asynchronous operations are serialized through a per-collection lock/queue.
- Corrupted part files can be recovered without crashing the process.
Key features at a glance
| Feature | Description |
|---|---|
| Zero dependencies | Only Node.js built-in modules (fs, path, crypto, events) |
| MongoDB-style API | insert, find, updateOne, $set, $push, aggregation, etc. |
| Chunked storage | Large collections automatically split across multiple part files |
| Secondary indexes | Fast equality lookups on configured fields |
| Atomic writes | Temp-file + rename with retry logic |
| Snapshot transactions | Commit / rollback without touching disk until commit |
| Sync + Async | Every major operation has both variants |
| Self-healing | Corrupted parts are isolated; the rest of the collection keeps working |
| TypeScript ready | Full .d.ts declarations included |
What it is not
It is also not designed for datasets of millions of documents or for high-concurrency production web servers. For those cases you should use a proper database engine.
Quick example
const { JSONDB } = require('file-json-db');
const db = new JSONDB('./data');
const users = db.collection({
name: 'users',
autoId: true,
indexes: ['email']
});
// Insert
const user = users.insert({
name: 'Ada Lovelace',
email: 'ada@analytical.engine',
role: 'admin'
});
// Find by indexed field (very fast)
const found = users.findOne({ email: 'ada@analytical.engine' });
// Update
users.updateOne(
{ email: 'ada@analytical.engine' },
{ $set: { lastLogin: new Date().toISOString() }, $push: { tags: 'verified' } }
);
// Query with operators
const admins = users.find({ role: 'admin', age: { $gte: 18 } }).toArray();