low-json-db

A lightweight, zero-dependency JSON document database for Node.js.

low-json-db provides a simple embedded document database using JSON files as persistent storage, with querying, indexing, transactions, aggregation, asynchronous operations, backups, and more.

🔗 Project Links

| Resource | Link | | ------------------------ | ------------------------------------------------------------------ | | 📦 npm Package | https://www.npmjs.com/package/low-json-db | | 💻 GitHub Repository | https://github.com/amk2406/low-json-db | | 📖 Documentation | https://amk2406.github.io/low-json-db/ | | 🐛 Issue Tracker | https://github.com/amk2406/low-json-db/issues | | 💬 Discussions | https://github.com/amk2406/low-json-db/discussions | | 📋 Changelog | https://github.com/amk2406/low-json-db/blob/main/CHANGELOG.md | | 🔐 Security Policy | https://github.com/amk2406/low-json-db/security/policy | | 🤝 Contributing | https://github.com/amk2406/low-json-db/blob/main/CONTRIBUTING.md | | 📜 License | https://github.com/amk2406/low-json-db/blob/main/LICENSE |

Replace any link above if your repository or documentation uses a different URL.

📖 Documentation

🌐 Official Documentation

Full documentation: https://amk2406.github.io/low-json-db/

The documentation website should contain the complete API reference and detailed guides.

Recommended documentation structure:

Documentation
│
├── Introduction
├── Installation
├── Getting Started
│
├── Core Concepts
│   ├── Database
│   ├── Collections
│   ├── Documents
│   └── Persistence
│
├── CRUD
│   ├── Insert
│   ├── Find
│   ├── Update
│   └── Delete
│
├── Queries
│   ├── Query Operators
│   ├── Logical Operators
│   ├── Query Builder
│   ├── Projection
│   ├── Sorting
│   └── Pagination
│
├── Indexes
├── Transactions
├── Aggregation
├── Async API
├── Import & Export
├── Backups
├── Events
│
├── Advanced Usage
├── Performance
├── Security
├── Troubleshooting
│
└── API Reference

📦 Installation

npm install low-json-db

Quick Start

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

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

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

users.insert({
  name: 'Alice',
  email: '[email protected]',
  age: 25
});

const user = users.findOne({
  email: '[email protected]'
});

console.log(user);

🧭 Learn More

| Topic | Documentation | | --------------- | ---------------------- | | Getting Started | /getting-started | | Database API | /api/jsondb | | Collection API | /api/collection | | Queries | /guide/queries | | Query Operators | /guide/operators | | Query Builder | /guide/query-builder | | Indexes | /guide/indexes | | Transactions | /guide/transactions | | Aggregation | /guide/aggregation | | Async API | /guide/async | | Backups | /guide/backups | | Events | /guide/events | | Configuration | /guide/configuration | | API Reference | /api |

🤝 Contributing

Contributions are welcome!

Before submitting a pull request, please read:

CONTRIBUTING.md

Typical workflow:

git clone https://github.com/amk2406/low-json-db.git

cd low-json-db

npm install

npm test

Create a feature branch:

git checkout -b feature/my-feature

Make your changes, test them, then submit a pull request.

Good contributions include

• 🐛 Bug fixes
• ✨ New features
• ⚡ Performance improvements
• 📖 Documentation improvements
• 🧪 Tests
• 🔧 Internal improvements
• 💡 Examples and tutorials

🐛 Bug Reports

Found a bug?

Please use the GitHub Issues page:

https://github.com/amk2406/low-json-db/issues

Include:

• low-json-db version
• Node.js version
• Operating system
• Reproduction code
• Expected behavior
• Actual behavior
• Error message/stack trace

Please remove passwords, tokens, API keys, and private database contents before posting.

💡 Feature Requests

Have an idea?

Open a feature request through GitHub Discussions or Issues.

A useful feature request should explain:

1. What problem it solves
2. Why it would be useful
3. Proposed API
4. Example usage
5. Potential compatibility concerns

