nx-mongo 3.6.0 → 3.8.1

package/dist/simpleMongoHelper.js

@@ -195,13 +195,14 @@ class ProgressAPIImpl {
      * Ensures the progress collection and unique index exist.
      * Called lazily on first use.
      */
-    async ensureProgressIndex(session) {
+    async ensureProgressIndex(session, database, ref, type) {
         if (this.indexEnsured) {
             return;
         }
         this.helper.ensureInitialized();
         try {
-            const collection = this.helper.getDb().collection(this.config.collection);
+            const db = this.helper.getDatabaseByName(database, ref, type);
+            const collection = db.collection(this.config.collection);
             const indexes = await collection.indexes();
             // Build index spec from uniqueIndexKeys
             const indexSpec = {};
@@ -253,12 +254,16 @@ class ProgressAPIImpl {
         return filter;
     }
     async isCompleted(key, options) {
-        await this.ensureProgressIndex(options?.session);
+        const database = options?.database;
+        const ref = options?.ref;
+        const type = options?.type;
+        await this.ensureProgressIndex(options?.session, database, ref, type);
         this.helper.ensureInitialized();
         const provider = this.resolveProvider(options);
         const process = options?.process;
         const filter = this.buildFilter(key, process, provider);
-        const collection = this.helper.getDb().collection(this.config.collection);
+        const db = this.helper.getDatabaseByName(database, ref, type);
+        const collection = db.collection(this.config.collection);
         const findOptions = {};
         if (options?.session) {
             findOptions.session = options.session;
@@ -267,12 +272,16 @@ class ProgressAPIImpl {
         return record?.completed === true;
     }
     async start(identity, options) {
-        await this.ensureProgressIndex(options?.session);
+        const database = options?.database;
+        const ref = options?.ref;
+        const type = options?.type;
+        await this.ensureProgressIndex(options?.session, database, ref, type);
         this.helper.ensureInitialized();
         const provider = this.resolveProvider({ provider: identity.provider });
         const process = identity.process;
         const filter = this.buildFilter(identity.key, process, provider);
-        const collection = this.helper.getDb().collection(this.config.collection);
+        const db = this.helper.getDatabaseByName(database, ref, type);
+        const collection = db.collection(this.config.collection);
         const update = {
             $set: {
                 key: identity.key,
@@ -296,12 +305,16 @@ class ProgressAPIImpl {
         await collection.updateOne(filter, update, updateOptions);
     }
     async complete(identity, options) {
-        await this.ensureProgressIndex(options?.session);
+        const database = options?.database;
+        const ref = options?.ref;
+        const type = options?.type;
+        await this.ensureProgressIndex(options?.session, database, ref, type);
         this.helper.ensureInitialized();
         const provider = this.resolveProvider({ provider: identity.provider });
         const process = identity.process;
         const filter = this.buildFilter(identity.key, process, provider);
-        const collection = this.helper.getDb().collection(this.config.collection);
+        const db = this.helper.getDatabaseByName(database, ref, type);
+        const collection = db.collection(this.config.collection);
         const update = {
             $set: {
                 key: identity.key,
@@ -329,7 +342,10 @@ class ProgressAPIImpl {
         await collection.updateOne(filter, update, updateOptions);
     }
     async getCompleted(options) {
-        await this.ensureProgressIndex(options?.session);
+        const database = options?.database;
+        const ref = options?.ref;
+        const type = options?.type;
+        await this.ensureProgressIndex(options?.session, database, ref, type);
         this.helper.ensureInitialized();
         const provider = this.resolveProvider(options);
         const process = options?.process;
@@ -340,7 +356,8 @@ class ProgressAPIImpl {
         if (provider !== undefined) {
             filter.provider = provider;
         }
-        const collection = this.helper.getDb().collection(this.config.collection);
+        const db = this.helper.getDatabaseByName(database, ref, type);
+        const collection = db.collection(this.config.collection);
         const findOptions = { projection: { key: 1, name: 1, completedAt: 1 } };
         if (options?.session) {
             findOptions.session = options.session;
@@ -353,7 +370,10 @@ class ProgressAPIImpl {
         }));
     }
     async getProgress(options) {
-        await this.ensureProgressIndex(options?.session);
+        const database = options?.database;
+        const ref = options?.ref;
+        const type = options?.type;
+        await this.ensureProgressIndex(options?.session, database, ref, type);
         this.helper.ensureInitialized();
         const provider = this.resolveProvider(options);
         const process = options?.process;
@@ -364,7 +384,8 @@ class ProgressAPIImpl {
         if (provider !== undefined) {
             filter.provider = provider;
         }
-        const collection = this.helper.getDb().collection(this.config.collection);
+        const db = this.helper.getDatabaseByName(database, ref, type);
+        const collection = db.collection(this.config.collection);
         const findOptions = {};
         if (options?.session) {
             findOptions.session = options.session;
@@ -372,12 +393,16 @@ class ProgressAPIImpl {
         return await collection.find(filter, findOptions).toArray();
     }
     async reset(key, options) {
-        await this.ensureProgressIndex(options?.session);
+        const database = options?.database;
+        const ref = options?.ref;
+        const type = options?.type;
+        await this.ensureProgressIndex(options?.session, database, ref, type);
         this.helper.ensureInitialized();
         const provider = this.resolveProvider(options);
         const process = options?.process;
         const filter = this.buildFilter(key, process, provider);
-        const collection = this.helper.getDb().collection(this.config.collection);
+        const db = this.helper.getDatabaseByName(database, ref, type);
+        const collection = db.collection(this.config.collection);
         const update = {
             $set: {
                 completed: false,
@@ -402,7 +427,8 @@ class SimpleMongoHelper {
         this.config = null;
         this.cleanupRegistered = false;
         this.isDisconnecting = false;
-        this.connectionString = connectionString;
+        // Strip database name from connection string if present
+        this.connectionString = this.stripDatabaseFromConnectionString(connectionString);
         this.retryOptions = {
             maxRetries: retryOptions?.maxRetries ?? 3,
             retryDelay: retryOptions?.retryDelay ?? 1000,
@@ -505,9 +531,8 @@ class SimpleMongoHelper {
                 connectTimeoutMS: 5000
             });
             await testClient.connect();
-            // Try to ping the server
-            const dbName = this.extractDatabaseName(this.connectionString);
-            const testDb = testClient.db(dbName);
+            // Try to ping the server using 'admin' database (default)
+            const testDb = testClient.db('admin');
             await testDb.admin().ping();
             // Test basic operation (list collections)
             try {
@@ -540,75 +565,115 @@ class SimpleMongoHelper {
                     // Ignore close errors
                 }
             }
-            const errorMessage = error instanceof Error ? error.message : String(error);
-            const errorString = String(error).toLowerCase();
+            // Extract error information more comprehensively
+            let errorMessage = 'Unknown error';
+            let errorName = 'Unknown';
+            let errorCode;
+            if (error instanceof Error) {
+                errorMessage = error.message || 'Unknown error';
+                errorName = error.name || 'Error';
+                // Check for MongoDB-specific error properties
+                const mongoError = error;
+                if (mongoError.code) {
+                    errorCode = mongoError.code;
+                }
+                if (mongoError.codeName) {
+                    errorName = mongoError.codeName;
+                }
+                if (mongoError.errmsg) {
+                    errorMessage = mongoError.errmsg;
+                }
+            }
+            else if (error && typeof error === 'object') {
+                // Try to extract meaningful information from error object
+                const errObj = error;
+                errorMessage = errObj.message || errObj.errmsg || errObj.error || JSON.stringify(error);
+                errorName = errObj.name || errObj.codeName || 'Error';
+                errorCode = errObj.code;
+            }
+            else {
+                errorMessage = String(error);
+            }
+            const errorMessageLower = errorMessage.toLowerCase();
+            // Check for Windows-specific localhost resolution issues
+            const isLocalhost = this.connectionString.includes('localhost');
+            const windowsHint = isLocalhost && process.platform === 'win32'
+                ? ' On Windows, try using 127.0.0.1 instead of localhost to avoid IPv6 resolution issues.'
+                : '';
             // Analyze error type
-            if (errorString.includes('authentication failed') ||
-                errorString.includes('auth failed') ||
-                errorString.includes('invalid credentials') ||
-                errorMessage.includes('Authentication failed')) {
+            if (errorMessageLower.includes('authentication failed') ||
+                errorMessageLower.includes('auth failed') ||
+                errorMessageLower.includes('invalid credentials') ||
+                errorMessageLower.includes('authentication failed') ||
+                errorCode === 18 || // MongoDB error code for authentication failed
+                errorName === 'MongoAuthenticationError') {
                 return {
                     success: false,
                     error: {
                         type: 'authentication_failed',
                         message: 'Authentication failed',
-                        details: `Invalid username or password. Error: ${errorMessage}. Verify credentials in connection string.`
+                        details: `Invalid username or password. Error: ${errorMessage}${errorCode ? ` (Code: ${errorCode})` : ''}. Verify credentials in connection string.`
                     }
                 };
             }
-            if (errorString.includes('timeout') ||
-                errorMessage.includes('timeout') ||
-                errorMessage.includes('ETIMEDOUT')) {
+            if (errorMessageLower.includes('timeout') ||
+                errorMessageLower.includes('etimedout') ||
+                errorCode === 'ETIMEDOUT' ||
+                errorName === 'MongoServerSelectionError') {
                 return {
                     success: false,
                     error: {
                         type: 'connection_failed',
                         message: 'Connection timeout',
-                        details: `Cannot reach MongoDB server. Error: ${errorMessage}. Check if server is running, host/port is correct, and firewall allows connections.`
+                        details: `Cannot reach MongoDB server. Error: ${errorMessage}${errorCode ? ` (Code: ${errorCode})` : ''}. Check if server is running, host/port is correct, and firewall allows connections.${windowsHint}`
                     }
                 };
             }
-            if (errorString.includes('dns') ||
-                errorMessage.includes('ENOTFOUND') ||
-                errorMessage.includes('getaddrinfo')) {
+            if (errorMessageLower.includes('dns') ||
+                errorMessageLower.includes('enotfound') ||
+                errorMessageLower.includes('getaddrinfo') ||
+                errorCode === 'ENOTFOUND') {
                 return {
                     success: false,
                     error: {
                         type: 'connection_failed',
                         message: 'DNS resolution failed',
-                        details: `Cannot resolve hostname. Error: ${errorMessage}. Check if hostname is correct and DNS is configured properly.`
+                        details: `Cannot resolve hostname. Error: ${errorMessage}${errorCode ? ` (Code: ${errorCode})` : ''}. Check if hostname is correct and DNS is configured properly.${windowsHint}`
                     }
                 };
             }
-            if (errorString.includes('refused') ||
-                errorMessage.includes('ECONNREFUSED')) {
+            if (errorMessageLower.includes('refused') ||
+                errorMessageLower.includes('econnrefused') ||
+                errorCode === 'ECONNREFUSED') {
                 return {
                     success: false,
                     error: {
                         type: 'connection_failed',
                         message: 'Connection refused',
-                        details: `MongoDB server refused connection. Error: ${errorMessage}. Check if MongoDB is running on the specified host and port.`
+                        details: `MongoDB server refused connection. Error: ${errorMessage}${errorCode ? ` (Code: ${errorCode})` : ''}. Check if MongoDB is running on the specified host and port.${windowsHint}`
                     }
                 };
             }
-            if (errorString.includes('network') ||
-                errorMessage.includes('network')) {
+            if (errorMessageLower.includes('network') ||
+                errorMessageLower.includes('network') ||
+                errorName === 'MongoNetworkError') {
                 return {
                     success: false,
                     error: {
                         type: 'connection_failed',
                         message: 'Network error',
-                        details: `Network connectivity issue. Error: ${errorMessage}. Check network connection and firewall settings.`
+                        details: `Network connectivity issue. Error: ${errorMessage}${errorCode ? ` (Code: ${errorCode})` : ''}. Check network connection and firewall settings.${windowsHint}`
                     }
                 };
             }
-            // Generic connection error
+            // Generic connection error with full details
+            const details = `Failed to connect to MongoDB. Error: ${errorMessage}${errorCode ? ` (Code: ${errorCode})` : ''}${errorName !== 'Error' ? ` (Type: ${errorName})` : ''}. Verify connection string, server status, and network connectivity.${windowsHint}`;
             return {
                 success: false,
                 error: {
                     type: 'connection_failed',
                     message: 'Connection failed',
-                    details: `Failed to connect to MongoDB. Error: ${errorMessage}. Verify connection string, server status, and network connectivity.`
+                    details
                 }
             };
         }
@@ -627,9 +692,8 @@ class SimpleMongoHelper {
             try {
                 this.client = new mongodb_1.MongoClient(this.connectionString);
                 await this.client.connect();
-                // Extract database name from connection string or use default
-                const dbName = this.extractDatabaseName(this.connectionString);
-                this.db = this.client.db(dbName);
+                // Default to 'admin' database for initial connection (not used for operations)
+                this.db = this.client.db('admin');
                 this.isInitialized = true;
                 return;
             }
@@ -655,10 +719,11 @@ class SimpleMongoHelper {
      * @returns Array of documents matching the query or paginated result
      * @throws Error if not initialized or if query fails
      */
-    async loadCollection(collectionName, query, options) {
+    async loadCollection(collectionName, query, options, database, ref, type) {
         this.ensureInitialized();
         try {
-            const collection = this.db.collection(collectionName);
+            const db = this.getDatabase(this.resolveDatabase({ database, ref, type }));
+            const collection = db.collection(collectionName);
             const filter = query || {};
             let cursor = collection.find(filter);
             // Apply sorting if provided
@@ -701,10 +766,11 @@ class SimpleMongoHelper {
      * @returns Single document matching the query or null
      * @throws Error if not initialized or if query fails
      */
-    async findOne(collectionName, query, options) {
+    async findOne(collectionName, query, options, database, ref, type) {
         this.ensureInitialized();
         try {
-            const collection = this.db.collection(collectionName);
+            const db = this.getDatabase(this.resolveDatabase({ database, ref, type }));
+            const collection = db.collection(collectionName);
             let findOptions = {};
             if (options?.sort) {
                 findOptions.sort = options.sort;
@@ -727,10 +793,11 @@ class SimpleMongoHelper {
      * @returns Insert result(s)
      * @throws Error if not initialized or if insert fails
      */
-    async insert(collectionName, data, options) {
+    async insert(collectionName, data, options, database, ref, type) {
         this.ensureInitialized();
         try {
-            const collection = this.db.collection(collectionName);
+            const db = this.getDatabase(this.resolveDatabase({ database, ref, type }));
+            const collection = db.collection(collectionName);
             const insertOptions = options?.session ? { session: options.session } : {};
             if (Array.isArray(data)) {
                 const result = await collection.insertMany(data, insertOptions);
@@ -754,10 +821,11 @@ class SimpleMongoHelper {
      * @returns Update result
      * @throws Error if not initialized or if update fails
      */
-    async update(collectionName, filter, updateData, options) {
+    async update(collectionName, filter, updateData, options, database, ref, type) {
         this.ensureInitialized();
         try {
-            const collection = this.db.collection(collectionName);
+            const db = this.getDatabase(this.resolveDatabase({ database, ref, type }));
+            const collection = db.collection(collectionName);
             const updateOptions = {};
             if (options?.upsert !== undefined)
                 updateOptions.upsert = options.upsert;
@@ -784,10 +852,11 @@ class SimpleMongoHelper {
      * @returns Delete result
      * @throws Error if not initialized or if delete fails
      */
-    async delete(collectionName, filter, options) {
+    async delete(collectionName, filter, options, database, ref, type) {
         this.ensureInitialized();
         try {
-            const collection = this.db.collection(collectionName);
+            const db = this.getDatabase(this.resolveDatabase({ database, ref, type }));
+            const collection = db.collection(collectionName);
             if (options?.multi) {
                 const result = await collection.deleteMany(filter);
                 return result;
@@ -808,10 +877,11 @@ class SimpleMongoHelper {
      * @returns Number of documents matching the query
      * @throws Error if not initialized or if count fails
      */
-    async countDocuments(collectionName, query) {
+    async countDocuments(collectionName, query, database, ref, type) {
         this.ensureInitialized();
         try {
-            const collection = this.db.collection(collectionName);
+            const db = this.getDatabase(this.resolveDatabase({ database, ref, type }));
+            const collection = db.collection(collectionName);
             const count = await collection.countDocuments(query || {});
             return count;
         }
@@ -825,10 +895,11 @@ class SimpleMongoHelper {
      * @returns Estimated number of documents
      * @throws Error if not initialized or if count fails
      */
-    async estimatedDocumentCount(collectionName) {
+    async estimatedDocumentCount(collectionName, database, ref, type) {
         this.ensureInitialized();
         try {
-            const collection = this.db.collection(collectionName);
+            const db = this.getDatabase(this.resolveDatabase({ database, ref, type }));
+            const collection = db.collection(collectionName);
             const count = await collection.estimatedDocumentCount();
             return count;
         }
@@ -843,10 +914,11 @@ class SimpleMongoHelper {
      * @returns Array of aggregated results
      * @throws Error if not initialized or if aggregation fails
      */
-    async aggregate(collectionName, pipeline) {
+    async aggregate(collectionName, pipeline, database, ref, type) {
         this.ensureInitialized();
         try {
-            const collection = this.db.collection(collectionName);
+            const db = this.getDatabase(this.resolveDatabase({ database, ref, type }));
+            const collection = db.collection(collectionName);
             const results = await collection.aggregate(pipeline).toArray();
             return results;
         }
@@ -862,10 +934,11 @@ class SimpleMongoHelper {
      * @returns Index name
      * @throws Error if not initialized or if index creation fails
      */
-    async createIndex(collectionName, indexSpec, options) {
+    async createIndex(collectionName, indexSpec, options, database, ref, type) {
         this.ensureInitialized();
         try {
-            const collection = this.db.collection(collectionName);
+            const db = this.getDatabase(this.resolveDatabase({ database, ref, type }));
+            const collection = db.collection(collectionName);
             const indexName = await collection.createIndex(indexSpec, options);
             return indexName;
         }
@@ -880,10 +953,11 @@ class SimpleMongoHelper {
      * @returns Result object
      * @throws Error if not initialized or if index drop fails
      */
-    async dropIndex(collectionName, indexName) {
+    async dropIndex(collectionName, indexName, database, ref, type) {
         this.ensureInitialized();
         try {
-            const collection = this.db.collection(collectionName);
+            const db = this.getDatabase(this.resolveDatabase({ database, ref, type }));
+            const collection = db.collection(collectionName);
             const result = await collection.dropIndex(indexName);
             return result;
         }
@@ -897,10 +971,11 @@ class SimpleMongoHelper {
      * @returns Array of index information
      * @throws Error if not initialized or if listing fails
      */
-    async listIndexes(collectionName) {
+    async listIndexes(collectionName, database, ref, type) {
         this.ensureInitialized();
         try {
-            const collection = this.db.collection(collectionName);
+            const db = this.getDatabase(this.resolveDatabase({ database, ref, type }));
+            const collection = db.collection(collectionName);
             const indexes = await collection.indexes();
             return indexes;
         }
@@ -962,9 +1037,13 @@ class SimpleMongoHelper {
         if (!inputConfig) {
             throw new Error(`Ref '${ref}' not found in configuration inputs.`);
         }
+        const database = options?.database;
+        const dbRef = options?.ref;
+        const dbType = options?.type;
+        const db = this.getDatabase(this.resolveDatabase({ database, ref: dbRef, type: dbType }));
         // Note: loadCollection doesn't support session yet, but we'll pass it through options
         // For now, we'll use the collection directly with session support
-        const collection = this.db.collection(inputConfig.collection);
+        const collection = db.collection(inputConfig.collection);
         const filter = inputConfig.query || {};
         const session = options?.session;
         try {
@@ -1019,8 +1098,12 @@ class SimpleMongoHelper {
         this.ensureInitialized();
         const fieldName = options?.fieldName || '_sig';
         const unique = options?.unique !== false; // Default to true
+        const database = options?.database;
+        const ref = options?.ref;
+        const type = options?.type;
         try {
-            const collection = this.db.collection(collectionName);
+            const db = this.getDatabase(this.resolveDatabase({ database, ref, type }));
+            const collection = db.collection(collectionName);
             const indexes = await collection.indexes();
             // Find existing index on the signature field
             const existingIndex = indexes.find(idx => {
@@ -1090,6 +1173,9 @@ class SimpleMongoHelper {
         const mode = outputConfig.mode || this.config.output?.mode || 'append';
         const ensureIndex = options?.ensureIndex !== false; // Default to true
         const session = options?.session;
+        const database = options?.database;
+        const dbRef = options?.ref;
+        const dbType = options?.type;
         const result = {
             inserted: 0,
             updated: 0,
@@ -1097,7 +1183,8 @@ class SimpleMongoHelper {
             indexCreated: false,
         };
         try {
-            const collection = this.db.collection(collectionName);
+            const db = this.getDatabase(this.resolveDatabase({ database, ref: dbRef, type: dbType }));
+            const collection = db.collection(collectionName);
             // Handle replace mode: clear collection first
             if (mode === 'replace') {
                 const deleteOptions = session ? { session } : {};
@@ -1251,6 +1338,9 @@ class SimpleMongoHelper {
         const writeResult = await this.writeByRef(ref, documents, {
             session: options?.session,
             ensureIndex: options?.ensureIndex,
+            database: options?.database,
+            ref: options?.ref,
+            type: options?.type,
         });
         const result = {
             ...writeResult,
@@ -1265,7 +1355,7 @@ class SimpleMongoHelper {
                     name: options.complete.name,
                     provider: options.complete.provider,
                     metadata: options.complete.metadata,
-                }, { session: options.session });
+                }, { session: options.session, database: options?.database, ref: options?.ref, type: options?.type });
                 result.completed = true;
             }
             catch (error) {
@@ -1286,7 +1376,7 @@ class SimpleMongoHelper {
      */
     async mergeCollections(options) {
         this.ensureInitialized();
-        const { sourceCollection1, sourceCollection2, targetCollection, strategy, key, compositeKeys, joinType, fieldPrefix1 = 'record', fieldPrefix2 = 'assessment', includeIndex = strategy === 'index', onUnmatched1 = 'include', onUnmatched2 = 'include', session, } = options;
+        const { sourceCollection1, sourceCollection2, targetCollection, strategy, key, compositeKeys, joinType, fieldPrefix1 = 'record', fieldPrefix2 = 'assessment', includeIndex = strategy === 'index', onUnmatched1 = 'include', onUnmatched2 = 'include', session, database, ref, type, } = options;
         // Determine join behavior from joinType or fallback to onUnmatched flags
         let includeUnmatched1;
         let includeUnmatched2;
@@ -1326,9 +1416,10 @@ class SimpleMongoHelper {
             errors: [],
         };
         try {
-            const coll1 = this.db.collection(sourceCollection1);
-            const coll2 = this.db.collection(sourceCollection2);
-            const targetColl = this.db.collection(targetCollection);
+            const db = this.getDatabase(this.resolveDatabase({ database, ref, type }));
+            const coll1 = db.collection(sourceCollection1);
+            const coll2 = db.collection(sourceCollection2);
+            const targetColl = db.collection(targetCollection);
             const findOptions = {};
             if (session) {
                 findOptions.session = session;
@@ -1724,21 +1815,110 @@ class SimpleMongoHelper {
         return this.db;
     }
     /**
-     * Extracts database name from MongoDB connection string.
-     * @param connectionString - MongoDB connection string
-     * @returns Database name or 'test' as default
+     * Strips database name from MongoDB connection string, returning base connection string.
+     * @param connectionString - MongoDB connection string (may include database name)
+     * @returns Base connection string without database name
+     * @example
+     * stripDatabaseFromConnectionString('mongodb://localhost:27017/admin')
+     * // Returns: 'mongodb://localhost:27017/'
      */
-    extractDatabaseName(connectionString) {
+    stripDatabaseFromConnectionString(connectionString) {
         try {
             const url = new URL(connectionString);
-            const dbName = url.pathname.slice(1); // Remove leading '/'
-            return dbName || 'test';
+            // Remove pathname (database name) but keep trailing slash
+            url.pathname = '/';
+            return url.toString();
         }
         catch {
-            // If URL parsing fails, try to extract from connection string pattern
-            const match = connectionString.match(/\/([^\/\?]+)(\?|$)/);
-            return match ? match[1] : 'test';
+            // If URL parsing fails, try regex pattern matching
+            // Match: mongodb://host:port/database?options or mongodb://host:port/database
+            const match = connectionString.match(/^([^\/]+\/\/[^\/]+)\/([^\/\?]+)(\?.*)?$/);
+            if (match) {
+                // Return base URL with trailing slash
+                return match[1] + '/';
+            }
+            // If no database found, return as-is (should already be base URL)
+            return connectionString.endsWith('/') ? connectionString : connectionString + '/';
+        }
+    }
+    /**
+     * Resolves the database name from provided options using the databases config map.
+     * Priority: database > ref+type > ref > type
+     * @param options - Options containing database, ref, and/or type
+     * @returns Resolved database name or undefined (will default to 'admin')
+     * @throws Error if no match found or multiple matches found
+     * @internal
+     */
+    resolveDatabase(options) {
+        // Priority 1: If database is provided directly, use it
+        if (options?.database) {
+            return options.database;
+        }
+        // If no config or no databases map, return undefined (will default to 'admin')
+        if (!this.config || !this.config.databases || this.config.databases.length === 0) {
+            return undefined;
+        }
+        const databases = this.config.databases;
+        // Priority 2: If both ref and type are provided, find exact match
+        if (options?.ref && options?.type) {
+            const matches = databases.filter(db => db.ref === options.ref && db.type === options.type);
+            if (matches.length === 0) {
+                throw new Error(`No database found for ref: ${options.ref} and type: ${options.type}`);
+            }
+            if (matches.length > 1) {
+                throw new Error(`Multiple databases found for ref: ${options.ref} and type: ${options.type}`);
+            }
+            return matches[0].database;
         }
+        // Priority 3: If ref is provided, find by ref
+        if (options?.ref) {
+            const matches = databases.filter(db => db.ref === options.ref);
+            if (matches.length === 0) {
+                throw new Error(`No database found for ref: ${options.ref}`);
+            }
+            if (matches.length > 1) {
+                throw new Error(`Multiple databases found for ref: ${options.ref}. Use 'type' parameter to narrow down.`);
+            }
+            return matches[0].database;
+        }
+        // Priority 4: If type is provided, find by type
+        if (options?.type) {
+            const matches = databases.filter(db => db.type === options.type);
+            if (matches.length === 0) {
+                throw new Error(`No database found for type: ${options.type}`);
+            }
+            if (matches.length > 1) {
+                throw new Error(`Multiple databases found for type: ${options.type}. Use 'ref' parameter to narrow down.`);
+            }
+            return matches[0].database;
+        }
+        // No options provided, return undefined (will default to 'admin')
+        return undefined;
+    }
+    /**
+     * Gets a database instance by name. Defaults to 'admin' if no name provided.
+     * @param databaseName - Optional database name (defaults to 'admin')
+     * @returns Database instance
+     * @throws Error if client is not initialized
+     * @internal
+     */
+    getDatabase(databaseName) {
+        if (!this.client) {
+            throw new Error('MongoDB client not initialized. Call initialize() first.');
+        }
+        return this.client.db(databaseName || 'admin');
+    }
+    /**
+     * Gets a database instance by name. Defaults to 'admin' if no name provided.
+     * Public method for use by ProgressAPIImpl.
+     * @param databaseName - Optional database name (defaults to 'admin')
+     * @param ref - Optional ref for database resolution
+     * @param type - Optional type for database resolution
+     * @returns Database instance
+     * @throws Error if client is not initialized
+     */
+    getDatabaseByName(databaseName, ref, type) {
+        return this.getDatabase(this.resolveDatabase({ database: databaseName, ref, type }));
     }
 }
 exports.SimpleMongoHelper = SimpleMongoHelper;