@push.rocks/smartmongo

A module for creating and managing a local MongoDB instance for testing purposes.

readme.md for @push.rocks/smartmongo

A MongoDB memory server toolkit for testing and development โ€” spin up real MongoDB replica sets on the fly with zero configuration. ๐Ÿš€

Install

pnpm add -D @push.rocks/smartmongo
# or
npm install @push.rocks/smartmongo --save-dev

Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit community.foss.global/. This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a code.foss.global/ account to submit Pull Requests directly.

What It Does

@push.rocks/smartmongo wraps mongodb-memory-server to give you a real MongoDB replica set running entirely in memory. It downloads and manages the MongoDB binary for you โ€” just createAndStart() and you're good to go.

Perfect for:

๐Ÿ’ก Looking for a lightweight, pure-TypeScript alternative? Check out @push.rocks/smartdb โ€” a wire-protocol-compatible MongoDB server with zero binary dependencies, instant startup, and file-based persistence.

Quick Start

import { SmartMongo } from '@push.rocks/smartmongo';

// Start a MongoDB replica set (downloads binary automatically on first run)
const mongo = await SmartMongo.createAndStart();

// Get connection details for your app or ORM
const descriptor = await mongo.getMongoDescriptor();
console.log(descriptor.mongoDbUrl);
// => mongodb://127.0.0.1:xxxxx/?replicaSet=testset

// Use with any MongoDB client
import { MongoClient } from 'mongodb';
const client = new MongoClient(descriptor.mongoDbUrl);
await client.connect();

const db = client.db(descriptor.mongoDbName);
await db.collection('users').insertOne({ name: 'Alice', role: 'admin' });

const user = await db.collection('users').findOne({ name: 'Alice' });
console.log(user); // { _id: ObjectId(...), name: 'Alice', role: 'admin' }

// Clean up
await client.close();
await mongo.stop();

API

SmartMongo.createAndStart(replCount?: number)

Static factory method that creates and starts a SmartMongo instance.

// Single replica (default)
const mongo = await SmartMongo.createAndStart();

// Multi-replica for testing replication scenarios
const mongo = await SmartMongo.createAndStart(3);

getMongoDescriptor()

Returns an IMongoDescriptor with the connection URL and database name, compatible with @push.rocks/smartdata and other push.rocks modules.

const descriptor = await mongo.getMongoDescriptor();
// {
//   mongoDbName: 'smartmongo_testdatabase',
//   mongoDbUrl: 'mongodb://127.0.0.1:xxxxx/?replicaSet=testset'
// }

stop()

Stops the replica set and cleans up all resources (temporary files, processes).

await mongo.stop();

stopAndDumpToDir(dir, nameFunction?, emptyDir?)

Stops the replica set and dumps all collections to a directory on disk before cleanup. Useful for debugging or archiving test data.

// Dump all collections with default naming
await mongo.stopAndDumpToDir('./test-output');

// With custom file naming
await mongo.stopAndDumpToDir('./test-output', (doc) => `${doc.collection}-${doc._id}.bson`);

// Keep existing files in the directory (don't empty it first)
await mongo.stopAndDumpToDir('./test-output', undefined, false);

readyPromise

A promise that resolves when the replica set is fully started and ready to accept connections.

const mongo = new SmartMongo();
mongo.start(2); // non-blocking
await mongo.readyPromise; // wait for startup

Testing Examples

With @git.zone/tstest (tapbundle)

import { expect, tap } from '@git.zone/tstest/tapbundle';
import { SmartMongo } from '@push.rocks/smartmongo';
import { MongoClient } from 'mongodb';

let mongo: SmartMongo;
let client: MongoClient;

tap.test('setup', async () => {
  mongo = await SmartMongo.createAndStart();
  const { mongoDbUrl, mongoDbName } = await mongo.getMongoDescriptor();
  client = new MongoClient(mongoDbUrl);
  await client.connect();
});

tap.test('should insert and query documents', async () => {
  const col = client.db('test').collection('items');
  await col.insertOne({ name: 'Widget', price: 9.99 });

  const item = await col.findOne({ name: 'Widget' });
  expect(item?.price).toEqual(9.99);
});

tap.test('teardown', async () => {
  await client.close();
  await mongo.stop();
});

export default tap.start();

With @push.rocks/smartdata

import { SmartMongo } from '@push.rocks/smartmongo';
import { SmartdataDb } from '@push.rocks/smartdata';

