@push.rocks/smartdb 1.0.1 → 2.1.1

package/license

@@ -1,4 +1,6 @@
-Copyright (c) 2021 Task Venture Capital GmbH (hello@task.vc)
+MIT License
+
+Copyright (c) 2024 Task Venture Capital GmbH
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/package.json

@@ -1,34 +1,35 @@
 {
   "name": "@push.rocks/smartdb",
-  "version": "1.0.1",
+  "version": "2.1.1",
   "private": false,
-  "description": "A pure TypeScript MongoDB wire-protocol-compatible database server with pluggable storage, indexing, transactions, and zero external binary dependencies.",
+  "description": "A MongoDB-compatible embedded database server with wire protocol support, backed by a high-performance Rust engine.",
   "exports": {
-    ".": "./dist_ts/index.js"
+    ".": "./dist_ts/index.js",
+    "./debugui": "./dist_ts_debugui/index.js",
+    "./debugserver": "./dist_ts_debugserver/index.js"
   },
   "type": "module",
   "author": "Task Venture Capital GmbH",
   "license": "MIT",
   "scripts": {
+    "test:before": "(tsrust)",
     "test": "(tstest test/. --verbose --logfile --timeout 60)",
-    "build": "(tsbuild tsfolders)",
+    "build": "(tsbundle) && (tsbuild tsfolders) && (tsrust)",
     "buildDocs": "tsdoc"
   },
   "devDependencies": {
     "@git.zone/tsbuild": "^4.4.0",
     "@git.zone/tsbundle": "^2.10.0",
     "@git.zone/tsrun": "^2.0.2",
+    "@git.zone/tsrust": "^1.3.2",
     "@git.zone/tstest": "^3.6.1",
     "@types/node": "^25.5.0",
     "mongodb": "^7.1.1"
   },
   "dependencies": {
-    "@push.rocks/smartfs": "^1.5.0",
-    "@push.rocks/smartpath": "^6.0.0",
-    "@push.rocks/smartpromise": "^4.2.3",
-    "@push.rocks/smartrx": "^3.0.10",
-    "bson": "^7.2.0",
-    "mingo": "^7.2.0"
+    "@api.global/typedserver": "^8.0.0",
+    "@design.estate/dees-element": "^2.0.0",
+    "@push.rocks/smartrust": "^1.3.2"
   },
   "browserslist": [
     "last 1 chrome versions"
@@ -46,14 +47,14 @@
     "readme.md"
   ],
   "keywords": [
-    "mongodb",
+    "mongodb-compatible",
     "wire protocol",
-    "typescript database",
+    "embedded database",
     "in-memory database",
     "testing",
     "local database",
     "database server",
-    "typescript"
+    "rust"
   ],
   "homepage": "https://code.foss.global/push.rocks/smartdb#readme",
   "repository": {

package/readme.md

@@ -1,6 +1,6 @@
 # @push.rocks/smartdb
 
-A pure TypeScript MongoDB wire-protocol-compatible database server. Zero binary dependencies, instant startup, pluggable storage — use the official MongoDB driver and it just works. ⚡
+A MongoDB-compatible embedded database server powered by Rust 🦀⚡ — use the official `mongodb` driver and it just works. No binary downloads, instant startup, zero config. Features a built-in **operation log** with **point-in-time revert** and a web-based **debug dashboard**.
 
 ## Install
 
@@ -14,24 +14,74 @@ npm install @push.rocks/smartdb
 
 For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://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/](https://code.foss.global/) account to submit Pull Requests directly.
 
+---
+
 ## What It Does
 
-`@push.rocks/smartdb` is a **real database server** written entirely in TypeScript that speaks the MongoDB binary wire protocol. Connect with the official `mongodb` Node.js driver — no mocks, no stubs, no MongoDB binary required.
+`@push.rocks/smartdb` is a **real database server** that speaks the wire protocol used by MongoDB drivers. The core engine is written in Rust for high performance, with a thin TypeScript orchestration layer. Connect with the standard `mongodb` Node.js driver — no mocks, no stubs, no external binaries required.
 
 ### Why SmartDB?
 
-| | SmartDB | Real MongoDB |
+| | SmartDB | External DB Server |
 |---|---|---|
-| **Startup time** | ~5ms | ~2-5s |
-| **Binary download** | None | ~200MB |
-| **Node.js only** | ✅ | ❌ |
+| **Startup time** | ~30ms | ~2-5s |
+| **Binary download** | Bundled (~7MB) | ~200MB+ |
+| **Install** | `pnpm add` | System package / Docker |
 | **Persistence** | Memory or file-based | Full disk engine |
-| **Perfect for** | Unit tests, CI/CD, prototyping, local dev | Production |
+| **Debug UI** | Built-in 🖥️ | External tooling |
+| **Point-in-time revert** | Built-in ⏪ | Requires oplog tailing |
+| **Perfect for** | Unit tests, CI/CD, prototyping, local dev, embedded | Production at scale |
 
-### Two Ways to Use It
+### Three Ways to Use It
 
+- 🎯 **`LocalSmartDb`** — Zero-config convenience. Give it a folder path, get a persistent database over a Unix socket. Done.
 - 🏗️ **`SmartdbServer`** — Full control. Configure port, host, storage backend, Unix sockets. Great for test fixtures or custom setups.
-- 🎯 **`LocalSmartDb`** — Zero-config convenience. Give it a folder path, get a persistent MongoDB-compatible database over a Unix socket. Done.
+- 🖥️ **`SmartdbDebugServer`** — Launch a web dashboard to visually browse collections, inspect the operation log, and revert to any point in time.
+
+### Architecture: TypeScript + Rust 🦀
+
+SmartDB uses a **sidecar binary** pattern — TypeScript handles lifecycle, Rust handles all database operations:
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│                   Your Application                            │
+│                  (TypeScript / Node.js)                        │
+│  ┌─────────────────┐     ┌───────────────────────────┐       │
+│  │  SmartdbServer   │────▶│  RustDbBridge (IPC)       │       │
+│  │  or LocalSmartDb │     │  @push.rocks/smartrust    │       │
+│  └─────────────────┘     └───────────┬───────────────┘       │
+└──────────────────────────────────────┼───────────────────────┘
+                                       │ spawn + JSON IPC
+                                       ▼
+┌──────────────────────────────────────────────────────────────┐
+│                    rustdb binary 🦀                           │
+│                                                              │
+│  ┌──────────────┐  ┌──────────────┐  ┌───────────────┐      │
+│  │ Wire Protocol│→ │Command Router│→ │   Handlers    │      │
+│  │  (OP_MSG)    │  │  (40+ cmds)  │  │ Find,Insert.. │      │
+│  └──────────────┘  └──────────────┘  └───────┬───────┘      │
+│                                               │              │
+│  ┌─────────┐ ┌────────┐ ┌───────────┐ ┌──────┴──────┐      │
+│  │  Query  │ │ Update │ │Aggregation│ │   Index     │      │
+│  │ Matcher │ │ Engine │ │  Engine   │ │   Engine    │      │
+│  └─────────┘ └────────┘ └───────────┘ └─────────────┘      │
+│                                                              │
+│  ┌──────────────────┐  ┌──────────────────┐  ┌──────────┐   │
+│  │  MemoryStorage   │  │   FileStorage    │  │  OpLog   │   │
+│  └──────────────────┘  └──────────────────┘  └──────────┘   │
+└──────────────────────────────────────────────────────────────┘
+              ▲
+              │ TCP / Unix Socket (wire protocol)
+              │
+┌─────────────┴────────────────────────────────────────────────┐
+│              MongoClient (mongodb npm driver)                  │
+│              Connects directly to Rust binary                 │
+└──────────────────────────────────────────────────────────────┘
+```
+
+The TypeScript layer handles **lifecycle only** (start/stop/configure via IPC). All database operations flow directly from the `MongoClient` to the Rust binary over TCP or Unix sockets — **zero per-query IPC overhead**.
+
+---
 
 ## Quick Start
 
@@ -47,11 +97,11 @@ import { MongoClient } from 'mongodb';
 const db = new LocalSmartDb({ folderPath: './my-data' });
 const { connectionUri } = await db.start();
 
-// Connect with the standard MongoDB driver
+// Connect with the standard driver
 const client = new MongoClient(connectionUri, { directConnection: true });
 await client.connect();
 
-// Use exactly like MongoDB
+// Use it like any wire-protocol-compatible database
 const users = client.db('myapp').collection('users');
 await users.insertOne({ name: 'Alice', email: 'alice@example.com' });
 const user = await users.findOne({ name: 'Alice' });
@@ -83,13 +133,94 @@ await client.close();
 await server.stop();
 ```
 
+### Option 3: Debug Server (Visual Dashboard) 🖥️
+
+Launch a web-based dashboard to inspect your database in real time:
+
+```typescript
+import { SmartdbServer } from '@push.rocks/smartdb';
+import { SmartdbDebugServer } from '@push.rocks/smartdb/debugserver';
+
+const server = new SmartdbServer({ storage: 'memory' });
+await server.start();
+
+const debugServer = new SmartdbDebugServer(server, { port: 4000 });
+await debugServer.start();
+// Open http://localhost:4000 in your browser 🚀
+```
+
+The debug dashboard gives you:
+- 📊 **Dashboard** — server status, uptime, database/collection counts, operation breakdown
+- 📁 **Collection Browser** — browse databases, collections, and documents interactively
+- 📝 **OpLog Timeline** — every insert, update, and delete with expandable field-level diffs
+- ⏪ **Point-in-Time Revert** — select any oplog sequence, preview what will be undone, and execute
+
+---
+
+## 📝 Operation Log & Point-in-Time Revert
+
+Every write operation (insert, update, delete) is automatically recorded in an in-memory **operation log (OpLog)** with full before/after document snapshots. This enables:
+
+- **Change tracking** — see exactly what changed, when, and in which collection
+- **Field-level diffs** — compare previous and new document states
+- **Point-in-time revert** — undo operations back to any sequence number
+- **Dry-run preview** — see what would be reverted before executing
+
+### Programmatic OpLog API
+
+```typescript
+import { SmartdbServer } from '@push.rocks/smartdb';
+
+const server = new SmartdbServer({ port: 27017 });
+await server.start();
+
+// ... perform some CRUD operations via MongoClient ...
+
+// Get oplog entries
+const oplog = await server.getOpLog({ limit: 50 });
+console.log(oplog.entries);
+// [{ seq: 1, op: 'insert', db: 'myapp', collection: 'users', document: {...}, previousDocument: null }, ...]
+
+// Get aggregate stats
+const stats = await server.getOpLogStats();
+console.log(stats);
+// { currentSeq: 42, totalEntries: 42, entriesByOp: { insert: 20, update: 15, delete: 7 } }
+
+// Preview a revert (dry run)
+const preview = await server.revertToSeq(30, true);
+console.log(`Would undo ${preview.reverted} operations`);
+
+// Execute the revert — undoes all operations after seq 30
+const result = await server.revertToSeq(30, false);
+console.log(`Reverted ${result.reverted} operations`);
+
+// Browse collections programmatically
+const collections = await server.getCollections();
+const docs = await server.getDocuments('myapp', 'users', 50, 0);
+```
+
+### OpLog Entry Structure
+
+Each entry contains:
+
+| Field | Type | Description |
+|---|---|---|
+| `seq` | `number` | Monotonically increasing sequence number |
+| `timestampMs` | `number` | Unix timestamp in milliseconds |
+| `op` | `'insert' \| 'update' \| 'delete'` | Operation type |
+| `db` | `string` | Database name |
+| `collection` | `string` | Collection name |
+| `documentId` | `string` | Document `_id` as hex string |
+| `document` | `object \| null` | New document state (null for deletes) |
+| `previousDocument` | `object \| null` | Previous document state (null for inserts) |
+
 ---
 
 ## API Reference
 
 ### SmartdbServer
 
-The core server class. Speaks MongoDB wire protocol over TCP or Unix sockets.
+The core server class. Manages the Rust database engine and exposes connection details.
 
 #### Constructor Options (`ISmartdbServerOptions`)
 
@@ -123,15 +254,19 @@ const server = new SmartdbServer({
 
 | Method / Property | Type | Description |
 |---|---|---|
-| `start()` | `Promise<void>` | Start the server |
+| `start()` | `Promise<void>` | Start the server (spawns Rust binary) |
 | `stop()` | `Promise<void>` | Stop the server and clean up |
-| `getConnectionUri()` | `string` | Get the MongoDB connection URI |
+| `getConnectionUri()` | `string` | Get the `mongodb://` connection URI |
 | `running` | `boolean` | Whether the server is currently running |
-| `port` | `number` | Bound port (TCP mode) |
-| `host` | `string` | Bound host (TCP mode) |
-| `socketPath` | `string` | Socket path (socket mode) |
-| `getUptime()` | `number` | Seconds since start |
-| `getConnectionCount()` | `number` | Active client connections |
+| `port` | `number` | Configured port (TCP mode) |
+| `host` | `string` | Configured host (TCP mode) |
+| `socketPath` | `string \| undefined` | Socket path (socket mode) |
+| `getMetrics()` | `Promise<ISmartDbMetrics>` | Server metrics (db/collection counts, uptime) |
+| `getOpLog(params?)` | `Promise<IOpLogResult>` | Query oplog entries with optional filters |
+| `getOpLogStats()` | `Promise<IOpLogStats>` | Aggregate oplog statistics |
+| `revertToSeq(seq, dryRun?)` | `Promise<IRevertResult>` | Revert to a specific oplog sequence |
+| `getCollections(db?)` | `Promise<ICollectionInfo[]>` | List all collections with counts |
+| `getDocuments(db, coll, limit?, skip?)` | `Promise<IDocumentsResult>` | Browse documents with pagination |
 
 ### LocalSmartDb
 
@@ -155,24 +290,45 @@ const db = new LocalSmartDb({
 | `start()` | `Promise<ILocalSmartDbConnectionInfo>` | Start and return connection info |
 | `stop()` | `Promise<void>` | Stop the server |
 | `getConnectionInfo()` | `ILocalSmartDbConnectionInfo` | Get current connection info |
-| `getConnectionUri()` | `string` | Get the MongoDB URI |
+| `getConnectionUri()` | `string` | Get the connection URI |
 | `getServer()` | `SmartdbServer` | Access the underlying server |
 | `running` | `boolean` | Whether the server is running |
 
-#### Connection Info (`ILocalSmartDbConnectionInfo`)
+### SmartdbDebugServer
+
+Web-based debug dashboard served via `@api.global/typedserver`. Import from the `debugserver` subpath:
+
+```typescript
+import { SmartdbDebugServer } from '@push.rocks/smartdb/debugserver';
+
+const debugServer = new SmartdbDebugServer(server, { port: 4000 });
+await debugServer.start();
+// Dashboard at http://localhost:4000
+
+await debugServer.stop();
+```
+
+The UI is bundled as base64-encoded content (via `@git.zone/tsbundle`) and served from memory — no static file directory needed.
+
+### SmartdbDebugUi (Web Component)
+
+For embedding the debug UI directly into your own web application, import the `<smartdb-debugui>` web component:
 
 ```typescript
-interface ILocalSmartDbConnectionInfo {
-  socketPath: string;      // e.g., /tmp/smartdb-abc123.sock
-  connectionUri: string;   // e.g., mongodb://%2Ftmp%2Fsmartdb-abc123.sock
-}
+import { SmartdbDebugUi } from '@push.rocks/smartdb/debugui';
+
+// In your HTML/lit template:
+// <smartdb-debugui .server=${mySmartdbServer}></smartdb-debugui>
+//
+// Or in HTTP mode (when served by SmartdbDebugServer):
+// <smartdb-debugui apiBaseUrl=""></smartdb-debugui>
 ```
 
 ---
 
-## Supported MongoDB Operations
+## Supported Operations
 
-SmartDB supports the core MongoDB operations through the wire protocol. Use the standard `mongodb` driver — these all work:
+SmartDB supports the core operations through the wire protocol. Use the standard `mongodb` driver — these all work:
 
 ### CRUD
 
@@ -258,7 +414,7 @@ const results = await collection.aggregate([
 ]).toArray();
 ```
 
-**Supported stages:** `$match`, `$project`, `$group`, `$sort`, `$limit`, `$skip`, `$unwind`, `$lookup`, `$addFields`, `$count`, `$facet`, `$replaceRoot`, `$set`, `$unset`
+**Supported stages:** `$match`, `$project`, `$group`, `$sort`, `$limit`, `$skip`, `$unwind`, `$lookup`, `$addFields`, `$count`, `$facet`, `$replaceRoot`, `$set`, `$unionWith`, `$out`, `$merge`
 
 **Group accumulators:** `$sum`, `$avg`, `$min`, `$max`, `$first`, `$last`, `$push`, `$addToSet`, `$count`
 
@@ -316,148 +472,34 @@ const names = await collection.distinct('name');
 | **CRUD** | `find`, `insert`, `update`, `delete`, `findAndModify`, `getMore`, `killCursors` |
 | **Aggregation** | `aggregate`, `count`, `distinct` |
 | **Indexes** | `createIndexes`, `dropIndexes`, `listIndexes` |
-| **Transactions** | `startTransaction`, `commitTransaction`, `abortTransaction` |
-| **Sessions** | `startSession`, `endSessions`, `refreshSessions` |
-| **Admin** | `ping`, `listDatabases`, `listCollections`, `drop`, `dropDatabase`, `create`, `serverStatus`, `buildInfo`, `dbStats`, `collStats`, `connectionStatus`, `currentOp`, `collMod`, `renameCollection` |
+| **Sessions** | `startSession`, `endSessions` |
+| **Transactions** | `commitTransaction`, `abortTransaction` |
+| **Admin** | `ping`, `listDatabases`, `listCollections`, `drop`, `dropDatabase`, `create`, `serverStatus`, `buildInfo`, `dbStats`, `collStats`, `connectionStatus`, `currentOp`, `renameCollection` |
 
-Compatible with MongoDB wire protocol versions 0–21 (MongoDB 3.6 through 7.0 drivers).
+Compatible with wire protocol versions 0–21 (driver versions 3.6 through 7.0).
 
 ---
 
-## Architecture
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                   Official MongoDB Driver                    │
-│                      (mongodb npm)                          │
-└─────────────────────────┬───────────────────────────────────┘
-                          │ TCP / Unix Socket + OP_MSG / BSON
-                          ▼
-┌─────────────────────────────────────────────────────────────┐
-│                      SmartdbServer                          │
-│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐  │
-│  │ WireProtocol │→ │CommandRouter │→ │     Handlers     │  │
-│  │  (OP_MSG)    │  │              │  │ (Find, Insert..) │  │
-│  └──────────────┘  └──────────────┘  └──────────────────┘  │
-└─────────────────────────┬───────────────────────────────────┘
-                          │
-                          ▼
-┌─────────────────────────────────────────────────────────────┐
-│                        Engines                              │
-│  ┌─────────┐ ┌────────┐ ┌───────────┐ ┌───────┐ ┌───────┐ │
-│  │  Query  │ │ Update │ │Aggregation│ │ Index │ │Session│ │
-│  │ Planner │ │ Engine │ │  Engine   │ │Engine │ │Engine │ │
-│  └─────────┘ └────────┘ └───────────┘ └───────┘ └───────┘ │
-│                   ┌──────────────────────┐                  │
-│                   │ Transaction Engine   │                  │
-│                   └──────────────────────┘                  │
-└─────────────────────────┬───────────────────────────────────┘
-                          │
-                          ▼
-┌─────────────────────────────────────────────────────────────┐
-│                    Storage Layer                            │
-│  ┌──────────────────┐  ┌──────────────────┐  ┌──────────┐  │
-│  │  MemoryStorage   │  │   FileStorage    │  │   WAL    │  │
-│  │                  │  │  (+ Checksums)   │  │          │  │
-│  └──────────────────┘  └──────────────────┘  └──────────┘  │
-└─────────────────────────────────────────────────────────────┘
-```
+## Rust Crate Architecture 🦀
 
-### Key Components
+The Rust engine is organized as a Cargo workspace with 8 focused crates:
 
-| Component | What It Does |
+| Crate | Purpose |
 |---|---|
-| **WireProtocol** | Parses/encodes MongoDB OP_MSG binary frames |
-| **CommandRouter** | Routes parsed commands to the right handler |
-| **QueryPlanner** | Picks COLLSCAN vs IXSCAN based on available indexes |
-| **QueryEngine** | Filter matching powered by [mingo](https://github.com/kofrasa/mingo) |
-| **UpdateEngine** | Processes `$set`, `$inc`, `$push`, and all update operators |
-| **AggregationEngine** | Runs aggregation pipelines via mingo |
-| **IndexEngine** | B-tree (range) and hash (equality) indexes |
-| **TransactionEngine** | ACID transactions with snapshot isolation |
-| **SessionEngine** | Client session tracking with automatic timeouts |
-| **WAL** | Write-ahead logging with CRC32 checksums for crash recovery |
+| `rustdb` | Binary entry point: TCP/Unix listener, management IPC, CLI |
+| `rustdb-config` | Server configuration types (serde, camelCase JSON) |
+| `rustdb-wire` | Wire protocol parser/encoder (OP_MSG, OP_QUERY, OP_REPLY) |
+| `rustdb-query` | Query matcher, update engine, aggregation, sort, projection |
+| `rustdb-storage` | Storage backends (memory, file), OpLog with point-in-time replay |
+| `rustdb-index` | B-tree/hash indexes, query planner (IXSCAN/COLLSCAN) |
+| `rustdb-txn` | Transaction + session management with snapshot isolation |
+| `rustdb-commands` | 40+ command handlers wiring everything together |
 
----
-
-## Advanced Usage
-
-### Storage Adapters
-
-```typescript
-import { SmartdbServer } from '@push.rocks/smartdb';
-
-// In-memory (default) — fast, data lost on stop
-const server = new SmartdbServer({ storage: 'memory' });
-
-// In-memory with periodic persistence
-const server = new SmartdbServer({
-  storage: 'memory',
-  persistPath: './data/snapshot.json',
-  persistIntervalMs: 30000,
-});
-
-// File-based — persistent storage with CRC32 checksums
-const server = new SmartdbServer({
-  storage: 'file',
-  storagePath: './data/smartdb',
-});
-```
-
-### Query Planner (Debugging)
-
-```typescript
-import { QueryPlanner, IndexEngine, MemoryStorageAdapter } from '@push.rocks/smartdb';
-
-const storage = new MemoryStorageAdapter();
-await storage.initialize();
-const indexEngine = new IndexEngine('mydb', 'mycoll', storage);
-const planner = new QueryPlanner(indexEngine);
-
-const plan = await planner.plan({ age: { $gte: 18 } });
-console.log(plan);
-// { type: 'IXSCAN_RANGE', indexName: 'age_1', selectivity: 0.3, usesRange: true, ... }
-
-const explain = await planner.explain({ age: 18 });
-// Returns winning plan, rejected plans, and detailed analysis
-```
-
-### Data Integrity Checksums
-
-```typescript
-import { calculateDocumentChecksum, addChecksum, verifyChecksum, removeChecksum } from '@push.rocks/smartdb';
-
-const doc = { name: 'Alice', age: 30 };
-
-const protected = addChecksum(doc);       // Adds _checksum field
-const valid = verifyChecksum(protected);  // true
-protected.age = 31;                       // Tamper!
-const still = verifyChecksum(protected);  // false
-const clean = removeChecksum(protected);  // Removes _checksum
-```
-
-### Write-Ahead Logging
-
-```typescript
-import { WAL } from '@push.rocks/smartdb';
-
-const wal = new WAL('./data/wal.log', { checkpointInterval: 100 });
-await wal.initialize();
-
-// Entries include: LSN, timestamp, operation, BSON data, CRC32 checksum
-const lsn = await wal.logInsert('mydb', 'users', doc);
-const entries = wal.getEntriesAfter(lastCheckpoint);
-const recovered = wal.recoverDocument(entry);
-
-await wal.checkpoint();
-await wal.close();
-```
+Cross-compiled for `linux_amd64` and `linux_arm64` via [@git.zone/tsrust](https://www.npmjs.com/package/@git.zone/tsrust).
 
 ---
 
-## Testing Examples
-
-### Unit Tests with @git.zone/tstest
+## Testing Example
 
 ```typescript
 import { expect, tap } from '@git.zone/tstest/tapbundle';
@@ -481,6 +523,12 @@ tap.test('should insert and find', async () => {
   expect(item?.price).toEqual(9.99);
 });
 
+tap.test('should track changes in oplog', async () => {
+  const oplog = await server.getOpLog();
+  expect(oplog.entries.length).toBeGreaterThan(0);
+  expect(oplog.entries[0].op).toEqual('insert');
+});
+
 tap.test('teardown', async () => {
   await client.close();
   await server.stop();
@@ -489,23 +537,7 @@ tap.test('teardown', async () => {
 export default tap.start();
 ```
 
-### With LocalSmartDb (Persistent Tests)
-
-```typescript
-import { LocalSmartDb } from '@push.rocks/smartdb';
-import { MongoClient } from 'mongodb';
-
-const db = new LocalSmartDb({ folderPath: './test-data' });
-const { connectionUri } = await db.start();
-
-const client = new MongoClient(connectionUri, { directConnection: true });
-await client.connect();
-
-// Tests here — data persists between test runs!
-
-await client.close();
-await db.stop();
-```
+---
 
 ## License and Legal Information
 
@@ -521,7 +553,7 @@ Use of these trademarks must comply with Task Venture Capital GmbH's Trademark G
 
 ### Company Information
 
-Task Venture Capital GmbH
+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.

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/smartdb',
-  version: '1.0.1',
-  description: 'A pure TypeScript MongoDB wire-protocol-compatible database server with pluggable storage, indexing, transactions, and zero external binary dependencies.'
+  version: '2.1.1',
+  description: 'A MongoDB-compatible embedded database server with wire protocol support, backed by a high-performance Rust engine.'
 }

package/ts/index.ts

@@ -9,3 +9,14 @@ export type { ILocalSmartDbOptions, ILocalSmartDbConnectionInfo } from './ts_loc
 
 // Export commitinfo
 export { commitinfo };
+
+// Re-export oplog / debug types for convenience
+export type {
+  IOpLogEntry,
+  IOpLogResult,
+  IOpLogStats,
+  IRevertResult,
+  ICollectionInfo,
+  IDocumentsResult,
+  ISmartDbMetrics,
+} from './ts_smartdb/index.js';

package/ts/ts_local/classes.localsmartdb.ts

@@ -1,4 +1,3 @@
-import * as plugins from './plugins.js';
 import * as crypto from 'crypto';
 import * as path from 'path';
 import * as os from 'os';
@@ -10,7 +9,7 @@ import { SmartdbServer } from '../ts_smartdb/index.js';
 export interface ILocalSmartDbConnectionInfo {
   /** The Unix socket file path */
   socketPath: string;
-  /** MongoDB connection URI ready for MongoClient */
+  /** Connection URI (mongodb:// scheme) ready for MongoClient */
   connectionUri: string;
 }
 
@@ -25,8 +24,8 @@ export interface ILocalSmartDbOptions {
  * LocalSmartDb - Lightweight local MongoDB-compatible database using Unix sockets
  *
  * This class wraps SmartdbServer and provides a simple interface for
- * starting a local file-based MongoDB-compatible server. Returns connection
- * info that you can use with your own MongoDB driver instance.
+ * starting a local file-based database server. Returns connection
+ * info that you can use with any compatible driver instance.
  *
  * @example
  * ```typescript
@@ -36,11 +35,11 @@ export interface ILocalSmartDbOptions {
  * const db = new LocalSmartDb({ folderPath: './data' });
  * const { connectionUri } = await db.start();
  *
- * // Connect with your own MongoDB client
+ * // Connect with the driver
  * const client = new MongoClient(connectionUri, { directConnection: true });
  * await client.connect();
  *
- * // Use the MongoDB client
+ * // Use the client
  * const collection = client.db('mydb').collection('users');
  * await collection.insertOne({ name: 'Alice' });
  *

package/ts/ts_local/plugins.ts

@@ -1,3 +1 @@
-import * as smartpromise from '@push.rocks/smartpromise';
-
-export { smartpromise };
+// Local module plugins - currently no external dependencies needed