@unchainedshop/mongodb 5.0.0-alpha.1 → 5.0.0-alpha.11

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 |
@@ -53,13 +49,6 @@ await stopDb(db);
 | `findLocalizedText` | Find localized text by locale with fallback |
 | `insensitiveTrimmedRegexOperator` | Create case-insensitive trimmed regex for text search |
 
-### DocumentDB Compatibility
-
-| Export | Description |
-|--------|-------------|
-| `isDocumentDBCompatModeEnabled` | Check if AWS DocumentDB compatibility mode is enabled |
-| `assertDocumentDBCompatMode` | Throw error if DocumentDB compat mode is enabled (for unsupported operations) |
-
 ### Re-exports
 
 | Export | Description |
@@ -80,9 +69,13 @@ await stopDb(db);
 
 ## Environment Variables
 
-| Variable | Description |
-|----------|-------------|
-| `UNCHAINED_DOCUMENTDB_COMPAT_MODE` | Enable AWS DocumentDB compatibility mode |
+| 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
 
@@ -126,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
 {
@@ -159,31 +152,7 @@ For full-text search, create compound text indexes:
 }
 ```
 
-**Important:** Text indexes are not supported in DocumentDB compatibility mode. Use `isDocumentDBCompatModeEnabled()` to conditionally create them.
-
-### DocumentDB Compatibility
-
-When running on AWS DocumentDB, some MongoDB features are not supported:
-
-| Feature | Alternative |
-|---------|-------------|
-| Text indexes | Use application-level search or external search service |
-| `$text` queries | Use regex queries (less performant) |
-| Some aggregation operators | Check DocumentDB documentation |
-
-Use the compatibility helpers:
-
-```typescript
-import { isDocumentDBCompatModeEnabled, assertDocumentDBCompatMode } from '@unchainedshop/mongodb';
-
-// Check before using unsupported features
-if (!isDocumentDBCompatModeEnabled()) {
-  // Create text index
-}
-
-// Throw error if DocumentDB mode is enabled
-assertDocumentDBCompatMode(); // Throws if in compat mode
-```
+`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/find-localized-text.js

@@ -7,21 +7,21 @@ const extendSelectorWithLocale = (selector, locale) => {
 };
 export const findLocalizedText = async (collection, selector, locale) => {
     const exactTranslation = await collection.findOne(extendSelectorWithLocale(selector, locale), {
-        sort: { updated: -1 },
+        sort: { updated: -1, _id: -1 },
     });
     if (exactTranslation) {
         return exactTranslation;
     }
     if (systemLocale.baseName !== locale.baseName) {
         const fallbackTranslation = await collection.findOne(extendSelectorWithLocale(selector, systemLocale), {
-            sort: { updated: -1 },
+            sort: { updated: -1, _id: -1 },
         });
         if (fallbackTranslation) {
             return fallbackTranslation;
         }
     }
     const foundText = await collection.findOne(selector, {
-        sort: { updated: -1 },
+        sort: { updated: -1, _id: -1 },
     });
     return foundText;
 };

package/lib/initDb.js

@@ -43,9 +43,9 @@ export const startDb = async (options) => {
         if (error.message?.includes('code "62"')) {
             throw new Error(`MongoDB database files in .db are incompatible with the current MongoDB version. ` +
                 `This usually happens after a MongoDB upgrade. ` +
-                `To fix this, remove the .db directory: rm -rf ${process.cwd()}/.db`, { cause: error });
+                `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/lib/mongodb-index.d.ts

@@ -8,7 +8,6 @@ export { findPreservingIds } from './find-preserving-ids.ts';
 export { buildSortOptions } from './build-sort-option.ts';
 export { findLocalizedText } from './find-localized-text.ts';
 export { insensitiveTrimmedRegexOperator, escapeRegexString, } from './insensitive-trimmed-regex-operator.ts';
-export * from './documentdb-compat-mode.ts';
 export { mongodb };
 export interface LogFields {
     log: ({

package/lib/mongodb-index.js

@@ -7,5 +7,4 @@ export { findPreservingIds } from "./find-preserving-ids.js";
 export { buildSortOptions } from "./build-sort-option.js";
 export { findLocalizedText } from "./find-localized-text.js";
 export { insensitiveTrimmedRegexOperator, escapeRegexString, } from "./insensitive-trimmed-regex-operator.js";
-export * from "./documentdb-compat-mode.js";
 export { mongodb };

package/package.json

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

package/lib/documentdb-compat-mode.d.ts

@@ -1,2 +0,0 @@
-export declare function assertDocumentDBCompatMode(): void;
-export declare const isDocumentDBCompatModeEnabled: () => boolean;

package/lib/documentdb-compat-mode.js

@@ -1,5 +0,0 @@
-export function assertDocumentDBCompatMode() {
-    if (isDocumentDBCompatModeEnabled())
-        throw new Error('Text search is not supported in DocumentDB Compatibility Mode');
-}
-export const isDocumentDBCompatModeEnabled = () => Boolean(process.env.UNCHAINED_DOCUMENTDB_COMPAT_MODE);