🔐 Security

If you discover a security vulnerability, do not publicly post sensitive exploit details in an issue.

Use the project's security reporting mechanism instead:

https://github.com/amk2406/low-json-db/security/policy

Security reports should include enough information to reproduce and investigate the issue without exposing unnecessary sensitive information.

🗺️ Roadmap

Planned improvements may include:

• [ ] More query operators
• [ ] Compound indexes
• [ ] Unique indexes
• [ ] Schema validation
• [ ] More aggregation operators
• [ ] Improved transaction isolation
• [ ] Database integrity checks
• [ ] Crash recovery improvements
• [ ] Streaming import/export
• [ ] Compression
• [ ] Optional encryption
• [ ] Performance benchmarks
• [ ] Expanded TypeScript support
• [ ] Dedicated documentation website
• [ ] More automated tests

Roadmap items are subject to change.

📋 Changelog

Release history is maintained in:

CHANGELOG.md

For the latest published version, see the npm package page.

📦 Versioning

low-json-db follows semantic versioning where applicable:

MAJOR.MINOR.PATCH

For example:

1.1.3

• MAJOR — breaking API changes
• MINOR — backwards-compatible features
• PATCH — backwards-compatible fixes

🧪 Development

Clone the repository:

git clone https://github.com/amk2406/low-json-db.git
cd low-json-db

Install dependencies:

npm install

Run tests:

npm test

Run your local examples:

node examples/basic.js

🏷️ npm Publishing

For maintainers:

npm login

Check the logged-in account:

npm whoami

Check the package:

npm pkg get name version

Publish:

npm publish

npm may require two-factor authentication or an appropriately configured publishing token.

📄 License

low-json-db is released under the MIT License.

See LICENSE for the complete license text.

👤 Author

Created and maintained by amk2406.

GitHub:

https://github.com/amk2406

⭐ Support the Project

If low-json-db is useful to you:

⭐ Star the repository 🐛 Report bugs 💡 Suggest features 🤝 Contribute code 📖 Improve documentation 📢 Share the project

📚 Related Documentation

• API Reference — complete class and method documentation
• Guides — practical examples and common patterns
• Examples — ready-to-run projects
• Migration Guide — upgrading between versions
• FAQ — frequently asked questions
• Troubleshooting — common problems and solutions

🧩 Example Projects

Recommended examples:

examples/
├── basic/
├── crud/
├── queries/
├── indexes/
├── transactions/
├── aggregation/
├── async/
├── backup/
└── desktop-app/

These examples can also be published on the documentation website.

🌐 Ecosystem

low-json-db is designed to work naturally with the Node.js ecosystem.

┌──────────────────────┐
│      Your App        │
├──────────────────────┤
│    low-json-db       │
├──────────────────────┤
│      Node.js         │
├──────────────────────┤
│    File System       │
├──────────────────────┤
│       JSON           │
└──────────────────────┘

It does not require a separate database server.

❓ FAQ

Does low-json-db require MongoDB?

No.

low-json-db is completely independent of MongoDB and stores its data locally as JSON files.

Does it require external dependencies?

The core package is designed to have zero runtime dependencies.

Can I use it in a desktop application?

Yes. It can be used as the local persistence layer of a Node.js-based desktop application.

Can multiple applications share the same database?

Concurrent access from multiple independent processes should be treated carefully. low-json-db is primarily designed as an embedded, in-process database.

Are the database files human-readable?

Yes. Collection data is stored as JSON.

Can I make backups?

Yes.

await db.backupAsync('./backups');

❤️ Why low-json-db?

Sometimes you don't need a database server.

You just need:

A Node.js application
        ↓
A simple API
        ↓
Persistent data
        ↓
Local JSON files

That's where low-json-db fits.

🔗 Quick Links

📖 Documentation · 📦 npm · 💻 GitHub · 🐛 Issues · 🤝 Contributing · 📜 License

low-json-db — Simple. Local. Lightweight.