MongoLite

A MongoDB-like client backed by SQLite. Use a familiar MongoDB API with the simplicity of a local file-based database — no server required.

Why MongoLite?

• You want a MongoDB-style API without running a MongoDB server
• You need a lightweight, embedded database for local apps, CLIs, or testing
• You want simple file-based persistence with zero infrastructure overhead

Features

• MongoDB-compatible API — insertOne, findOne, updateOne, deleteOne, find, aggregate, and more
• SQLite persistence — single file, zero configuration, works offline
• Automatic _id generation — UUID assigned on insert if not provided
• WAL mode — Write-Ahead Logging for better concurrent read access
• Rich query operators — $eq, $gt, $in, $and, $or, $elemMatch, $regex, and more
• Update operators — $set, $inc, $push, $pull, $addToSet, $mul, and more
• Indexing — create, list, and drop indexes including unique and compound indexes
• Change streams — real-time change tracking via collection.watch()
• JSON safety — validates documents before insert and recovers from corrupted data
• TypeScript — fully typed with strict mode

Installation

npm install mongolite-ts

Quick Start

import { MongoLite } from 'mongolite-ts';

async function main() {
  const client = new MongoLite('./myapp.sqlite');
  // Use ':memory:' for an ephemeral in-memory database

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

  // Insert
  const result = await users.insertOne({ name: 'Alice', age: 30 });

  // Find
  const user = await users.findOne({ name: 'Alice' });

  // Update
  await users.updateOne({ name: 'Alice' }, { $set: { age: 31 } });

  // Delete
  await users.deleteOne({ name: 'Alice' });

  await client.close();
}

main();

Documentation

| Topic | Description | |-------|-------------| | API Reference | Full API docs: methods, query operators, update operators | | Change Streams | Real-time change tracking with collection.watch() | | JSON Safety | Document validation and corrupted data recovery | | Query Debugger | Interactive CLI for debugging queries and inspecting SQL | | Benchmarks | Performance benchmarks and storage characteristics | | Cloudflare Durable Objects | Using MongoLite inside a Cloudflare Durable Object |

Backend Examples

SQLite file (Node.js / Bun)

import { MongoLite } from 'mongolite-ts';

const client = new MongoLite('./myapp.sqlite');
await client.connect();
const users = client.collection('users');
await users.insertOne({ name: 'Alice', age: 30 });
await client.close();

In-memory (tests / ephemeral)

import { MongoLite } from 'mongolite-ts';

const client = new MongoLite(':memory:');
await client.connect();
const users = client.collection('users');
await users.insertOne({ name: 'Alice', age: 30 });
// Data is discarded when the process exits
await client.close();

Browser (via sql.js)

Requires sql.js (npm install sql.js).

import initSqlJs from 'sql.js';
import { MongoLite, BrowserSqliteAdapter } from 'mongolite-ts';

const SQL = await initSqlJs({
  locateFile: (file) => `https://cdn.jsdelivr.net/npm/sql.js/dist/${file}`,
});
const sqlJsDb = new SQL.Database(); // in-memory; use OPFS/IndexedDB for persistence

const client = new MongoLite(new BrowserSqliteAdapter(sqlJsDb));
await client.connect();
const users = client.collection('users');
await users.insertOne({ name: 'Alice', age: 30 });
console.log(await users.findOne({ name: 'Alice' }));
await client.close();

Cloudflare Durable Objects

import { DurableObject } from 'cloudflare:workers';
import { MongoLite, CloudflareDurableObjectAdapter } from 'mongolite-ts/cloudflare';

export class MyDurableObject extends DurableObject {
  private client: MongoLite;

  constructor(ctx: DurableObjectState, env: Env) {
    super(ctx, env);
    // Pass ctx.storage.sql — no file path needed
    this.client = new MongoLite(new CloudflareDurableObjectAdapter(ctx.storage.sql));
    ctx.blockConcurrencyWhile(() => this.client.collection('users').ensureTable());
  }

  async fetch(request: Request) {
    const users = this.client.collection('users');
    await users.insertOne({ name: 'Alice', age: 30 });
    return Response.json(await users.findOne({ name: 'Alice' }));
  }
}

See docs/CLOUDFLARE.md for the full guide, supported operations, and limitations.

Development

git clone https://github.com/semics-tech/mongolite.git
cd mongolite
npm install
npm test          # Run tests
npm run build     # Compile TypeScript
npm run lint      # Lint code

Contributing

Contributions are welcome! Please read CONTRIBUTING.md before submitting a pull request.

License

MIT