push.rocks/smartmongo
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(docs): add LocalTsmDb documentation and examples; update README code samples and imports; correct examples and variable names; update package author

Browse Source
This commit is contained in:
Jürgen Kunz
2026-02-03 08:14:58 +00:00
parent 1fff277698
commit 6a37a773ea
4 changed files with 170 additions and 65 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
changelog.md
View File

@@ -1,5 +1,14 @@
# Changelog # Changelog
## 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
- Introduce LocalTsmDb: zero-config local database with automatic persistence, auto port discovery, and pre-connected client (added Quick Start, API, Features, and testing examples).
- Expand comparison table to include LocalTsmDb alongside SmartMongo and TsmDB.
- Update README examples: new LocalTsmDb usage, reorder options (LocalTsmDb, TsmDB, SmartMongo), rename test DB variable (db -> testDb), and adjust test snippets for Jest/Mocha and tap.
- Adjust code snippets and API notes: switch some example imports to use tsmdb, replace FileStorageAdapter references, change planner.createPlan to await planner.plan, and use wal.getEntriesAfter(...) without awaiting.
- Update package.json author from 'Lossless GmbH' to 'Task Venture Capital GmbH'.
## 2026-02-03 - 4.2.1 - fix(package.json) ## 2026-02-03 - 4.2.1 - fix(package.json)
replace main and typings with exports field pointing to ./dist_ts/index.js replace main and typings with exports field pointing to ./dist_ts/index.js

2
package.json
View File

