v7.0.0

.gitea/workflows/default_nottags.yaml

@@ -6,8 +6,8 @@ on:
       - '**'
 
 env:
-  IMAGE: registry.gitlab.com/hosttoday/ht-docker-node:npmci
-  NPMCI_COMPUTED_REPOURL: https://${{gitea.repository_owner}}:${{secrets.GITEA_TOKEN}}@gitea.lossless.digital/${{gitea.repository}}.git
+  IMAGE: code.foss.global/host.today/ht-docker-node:npmci
+  NPMCI_COMPUTED_REPOURL: https://${{gitea.repository_owner}}:${{secrets.GITEA_TOKEN}}@/${{gitea.repository}}.git
   NPMCI_TOKEN_NPM: ${{secrets.NPMCI_TOKEN_NPM}}
   NPMCI_TOKEN_NPM2: ${{secrets.NPMCI_TOKEN_NPM2}}
   NPMCI_GIT_GITHUBTOKEN: ${{secrets.NPMCI_GIT_GITHUBTOKEN}}
@@ -26,7 +26,7 @@ jobs:
       - name: Install pnpm and npmci
         run: |
           pnpm install -g pnpm
-          pnpm install -g @shipzone/npmci
+          pnpm install -g @ship.zone/npmci
 
       - name: Run npm prepare
         run: npmci npm prepare

.gitea/workflows/default_tags.yaml

@@ -6,8 +6,8 @@ on:
       - '*'
 
 env:
-  IMAGE: registry.gitlab.com/hosttoday/ht-docker-node:npmci
-  NPMCI_COMPUTED_REPOURL: https://${{gitea.repository_owner}}:${{secrets.GITEA_TOKEN}}@gitea.lossless.digital/${{gitea.repository}}.git
+  IMAGE: code.foss.global/host.today/ht-docker-node:npmci
+  NPMCI_COMPUTED_REPOURL: https://${{gitea.repository_owner}}:${{secrets.GITEA_TOKEN}}@/${{gitea.repository}}.git
   NPMCI_TOKEN_NPM: ${{secrets.NPMCI_TOKEN_NPM}}
   NPMCI_TOKEN_NPM2: ${{secrets.NPMCI_TOKEN_NPM2}}
   NPMCI_GIT_GITHUBTOKEN: ${{secrets.NPMCI_GIT_GITHUBTOKEN}}
@@ -26,7 +26,7 @@ jobs:
       - name: Prepare
         run: |
           pnpm install -g pnpm
-          pnpm install -g @shipzone/npmci
+          pnpm install -g @ship.zone/npmci
           npmci npm prepare
 
       - name: Audit production dependencies
@@ -54,7 +54,7 @@ jobs:
       - name: Prepare
         run: |
           pnpm install -g pnpm
-          pnpm install -g @shipzone/npmci
+          pnpm install -g @ship.zone/npmci
           npmci npm prepare
 
       - name: Test stable
@@ -82,7 +82,7 @@ jobs:
       - name: Prepare
         run: |
           pnpm install -g pnpm
-          pnpm install -g @shipzone/npmci
+          pnpm install -g @ship.zone/npmci
           npmci npm prepare
 
       - name: Release
@@ -104,7 +104,7 @@ jobs:
       - name: Prepare
         run: |
           pnpm install -g pnpm
-          pnpm install -g @shipzone/npmci
+          pnpm install -g @ship.zone/npmci
           npmci npm prepare
 
       - name: Code quality

.gitignore

@@ -3,7 +3,6 @@
 # artifacts
 coverage/
 public/
-pages/
 
 # installs
 node_modules/
@@ -17,4 +16,4 @@ node_modules/
 dist/
 dist_*/
 
-# custom
+#------# custom

.smartconfig.json

@@ -1,11 +1,11 @@
 {
-  "gitzone": {
+  "@git.zone/cli": {
     "projectType": "npm",
     "module": {
       "githost": "code.foss.global",
       "gitscope": "push.rocks",
       "gitrepo": "smartmongo",
-      "description": "A module for creating and managing a local MongoDB instance for testing purposes.",
+      "description": "A MongoDB memory server toolkit for testing and development, providing real MongoDB replica sets via mongodb-memory-server.",
       "npmPackagename": "@push.rocks/smartmongo",
       "license": "MIT",
       "projectDomain": "push.rocks",
@@ -18,13 +18,23 @@
         "database management",
         "typescript"
       ]
-    }
+    },
+    "release": {
+      "registries": [
+        "https://verdaccio.lossless.digital",
+        "https://registry.npmjs.org"
+      ],
+      "accessLevel": "public"
+    },
+    "services": [
+      "mongodb",
+      "minio"
+    ]
   },