const mongo = await SmartMongo.createAndStart();
const descriptor = await mongo.getMongoDescriptor();

const db = new SmartdataDb(descriptor);
await db.init();

// Use smartdata models against the memory server...

await db.close();
await mongo.stop();

This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the LICENSE file.

Please note: The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.

Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.

Company Information

Task Venture Capital GmbH Registered at District Court Bremen HRB 35230 HB, Germany

By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.

changelog.md for @push.rocks/smartmongo

2026-03-26 - 7.0.0 - BREAKING CHANGE(api)

reduce the package to the SmartMongo memory replica set API and remove bundled TsmDB and LocalTsmDb modules

2026-03-26 - 5.1.1 - fix(build)

migrate smartconfig metadata and refresh build dependencies

2026-02-03 - 5.1.0 - feat(localtsmdb)

export ILocalTsmDbConnectionInfo and expand LocalTsmDb/TsmDB documentation and examples

2026-02-03 - 5.0.0 - BREAKING CHANGE(localtsmdb)

add Unix socket support and change LocalTsmDb API to return connection info instead of a MongoClient

2026-02-03 - 4.3.0 - feat(docs)

add LocalTsmDb documentation and examples; update README code samples and imports; correct examples and variable names; update package author

2026-02-03 - 4.2.1 - fix(package.json)

replace main and typings with exports field pointing to ./dist_ts/index.js

2026-02-01 - 4.2.0 - feat(tsmdb)

implement TsmDB Mongo-wire-compatible server, add storage/engine modules and reorganize exports

2026-02-01 - 4.1.1 - fix(tsmdb)

add comprehensive unit tests for tsmdb components: checksum, query planner, index engine, session, and WAL

2026-02-01 - 4.1.0 - feat(readme)

expand README with storage integrity, WAL, query planner, session & transaction docs; update test script to enable verbose logging and increase timeout

2026-02-01 - 4.0.0 - BREAKING CHANGE(storage,engine,server)

add session & transaction management, index/query planner, WAL and checksum support; integrate index-accelerated queries and update storage API (findByIds) to enable index optimizations

2026-02-01 - 3.0.0 - BREAKING CHANGE(tsmdb)

rename CongoDB to TsmDB and relocate/rename wire-protocol server implementation and public exports

2026-01-31 - 2.2.0 - feat(readme)

update README with expanded documentation covering CongoDB and SmartMongo, installation, quick start examples, architecture, usage examples, and legal/company information

2026-01-31 - 2.1.0 - feat(congodb)

implement CongoDB MongoDB wire-protocol compatible in-memory server and APIs

2025-11-17 - 2.0.14 - fix(smartmongo.plugins)

Use default import for mongodb-memory-server (Deno compatibility), update hints and bump package version to 2.0.13

2025-04-06 - 2.0.12 - fix(ci/config)

Update CI workflow environment variables, refine package metadata, and improve configuration settings

2025-04-06 - 2.0.11 - fix(dependencies)

Update dependency names and versions in CI workflows and package configuration

2024-05-29 - 2.0.10 - misc

Various updates to project configuration and documentation.

2023-08-08 - 2.0.9 - core

Core fix.

2023-08-08 - 2.0.8 - core

Core fix.

2023-08-08 - 2.0.7 - core & org

Combined changes for core stability and organization improvements.

2022-06-08 - 2.0.6 - core

Core fix.

2022-06-08 - 2.0.5 - core

Core fix.

2022-06-06 - 2.0.4 - core

Core fix.

2022-06-06 - 2.0.3 - core

Core fix.

2022-06-03 - 2.0.2 - core

Core fix.

2022-05-19 - 2.0.1 - core

Core fix.

2022-05-18 - 2.0.0 - core

Core fix.

2022-05-17 - 1.0.9 - core

Breaking change for module format.

2022-05-17 - 1.0.8 - core

Core fix.

2021-12-21 - 1.0.7 - core

Core fix.

2021-12-20 - 1.0.6 - core

Core fix.

2021-12-20 - 1.0.5 - core

Core fix.

2021-12-20 - 1.0.4 - core

Core fix.

2021-12-20 - 1.0.3 - core

Core fix.

2021-12-20 - 1.0.2 - no notable changes

These version bumps did not include additional modifications.

2021-12-20 - 1.0.1 - core

Core fix.