@unchainedshop/mongodb 4.5.0 → 4.6.0

package/README.md

@@ -84,6 +84,107 @@ await stopDb(db);
 |----------|-------------|
 | `UNCHAINED_DOCUMENTDB_COMPAT_MODE` | Enable AWS DocumentDB compatibility mode |
 
+## Best Practices
+
+### Collection Naming Conventions
+
+Unchained uses the following collection naming patterns:
+
+| Pattern | Example | Usage |
+|---------|---------|-------|
+| Plural lowercase | `products`, `orders`, `users` | Main entity collections |
+| Underscore-separated | `product_texts`, `product_media` | Related sub-collections |
+
+**Note:** Some legacy collections may use different patterns. When creating new collections, prefer the underscore-separated pattern for sub-collections.
+
+### Index Guidelines
+
+#### Using `buildDbIndexes`
+
+Always use the `buildDbIndexes` helper to create indexes:
+
+```typescript
+import { buildDbIndexes } from '@unchainedshop/mongodb';
+
+await buildDbIndexes<Product>(Products, [
+  { index: { deleted: 1 } },           // Soft delete support
+  { index: { status: 1 } },            // Query by status
+  { index: { slugs: 1 } },             // URL slug lookups
+  { index: { tags: 1 } },              // Tag filtering
+]);
+```
+
+#### Soft Delete Pattern
+
+Collections using soft delete should always include a `deleted` index:
+
+```typescript
+{ index: { deleted: 1 } }
+```
+
+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:
+
+```typescript
+{
+  index: { optionalField: 1 },
+  options: { sparse: true }
+}
+```
+
+Sparse indexes are smaller and more efficient when the field is rarely present.
+
+#### Text Indexes
+
+For full-text search, create compound text indexes:
+
+```typescript
+{
+  index: {
+    _id: 'text',
+    name: 'text',
+    description: 'text',
+  } as any,
+  options: {
+    weights: {
+      _id: 10,
+      name: 5,
+      description: 1,
+    },
+    name: 'fulltext_search',
+  },
+}
+```
+
+**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
+```
+
 ## License
 
 EUPL-1.2

package/lib/initDb.d.ts

@@ -1,9 +1,20 @@
 import type { Db } from 'mongodb';
+import { MongoClient } from 'mongodb';
 export declare const startDb: (options?: {
     forceInMemory?: boolean;
+    port?: number;
 }) => Promise<string>;
 export declare const stopDb: () => Promise<void>;
+export interface DatabaseResource extends AsyncDisposable {
+    db: Db;
+    client: MongoClient;
+}
+export declare const createDatabaseResource: (options?: {
+    forceInMemory?: boolean;
+    port?: number;
+}) => Promise<DatabaseResource>;
 declare const initDb: (options?: {
     forceInMemory?: boolean;
+    port?: number;
 }) => Promise<Db>;
 export { initDb };

package/lib/initDb.js

@@ -1,8 +1,9 @@
 import { MongoClient } from 'mongodb';
 let zstdEnabled = false;
-let mongod;
-let mongoClient;
-const { PORT = '4010' } = process.env;
+let mongod = null;
+let mongoClient = null;
+let useEphemeralStorage = false;
+const CLEANUP_TIMEOUT_MS = 10000;
 try {
     await import('@mongodb-js/zstd');
     zstdEnabled = true;
@@ -13,6 +14,8 @@ export const startDb = async (options) => {
     const { mkdir } = await import('node:fs/promises');
     const { MongoMemoryServer } = await import('mongodb-memory-server');
     const useInMemory = options?.forceInMemory || process.env.NODE_ENV === 'test';
+    useEphemeralStorage = useInMemory;
+    const mongoPort = options?.port ?? parseInt(process.env.PORT || '4010', 10) + 1;
     if (!useInMemory) {
         try {
             await mkdir(`${process.cwd()}/.db`);
@@ -23,11 +26,11 @@ export const startDb = async (options) => {
     try {
         mongod = MongoMemoryServer.create({
             instance: useInMemory
-                ? { dbName: 'test', port: parseInt(PORT, 10) + 1, storageEngine: 'ephemeralForTest' }
+                ? { dbName: 'test', port: mongoPort, storageEngine: 'ephemeralForTest' }
                 : {
                     dbPath: `${process.cwd()}/.db`,
                     storageEngine: 'wiredTiger',
-                    port: parseInt(PORT, 10) + 1,
+                    port: mongoPort,
                 },
         });
         const mongoInstance = await mongod;
@@ -35,22 +38,56 @@ export const startDb = async (options) => {
             return `${mongoInstance.getUri()}${useInMemory ? 'test' : 'unchained'}`;
         }
     }
-    catch {
+    catch (e) {
+        const error = e;
+        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`);
+        }
+        throw error;
     }
     throw new Error("Can't connect to MongoDB: Could not start mongodb-memory-server and MONGO_URL env is not set");
 };
 export const stopDb = async () => {
-    try {
+    const cleanup = async () => {
         await mongoClient?.close();
-        await (await mongod)?.stop();
+        const server = await mongod;
+        await server?.stop({ doCleanup: useEphemeralStorage, force: true });
+    };
+    const timeout = new Promise((_, reject) => setTimeout(() => reject(new Error('Database cleanup timeout')), CLEANUP_TIMEOUT_MS));
+    try {
+        await Promise.race([cleanup(), timeout]);
     }
     catch {
+        const server = await mongod;
+        await server?.stop({ force: true }).catch(() => {
+        });
+    }
+    finally {
+        mongoClient = null;
+        mongod = null;
     }
 };
+export const createDatabaseResource = async (options) => {
+    const url = options?.forceInMemory
+        ? await startDb({ forceInMemory: true, port: options.port })
+        : process.env.MONGO_URL || (await startDb({ port: options?.port }));
+    mongoClient = new MongoClient(url, {
+        compressors: zstdEnabled ? 'zstd' : undefined,
+    });
+    await mongoClient.connect();
+    const db = mongoClient.db();
+    return {
+        db,
+        client: mongoClient,
+        [Symbol.asyncDispose]: stopDb,
+    };
+};
 const initDb = async (options) => {
     const url = options?.forceInMemory
-        ? await startDb({ forceInMemory: true })
-        : process.env.MONGO_URL || (await startDb());
+        ? await startDb({ forceInMemory: true, port: options.port })
+        : process.env.MONGO_URL || (await startDb({ port: options?.port }));
     mongoClient = new MongoClient(url, {
         compressors: zstdEnabled ? 'zstd' : undefined,
     });

package/lib/insensitive-trimmed-regex-operator.d.ts

@@ -1,3 +1,4 @@
+export declare function escapeRegexString(string: string): string;
 export declare function insensitiveTrimmedRegexOperator(string: any): {
     $regex: RegExp;
 };

package/lib/insensitive-trimmed-regex-operator.js

@@ -1,11 +1,17 @@
+export function escapeRegexString(string) {
+    if (typeof string !== 'string') {
+        throw new TypeError('Expected a string');
+    }
+    return string.replace(/[-/\\^$*+?.()|[\]{}]/g, '\\$&');
+}
 export function insensitiveTrimmedRegexOperator(string) {
     if (typeof string !== 'string') {
         throw new TypeError('Expected a string');
     }
-    const escapped = string.trim().replace(/[-/\\^$*+?.()|[\]{}]/g, '\\$&');
-    if (escapped.length === 0)
+    const escaped = escapeRegexString(string.trim());
+    if (escaped.length === 0)
         throw new Error('String is empty after trimming');
-    if (escapped.length > 255)
+    if (escaped.length > 255)
         throw new Error('String exceeds maximum allowed length');
-    return { $regex: new RegExp(`^${escapped}$`, 'i') };
+    return { $regex: new RegExp(`^${escaped}$`, 'i') };
 }

package/lib/mongodb-index.d.ts

@@ -1,12 +1,13 @@
 import * as mongodb from 'mongodb';
-export { initDb, startDb, stopDb } from './initDb.ts';
+export { initDb, startDb, stopDb, createDatabaseResource } from './initDb.ts';
+export type { DatabaseResource } from './initDb.ts';
 export { generateDbObjectId } from './generate-db-object-id.ts';
 export { generateDbFilterById } from './generate-db-filter-by-id.ts';
 export { buildDbIndexes } from './build-db-indexes.ts';
 export { findPreservingIds } from './find-preserving-ids.ts';
 export { buildSortOptions } from './build-sort-option.ts';
 export { findLocalizedText } from './find-localized-text.ts';
-export { insensitiveTrimmedRegexOperator } from './insensitive-trimmed-regex-operator.ts';
+export { insensitiveTrimmedRegexOperator, escapeRegexString, } from './insensitive-trimmed-regex-operator.ts';
 export * from './documentdb-compat-mode.ts';
 export { mongodb };
 export interface LogFields {

package/lib/mongodb-index.js

@@ -1,11 +1,11 @@
 import * as mongodb from 'mongodb';
-export { initDb, startDb, stopDb } from "./initDb.js";
+export { initDb, startDb, stopDb, createDatabaseResource } from "./initDb.js";
 export { generateDbObjectId } from "./generate-db-object-id.js";
 export { generateDbFilterById } from "./generate-db-filter-by-id.js";
 export { buildDbIndexes } from "./build-db-indexes.js";
 export { findPreservingIds } from "./find-preserving-ids.js";
 export { buildSortOptions } from "./build-sort-option.js";
 export { findLocalizedText } from "./find-localized-text.js";
-export { insensitiveTrimmedRegexOperator } from "./insensitive-trimmed-regex-operator.js";
+export { insensitiveTrimmedRegexOperator, escapeRegexString, } from "./insensitive-trimmed-regex-operator.js";
 export * from "./documentdb-compat-mode.js";
 export { mongodb };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@unchainedshop/mongodb",
-  "version": "4.5.0",
-  "description": "MongoDB provider for unchained platform",
+  "version": "4.6.0",
+  "description": "MongoDB database abstraction layer for the Unchained Engine",
   "main": "lib/mongodb-index.js",
   "types": "lib/mongodb-index.d.ts",
   "type": "module",
@@ -33,7 +33,7 @@
   },
   "homepage": "https://github.com/unchainedshop/unchained#readme",
   "dependencies": {
-    "@unchainedshop/utils": "^4.5.0"
+    "@unchainedshop/utils": "^4.6.0"
   },
   "peerDependencies": {
     "@mongodb-js/zstd": ">= 7 < 8",