v5.0.0

changelog.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## 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
+
+- LocalTsmDb.start() now returns ILocalTsmDbConnectionInfo { socketPath, connectionUri } instead of a connected MongoClient
+- Removed internal MongoClient management: consumers must create/connect/close their own MongoClient using the returned connectionUri (close client before calling db.stop())
+- Added ILocalTsmDbConnectionInfo type and getConnectionInfo() (replaces getClient())
+- TsmdbServer: added socketPath option to listen on Unix sockets, cleans up stale socket files on start/stop, and encodes socket paths in getConnectionUri()
+- LocalTsmDb can auto-generate socket paths in the OS temp dir; LocalTsmDb no longer depends on the mongodb package internally (lightweight Unix socket wrapper)
+- Updated docs and tests to use MongoClient externally and to demonstrate socketPath/connectionUri workflow
+- ts_local plugins no longer export net (net usage moved to server implementation)
+
+## 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)
+replace main and typings with exports field pointing to ./dist_ts/index.js
+
+- Added package.json exports field mapping "." to ./dist_ts/index.js to declare the package entrypoint.
+- Removed main (dist_ts/index.js) and typings (dist_ts/index.d.ts) entries.
+- Note: switching to exports improves Node resolution but removing the typings entry may affect TypeScript consumers expecting index.d.ts.
+
+## 2026-02-01 - 4.2.0 - feat(tsmdb)
+implement TsmDB Mongo-wire-compatible server, add storage/engine modules and reorganize exports
+
+- Add full TsmDB implementation under ts/ts_tsmdb: wire protocol, server, command router, handlers, engines (Query, Update, Aggregation, Index, Transaction, Session), storage adapters (Memory, File), OpLog, WAL, utils and types.
+- Remove legacy ts/tsmdb implementation and replace with new ts_tsmdb module exports.
+- Introduce ts/ts_mongotools module and move SmartMongo class there; update top-level exports in ts/index.ts to export SmartMongo, tsmdb (from ts_tsmdb) and LocalTsmDb.
+- Add LocalTsmDb convenience class (ts/ts_local) to start a file-backed TsmDB and return a connected MongoClient.
+- Refactor plugin imports into per-module plugins files and add utilities (checksum, persistence, query planner, index engine).
+
 ## 2026-02-01 - 4.1.1 - fix(tsmdb)
 add comprehensive unit tests for tsmdb components: checksum, query planner, index engine, session, and WAL
 

package.json

