MangoDB 🥭

A file-based MongoDB drop-in replacement for TypeScript/Node.js.

SQLite is to SQL as MangoDB is to MongoDB.

MangoDB stores your data as simple JSON files on disk while exposing the same API as the official MongoDB driver. Write your application once, develop locally without any database setup, then deploy to real MongoDB by changing a single environment variable.

Why MangoDB?

Working with MongoDB during development often means running local instances, configuring Docker containers, or connecting to cloud databases just to run your tests. MangoDB removes that friction entirely - your data lives in plain JSON files that you can inspect, version control, or simply delete between test runs.

The best part: when you're ready for production, your code doesn't change. Just point to a real MongoDB instance and everything works.

Installation

npm install @jkershaw/mangodb

Requires Node.js >= 22.0.0

Quick Start

import { MangoClient } from '@jkershaw/mangodb';

const client = new MangoClient('./data');
await client.connect();

const db = client.db('myapp');
const users = db.collection('users');

// Same API as MongoDB driver
await users.insertOne({ name: 'Alice', email: '[email protected]' });
const user = await users.findOne({ name: 'Alice' });

await client.close();

Switching to MongoDB

The API is identical. Only initialization differs:

import { MongoClient } from 'mongodb';
import { MangoClient } from '@jkershaw/mangodb';

// Environment-based switching
const client = process.env.MONGODB_URI
  ? new MongoClient(process.env.MONGODB_URI)
  : new MangoClient('./data');

await client.connect();
// ... rest of your code works unchanged

Documentation

| Document | Description | |----------|-------------| | Compatibility | What's supported, what's not | | Migration | Switching between MangoDB and MongoDB | | Testing | Test patterns and best practices | | Edge Cases | Behavioral quirks and gotchas | | Examples | Framework integration examples | | API Reference | Quick reference for all operations | | Troubleshooting | Common issues and solutions | | Initial Prompt | The original AI prompt that started this project |

Feature Coverage

| Category | Coverage | |----------|----------| | Query Operators | 31/32 (97%) | | Update Operators | 20/20 (100%) | | Aggregation Stages | 29/34 (85%) | | Expression Operators | 121/127 (95%) | | Index Types | 9/9 (100%) |

See COMPATIBILITY.md for details.

When to Use MangoDB

Ideal for:

• Local development without MongoDB setup
• Unit and integration testing
• CI/CD pipelines (no database service needed)
• Prototyping and learning
• Small datasets (< 10,000 documents)

Not recommended for:

• Production deployments
• Large datasets
• Multi-process access
• Applications requiring transactions

Running Tests

# Run against MangoDB
npm test

# Run against MongoDB (requires MongoDB instance)
MONGODB_URI=mongodb://localhost:27017 npm test

Both modes should pass for full compatibility.

License

MIT