BREAKING CHANGE(localtsmdb): add Unix socket support and change LocalTsmDb API to return connection info instead of a MongoClient

readme.md

@@ -21,9 +21,9 @@ For reporting bugs, issues, or security vulnerabilities, please visit [community
 | Feature | SmartMongo | TsmDB | LocalTsmDb |
 |---------|------------|-------|------------|
 | **Type** | Real MongoDB (memory server) | Wire protocol server | Zero-config local DB |
-| **Speed** | ~2-5s startup | ⚡ Instant (~5ms) | ⚡ Instant + auto-connect |
+| **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 |
+| **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 |
@@ -32,16 +32,21 @@ For reporting bugs, issues, or security vulnerabilities, please visit [community
 
 ### 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 with automatic port discovery!
+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 a connected MongoDB client
-const client = await db.start();
+// 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');
@@ -51,11 +56,14 @@ 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 client2 = await db2.start();
+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!
 ```
@@ -111,21 +119,31 @@ await mongo.stop();
 
 ## 📖 LocalTsmDb API
 
-The simplest option for local development and prototyping — zero config, auto port discovery, and automatic persistence.
+The simplest option for local development and prototyping — lightweight, Unix socket-based, and automatic persistence.
 
 ### Basic Usage
 
 ```typescript
 import { LocalTsmDb } from '@push.rocks/smartmongo';
+import { MongoClient } from 'mongodb';
 
 const db = new LocalTsmDb({
   folderPath: './data',    // Required: where to store data
-  port: 27017,             // Optional: defaults to auto-discovery
-  host: '127.0.0.1',       // Optional: bind address
+  socketPath: '/tmp/my.sock', // Optional: custom socket path (default: auto-generated)
 });
 
-// Start and get connected client
-const client = await db.start();
+// 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 the client
+const users = client.db('mydb').collection('users');
+await users.insertOne({ name: 'Alice' });
 
 // Access the underlying server if needed
 const server = db.getServer();
@@ -134,16 +152,18 @@ const uri = db.getConnectionUri();
 // Check status
 console.log(db.running); // true
 
-// Stop when done
+// Stop when done (close your client first!)
+await client.close();
 await db.stop();
 ```
 
 ### Features
 
-- 🔍 **Auto Port Discovery** — Automatically finds an available port if 27017 is in use
+- 🔌 **Unix Sockets** — No port conflicts, faster IPC than TCP
 - 💾 **Automatic Persistence** — Data saved to files, survives restarts
-- 🔌 **Pre-connected Client** — `start()` returns a ready-to-use MongoDB client
+- 🪶 **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
 
@@ -492,10 +512,13 @@ let client: MongoClient;
 
 beforeAll(async () => {
   db = new LocalTsmDb({ folderPath: './test-data' });
-  client = await db.start();
+  const { connectionUri } = await db.start();
+  client = new MongoClient(connectionUri, { directConnection: true });
+  await client.connect();
 });
 
 afterAll(async () => {
+  await client.close();
   await db.stop();
 });
 
@@ -555,16 +578,19 @@ test('should insert and find user', async () => {
 ```typescript
 import { expect, tap } from '@git.zone/tstest/tapbundle';
 import { LocalTsmDb } from '@push.rocks/smartmongo';
+import { MongoClient } from 'mongodb';
 
 let db: LocalTsmDb;
+let client: MongoClient;
 
 tap.test('setup', async () => {
   db = new LocalTsmDb({ folderPath: './test-data' });
-  await db.start();
+  const { connectionUri } = await db.start();
+  client = new MongoClient(connectionUri, { directConnection: true });
+  await client.connect();
 });
 
 tap.test('should perform CRUD operations', async () => {
-  const client = db.getClient();
   const col = client.db('test').collection('items');
 
   // Create
@@ -587,6 +613,7 @@ tap.test('should perform CRUD operations', async () => {
 });
 
 tap.test('teardown', async () => {
+  await client.close();
   await db.stop();
 });
 
@@ -601,7 +628,7 @@ export default tap.start();
 @push.rocks/smartmongo
 ├── SmartMongo      → Real MongoDB memory server (mongodb-memory-server wrapper)
 ├── tsmdb           → Wire protocol server with full engine stack
-└── LocalTsmDb      → Zero-config local database (convenience wrapper)
+└── LocalTsmDb      → Lightweight Unix socket wrapper (no MongoDB driver dependency)
 ```
 
 ### TsmDB Wire Protocol Stack