From b72174ca7b3c2f093c438e61e1663c0d900a8d85 Mon Sep 17 00:00:00 2001 From: Juergen Kunz Date: Tue, 3 Feb 2026 16:48:50 +0000 Subject: [PATCH] feat(localtsmdb): export ILocalTsmDbConnectionInfo and expand LocalTsmDb/TsmDB documentation and examples --- changelog.md | 9 +++ readme.md | 142 ++++++++++++++++++++++++++++++++------- ts/00_commitinfo_data.ts | 2 +- ts/index.ts | 2 +- 4 files changed, 127 insertions(+), 28 deletions(-) diff --git a/changelog.md b/changelog.md index 1a7f29b..0d6fcd3 100644 --- a/changelog.md +++ b/changelog.md @@ -1,5 +1,14 @@ # Changelog +## 2026-02-03 - 5.1.0 - feat(localtsmdb) +export ILocalTsmDbConnectionInfo and expand LocalTsmDb/TsmDB documentation and examples + +- Exported new type ILocalTsmDbConnectionInfo from ts_local (ts/index.ts) +- Added LocalTsmDb configuration example, methods table, and ConnectionInfo interface to README +- Documented Unix socket vs TCP connection modes and updated usage examples (TCP and socket examples) +- Expanded TsmDB docs: additional server properties, aggregation stages, regex examples, index operations, database ops, checksums, and wire protocol commands +- Updated architecture notes to include Unix socket support and new engine components (QueryEngine, UpdateEngine, AggregationEngine) + ## 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 diff --git a/readme.md b/readme.md index 1f42383..39b81c5 100644 --- a/readme.md +++ b/readme.md @@ -24,13 +24,14 @@ For reporting bugs, issues, or security vulnerabilities, please visit [community | **Speed** | ~2-5s startup | โšก Instant (~5ms) | โšก Instant (Unix socket) | | **Compatibility** | 100% MongoDB | MongoDB driver compatible | MongoDB driver compatible | | **Dependencies** | Downloads MongoDB binary | Zero external deps | Zero external deps (no MongoDB driver!) | +| **Connection** | TCP | TCP or Unix socket | Unix socket (default) | | **Replication** | โœ… Full replica set | Single node | Single node | | **Persistence** | Dump to directory | Memory or file | File-based (automatic) | | **Use Case** | Integration testing | Unit testing, CI/CD | Quick prototyping, local dev | ## ๐Ÿš€ Quick Start -### Option 1: LocalTsmDb (Zero-Config Local Database) โญ NEW +### Option 1: LocalTsmDb (Zero-Config Local Database) โญ The easiest way to get started โ€” just point it at a folder and you have a persistent MongoDB-compatible database using Unix sockets. No port conflicts, no MongoDB driver dependency in LocalTsmDb! @@ -76,7 +77,7 @@ A lightweight, pure TypeScript MongoDB-compatible server โ€” use the official `m import { tsmdb } from '@push.rocks/smartmongo'; import { MongoClient } from 'mongodb'; -// Start TsmDB server +// Start TsmDB server (TCP mode) const server = new tsmdb.TsmdbServer({ port: 27017 }); await server.start(); @@ -117,20 +118,55 @@ console.log(descriptor.mongoDbUrl); // mongodb://127.0.0.1:xxxxx/... await mongo.stop(); ``` +--- + ## ๐Ÿ“– LocalTsmDb API The simplest option for local development and prototyping โ€” lightweight, Unix socket-based, and automatic persistence. +### Configuration + +```typescript +import { LocalTsmDb } from '@push.rocks/smartmongo'; +import type { ILocalTsmDbOptions, ILocalTsmDbConnectionInfo } from '@push.rocks/smartmongo'; + +const options: ILocalTsmDbOptions = { + folderPath: './data', // Required: where to store data + socketPath: '/tmp/my.sock', // Optional: custom socket path (default: auto-generated) +}; + +const db = new LocalTsmDb(options); +``` + +### Methods + +| Method | Returns | Description | +|--------|---------|-------------| +| `start()` | `Promise` | Starts the server and returns connection info | +| `stop()` | `Promise` | Stops the server and cleans up the socket | +| `getConnectionInfo()` | `ILocalTsmDbConnectionInfo` | Returns current connection info | +| `getConnectionUri()` | `string` | Returns the MongoDB connection URI | +| `getServer()` | `TsmdbServer` | Returns the underlying TsmDB server instance | +| `running` | `boolean` | Property indicating if the server is running | + +### Connection Info + +The `start()` method returns an `ILocalTsmDbConnectionInfo` object: + +```typescript +interface ILocalTsmDbConnectionInfo { + socketPath: string; // The Unix socket file path, e.g., /tmp/smartmongo-abc123.sock + connectionUri: string; // MongoDB URI, e.g., mongodb://%2Ftmp%2Fsmartmongo-abc123.sock +} +``` + ### Basic Usage ```typescript import { LocalTsmDb } from '@push.rocks/smartmongo'; import { MongoClient } from 'mongodb'; -const db = new LocalTsmDb({ - folderPath: './data', // Required: where to store data - socketPath: '/tmp/my.sock', // Optional: custom socket path (default: auto-generated) -}); +const db = new LocalTsmDb({ folderPath: './data' }); // Start and get connection info const { socketPath, connectionUri } = await db.start(); @@ -145,10 +181,6 @@ await client.connect(); const users = client.db('mydb').collection('users'); await users.insertOne({ name: 'Alice' }); -// Access the underlying server if needed -const server = db.getServer(); -const uri = db.getConnectionUri(); - // Check status console.log(db.running); // true @@ -165,8 +197,12 @@ await db.stop(); - ๐ŸŽฏ **Zero Config** โ€” Just specify a folder path and you're good to go - ๐Ÿ”— **Connection URI** โ€” Ready-to-use URI for your own MongoClient +--- + ## ๐Ÿ“– SmartMongo API +Full MongoDB replica set in memory using `mongodb-memory-server`. + ### Creating an Instance ```typescript @@ -202,27 +238,44 @@ await mongo.stopAndDumpToDir('./test-data'); await mongo.stopAndDumpToDir('./test-data', (doc) => `${doc.collection}-${doc._id}.bson`); ``` +--- + ## ๐Ÿ”ง TsmDB API +Pure TypeScript MongoDB wire protocol server. No external dependencies. + ### Server Configuration ```typescript import { tsmdb } from '@push.rocks/smartmongo'; +// TCP mode (default) const server = new tsmdb.TsmdbServer({ - port: 27017, // Default MongoDB port - host: '127.0.0.1', // Bind address - storage: 'memory', // 'memory' or 'file' - storagePath: './data', // For file-based storage + port: 27017, // Default MongoDB port + host: '127.0.0.1', // Bind address + storage: 'memory', // 'memory' or 'file' + storagePath: './data', // For file-based storage +}); + +// Unix socket mode (no port conflicts!) +const server = new tsmdb.TsmdbServer({ + socketPath: '/tmp/my-tsmdb.sock', + storage: 'file', + storagePath: './data', }); await server.start(); -console.log(server.getConnectionUri()); // mongodb://127.0.0.1:27017 +console.log(server.getConnectionUri()); +// TCP: mongodb://127.0.0.1:27017 +// Socket: mongodb://%2Ftmp%2Fmy-tsmdb.sock // Server properties console.log(server.running); // true -console.log(server.getUptime()); // seconds -console.log(server.getConnectionCount()); // active connections +console.log(server.port); // 27017 (TCP mode) +console.log(server.host); // '127.0.0.1' (TCP mode) +console.log(server.socketPath); // '/tmp/my-tsmdb.sock' (socket mode) +console.log(server.getUptime()); // seconds since start +console.log(server.getConnectionCount()); // active client connections await server.stop(); ``` @@ -232,6 +285,7 @@ await server.stop(); TsmDB supports the core MongoDB operations via the wire protocol: #### ๐Ÿ”น CRUD Operations + ```typescript // Insert await collection.insertOne({ name: 'Bob' }); @@ -261,6 +315,7 @@ const result = await collection.findOneAndUpdate( ``` #### ๐Ÿ”น Query Operators + ```typescript // Comparison { age: { $eq: 25 } } @@ -283,9 +338,14 @@ const result = await collection.findOneAndUpdate( { tags: { $all: ['mongodb', 'database'] } } { scores: { $elemMatch: { $gte: 80, $lt: 90 } } } { tags: { $size: 3 } } + +// Regex +{ name: { $regex: /^Al/i } } +{ email: { $regex: '@example\\.com$' } } ``` #### ๐Ÿ”น Update Operators + ```typescript { $set: { name: 'New Name' } } { $unset: { tempField: '' } } @@ -298,9 +358,12 @@ const result = await collection.findOneAndUpdate( { $addToSet: { tags: 'unique-tag' } } { $pop: { queue: 1 } } // Remove last { $pop: { queue: -1 } } // Remove first +{ $rename: { oldField: 'newField' } } +{ $currentDate: { lastModified: true } } ``` #### ๐Ÿ”น Aggregation Pipeline + ```typescript const results = await collection.aggregate([ { $match: { status: 'active' } }, @@ -311,17 +374,28 @@ const results = await collection.aggregate([ ]).toArray(); ``` -Supported stages: `$match`, `$project`, `$group`, `$sort`, `$limit`, `$skip`, `$unwind`, `$lookup`, `$addFields`, `$count`, `$facet`, and more. +**Supported stages:** `$match`, `$project`, `$group`, `$sort`, `$limit`, `$skip`, `$unwind`, `$lookup`, `$addFields`, `$count`, `$facet`, `$replaceRoot`, `$set`, `$unset`, and more. + +**Supported group accumulators:** `$sum`, `$avg`, `$min`, `$max`, `$first`, `$last`, `$push`, `$addToSet`, `$count`. #### ๐Ÿ”น Index Operations + ```typescript +// Create indexes await collection.createIndex({ email: 1 }, { unique: true }); await collection.createIndex({ name: 1, age: -1 }); +await collection.createIndex({ location: '2dsphere' }); // Geospatial + +// List indexes const indexes = await collection.listIndexes().toArray(); + +// Drop indexes await collection.dropIndex('email_1'); +await collection.dropIndexes(); // Drop all except _id ``` #### ๐Ÿ”น Database Operations + ```typescript // List databases const dbs = await client.db().admin().listDatabases(); @@ -335,9 +409,13 @@ await db.dropCollection('oldcollection'); // Drop database await db.dropDatabase(); + +// Database stats +const stats = await db.stats(); ``` #### ๐Ÿ”น Count & Distinct + ```typescript // Count documents const total = await collection.countDocuments({}); @@ -350,6 +428,7 @@ const activeDepts = await collection.distinct('department', { status: 'active' } ``` #### ๐Ÿ”น Bulk Operations + ```typescript const result = await collection.bulkWrite([ { insertOne: { document: { name: 'Bulk1' } } }, @@ -378,22 +457,22 @@ const server = new tsmdb.TsmdbServer({ persistIntervalMs: 30000 // Save every 30 seconds }); -// File-based - persistent storage with optional checksums -import { tsmdb } from '@push.rocks/smartmongo'; - +// File-based - persistent storage with checksums const server = new tsmdb.TsmdbServer({ storage: 'file', storagePath: './data/tsmdb' }); ``` +--- + ## โšก Performance & Reliability Features TsmDB includes enterprise-grade features for robustness: ### ๐Ÿ” Index-Accelerated Queries -Indexes are automatically used to accelerate queries. Instead of scanning all documents, TsmDB uses: +Indexes are automatically used to accelerate queries: - **Hash indexes** for equality queries (`$eq`, `$in`) - **B-tree indexes** for range queries (`$gt`, `$gte`, `$lt`, `$lte`) @@ -483,22 +562,26 @@ import { tsmdb } from '@push.rocks/smartmongo'; // Checksums are used internally for WAL and data integrity // Documents are checksummed on write, verified on read +const checksum = tsmdb.calculateDocumentChecksum(doc); +const isValid = tsmdb.verifyChecksum(docWithChecksum); ``` ### ๐Ÿ“‹ Supported Wire Protocol Commands | Category | Commands | |----------|----------| -| **Handshake** | `hello`, `isMaster` | +| **Handshake** | `hello`, `isMaster`, `ismaster` | | **CRUD** | `find`, `insert`, `update`, `delete`, `findAndModify`, `getMore`, `killCursors` | | **Aggregation** | `aggregate`, `count`, `distinct` | | **Indexes** | `createIndexes`, `dropIndexes`, `listIndexes` | | **Transactions** | `startTransaction`, `commitTransaction`, `abortTransaction` | -| **Sessions** | `startSession`, `endSessions` | -| **Admin** | `ping`, `listDatabases`, `listCollections`, `drop`, `dropDatabase`, `create`, `serverStatus`, `buildInfo`, `dbStats`, `collStats` | +| **Sessions** | `startSession`, `endSessions`, `refreshSessions` | +| **Admin** | `ping`, `listDatabases`, `listCollections`, `drop`, `dropDatabase`, `create`, `serverStatus`, `buildInfo`, `dbStats`, `collStats`, `connectionStatus` | TsmDB supports MongoDB wire protocol versions 0-21, compatible with MongoDB 3.6 through 7.0 drivers. +--- + ## ๐Ÿงช Testing Examples ### Jest/Mocha with LocalTsmDb @@ -620,6 +703,8 @@ tap.test('teardown', async () => { export default tap.start(); ``` +--- + ## ๐Ÿ—๏ธ Architecture ### Module Structure @@ -638,7 +723,7 @@ export default tap.start(); โ”‚ Official MongoDB Driver โ”‚ โ”‚ (mongodb npm) โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ - โ”‚ TCP + OP_MSG/BSON + โ”‚ TCP/Unix Socket + OP_MSG/BSON โ–ผ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ TsmdbServer โ”‚ @@ -677,11 +762,16 @@ export default tap.start(); | **WireProtocol** | Parses MongoDB OP_MSG binary protocol | | **CommandRouter** | Routes commands to appropriate handlers | | **QueryPlanner** | Analyzes queries and selects execution strategy | +| **QueryEngine** | Executes queries with filter matching | +| **UpdateEngine** | Processes update operators (`$set`, `$inc`, etc.) | +| **AggregationEngine** | Executes aggregation pipelines | | **IndexEngine** | Manages B-tree and hash indexes | | **SessionEngine** | Tracks client sessions and timeouts | | **TransactionEngine** | Handles ACID transaction semantics | | **WAL** | Write-ahead logging for durability | +--- + ## 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 [LICENSE](./LICENSE) file. diff --git a/ts/00_commitinfo_data.ts b/ts/00_commitinfo_data.ts index 6bb66a3..a456976 100644 --- a/ts/00_commitinfo_data.ts +++ b/ts/00_commitinfo_data.ts @@ -3,6 +3,6 @@ */ export const commitinfo = { name: '@push.rocks/smartmongo', - version: '5.0.0', + version: '5.1.0', description: 'A module for creating and managing a local MongoDB instance for testing purposes.' } diff --git a/ts/index.ts b/ts/index.ts index d2d20d1..170266e 100644 --- a/ts/index.ts +++ b/ts/index.ts @@ -8,7 +8,7 @@ export * as tsmdb from './ts_tsmdb/index.js'; // Export LocalTsmDb from ts_local export { LocalTsmDb } from './ts_local/index.js'; -export type { ILocalTsmDbOptions } from './ts_local/index.js'; +export type { ILocalTsmDbOptions, ILocalTsmDbConnectionInfo } from './ts_local/index.js'; // Export commitinfo export { commitinfo };