smartmongo/readme.hints.md

Project Hints

Deno Compatibility

mongodb-memory-server Import

• The package uses a default import for mongodb-memory-server in ts/smartmongo.plugins.ts
• Syntax: import mongoPlugin from 'mongodb-memory-server';
• This works in both Node.js and Deno environments
• Why: Deno wraps CommonJS exports in a default property, so default imports are required
• Fixed in version 2.0.13 (changed from import * as mongoPlugin)

TsmDB - MongoDB Wire Protocol Server

Architecture

TsmDB implements the MongoDB binary wire protocol (OP_MSG, OP_QUERY) allowing official MongoDB drivers to connect directly.

Official MongoClient  →  TCP (wire protocol)  →  TsmdbServer  →  Engines  →  Storage
     (mongodb npm)           OP_MSG/BSON            (port)

Module Structure

ts/tsmdb/
├── server/                   # Wire protocol server
│   ├── TsmdbServer.ts        # TCP server, connection handling
│   ├── WireProtocol.ts       # OP_MSG/OP_QUERY parsing & encoding
│   ├── CommandRouter.ts      # Route commands to handlers
│   └── handlers/             # Command implementations
│       ├── HelloHandler.ts   # hello/isMaster handshake
│       ├── FindHandler.ts    # find, getMore, killCursors, count, distinct
│       ├── InsertHandler.ts  # insert
│       ├── UpdateHandler.ts  # update, findAndModify
│       ├── DeleteHandler.ts  # delete
│       ├── AggregateHandler.ts # aggregate
│       ├── IndexHandler.ts   # createIndexes, dropIndexes, listIndexes
│       └── AdminHandler.ts   # ping, listDatabases, listCollections, etc.
│
├── engine/                   # Core logic (reused)
│   ├── QueryEngine.ts        # Query filtering with mingo
│   ├── UpdateEngine.ts       # Update operations
│   ├── AggregationEngine.ts  # Aggregation pipelines
│   ├── IndexEngine.ts        # Index management
│   └── TransactionEngine.ts  # Transaction support
│
├── storage/                  # Storage layer
│   ├── IStorageAdapter.ts    # Interface
│   ├── MemoryStorageAdapter.ts
│   └── FileStorageAdapter.ts
│
└── types/interfaces.ts       # Type definitions

Usage Example

import { TsmdbServer } from '@push.rocks/smartmongo/tsmdb';
import { MongoClient } from 'mongodb';

// Start server
const server = new TsmdbServer({ port: 27117 });
await server.start();

// Connect with official MongoDB driver
const client = new MongoClient('mongodb://127.0.0.1:27117', {
  directConnection: true
});
await client.connect();

// Use like any MongoDB instance
const db = client.db('mydb');
await db.collection('users').insertOne({ name: 'John' });
const user = await db.collection('users').findOne({ name: 'John' });

// Cleanup
await client.close();
await server.stop();

Supported Commands

• Handshake: hello, isMaster
• CRUD: find, insert, update, delete, findAndModify, getMore, killCursors
• Aggregation: aggregate, count, distinct
• Indexes: createIndexes, dropIndexes, listIndexes
• Admin: ping, listDatabases, listCollections, drop, dropDatabase, create, serverStatus, buildInfo