-  "npmci": {
-    "npmGlobalTools": [],
-    "npmAccessLevel": "public"
-  },
-  "tsdoc": {
+  "@git.zone/tsdoc": {
     "legal": "\n## License and Legal Information\n\nThis repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository. \n\n**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.\n\n### Trademarks\n\nThis project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.\n\n### Company Information\n\nTask Venture Capital GmbH  \nRegistered at District court Bremen HRB 35230 HB, Germany\n\nFor any legal inquiries or if you require further information, please contact us via email at hello@task.vc.\n\nBy using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.\n"
+  },
+  "@ship.zone/szci": {
+    "npmGlobalTools": []
   }
 }

.vscode/settings.json

@@ -1,7 +1,7 @@
 {
   "json.schemas": [
     {
-      "fileMatch": ["/npmextra.json"],
+      "fileMatch": ["/.smartconfig.json"],
       "schema": {
         "type": "object",
         "properties": {

changelog.md

@@ -1,5 +1,145 @@
 # Changelog
 
+## 2026-03-26 - 7.0.0 - BREAKING CHANGE(api)
+reduce the package to the SmartMongo memory replica set API and remove bundled TsmDB and LocalTsmDb modules
+
+- remove exports and source code for TsmDB, LocalTsmDb, and related utilities, handlers, storage adapters, and tests
+- flatten SmartMongo into the main package entrypoint and keep mongodb-memory-server-based replica set startup as the core feature
+- trim dependencies and documentation to focus the package on in-memory MongoDB replica sets for testing and development
+
+## 2026-03-26 - 5.1.1 - fix(build)
+migrate smartconfig metadata and refresh build dependencies
+
+- replace npmextra.json with .smartconfig.json and update packaged config file inclusion
+- switch the build script to tsbuild tsfolders
+- update core build and runtime dependencies and add explicit TypeScript type annotations to satisfy newer tooling
+
+## 2026-02-03 - 5.1.0 - feat(localtsmdb)
+export ILocalTsmDbConnectionInfo and expand LocalTsmDb/TsmDB documentation and examples
+
+- Exported new type ILocalTsmDbConnectionInfo from ts_local (ts/index.ts)
+- Added LocalTsmDb configuration example, methods table, and ConnectionInfo interface to README
+- Documented Unix socket vs TCP connection modes and updated usage examples (TCP and socket examples)
+- Expanded TsmDB docs: additional server properties, aggregation stages, regex examples, index operations, database ops, checksums, and wire protocol commands
+- Updated architecture notes to include Unix socket support and new engine components (QueryEngine, UpdateEngine, AggregationEngine)
+
+## 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
+
+- Add new tests: test.tsmdb.checksum.ts — CRC32 and document checksum utilities (add/verify/remove)
+- Add new tests: test.tsmdb.queryplanner.ts — QueryPlanner plans, index usage, selectivity, explain output, and edge cases
+- Add new tests: test.tsmdb.indexengine.ts — Index creation, unique/sparse options, candidate selection, and constraints
+- Add new tests: test.tsmdb.session.ts — Session lifecycle, touch/refresh/close, extractSessionId handling
+- Add new tests: test.tsmdb.wal.ts — WAL initialization, LSN increments, logging/recovery for inserts/updates/deletes, binary and nested data handling
+- Tests only — no production API changes; increases test coverage
+- Recommend patch bump from 4.1.0 to 4.1.1
+
+## 2026-02-01 - 4.1.0 - feat(readme)
+expand README with storage integrity, WAL, query planner, session & transaction docs; update test script to enable verbose logging and increase timeout
+
+- Updated npm test script to run tstest with --verbose, --logfile and --timeout 60 to improve test output and avoid timeouts.
+- Extensive README additions: file storage adapter examples with checksum options, write-ahead logging (WAL) usage and recovery, query planner examples, index and query execution details, session and transaction examples and features.
+- Wire protocol / features table updated to include Transactions and Sessions and added admin commands (dbStats, collStats).
+- Architecture diagram and component list updated to include QueryPlanner, SessionEngine, TransactionEngine and WAL; storage layer annotated with checksums and WAL.
+- Minor example import tweak: MongoClient import now includes Db type in test examples.
+
+## 2026-02-01 - 4.0.0 - BREAKING CHANGE(storage,engine,server)
+add session & transaction management, index/query planner, WAL and checksum support; integrate index-accelerated queries and update storage API (findByIds) to enable index optimizations
+
+- Add SessionEngine with session lifecycle, auto-abort of transactions on expiry and session tracking in CommandRouter and AdminHandler.
+- Introduce TransactionEngine integrations in CommandRouter and AdminHandler; handlers now support start/commit/abort transaction workflows.
+- Add IndexEngine enhancements including a simple B-tree and hash map optimizations; integrate index usage into Find/Count/Insert/Update/Delete handlers for index-accelerated queries and index maintenance on mutations.
+- Add QueryPlanner to choose IXSCAN vs COLLSCAN and provide explain plans.
+- Add WAL (write-ahead log) for durability, with LSNs, checkpoints and recovery APIs.
+- Add checksum utilities and FileStorageAdapter support for checksums (enableChecksums/strictChecksums), with verification on read and optional strict failure behavior.
+- IStorageAdapter interface changed to include findByIds; MemoryStorageAdapter and FileStorageAdapter implement findByIds to support index lookups.
+- Exported API additions: WAL, QueryPlanner, SessionEngine, checksum utilities; CommandRouter now caches IndexEngines and exposes transaction/session engines.
+- Breaking change: the IStorageAdapter interface change requires third-party storage adapters to implement the new findByIds method.
+
+## 2026-02-01 - 3.0.0 - BREAKING CHANGE(tsmdb)
+rename CongoDB to TsmDB and relocate/rename wire-protocol server implementation and public exports
+
+- Project refactor renames the in-memory wire-protocol server from CongoDB -> TsmDB (identifiers, files and namespaces changed).
+- ts/index.ts now exports tsmdb instead of congodb (public API change; consumers must update imports).
+- All congodb sources under ts/congodb were removed and equivalent implementations added under ts/tsmdb (errors, engines, storage adapters, server, handlers, WireProtocol, types).
+- Readme and usage examples updated to reference TsmDB/tsmdb and example code updated accordingly.
+- Tests renamed/updated from test.congodb.ts -> test.tsmdb.ts to exercise the new tsmdb export and server.
+
+## 2026-01-31 - 2.2.0 - feat(readme)
+update README with expanded documentation covering CongoDB and SmartMongo, installation, quick start examples, architecture, usage examples, and legal/company information
+
+- Completely expanded README: added detailed overview for SmartMongo and new CongoDB (wire-protocol server)
+- Added Quick Start examples for both SmartMongo and CongoDB (TypeScript/ESM snippets)
+- Included installation instructions for npm and pnpm and issue reporting/security guidance
+- Added architecture diagram, example tests, and storage/engine descriptions
+- Clarified license, trademark, and company contact information
+- Large non-functional documentation-only change (+398 -44)
+
+## 2026-01-31 - 2.1.0 - feat(congodb)
+implement CongoDB MongoDB wire-protocol compatible in-memory server and APIs
+
+- Add full congodb module: CongoServer, WireProtocol, CommandRouter and handlers (Hello, Insert, Find, Update, Delete, Aggregate, Index, Admin).
+- Implement query/update/aggregation/index/transaction engines (QueryEngine, UpdateEngine, AggregationEngine, IndexEngine, TransactionEngine) and OpLog for change stream support.
+- Add storage adapters: in-memory (MemoryStorageAdapter) and file-backed (FileStorageAdapter) with persistence and oplog support.
+- Introduce types/interfaces and rich error classes (CongoErrors) plus congodb.plugins re-exports (bson, mingo, smartfs, smartpath, smartrx).
+- Add many server-side utilities: IndexEngine, Aggregation helpers ($lookup, $graphLookup, $merge, $facet, $unionWith), cursor management and command routing.
+- Add integration tests for CongoDB using official mongodb MongoClient (test/test.congodb.ts) and update unit test entry (test/test.ts) to use tstest tapbundle.
+- Export congodb from ts/index.ts and update package.json: bump devDependencies, add runtime deps (mongodb, bson, mingo, mingo), add new @push.rocks/* deps and dev tool versions.
+- Update readme.hints.md with CongoDB architecture, usage examples and supported commands.
+- Update npmextra.json metadata and release/registry config and reorganize tsdoc mappings.
+
+## 2025-11-17 - 2.0.14 - fix(smartmongo.plugins)
+Use default import for mongodb-memory-server (Deno compatibility), update hints and bump package version to 2.0.13
+
+- Replace namespace import with default import for mongodb-memory-server to ensure compatibility with Deno (ts/smartmongo.plugins.ts).
+- Add readme.hints.md documenting the Deno compatibility change and the reason for using a default import.
+- Bump package.json version to 2.0.13.
+- Note: ts/00_commitinfo_data.ts still lists version 2.0.12 and may need to be updated to match package.json.
+
+## 2025-04-06 - 2.0.12 - fix(ci/config)
+Update CI workflow environment variables, refine package metadata, and improve configuration settings
+
+- Updated workflow YAML files to use new IMAGE and npmci package names
+- Adjusted package.json homepage, added bugs field and pnpm overrides
+- Minor formatting improvements in readme.md and .gitignore
+- Enhanced tsconfig with baseUrl and paths for improved module resolution
+
 ## 2025-04-06 - 2.0.11 - fix(dependencies)
 Update dependency names and versions in CI workflows and package configuration
 

license

@@ -1,4 +1,4 @@
-Copyright (c) 2021 Lossless GmbH (hello@lossless.com)
+Copyright (c) 2021 Task Venture Capital GmbH (hello@task.vc)
 
 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.json

@@ -1,32 +1,33 @@
 {
   "name": "@push.rocks/smartmongo",
-  "version": "2.0.11",
+  "version": "7.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",
+  "description": "A MongoDB memory server toolkit for testing and development, providing real MongoDB replica sets via mongodb-memory-server.",
+  "exports": {
+    ".": "./dist_ts/index.js"
+  },
   "type": "module",
-  "author": "Lossless GmbH",
+  "author": "Task Venture Capital GmbH",
   "license": "MIT",
   "scripts": {
-    "test": "(tstest test/ --web)",
-    "build": "(tsbuild --web --allowimplicitany)",
+    "test": "(tstest test/. --verbose --logfile --timeout 60)",
+    "build": "(tsbuild tsfolders)",
     "buildDocs": "tsdoc"
   },
   "devDependencies": {
-    "@git.zone/tsbuild": "^2.1.66",
-    "@git.zone/tsbundle": "^2.0.8",
-    "@git.zone/tsrun": "^1.2.44",
-    "@git.zone/tstest": "^1.0.77",
-    "@push.rocks/tapbundle": "^5.0.12",
-    "@types/node": "^22.14.0"
+    "@git.zone/tsbuild": "^4.4.0",
+    "@git.zone/tsbundle": "^2.10.0",
+    "@git.zone/tsrun": "^2.0.2",
+    "@git.zone/tstest": "^3.6.1",
+    "@types/node": "^25.5.0",
+    "mongodb": "^7.1.1"
   },
   "dependencies": {
-    "@push.rocks/mongodump": "^1.0.7",
-    "@push.rocks/smartdata": "^5.0.23",
-    "@push.rocks/smartpath": "^5.0.11",
-    "@push.rocks/smartpromise": "^4.0.3",
-    "mongodb-memory-server": "^10.1.4"
+    "@push.rocks/mongodump": "^1.1.0",
+    "@push.rocks/smartdata": "^7.1.3",
+    "@push.rocks/smartpath": "^6.0.0",
+    "@push.rocks/smartpromise": "^4.2.3",
+    "mongodb-memory-server": "^11.0.1"
   },
   "browserslist": [
     "last 1 chrome versions"
@@ -40,22 +41,27 @@
     "dist_ts_web/**/*",
     "assets/**/*",
     "cli.js",
-    "npmextra.json",
+    ".smartconfig.json",
     "readme.md"
   ],
   "keywords": [
     "mongodb",
     "testing",
-    "local database",
     "replica set",
     "memory server",
     "database management",
     "typescript"
   ],
-  "homepage": "https://code.foss.global/push.rocks/smartmongo",
+  "homepage": "https://code.foss.global/push.rocks/smartmongo#readme",
   "repository": {
     "type": "git",
     "url": "https://code.foss.global/push.rocks/smartmongo.git"
   },
-  "packageManager": "pnpm@10.7.0+sha512.6b865ad4b62a1d9842b61d674a393903b871d9244954f652b8842c2b553c72176b278f64c463e52d40fff8aba385c235c8c9ecf5cc7de4fd78b8bb6d49633ab6"
+  "packageManager": "pnpm@10.7.0+sha512.6b865ad4b62a1d9842b61d674a393903b871d9244954f652b8842c2b553c72176b278f64c463e52d40fff8aba385c235c8c9ecf5cc7de4fd78b8bb6d49633ab6",
+  "bugs": {
+    "url": "https://code.foss.global/push.rocks/smartmongo/issues"
+  },
+  "pnpm": {
+    "overrides": {}
+  }
 }

pnpm-workspace.yaml

@@ -1,4 +0,0 @@
-onlyBuiltDependencies:
-  - esbuild
-  - mongodb-memory-server
-  - puppeteer

readme.hints.md

@@ -1 +1,84 @@
- 
+# 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
+```typescript
+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

readme.md

@@ -1,103 +1,190 @@
 # @push.rocks/smartmongo
-create a local mongodb for testing
+
+A MongoDB memory server toolkit for testing and development — spin up real MongoDB replica sets on the fly with zero configuration. 🚀
 
 ## Install
 
-To start using @push.rocks/smartmongo in your project, you first need to install it via npm. You can do this by running the following command in your terminal:
-
 ```bash
+pnpm add -D @push.rocks/smartmongo
+# or
 npm install @push.rocks/smartmongo --save-dev
 ```
 
-This will add `@push.rocks/smartmongo` as a development dependency to your project because it's typically used for testing purposes.
+## Issue Reporting and Security
 
-## Usage
+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.
 
-The `@push.rocks/smartmongo` package provides a convenient way to spin up a local MongoDB instance, primarily for testing purposes. It's designed to simplify the process of configuring and managing a MongoDB replica set during development or in CI/CD pipelines. Below, we present a comprehensive guide on how to utilize the full feature set of this module, employing ESM syntax and TypeScript.
+## What It Does
 
-### Setting Up
+`@push.rocks/smartmongo` wraps [mongodb-memory-server](https://github.com/nodkz/mongodb-memory-server) to give you a **real MongoDB replica set** running entirely in memory. It downloads and manages the MongoDB binary for you — just `createAndStart()` and you're good to go.
 
-To get started, you must first import the `SmartMongo` class from the package. This class is responsible for handling the MongoDB instances.
+Perfect for:
+
+- ⚡ **Integration tests** that need 100% MongoDB compatibility
+- 🧪 **CI/CD pipelines** where you can't install MongoDB system-wide
+- 🔬 **Development environments** that need a disposable database
+- 📦 **Data dump/export** with built-in support for dumping collections to disk
+
+> 💡 **Looking for a lightweight, pure-TypeScript alternative?** Check out [`@push.rocks/smartdb`](https://code.foss.global/push.rocks/smartdb) — a wire-protocol-compatible MongoDB server with zero binary dependencies, instant startup, and file-based persistence.
+
+## Quick Start
 
 ```typescript
 import { SmartMongo } from '@push.rocks/smartmongo';
+
+// Start a MongoDB replica set (downloads binary automatically on first run)
+const mongo = await SmartMongo.createAndStart();
+
+// Get connection details for your app or ORM
+const descriptor = await mongo.getMongoDescriptor();
+console.log(descriptor.mongoDbUrl);
+// => mongodb://127.0.0.1:xxxxx/?replicaSet=testset
+
+// Use with any MongoDB client
+import { MongoClient } from 'mongodb';
+const client = new MongoClient(descriptor.mongoDbUrl);
+await client.connect();
+
+const db = client.db(descriptor.mongoDbName);
+await db.collection('users').insertOne({ name: 'Alice', role: 'admin' });
+
+const user = await db.collection('users').findOne({ name: 'Alice' });
+console.log(user); // { _id: ObjectId(...), name: 'Alice', role: 'admin' }
+
+// Clean up
+await client.close();
+await mongo.stop();
 ```
 
-### Creating and Starting a MongoDB Instance
+## API
 
-With `SmartMongo`, you can easily create and start a MongoDB replica set. You can specify the number of replica instances; however, if not specified, it defaults to 1.
+### `SmartMongo.createAndStart(replCount?: number)`
+
+Static factory method that creates and starts a SmartMongo instance.
 
 ```typescript
-async function setupMongoDB() {
-  const smartMongoInstance = await SmartMongo.createAndStart(1); // Number of replicas is optional
-  return smartMongoInstance;
-}
+// Single replica (default)
+const mongo = await SmartMongo.createAndStart();
 
-const myDbInstance = await setupMongoDB();
+// Multi-replica for testing replication scenarios
+const mongo = await SmartMongo.createAndStart(3);
 ```
 
-After invoking `createAndStart`, an instance of MongoDB is spun up and is ready for use. The `createAndStart` function returns a `SmartMongo` instance which can be interacted with for further operations.
+### `getMongoDescriptor()`
 
-### Accessing MongoDB Connection Information
-
-After instantiation, you might want to connect your application or test suite to the MongoDB instance. The `getMongoDescriptor` method facilitates this by providing essential connection details.
+Returns an `IMongoDescriptor` with the connection URL and database name, compatible with `@push.rocks/smartdata` and other push.rocks modules.
 
 ```typescript
-const mongoDescriptor = await myDbInstance.getMongoDescriptor();
-console.log(mongoDescriptor.mongoDbUrl); // Use this URL to connect with Mongoose or MongoDB clients.
+const descriptor = await mongo.getMongoDescriptor();
+// {
+//   mongoDbName: 'smartmongo_testdatabase',
+//   mongoDbUrl: 'mongodb://127.0.0.1:xxxxx/?replicaSet=testset'
+// }
 ```
 
-### Stopping and Cleaning Up
+### `stop()`
 
-Once your tests have completed or you're done using the MongoDB instance, it’s crucial to properly stop and clean up the resources. `@push.rocks/smartmongo` provides two methods for this purpose:
-
-1. **stop()**: Stops the MongoDB instance without persisting any data.
-   
-   ```typescript
-   await myDbInstance.stop();
-   ```
-
-2. **stopAndDumpToDir(dirPath)**: Stops the MongoDB instance and persists the data to the specified directory. This is useful if you need to examine the data post-test or reuse it in subsequent runs.
-
-   ```typescript
-   await myDbInstance.stopAndDumpToDir('./path/to/dump');
-   ```
-
-### Advanced Usage
-
-`@push.rocks/smartmongo` also provides advanced features for dumping the database and configuring MongoDB replica sets. These features can be particularly useful for complex testing scenarios or when specific MongoDB behaviors need to be emulated.
-
-#### Dumping Data
-
-To dump the MongoDB data for inspection or backup purposes, use the `stopAndDumpToDir` method. This method optionally takes a function to customize the naming scheme of the dumped files based on the document content.
+Stops the replica set and cleans up all resources (temporary files, processes).
 
 ```typescript
-await myDbInstance.stopAndDumpToDir('./path/to/dump', (doc) => {
-  return `customNameBasedOnDoc-${doc._id}.bson`;
+await mongo.stop();
+```
+
+### `stopAndDumpToDir(dir, nameFunction?, emptyDir?)`
+
+Stops the replica set **and** dumps all collections to a directory on disk before cleanup. Useful for debugging or archiving test data.
+
+```typescript
+// Dump all collections with default naming
+await mongo.stopAndDumpToDir('./test-output');
+
+// With custom file naming
+await mongo.stopAndDumpToDir('./test-output', (doc) => `${doc.collection}-${doc._id}.bson`);
+
+// Keep existing files in the directory (don't empty it first)
+await mongo.stopAndDumpToDir('./test-output', undefined, false);
+```
+
+### `readyPromise`
+
+A promise that resolves when the replica set is fully started and ready to accept connections.
+
+```typescript
+const mongo = new SmartMongo();
+mongo.start(2); // non-blocking
+await mongo.readyPromise; // wait for startup
+```
+
+## Testing Examples
+
+### With @git.zone/tstest (tapbundle)
+
+```typescript
+import { expect, tap } from '@git.zone/tstest/tapbundle';
+import { SmartMongo } from '@push.rocks/smartmongo';
+import { MongoClient } from 'mongodb';
+
+let mongo: SmartMongo;
+let client: MongoClient;
+
+tap.test('setup', async () => {
+  mongo = await SmartMongo.createAndStart();
+  const { mongoDbUrl, mongoDbName } = await mongo.getMongoDescriptor();
+  client = new MongoClient(mongoDbUrl);
+  await client.connect();
 });
+
+tap.test('should insert and query documents', async () => {
+  const col = client.db('test').collection('items');
+  await col.insertOne({ name: 'Widget', price: 9.99 });
+
+  const item = await col.findOne({ name: 'Widget' });
+  expect(item?.price).toEqual(9.99);
+});
+
+tap.test('teardown', async () => {
+  await client.close();
+  await mongo.stop();
+});
+
+export default tap.start();
 ```
 
-Using `@push.rocks/smartmongo` significantly simplifies the process of managing MongoDB instances for local testing environments. It abstracts away the complexity of starting, operating, and tearing down MongoDB replica sets, allowing developers to focus on building and testing their applications.
+### With @push.rocks/smartdata
 
-### Conclusion
+```typescript
+import { SmartMongo } from '@push.rocks/smartmongo';
+import { SmartdataDb } from '@push.rocks/smartdata';
 
-`@push.rocks/smartmongo` serves as a powerful tool in a developer's arsenal for efficiently configuring, running, and managing MongoDB instances in testing scenarios. By following the above guide, developers can leverage MongoDB in their projects with minimal setup and gain valuable insights into their applications' data interactions in a controlled and reproducible environment.
+const mongo = await SmartMongo.createAndStart();
+const descriptor = await mongo.getMongoDescriptor();
+
+const db = new SmartdataDb(descriptor);
+await db.init();
+
+// Use smartdata models against the memory server...
+
+await db.close();
+await mongo.stop();
+```
 
 ## License and Legal Information
 
-This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository. 
+This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [LICENSE](./LICENSE) file.
 
 **Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
 
 ### Trademarks
 
-This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.
+This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.
+
+Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.
 
 ### Company Information
 
-Task Venture Capital GmbH  
-Registered at District court Bremen HRB 35230 HB, Germany
+Task Venture Capital GmbH
+Registered at District Court Bremen HRB 35230 HB, Germany
 
-For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.
+For any legal inquiries or further information, please contact us via email at hello@task.vc.
 
 By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.

test/test.ts

@@ -1,4 +1,4 @@
-import { expect, tap } from '@push.rocks/tapbundle';
+import { tap } from '@git.zone/tstest/tapbundle';
 import * as smartmongo from '../ts/index.js';
 
 let smartmongoInstance: smartmongo.SmartMongo;
@@ -11,4 +11,4 @@ tap.test('should stop the instance', async () => {
   await smartmongoInstance.stopAndDumpToDir('.nogit/');
 });
 
-tap.start();
+export default tap.start();

ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/smartmongo',
-  version: '2.0.11',
-  description: 'A module for creating and managing a local MongoDB instance for testing purposes.'
+  version: '7.0.0',
+  description: 'A MongoDB memory server toolkit for testing and development, providing real MongoDB replica sets via mongodb-memory-server.'
 }

ts/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/index.ts

@@ -1,71 +1,4 @@
 import { commitinfo } from './00_commitinfo_data.js';
-import * as plugins from './smartmongo.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();
-  }
-}
+export { SmartMongo } from './classes.smartmongo.js';
+export { commitinfo };

ts/plugins.ts

@@ -7,6 +7,6 @@ import * as smartpromise from '@push.rocks/smartpromise';
 export { mongodump, smartdata, smartpath, smartpromise };
 
 // thirdparty
-import * as mongoPlugin from 'mongodb-memory-server';
+import mongoPlugin from 'mongodb-memory-server';
 
 export { mongoPlugin };

tsconfig.json

@@ -1,7 +1,5 @@
 {
   "compilerOptions": {
-    "experimentalDecorators": true,
-    "useDefineForClassFields": false,
     "target": "ES2022",
     "module": "NodeNext",
     "moduleResolution": "NodeNext",