@unchainedshop/mongodb 4.8.29 → 5.0.0-alpha.10

package/README.md

@@ -14,21 +14,16 @@ npm install @unchainedshop/mongodb
 ## Usage
 
 ```typescript
-import { initDb, startDb, stopDb, generateDbObjectId } from '@unchainedshop/mongodb';
+import { initDb, stopDb, generateDbObjectId } from '@unchainedshop/mongodb';
 
-// Initialize the database connection
-const db = await initDb({
-  connectionString: 'mongodb://localhost:27017/unchained',
-});
+// Connect to MONGO_URL, or start a local MongoDB instance when it is unset
+const db = await initDb();
 
-// Start the database
-await startDb(db);
-
-// Generate a new ObjectId
+// Generate a random hexadecimal string ID (24 characters by default)
 const id = generateDbObjectId();
 
 // Stop the database when shutting down
-await stopDb(db);
+await stopDb();
 ```
 
 ## API Overview
@@ -37,15 +32,16 @@ await stopDb(db);
 
 | Export | Description |
 |--------|-------------|
-| `initDb` | Initialize MongoDB connection with connection string |
-| `startDb` | Start the database connection |
+| `initDb` | Connect using `MONGO_URL`, or start and connect to local MongoDB |
+| `startDb` | Start a local MongoDB server and return its connection URL |
 | `stopDb` | Close the database connection |
+| `createDatabaseResource` | Create an async-disposable database resource |
 
 ### Query Utilities
 
 | Export | Description |
 |--------|-------------|
-| `generateDbObjectId` | Generate a new MongoDB ObjectId |
+| `generateDbObjectId` | Generate a random hexadecimal string ID |
 | `generateDbFilterById` | Create a filter object for querying by ID |
 | `buildDbIndexes` | Create indexes for a collection |
 | `findPreservingIds` | Find documents while preserving ID order |
@@ -71,6 +67,16 @@ await stopDb(db);
 | `MigrationRepository` | Interface for managing migrations |
 | `ModuleInput` | Interface for core module initialization input |
 
+## Environment Variables
+
+| Variable | Purpose |
+|----------|---------|
+| `MONGO_URL` | External MongoDB connection URL; when unset, start local MongoDB |
+| `PORT` | Local MongoDB defaults to this port plus one (`4011` if unset) |
+| `NODE_ENV` | `test` selects ephemeral storage for local MongoDB |
+
+`initDb()`, `startDb()`, and `createDatabaseResource()` accept `{ forceInMemory, port }`. Local non-test data is stored in `.db` under the current working directory; `stopDb()` preserves those persistent files.
+
 ## Best Practices
 
 ### Collection Naming Conventions
@@ -113,7 +119,7 @@ Queries should filter by `deleted: null` to exclude soft-deleted documents.
 
 #### Sparse Indexes
 
-Use sparse indexes when the indexed field may be null/undefined for most documents:
+Use sparse indexes when the indexed field is absent from most documents:
 
 ```typescript
 {
@@ -146,7 +152,7 @@ For full-text search, create compound text indexes:
 }
 ```
 
-**Note:** Text indexes are supported natively on MongoDB 4.4+, AWS DocumentDB 5.0+, and FerretDB 2.x. If you target AWS DocumentDB ≤4.0 or FerretDB 1.x, use an external search service instead (Elasticsearch, Algolia, Meilisearch).
+`buildDbIndexes()` attempts the indexes supplied by each collection, including any text indexes. It does not detect database vendors or versions. Check your database's support for the index definitions used by your modules.
 
 ## License
 

package/lib/initDb.js

@@ -26,7 +26,7 @@ export const startDb = async (options) => {
     try {
         mongod = MongoMemoryServer.create({
             instance: useInMemory
-                ? { dbName: 'test', port: mongoPort, storageEngine: 'ephemeralForTest' }
+                ? { dbName: 'test', port: mongoPort, storageEngine: 'wiredTiger' }
                 : {
                     dbPath: `${process.cwd()}/.db`,
                     storageEngine: 'wiredTiger',
@@ -45,7 +45,7 @@ export const startDb = async (options) => {
                 `This usually happens after a MongoDB upgrade. ` +
                 `To fix this, remove the .db directory: rm -rf ${process.cwd()}/.db`, { cause: e });
         }
-        throw error;
+        throw e;
     }
     throw new Error("Can't connect to MongoDB: Could not start mongodb-memory-server and MONGO_URL env is not set");
 };

package/package.json

@@ -1,6 +1,9 @@
 {
   "name": "@unchainedshop/mongodb",
-  "version": "4.8.29",
+  "version": "5.0.0-alpha.10",
+  "files": [
+    "lib"
+  ],
   "description": "MongoDB database abstraction layer for the Unchained Engine",
   "main": "lib/mongodb-index.js",
   "types": "lib/mongodb-index.d.ts",
@@ -33,8 +36,8 @@
   },
   "homepage": "https://github.com/unchainedshop/unchained#readme",
   "dependencies": {
-    "@unchainedshop/logger": "^4.8.27",
-    "@unchainedshop/utils": "^4.8.27"
+    "@unchainedshop/logger": "^5.0.0-alpha.10",
+    "@unchainedshop/utils": "^5.0.0-alpha.10"
   },
   "peerDependencies": {
     "@mongodb-js/zstd": ">= 7 < 8",
@@ -54,6 +57,6 @@
   },
   "devDependencies": {
     "@types/node": "^26.2.0",
-    "typescript": "^5.8.3"
+    "typescript": "^6.0.3"
   }
 }