@@ -1,12 +1,13 @@
 {
   "name": "@push.rocks/smartmongo",
-  "version": "4.1.1",
+  "version": "5.0.0",
   "private": false,
   "description": "A module for creating and managing a local MongoDB instance for testing purposes.",
-  "main": "dist_ts/index.js",
-  "typings": "dist_ts/index.d.ts",
+  "exports": {
+    ".": "./dist_ts/index.js"
+  },
   "type": "module",
-  "author": "Lossless GmbH",
+  "author": "Task Venture Capital GmbH",
   "license": "MIT",
   "scripts": {
     "test": "(tstest test/. --verbose --logfile --timeout 60)",

readme.md

@@ -1,6 +1,6 @@
 # @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
 
@@ -16,21 +16,87 @@ For reporting bugs, issues, or security vulnerabilities, please visit [community
 
 ## 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 |
-|---------|------------|---------|
-| **Type** | Real MongoDB (memory server) | Pure TypeScript wire protocol server |
-| **Speed** | ~2-5s startup | ⚡ Instant startup (~5ms) |
-| **Compatibility** | 100% MongoDB | MongoDB driver compatible |
-| **Dependencies** | Downloads MongoDB binary | Zero external dependencies |
-| **Replication** | ✅ Full replica set support | Single node emulation |
-| **Use Case** | Integration testing | Unit testing, CI/CD |
-| **Persistence** | Dump to directory | Optional file/memory persistence |
+| Feature | SmartMongo | TsmDB | LocalTsmDb |
+|---------|------------|-------|------------|
+| **Type** | Real MongoDB (memory server) | Wire protocol server | Zero-config local DB |
+| **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!) |
+| **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: 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 using Unix sockets. No port conflicts, no MongoDB driver dependency in LocalTsmDb!
+
+```typescript
+import { LocalTsmDb } from '@push.rocks/smartmongo';
+import { MongoClient } from 'mongodb';
+
+// Create a local database backed by files
+const db = new LocalTsmDb({ folderPath: './my-data' });
+
+// Start and get connection info (Unix socket path + connection URI)
+const { connectionUri } = await db.start();
+
+// Connect with your own MongoDB client
+const client = new MongoClient(connectionUri, { directConnection: true });
+await client.connect();
+
+// 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 client.close();
+await db.stop();
+
+// Later... data is still there
+const db2 = new LocalTsmDb({ folderPath: './my-data' });
+const { connectionUri: uri2 } = await db2.start();
+const client2 = new MongoClient(uri2, { directConnection: true });
+await client2.connect();
+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.
 
@@ -51,34 +117,54 @@ console.log(descriptor.mongoDbUrl); // mongodb://127.0.0.1:xxxxx/...
 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 — lightweight, Unix socket-based, and automatic persistence.
+
+### Basic Usage
 
 ```typescript
-import { tsmdb } from '@push.rocks/smartmongo';
+import { LocalTsmDb } from '@push.rocks/smartmongo';
 import { MongoClient } from 'mongodb';
 
-// Start TsmDB server
-const server = new tsmdb.TsmdbServer({ port: 27017 });
-await server.start();
+const db = new LocalTsmDb({
+  folderPath: './data',    // Required: where to store data
+  socketPath: '/tmp/my.sock', // Optional: custom socket path (default: auto-generated)
+});
 
-// Connect with the official MongoDB driver!
-const client = new MongoClient('mongodb://127.0.0.1:27017');
+// Start and get connection info
+const { socketPath, connectionUri } = await db.start();
+console.log(socketPath);    // /tmp/smartmongo-abc123.sock (auto-generated)
+console.log(connectionUri); // mongodb://%2Ftmp%2Fsmartmongo-abc123.sock
+
+// Connect with your own MongoDB client
+const client = new MongoClient(connectionUri, { directConnection: true });
 await client.connect();
 
-// Use exactly like real MongoDB
-const db = client.db('myapp');
-await db.collection('users').insertOne({ name: 'Alice', age: 30 });
+// Use the client
+const users = client.db('mydb').collection('users');
+await users.insertOne({ name: 'Alice' });
 
-const user = await db.collection('users').findOne({ name: 'Alice' });
-console.log(user); // { _id: ObjectId(...), name: 'Alice', age: 30 }
+// Access the underlying server if needed
+const server = db.getServer();
+const uri = db.getConnectionUri();
 
-// Clean up
+// Check status
+console.log(db.running); // true
+
+// Stop when done (close your client first!)
 await client.close();
-await server.stop();
+await db.stop();
 ```
 
+### Features
+
+- 🔌 **Unix Sockets** — No port conflicts, faster IPC than TCP
+- 💾 **Automatic Persistence** — Data saved to files, survives restarts
+- 🪶 **Lightweight** — No MongoDB driver dependency in LocalTsmDb itself
+- 🎯 **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
 
 ### Creating an Instance
@@ -293,11 +379,11 @@ const server = new tsmdb.TsmdbServer({
 });
 
 // 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', {
-  enableChecksums: true,   // CRC32 checksums for data integrity
-  strictChecksums: false   // Log warnings vs throw on mismatch
+const server = new tsmdb.TsmdbServer({
+  storage: 'file',
+  storagePath: './data/tsmdb'
 });
 ```
 
@@ -331,14 +417,14 @@ import { tsmdb } from '@push.rocks/smartmongo';
 
 // For debugging, you can access the query planner
 const planner = new tsmdb.QueryPlanner(indexEngine);
-const plan = planner.createPlan(filter);
+const plan = await planner.plan(filter);
 
 console.log(plan);
 // {
 //   type: 'IXSCAN',           // or 'IXSCAN_RANGE', 'COLLSCAN'
 //   indexName: 'email_1',
-//   estimatedCost: 1,
-//   selectivity: 0.001
+//   selectivity: 0.01,
+//   indexCovering: true
 // }
 ```
 
@@ -357,10 +443,10 @@ await wal.initialize();
 // - Timestamp
 // - Operation type (insert, update, delete, checkpoint)
 // - Document data (BSON serialized)
-// - CRC32 checksum
+// - CRC32 checksum for integrity
 
 // Recovery support
-const entries = await wal.getEntriesAfter(lastCheckpointLsn);
+const entries = wal.getEntriesAfter(lastCheckpointLsn);
 ```
 
 ### 🔐 Session Management
@@ -393,15 +479,10 @@ try {
 File-based storage supports CRC32 checksums to detect corruption:
 
 ```typescript
-import { FileStorageAdapter } from '@push.rocks/smartmongo/tsmdb';
-
-const adapter = new FileStorageAdapter('./data', {
-  enableChecksums: true,
-  strictChecksums: true  // Throw error on corruption (vs warning)
-});
+import { tsmdb } from '@push.rocks/smartmongo';
 
+// Checksums are used internally for WAL and data integrity
 // Documents are checksummed on write, verified on read
-// Checksums are automatically stripped before returning to client
 ```
 
 ### 📋 Supported Wire Protocol Commands
@@ -420,6 +501,41 @@ TsmDB supports MongoDB wire protocol versions 0-21, compatible with MongoDB 3.6
 
 ## 🧪 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' });
+  const { connectionUri } = await db.start();
+  client = new MongoClient(connectionUri, { directConnection: true });
+  await client.connect();
+});
+
+afterAll(async () => {
+  await client.close();
+  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
 
 ```typescript
@@ -428,7 +544,7 @@ import { MongoClient, Db } from 'mongodb';
 
 let server: tsmdb.TsmdbServer;
 let client: MongoClient;
-let db: Db;
+let testDb: Db;
 
 beforeAll(async () => {
   server = new tsmdb.TsmdbServer({ port: 27117 });
@@ -436,7 +552,7 @@ beforeAll(async () => {
 
   client = new MongoClient('mongodb://127.0.0.1:27117');
   await client.connect();
-  db = client.db('test');
+  testDb = client.db('test');
 });
 
 afterAll(async () => {
@@ -445,12 +561,11 @@ afterAll(async () => {
 });
 
 beforeEach(async () => {
-  // Clean slate for each test
-  await db.dropDatabase();
+  await testDb.dropDatabase();
 });
 
 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' });
 
   const user = await users.findOne({ name: 'Alice' });
@@ -462,22 +577,21 @@ test('should insert and find user', async () => {
 
 ```typescript
 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 () => {
-  server = new tsmdb.TsmdbServer({ port: 27117 });
-  await server.start();
-  client = new MongoClient('mongodb://127.0.0.1:27117');
+  db = new LocalTsmDb({ folderPath: './test-data' });
+  const { connectionUri } = await db.start();
+  client = new MongoClient(connectionUri, { directConnection: true });
   await client.connect();
 });
 
 tap.test('should perform CRUD operations', async () => {
-  const db = client.db('test');
-  const col = db.collection('items');
+  const col = client.db('test').collection('items');
 
   // Create
   const result = await col.insertOne({ name: 'Widget', price: 9.99 });
@@ -500,7 +614,7 @@ tap.test('should perform CRUD operations', async () => {
 
 tap.test('teardown', async () => {
   await client.close();
-  await server.stop();
+  await db.stop();
 });
 
 export default tap.start();
@@ -508,6 +622,15 @@ export default tap.start();
 
 ## 🏗️ Architecture
 
+### Module Structure
+
+```
+@push.rocks/smartmongo
+├── SmartMongo      → Real MongoDB memory server (mongodb-memory-server wrapper)
+├── tsmdb           → Wire protocol server with full engine stack
+└── LocalTsmDb      → Lightweight Unix socket wrapper (no MongoDB driver dependency)
+```
+
 ### TsmDB Wire Protocol Stack
 
 ```

ts/00_commitinfo_data.ts

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

ts/index.ts

@@ -1,74 +1,14 @@
 import { commitinfo } from './00_commitinfo_data.js';
-import * as plugins from './smartmongo.plugins.js';
+
+// Export SmartMongo from ts_mongotools
+export { SmartMongo } from './ts_mongotools/index.js';
 
 // Export TsmDB module
-export * as tsmdb from './tsmdb/index.js';
+export * as tsmdb from './ts_tsmdb/index.js';
 
-export class SmartMongo {
-  // STATIC
-  public static async createAndStart(replCountArg: number = 1) {
-    const smartMongoInstance = new SmartMongo();
-    await smartMongoInstance.start(replCountArg);
-    return smartMongoInstance;
-  }
+// Export LocalTsmDb from ts_local
+export { LocalTsmDb } from './ts_local/index.js';
+export type { ILocalTsmDbOptions } from './ts_local/index.js';
 
-  // INSTANCE
-  private _readyDeferred = plugins.smartpromise.defer();
-  public readyPromise = this._readyDeferred.promise;
-  public mongoReplicaSet: plugins.mongoPlugin.MongoMemoryReplSet;
-
-  constructor() {}
-
-  public async start(countArg: number = 1) {
-    this.mongoReplicaSet = await plugins.mongoPlugin.MongoMemoryReplSet.create({
-      replSet: { count: countArg },
-      instanceOpts: [
-        {
-          storageEngine: 'wiredTiger',
-        },
-      ],
-    });
-    this._readyDeferred.resolve();
-    console.log(`mongoReplicaSet with ${countArg} replicas started.`);
-    console.log(`@pushrocks/smartmongo version ${commitinfo.version}`);
-  }
-
-  /**
-   * returns a mongo descriptor for modules like
-   * @pushrocks/smartfile.
-   */
-  public async getMongoDescriptor(): Promise<plugins.smartdata.IMongoDescriptor> {
-    await this.readyPromise;
-    return {
-      mongoDbName: `smartmongo_testdatabase`,
-      mongoDbUrl: this.mongoReplicaSet.getUri(),
-    };
-  }
-
-  /**
-   * stops the smartmongo instance
-   * and cleans up after itself
-   */
-  public async stop() {
-    await this.mongoReplicaSet.stop();
-    await this.mongoReplicaSet.cleanup();
-  }
-
-  /**
-   * like stop() but allows you to actually store
-   * the database on disk
-   */
-  public async stopAndDumpToDir(
-    dirArg: string,
-    nameFunctionArg?: (doc: any) => string,
-    emptyDirArg = true,
-  ) {
-    const mongodumpInstance = new plugins.mongodump.MongoDump();
-    const mongodumpTarget = await mongodumpInstance.addMongoTargetByMongoDescriptor(
-      await this.getMongoDescriptor(),
-    );
-    await mongodumpTarget.dumpAllCollectionsToDir(dirArg, nameFunctionArg, emptyDirArg);
-    await mongodumpInstance.stop();
-    await this.stop();
-  }
-}
+// Export commitinfo
+export { commitinfo };

ts/ts_local/classes.localtsmdb.ts

@@ -0,0 +1,143 @@
+import * as plugins from './plugins.js';
+import * as crypto from 'crypto';
+import * as path from 'path';
+import * as os from 'os';
+import { TsmdbServer } from '../ts_tsmdb/index.js';
+
+/**
+ * Connection information returned by LocalTsmDb.start()
+ */
+export interface ILocalTsmDbConnectionInfo {
+  /** The Unix socket file path */
+  socketPath: string;
+  /** MongoDB connection URI ready for MongoClient */
+  connectionUri: string;
+}
+
+export interface ILocalTsmDbOptions {
+  /** Required: where to store data */
+  folderPath: string;
+  /** Optional: custom socket path (default: auto-generated in /tmp) */
+  socketPath?: string;
+}
+
+/**
+ * LocalTsmDb - Lightweight local MongoDB-compatible database using Unix sockets
+ *
+ * This class wraps TsmdbServer 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.
+ *
+ * @example
+ * ```typescript
+ * import { LocalTsmDb } from '@push.rocks/smartmongo';
+ * import { MongoClient } from 'mongodb';
+ *
+ * const db = new LocalTsmDb({ folderPath: './data' });
+ * const { connectionUri } = await db.start();
+ *
+ * // Connect with your own MongoDB client
+ * const client = new MongoClient(connectionUri, { directConnection: true });
+ * await client.connect();
+ *
+ * // Use the MongoDB client
+ * const collection = client.db('mydb').collection('users');
+ * await collection.insertOne({ name: 'Alice' });
+ *
+ * // When done
+ * await client.close();
+ * await db.stop();
+ * ```
+ */
+export class LocalTsmDb {
+  private options: ILocalTsmDbOptions;
+  private server: TsmdbServer | null = null;
+  private generatedSocketPath: string | null = null;
+
+  constructor(options: ILocalTsmDbOptions) {
+    this.options = options;
+  }
+
+  /**
+   * Generate a unique socket path in /tmp
+   */
+  private generateSocketPath(): string {
+    const randomId = crypto.randomBytes(8).toString('hex');
+    return path.join(os.tmpdir(), `smartmongo-${randomId}.sock`);
+  }
+
+  /**
+   * Start the local TsmDB server and return connection info
+   */
+  async start(): Promise<ILocalTsmDbConnectionInfo> {
+    if (this.server) {
+      throw new Error('LocalTsmDb is already running');
+    }
+
+    // Use provided socket path or generate one
+    this.generatedSocketPath = this.options.socketPath ?? this.generateSocketPath();
+
+    this.server = new TsmdbServer({
+      socketPath: this.generatedSocketPath,
+      storage: 'file',
+      storagePath: this.options.folderPath,
+    });
+    await this.server.start();
+
+    return {
+      socketPath: this.generatedSocketPath,
+      connectionUri: this.server.getConnectionUri(),
+    };
+  }
+
+  /**
+   * Get connection info (throws if not started)
+   */
+  getConnectionInfo(): ILocalTsmDbConnectionInfo {
+    if (!this.server || !this.generatedSocketPath) {
+      throw new Error('LocalTsmDb is not running. Call start() first.');
+    }
+    return {
+      socketPath: this.generatedSocketPath,
+      connectionUri: this.server.getConnectionUri(),
+    };
+  }
+
+  /**
+   * Get the underlying TsmdbServer instance (throws if not started)
+   */
+  getServer(): TsmdbServer {
+    if (!this.server) {
+      throw new Error('LocalTsmDb is not running. Call start() first.');
+    }
+    return this.server;
+  }
+
+  /**
+   * Get the connection URI
+   */
+  getConnectionUri(): string {
+    if (!this.server) {
+      throw new Error('LocalTsmDb is not running. Call start() first.');
+    }
+    return this.server.getConnectionUri();
+  }
+
+  /**
+   * Check if the server is running
+   */
+  get running(): boolean {
+    return this.server !== null && this.server.running;
+  }
+
+  /**
+   * Stop the local TsmDB server
+   */
+  async stop(): Promise<void> {
+    if (this.server) {
+      await this.server.stop();
+      this.server = null;
+      this.generatedSocketPath = null;
+    }
+  }
+}

ts/ts_local/index.ts

@@ -0,0 +1,2 @@
+export { LocalTsmDb } from './classes.localtsmdb.js';
+export type { ILocalTsmDbOptions, ILocalTsmDbConnectionInfo } from './classes.localtsmdb.js';

ts/ts_local/plugins.ts

@@ -0,0 +1,3 @@
+import * as smartpromise from '@push.rocks/smartpromise';
+
+export { smartpromise };

ts/ts_mongotools/classes.smartmongo.ts

@@ -0,0 +1,71 @@
+import { commitinfo } from '../00_commitinfo_data.js';
+import * as plugins from './plugins.js';
+
+export class SmartMongo {
+  // STATIC
+  public static async createAndStart(replCountArg: number = 1) {
+    const smartMongoInstance = new SmartMongo();
+    await smartMongoInstance.start(replCountArg);
+    return smartMongoInstance;
+  }
+
+  // INSTANCE
+  private _readyDeferred = plugins.smartpromise.defer();
+  public readyPromise = this._readyDeferred.promise;
+  public mongoReplicaSet: plugins.mongoPlugin.MongoMemoryReplSet;
+
+  constructor() {}
+
+  public async start(countArg: number = 1) {
+    this.mongoReplicaSet = await plugins.mongoPlugin.MongoMemoryReplSet.create({
+      replSet: { count: countArg },
+      instanceOpts: [
+        {
+          storageEngine: 'wiredTiger',
+        },
+      ],
+    });
+    this._readyDeferred.resolve();
+    console.log(`mongoReplicaSet with ${countArg} replicas started.`);
+    console.log(`@pushrocks/smartmongo version ${commitinfo.version}`);
+  }
+
+  /**
+   * returns a mongo descriptor for modules like
+   * @pushrocks/smartfile.
+   */
+  public async getMongoDescriptor(): Promise<plugins.smartdata.IMongoDescriptor> {
+    await this.readyPromise;
+    return {
+      mongoDbName: `smartmongo_testdatabase`,
+      mongoDbUrl: this.mongoReplicaSet.getUri(),
+    };
+  }
+
+  /**
+   * stops the smartmongo instance
+   * and cleans up after itself
+   */
+  public async stop() {
+    await this.mongoReplicaSet.stop();
+    await this.mongoReplicaSet.cleanup();
+  }
+
+  /**
+   * like stop() but allows you to actually store
+   * the database on disk
+   */
+  public async stopAndDumpToDir(
+    dirArg: string,
+    nameFunctionArg?: (doc: any) => string,
+    emptyDirArg = true,
+  ) {
+    const mongodumpInstance = new plugins.mongodump.MongoDump();
+    const mongodumpTarget = await mongodumpInstance.addMongoTargetByMongoDescriptor(
+      await this.getMongoDescriptor(),
+    );
+    await mongodumpTarget.dumpAllCollectionsToDir(dirArg, nameFunctionArg, emptyDirArg);
+    await mongodumpInstance.stop();
+    await this.stop();
+  }
+}

ts/ts_mongotools/index.ts

@@ -0,0 +1,2 @@
+export * from './plugins.js';
+export { SmartMongo } from './classes.smartmongo.js';

ts/ts_tsmdb/engine/AggregationEngine.ts

@@ -1,4 +1,4 @@
-import * as plugins from '../tsmdb.plugins.js';
+import * as plugins from '../plugins.js';
 import type { Document, IStoredDocument, IAggregateOptions } from '../types/interfaces.js';
 
 // Import mingo Aggregator

ts/ts_tsmdb/engine/IndexEngine.ts

@@ -1,4 +1,4 @@
-import * as plugins from '../tsmdb.plugins.js';
+import * as plugins from '../plugins.js';
 import type { IStorageAdapter } from '../storage/IStorageAdapter.js';
 
 // Simple B-Tree implementation for range queries

ts/ts_tsmdb/engine/QueryEngine.ts

@@ -1,4 +1,4 @@
-import * as plugins from '../tsmdb.plugins.js';
+import * as plugins from '../plugins.js';
 import type { Document, IStoredDocument, ISortSpecification, ISortDirection } from '../types/interfaces.js';
 
 // Import mingo Query class

ts/ts_tsmdb/engine/QueryPlanner.ts

@@ -1,4 +1,4 @@
-import * as plugins from '../tsmdb.plugins.js';
+import * as plugins from '../plugins.js';
 import type { Document, IStoredDocument } from '../types/interfaces.js';
 import { IndexEngine } from './IndexEngine.js';
 

ts/ts_tsmdb/engine/SessionEngine.ts

@@ -1,4 +1,4 @@
-import * as plugins from '../tsmdb.plugins.js';
+import * as plugins from '../plugins.js';
 import type { TransactionEngine } from './TransactionEngine.js';
 
 /**

ts/ts_tsmdb/engine/TransactionEngine.ts

@@ -1,4 +1,4 @@
-import * as plugins from '../tsmdb.plugins.js';
+import * as plugins from '../plugins.js';
 import type { IStorageAdapter } from '../storage/IStorageAdapter.js';
 import type { Document, IStoredDocument, ITransactionOptions } from '../types/interfaces.js';
 import { TsmdbTransactionError, TsmdbWriteConflictError } from '../errors/TsmdbErrors.js';

ts/ts_tsmdb/engine/UpdateEngine.ts

@@ -1,4 +1,4 @@
-import * as plugins from '../tsmdb.plugins.js';
+import * as plugins from '../plugins.js';
 import type { Document, IStoredDocument } from '../types/interfaces.js';
 import { QueryEngine } from './QueryEngine.js';
 

ts/ts_tsmdb/index.ts

@@ -2,7 +2,7 @@
 // Use the official MongoDB driver to connect to TsmdbServer
 
 // Re-export plugins for external use
-import * as plugins from './tsmdb.plugins.js';
+import * as plugins from './plugins.js';
 export { plugins };
 
 // Export BSON types for convenience

ts/ts_tsmdb/server/CommandRouter.ts

@@ -1,4 +1,4 @@
-import * as plugins from '../tsmdb.plugins.js';
+import * as plugins from '../plugins.js';
 import type { IStorageAdapter } from '../storage/IStorageAdapter.js';
 import type { IParsedCommand } from './WireProtocol.js';
 import type { TsmdbServer } from './TsmdbServer.js';

ts/ts_tsmdb/server/TsmdbServer.ts

@@ -1,5 +1,6 @@
 import * as net from 'net';
-import * as plugins from '../tsmdb.plugins.js';
+import * as fs from 'fs/promises';
+import * as plugins from '../plugins.js';
 import { WireProtocol, OP_QUERY } from './WireProtocol.js';
 import { CommandRouter } from './CommandRouter.js';
 import { MemoryStorageAdapter } from '../storage/MemoryStorageAdapter.js';
@@ -10,10 +11,12 @@ import type { IStorageAdapter } from '../storage/IStorageAdapter.js';
  * Server configuration options
  */
 export interface ITsmdbServerOptions {
-  /** Port to listen on (default: 27017) */
+  /** Port to listen on (default: 27017) - ignored if socketPath is set */
   port?: number;
-  /** Host to bind to (default: 127.0.0.1) */
+  /** Host to bind to (default: 127.0.0.1) - ignored if socketPath is set */
   host?: string;
+  /** Unix socket path - if set, server listens on socket instead of TCP */
+  socketPath?: string;
   /** Storage type: 'memory' or 'file' (default: 'memory') */
   storage?: 'memory' | 'file';
   /** Path for file storage (required if storage is 'file') */
@@ -54,7 +57,7 @@ interface IConnectionState {
  * ```
  */
 export class TsmdbServer {
-  private options: Required<ITsmdbServerOptions>;
+  private options: Required<Omit<ITsmdbServerOptions, 'socketPath'>> & { socketPath: string };
   private server: net.Server | null = null;
   private storage: IStorageAdapter;
   private commandRouter: CommandRouter;
@@ -62,11 +65,14 @@ export class TsmdbServer {
   private connectionIdCounter = 0;
   private isRunning = false;
   private startTime: Date = new Date();
+  private useSocket: boolean;
 
   constructor(options: ITsmdbServerOptions = {}) {
+    this.useSocket = !!options.socketPath;
     this.options = {
       port: options.port ?? 27017,
       host: options.host ?? '127.0.0.1',
+      socketPath: options.socketPath ?? '',
       storage: options.storage ?? 'memory',
       storagePath: options.storagePath ?? './data',
       persistPath: options.persistPath ?? '',
@@ -119,6 +125,18 @@ export class TsmdbServer {
     // Initialize storage
     await this.storage.initialize();
 
+    // Clean up stale socket file if using Unix socket
+    if (this.useSocket && this.options.socketPath) {
+      try {
+        await fs.unlink(this.options.socketPath);
+      } catch (err: any) {
+        // Ignore ENOENT (file doesn't exist)
+        if (err.code !== 'ENOENT') {
+          throw err;
+        }
+      }
+    }
+
     return new Promise((resolve, reject) => {
       this.server = net.createServer((socket) => {
         this.handleConnection(socket);
@@ -132,11 +150,21 @@ export class TsmdbServer {
         }
       });
 
+      if (this.useSocket && this.options.socketPath) {
+        // Listen on Unix socket
+        this.server.listen(this.options.socketPath, () => {
+          this.isRunning = true;
+          this.startTime = new Date();
+          resolve();
+        });
+      } else {
+        // Listen on TCP
         this.server.listen(this.options.port, this.options.host, () => {
           this.isRunning = true;
           this.startTime = new Date();
           resolve();
         });
+      }
     });
   }
 
@@ -161,9 +189,22 @@ export class TsmdbServer {
     await this.storage.close();
 
     return new Promise((resolve) => {
-      this.server!.close(() => {
+      this.server!.close(async () => {
         this.isRunning = false;
         this.server = null;
+
+        // Clean up socket file if using Unix socket
+        if (this.useSocket && this.options.socketPath) {
+          try {
+            await fs.unlink(this.options.socketPath);
+          } catch (err: any) {
+            // Ignore ENOENT (file doesn't exist)
+            if (err.code !== 'ENOENT') {
+              console.error('Failed to remove socket file:', err);
+            }
+          }
+        }
+
         resolve();
       });
     });
@@ -275,9 +316,21 @@ export class TsmdbServer {
    * Get the connection URI for this server
    */
   getConnectionUri(): string {
+    if (this.useSocket && this.options.socketPath) {
+      // URL-encode the socket path (replace / with %2F)
+      const encodedPath = encodeURIComponent(this.options.socketPath);
+      return `mongodb://${encodedPath}`;
+    }
     return `mongodb://${this.options.host}:${this.options.port}`;
   }
 
+  /**
+   * Get the socket path (if using Unix socket mode)
+   */
+  get socketPath(): string | undefined {
+    return this.useSocket ? this.options.socketPath : undefined;
+  }
+
   /**
    * Check if the server is running
    */

ts/ts_tsmdb/server/WireProtocol.ts

@@ -1,4 +1,4 @@
-import * as plugins from '../tsmdb.plugins.js';
+import * as plugins from '../plugins.js';
 
 /**
  * MongoDB Wire Protocol Implementation

ts/ts_tsmdb/server/handlers/AdminHandler.ts

@@ -1,4 +1,4 @@
-import * as plugins from '../../tsmdb.plugins.js';
+import * as plugins from '../../plugins.js';
 import type { ICommandHandler, IHandlerContext } from '../CommandRouter.js';
 import { SessionEngine } from '../../engine/SessionEngine.js';
 

ts/ts_tsmdb/server/handlers/AggregateHandler.ts

@@ -1,4 +1,4 @@
-import * as plugins from '../../tsmdb.plugins.js';
+import * as plugins from '../../plugins.js';
 import type { ICommandHandler, IHandlerContext, ICursorState } from '../CommandRouter.js';
 import { AggregationEngine } from '../../engine/AggregationEngine.js';
 

ts/ts_tsmdb/server/handlers/DeleteHandler.ts

@@ -1,4 +1,4 @@
-import * as plugins from '../../tsmdb.plugins.js';
+import * as plugins from '../../plugins.js';
 import type { ICommandHandler, IHandlerContext } from '../CommandRouter.js';
 import type { IStoredDocument } from '../../types/interfaces.js';
 import { QueryEngine } from '../../engine/QueryEngine.js';

ts/ts_tsmdb/server/handlers/FindHandler.ts

@@ -1,4 +1,4 @@
-import * as plugins from '../../tsmdb.plugins.js';
+import * as plugins from '../../plugins.js';
 import type { ICommandHandler, IHandlerContext, ICursorState } from '../CommandRouter.js';
 import type { IStoredDocument } from '../../types/interfaces.js';
 import { QueryEngine } from '../../engine/QueryEngine.js';

ts/ts_tsmdb/server/handlers/HelloHandler.ts

@@ -1,4 +1,4 @@
-import * as plugins from '../../tsmdb.plugins.js';
+import * as plugins from '../../plugins.js';
 import type { ICommandHandler, IHandlerContext } from '../CommandRouter.js';
 
 /**

ts/ts_tsmdb/server/handlers/IndexHandler.ts

@@ -1,4 +1,4 @@
-import * as plugins from '../../tsmdb.plugins.js';
+import * as plugins from '../../plugins.js';
 import type { ICommandHandler, IHandlerContext } from '../CommandRouter.js';
 import { IndexEngine } from '../../engine/IndexEngine.js';
 

ts/ts_tsmdb/server/handlers/InsertHandler.ts

@@ -1,4 +1,4 @@
-import * as plugins from '../../tsmdb.plugins.js';
+import * as plugins from '../../plugins.js';
 import type { ICommandHandler, IHandlerContext } from '../CommandRouter.js';
 import type { IStoredDocument } from '../../types/interfaces.js';
 

ts/ts_tsmdb/server/handlers/UpdateHandler.ts

@@ -1,4 +1,4 @@
-import * as plugins from '../../tsmdb.plugins.js';
+import * as plugins from '../../plugins.js';
 import type { ICommandHandler, IHandlerContext } from '../CommandRouter.js';
 import type { IStoredDocument } from '../../types/interfaces.js';
 import { QueryEngine } from '../../engine/QueryEngine.js';

ts/ts_tsmdb/storage/FileStorageAdapter.ts

@@ -1,4 +1,4 @@
-import * as plugins from '../tsmdb.plugins.js';
+import * as plugins from '../plugins.js';
 import type { IStorageAdapter } from './IStorageAdapter.js';
 import type { IStoredDocument, IOpLogEntry, Document } from '../types/interfaces.js';
 import { calculateDocumentChecksum, verifyChecksum } from '../utils/checksum.js';

ts/ts_tsmdb/storage/IStorageAdapter.ts

@@ -1,4 +1,4 @@
-import type * as plugins from '../tsmdb.plugins.js';
+import type * as plugins from '../plugins.js';
 import type { IStoredDocument, IOpLogEntry, Document } from '../types/interfaces.js';
 
 /**

ts/ts_tsmdb/storage/MemoryStorageAdapter.ts

@@ -1,4 +1,4 @@
-import * as plugins from '../tsmdb.plugins.js';
+import * as plugins from '../plugins.js';
 import type { IStorageAdapter } from './IStorageAdapter.js';
 import type { IStoredDocument, IOpLogEntry, Document } from '../types/interfaces.js';
 

ts/ts_tsmdb/storage/OpLog.ts

@@ -1,4 +1,4 @@
-import * as plugins from '../tsmdb.plugins.js';
+import * as plugins from '../plugins.js';
 import type { IStorageAdapter } from './IStorageAdapter.js';
 import type { IOpLogEntry, Document, IResumeToken, ChangeStreamOperationType } from '../types/interfaces.js';
 

ts/ts_tsmdb/storage/WAL.ts

@@ -1,4 +1,4 @@
-import * as plugins from '../tsmdb.plugins.js';
+import * as plugins from '../plugins.js';
 import type { Document, IStoredDocument } from '../types/interfaces.js';
 
 /**

ts/ts_tsmdb/types/interfaces.ts

@@ -1,4 +1,4 @@
-import type * as plugins from '../tsmdb.plugins.js';
+import type * as plugins from '../plugins.js';
 
 // ============================================================================
 // Document Types