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`)

## CongoDB - MongoDB Wire Protocol Server

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

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

### Module Structure
```
ts/congodb/
├── server/                   # Wire protocol server
│   ├── CongoServer.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
```typescript
import { CongoServer } from '@push.rocks/smartmongo/congodb';
import { MongoClient } from 'mongodb';

// Start server
const server = new CongoServer({ 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

### Notes
- The old CongoClient/CongoDb/CongoCollection classes have been removed
- Use the official `mongodb` npm package's MongoClient instead
- Server supports MongoDB wire protocol versions 0-21 (MongoDB 3.6 through 7.0 compatible)