@push.rocks/smartmongo

A disposable MongoDB-wire-compatible database for tests and local development, backed by SmartDB memory storage.

Install

pnpm add -D @push.rocks/smartmongo mongodb

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 starts an @push.rocks/smartdb server with memory storage and returns a descriptor accepted by @push.rocks/smartdata and the official MongoDB driver. It downloads no MongoDB binary and leaves no database files behind.

SmartMongo is intended for:

• integration tests using SmartDB's documented MongoDB wire-protocol surface
• CI pipelines that need an isolated disposable database
• local development with instant, in-memory state
• per-document JSON dumps for debugging failed tests

SmartMongo is single-node and does not provide MongoDB replication or complete MongoDB API parity. Published SmartDB binaries currently target Linux.

Quick Start

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

// Start a single memory-backed SmartDB node.
const mongo = await SmartMongo.createAndStart();

// Get connection details for your app or ORM
const descriptor = await mongo.getMongoDescriptor();
// Use with any MongoDB client
import { MongoClient } from 'mongodb';
const client = new MongoClient(descriptor.mongoDbUrl, { directConnection: true });
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(replicaCount?: number)

Creates and starts a SmartMongo instance. replicaCount defaults to 1; any other value is rejected because SmartDB is single-node.

const mongo = await SmartMongo.createAndStart();

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:<os-assigned-port>'
// }

smartdbServer

The readonly underlying SmartdbServer is available for deliberate low-level lifecycle and management tests.

await mongo.smartdbServer.stop();
await mongo.smartdbServer.start();

Direct lifecycle calls bypass SmartMongo's wrapper state. Prefer SmartMongo.start() and SmartMongo.stop() unless the test specifically needs to interrupt and restart the backend. An OS-assigned TCP port is resolved on each start, so the connection URI may change after a low-level restart.

stop()

Stops SmartDB and confirms Rust bridge termination. Repeated calls are safe.

await mongo.stop();

stopAndDumpToDir(dir, nameFunction?, emptyDir?)

Dumps all collections before stopping. The output contains one directory per collection and one .json file per document.

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

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

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

readyPromise

A promise for the active SmartMongo startup. Access before start() or after stop() rejects immediately, and startup failures reject the same promise returned by start().

const mongo = new SmartMongo();
void mongo.start();
await mongo.readyPromise;

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, { directConnection: true });
  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

Install @push.rocks/smartdata separately when using this integration.

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-backed SmartDB server...

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

License and Legal Information

This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the repository 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

For any legal inquiries or further information, please contact us via email at hello@task.vc.

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.