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