@@ -7,7 +7,7 @@
".": "./dist_ts/index.js" ".": "./dist_ts/index.js"
}, },
"type": "module", "type": "module",
"author": "Lossless GmbH", "author": "Task Venture Capital GmbH",
"license": "MIT", "license": "MIT",
"scripts": { "scripts": {
"test": "(tstest test/. --verbose --logfile --timeout 60)", "test": "(tstest test/. --verbose --logfile --timeout 60)",

222
readme.md
View File

@@ -1,6 +1,6 @@
# @push.rocks/smartmongo # @push.rocks/smartmongo
A powerful MongoDB toolkit for testing and development — featuring both a real MongoDB memory server (**SmartMongo**) and an ultra-fast, lightweight wire-protocol-compatible in-memory database server (**TsmDB**). 🚀 A powerful MongoDB toolkit for testing and development — featuring a real MongoDB memory server (**SmartMongo**), an ultra-fast wire-protocol-compatible in-memory database server (**TsmDB**), and a zero-config local database (**LocalTsmDb**). 🚀
## Install ## Install
@@ -16,21 +16,79 @@ For reporting bugs, issues, or security vulnerabilities, please visit [community
## Overview ## Overview
`@push.rocks/smartmongo` provides two powerful approaches for MongoDB in testing and development: `@push.rocks/smartmongo` provides three powerful approaches for MongoDB in testing and development:
| Feature | SmartMongo | TsmDB | | Feature | SmartMongo | TsmDB | LocalTsmDb |
|---------|------------|---------| |---------|------------|-------|------------|
| **Type** | Real MongoDB (memory server) | Pure TypeScript wire protocol server | | **Type** | Real MongoDB (memory server) | Wire protocol server | Zero-config local DB |
| **Speed** | ~2-5s startup | ⚡ Instant startup (~5ms) | | **Speed** | ~2-5s startup | ⚡ Instant (~5ms) | ⚡ Instant + auto-connect |
| **Compatibility** | 100% MongoDB | MongoDB driver compatible | | **Compatibility** | 100% MongoDB | MongoDB driver compatible | MongoDB driver compatible |
| **Dependencies** | Downloads MongoDB binary | Zero external dependencies | | **Dependencies** | Downloads MongoDB binary | Zero external deps | Zero external deps |
| **Replication** | ✅ Full replica set support | Single node emulation | | **Replication** | ✅ Full replica set | Single node | Single node |
| **Use Case** | Integration testing | Unit testing, CI/CD | | **Persistence** | Dump to directory | Memory or file | File-based (automatic) |
| **Persistence** | Dump to directory | Optional file/memory persistence | | **Use Case** | Integration testing | Unit testing, CI/CD | Quick prototyping, local dev |
## 🚀 Quick Start ## 🚀 Quick Start
### Option 1: SmartMongo (Real MongoDB) ### Option 1: LocalTsmDb (Zero-Config Local Database) ⭐ NEW
The easiest way to get started — just point it at a folder and you have a persistent MongoDB-compatible database with automatic port discovery!
```typescript
import { LocalTsmDb } from '@push.rocks/smartmongo';
// Create a local database backed by files
const db = new LocalTsmDb({ folderPath: './my-data' });
// Start and get a connected MongoDB client
const client = await db.start();
// Use exactly like MongoDB
const users = client.db('myapp').collection('users');
await users.insertOne({ name: 'Alice', email: 'alice@example.com' });
const user = await users.findOne({ name: 'Alice' });
console.log(user); // { _id: ObjectId(...), name: 'Alice', email: 'alice@example.com' }
// Data persists to disk automatically!
await db.stop();
// Later... data is still there
const db2 = new LocalTsmDb({ folderPath: './my-data' });
const client2 = await db2.start();
const savedUser = await client2.db('myapp').collection('users').findOne({ name: 'Alice' });
// savedUser exists!
```
### Option 2: TsmDB (Wire Protocol Server)
A lightweight, pure TypeScript MongoDB-compatible server — use the official `mongodb` driver directly!
```typescript
import { tsmdb } from '@push.rocks/smartmongo';
import { MongoClient } from 'mongodb';
// Start TsmDB server
const server = new tsmdb.TsmdbServer({ port: 27017 });
await server.start();
// Connect with the official MongoDB driver
const client = new MongoClient('mongodb://127.0.0.1:27017');
await client.connect();
// Use exactly like real MongoDB
const db = client.db('myapp');
await db.collection('users').insertOne({ name: 'Alice', age: 30 });
const user = await db.collection('users').findOne({ name: 'Alice' });
console.log(user); // { _id: ObjectId(...), name: 'Alice', age: 30 }
// Clean up
await client.close();
await server.stop();
```
### Option 3: SmartMongo (Real MongoDB)
Spin up a real MongoDB replica set in memory — perfect for integration tests that need full MongoDB compatibility. Spin up a real MongoDB replica set in memory — perfect for integration tests that need full MongoDB compatibility.
@@ -51,34 +109,42 @@ console.log(descriptor.mongoDbUrl); // mongodb://127.0.0.1:xxxxx/...
await mongo.stop(); await mongo.stop();
``` ```
### Option 2: TsmDB (Wire Protocol Server) ## 📖 LocalTsmDb API
A lightweight, pure TypeScript MongoDB-compatible server that speaks the wire protocol — use the official `mongodb` driver directly! The simplest option for local development and prototyping — zero config, auto port discovery, and automatic persistence.
### Basic Usage
```typescript ```typescript
import { tsmdb } from '@push.rocks/smartmongo'; import { LocalTsmDb } from '@push.rocks/smartmongo';
import { MongoClient } from 'mongodb';
// Start TsmDB server const db = new LocalTsmDb({
const server = new tsmdb.TsmdbServer({ port: 27017 }); folderPath: './data', // Required: where to store data
await server.start(); port: 27017, // Optional: defaults to auto-discovery
host: '127.0.0.1', // Optional: bind address
});
// Connect with the official MongoDB driver! // Start and get connected client
const client = new MongoClient('mongodb://127.0.0.1:27017'); const client = await db.start();
await client.connect();
// Use exactly like real MongoDB // Access the underlying server if needed
const db = client.db('myapp'); const server = db.getServer();
await db.collection('users').insertOne({ name: 'Alice', age: 30 }); const uri = db.getConnectionUri();
const user = await db.collection('users').findOne({ name: 'Alice' }); // Check status
console.log(user); // { _id: ObjectId(...), name: 'Alice', age: 30 } console.log(db.running); // true
// Clean up // Stop when done
await client.close(); await db.stop();
await server.stop();
``` ```
### Features
- 🔍 **Auto Port Discovery** — Automatically finds an available port if 27017 is in use
- 💾 **Automatic Persistence** — Data saved to files, survives restarts
- 🔌 **Pre-connected Client** — `start()` returns a ready-to-use MongoDB client
- 🎯 **Zero Config** — Just specify a folder path and you're good to go
## 📖 SmartMongo API ## 📖 SmartMongo API
### Creating an Instance ### Creating an Instance
@@ -293,11 +359,11 @@ const server = new tsmdb.TsmdbServer({
}); });
// File-based - persistent storage with optional checksums // File-based - persistent storage with optional checksums
import { FileStorageAdapter } from '@push.rocks/smartmongo/tsmdb'; import { tsmdb } from '@push.rocks/smartmongo';
const adapter = new FileStorageAdapter('./data/tsmdb', { const server = new tsmdb.TsmdbServer({
enableChecksums: true, // CRC32 checksums for data integrity storage: 'file',
strictChecksums: false // Log warnings vs throw on mismatch storagePath: './data/tsmdb'
}); });
``` ```
@@ -331,14 +397,14 @@ import { tsmdb } from '@push.rocks/smartmongo';
// For debugging, you can access the query planner // For debugging, you can access the query planner
const planner = new tsmdb.QueryPlanner(indexEngine); const planner = new tsmdb.QueryPlanner(indexEngine);
const plan = planner.createPlan(filter); const plan = await planner.plan(filter);
console.log(plan); console.log(plan);
// { // {
// type: 'IXSCAN', // or 'IXSCAN_RANGE', 'COLLSCAN' // type: 'IXSCAN', // or 'IXSCAN_RANGE', 'COLLSCAN'
// indexName: 'email_1', // indexName: 'email_1',
// estimatedCost: 1, // selectivity: 0.01,
// selectivity: 0.001 // indexCovering: true
// } // }
``` ```
@@ -357,10 +423,10 @@ await wal.initialize();
// - Timestamp // - Timestamp
// - Operation type (insert, update, delete, checkpoint) // - Operation type (insert, update, delete, checkpoint)
// - Document data (BSON serialized) // - Document data (BSON serialized)
// - CRC32 checksum // - CRC32 checksum for integrity
// Recovery support // Recovery support
const entries = await wal.getEntriesAfter(lastCheckpointLsn); const entries = wal.getEntriesAfter(lastCheckpointLsn);
``` ```
### 🔐 Session Management ### 🔐 Session Management
@@ -393,15 +459,10 @@ try {
File-based storage supports CRC32 checksums to detect corruption: File-based storage supports CRC32 checksums to detect corruption:
```typescript ```typescript
import { FileStorageAdapter } from '@push.rocks/smartmongo/tsmdb'; import { tsmdb } from '@push.rocks/smartmongo';
const adapter = new FileStorageAdapter('./data', {
enableChecksums: true,
strictChecksums: true // Throw error on corruption (vs warning)
});
// Checksums are used internally for WAL and data integrity
// Documents are checksummed on write, verified on read // Documents are checksummed on write, verified on read
// Checksums are automatically stripped before returning to client
``` ```
### 📋 Supported Wire Protocol Commands ### 📋 Supported Wire Protocol Commands
@@ -420,6 +481,38 @@ TsmDB supports MongoDB wire protocol versions 0-21, compatible with MongoDB 3.6
## 🧪 Testing Examples ## 🧪 Testing Examples
### Jest/Mocha with LocalTsmDb
```typescript
import { LocalTsmDb } from '@push.rocks/smartmongo';
import { MongoClient, Db } from 'mongodb';
let db: LocalTsmDb;
let client: MongoClient;
beforeAll(async () => {
db = new LocalTsmDb({ folderPath: './test-data' });
client = await db.start();
});
afterAll(async () => {
await db.stop();
});
beforeEach(async () => {
// Clean slate for each test
await client.db('test').dropDatabase();
});
test('should insert and find user', async () => {
const users = client.db('test').collection('users');
await users.insertOne({ name: 'Alice', email: 'alice@example.com' });
const user = await users.findOne({ name: 'Alice' });
expect(user?.email).toBe('alice@example.com');
});
```
### Jest/Mocha with TsmDB ### Jest/Mocha with TsmDB
```typescript ```typescript
@@ -428,7 +521,7 @@ import { MongoClient, Db } from 'mongodb';
let server: tsmdb.TsmdbServer; let server: tsmdb.TsmdbServer;
let client: MongoClient; let client: MongoClient;
let db: Db; let testDb: Db;
beforeAll(async () => { beforeAll(async () => {
server = new tsmdb.TsmdbServer({ port: 27117 }); server = new tsmdb.TsmdbServer({ port: 27117 });
@@ -436,7 +529,7 @@ beforeAll(async () => {
client = new MongoClient('mongodb://127.0.0.1:27117'); client = new MongoClient('mongodb://127.0.0.1:27117');
await client.connect(); await client.connect();
db = client.db('test'); testDb = client.db('test');
}); });
afterAll(async () => { afterAll(async () => {
@@ -445,12 +538,11 @@ afterAll(async () => {
}); });
beforeEach(async () => { beforeEach(async () => {
// Clean slate for each test await testDb.dropDatabase();
await db.dropDatabase();
}); });
test('should insert and find user', async () => { test('should insert and find user', async () => {
const users = db.collection('users'); const users = testDb.collection('users');
await users.insertOne({ name: 'Alice', email: 'alice@example.com' }); await users.insertOne({ name: 'Alice', email: 'alice@example.com' });
const user = await users.findOne({ name: 'Alice' }); const user = await users.findOne({ name: 'Alice' });
@@ -462,22 +554,18 @@ test('should insert and find user', async () => {
```typescript ```typescript
import { expect, tap } from '@git.zone/tstest/tapbundle'; import { expect, tap } from '@git.zone/tstest/tapbundle';
import { tsmdb } from '@push.rocks/smartmongo'; import { LocalTsmDb } from '@push.rocks/smartmongo';
import { MongoClient } from 'mongodb';
let server: tsmdb.TsmdbServer; let db: LocalTsmDb;
let client: MongoClient;
tap.test('setup', async () => { tap.test('setup', async () => {
server = new tsmdb.TsmdbServer({ port: 27117 }); db = new LocalTsmDb({ folderPath: './test-data' });
await server.start(); await db.start();
client = new MongoClient('mongodb://127.0.0.1:27117');
await client.connect();
}); });
tap.test('should perform CRUD operations', async () => { tap.test('should perform CRUD operations', async () => {
const db = client.db('test'); const client = db.getClient();
const col = db.collection('items'); const col = client.db('test').collection('items');
// Create // Create
const result = await col.insertOne({ name: 'Widget', price: 9.99 }); const result = await col.insertOne({ name: 'Widget', price: 9.99 });
@@ -499,8 +587,7 @@ tap.test('should perform CRUD operations', async () => {
}); });
tap.test('teardown', async () => { tap.test('teardown', async () => {
await client.close(); await db.stop();
await server.stop();
}); });
export default tap.start(); export default tap.start();
@@ -508,6 +595,15 @@ export default tap.start();
## 🏗️ Architecture ## 🏗️ Architecture
### Module Structure
```
@push.rocks/smartmongo
├── SmartMongo → Real MongoDB memory server (mongodb-memory-server wrapper)
├── tsmdb → Wire protocol server with full engine stack
└── LocalTsmDb → Zero-config local database (convenience wrapper)
```
### TsmDB Wire Protocol Stack ### TsmDB Wire Protocol Stack
``` ```

2
ts/00_commitinfo_data.ts
View File

@@ -3,6 +3,6 @@
*/ */
export const commitinfo = { export const commitinfo = {
name: '@push.rocks/smartmongo', name: '@push.rocks/smartmongo',
version: '4.2.1', version: '4.3.0',
description: 'A module for creating and managing a local MongoDB instance for testing purposes.' description: 'A module for creating and managing a local MongoDB instance for testing purposes.'
} }