nx-mongo 3.5.0 → 3.8.0

package/src/simpleMongoHelper.ts

@@ -47,6 +47,11 @@ export interface HelperConfig {
     uniqueIndexKeys?: string[];
     provider?: string;
   };
+  databases?: Array<{
+    ref: string;
+    type: string;
+    database: string;
+  }>;
 }
 
 export interface WriteByRefResult {
@@ -82,7 +87,7 @@ export interface StageRecord extends StageIdentity {
   metadata?: StageMetadata;
 }
 
-export type ProgressSessionOptions = { session?: ClientSession };
+export type ProgressSessionOptions = { session?: ClientSession; database?: string; ref?: string; type?: string };
 
 export interface ProgressAPI {
   isCompleted(key: string, options?: ProgressSessionOptions & { process?: string; provider?: string }): Promise<boolean>;
@@ -99,6 +104,9 @@ export interface ProgressAPI {
 export interface WriteStageOptions {
   ensureIndex?: boolean;
   session?: ClientSession;
+  database?: string;
+  ref?: string;
+  type?: string;
   complete?: {
     key: string;
     process?: string;
@@ -126,6 +134,9 @@ export interface MergeCollectionsOptions {
   onUnmatched1?: 'include' | 'skip'; // What to do with unmatched records from collection 1 (default: 'include', deprecated: use joinType instead)
   onUnmatched2?: 'include' | 'skip'; // What to do with unmatched records from collection 2 (default: 'include', deprecated: use joinType instead)
   session?: ClientSession;
+  database?: string; // Database name (defaults to 'admin')
+  ref?: string; // Optional ref for database resolution
+  type?: string; // Optional type for database resolution
 }
 
 export interface MergeCollectionsResult {
@@ -361,7 +372,7 @@ class ProgressAPIImpl implements ProgressAPI {
    * Ensures the progress collection and unique index exist.
    * Called lazily on first use.
    */
-  private async ensureProgressIndex(session?: ClientSession): Promise<void> {
+  private async ensureProgressIndex(session?: ClientSession, database?: string, ref?: string, type?: string): Promise<void> {
     if (this.indexEnsured) {
       return;
     }
@@ -369,7 +380,8 @@ class ProgressAPIImpl implements ProgressAPI {
     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
@@ -429,13 +441,17 @@ class ProgressAPIImpl implements ProgressAPI {
   }
 
   async isCompleted(key: string, options?: ProgressSessionOptions & { process?: string; provider?: string }): Promise<boolean> {
-    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<StageRecord>(this.config.collection);
+    const db = this.helper.getDatabaseByName(database, ref, type);
+    const collection = db.collection<StageRecord>(this.config.collection);
     
     const findOptions: any = {};
     if (options?.session) {
@@ -447,13 +463,17 @@ class ProgressAPIImpl implements ProgressAPI {
   }
 
   async start(identity: StageIdentity, options?: ProgressSessionOptions): Promise<void> {
-    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<StageRecord>(this.config.collection);
+    const db = this.helper.getDatabaseByName(database, ref, type);
+    const collection = db.collection<StageRecord>(this.config.collection);
 
     const update: UpdateFilter<StageRecord> = {
       $set: {
@@ -485,13 +505,17 @@ class ProgressAPIImpl implements ProgressAPI {
     identity: StageIdentity & { metadata?: StageMetadata },
     options?: ProgressSessionOptions
   ): Promise<void> {
-    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<StageRecord>(this.config.collection);
+    const db = this.helper.getDatabaseByName(database, ref, type);
+    const collection = db.collection<StageRecord>(this.config.collection);
 
     const update: UpdateFilter<StageRecord> = {
       $set: {
@@ -526,7 +550,10 @@ class ProgressAPIImpl implements ProgressAPI {
   }
 
   async getCompleted(options?: ProgressSessionOptions & { process?: string; provider?: string }): Promise<Array<Pick<StageRecord, 'key' | 'name' | 'completedAt'>>> {
-    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);
@@ -539,7 +566,8 @@ class ProgressAPIImpl implements ProgressAPI {
       filter.provider = provider;
     }
 
-    const collection = this.helper.getDb().collection<StageRecord>(this.config.collection);
+    const db = this.helper.getDatabaseByName(database, ref, type);
+    const collection = db.collection<StageRecord>(this.config.collection);
     const findOptions: any = { projection: { key: 1, name: 1, completedAt: 1 } };
     if (options?.session) {
       findOptions.session = options.session;
@@ -554,7 +582,10 @@ class ProgressAPIImpl implements ProgressAPI {
   }
 
   async getProgress(options?: ProgressSessionOptions & { process?: string; provider?: string }): Promise<StageRecord[]> {
-    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);
@@ -567,7 +598,8 @@ class ProgressAPIImpl implements ProgressAPI {
       filter.provider = provider;
     }
 
-    const collection = this.helper.getDb().collection<StageRecord>(this.config.collection);
+    const db = this.helper.getDatabaseByName(database, ref, type);
+    const collection = db.collection<StageRecord>(this.config.collection);
     const findOptions: any = {};
     if (options?.session) {
       findOptions.session = options.session;
@@ -577,13 +609,17 @@ class ProgressAPIImpl implements ProgressAPI {
   }
 
   async reset(key: string, options?: ProgressSessionOptions & { process?: string; provider?: string }): Promise<void> {
-    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<StageRecord>(this.config.collection);
+    const db = this.helper.getDatabaseByName(database, ref, type);
+    const collection = db.collection<StageRecord>(this.config.collection);
 
     const update: UpdateFilter<StageRecord> = {
       $set: {
@@ -612,9 +648,12 @@ export class SimpleMongoHelper {
   private retryOptions: RetryOptions;
   private config: HelperConfig | null = null;
   public readonly progress: ProgressAPI;
+  private cleanupRegistered: boolean = false;
+  private isDisconnecting: boolean = false;
 
   constructor(connectionString: string, retryOptions?: RetryOptions, config?: HelperConfig) {
-    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,
@@ -622,6 +661,9 @@ export class SimpleMongoHelper {
     };
     this.config = config || null;
     this.progress = new ProgressAPIImpl(this, config?.progress);
+    
+    // Register automatic cleanup on process exit
+    this.registerCleanup();
   }
 
   /**
@@ -728,9 +770,8 @@ export class SimpleMongoHelper {
       
       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)
@@ -859,9 +900,8 @@ export class SimpleMongoHelper {
       try {
         this.client = new 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;
       } catch (error) {
@@ -892,12 +932,16 @@ export class SimpleMongoHelper {
   async loadCollection<T extends Document = Document>(
     collectionName: string, 
     query?: Filter<T>,
-    options?: PaginationOptions
+    options?: PaginationOptions,
+    database?: string,
+    ref?: string,
+    type?: string
   ): Promise<WithId<T>[] | PaginatedResult<T>> {
     this.ensureInitialized();
 
     try {
-      const collection: Collection<T> = this.db!.collection<T>(collectionName);
+      const db = this.getDatabase(this.resolveDatabase({ database, ref, type }));
+      const collection: Collection<T> = db.collection<T>(collectionName);
       const filter = query || {};
       let cursor = collection.find(filter);
 
@@ -949,12 +993,16 @@ export class SimpleMongoHelper {
   async findOne<T extends Document = Document>(
     collectionName: string,
     query: Filter<T>,
-    options?: { sort?: Sort; projection?: Document }
+    options?: { sort?: Sort; projection?: Document },
+    database?: string,
+    ref?: string,
+    type?: string
   ): Promise<WithId<T> | null> {
     this.ensureInitialized();
 
     try {
-      const collection: Collection<T> = this.db!.collection<T>(collectionName);
+      const db = this.getDatabase(this.resolveDatabase({ database, ref, type }));
+      const collection: Collection<T> = db.collection<T>(collectionName);
       let findOptions: any = {};
       
       if (options?.sort) {
@@ -982,12 +1030,16 @@ export class SimpleMongoHelper {
   async insert<T extends Document = Document>(
     collectionName: string, 
     data: OptionalUnlessRequiredId<T> | OptionalUnlessRequiredId<T>[],
-    options?: { session?: ClientSession }
+    options?: { session?: ClientSession },
+    database?: string,
+    ref?: string,
+    type?: string
   ): Promise<any> {
     this.ensureInitialized();
 
     try {
-      const collection: Collection<T> = this.db!.collection<T>(collectionName);
+      const db = this.getDatabase(this.resolveDatabase({ database, ref, type }));
+      const collection: Collection<T> = db.collection<T>(collectionName);
       const insertOptions = options?.session ? { session: options.session } : {};
       
       if (Array.isArray(data)) {
@@ -1015,12 +1067,16 @@ export class SimpleMongoHelper {
     collectionName: string,
     filter: Filter<T>,
     updateData: UpdateFilter<T>,
-    options?: { upsert?: boolean; multi?: boolean; session?: ClientSession }
+    options?: { upsert?: boolean; multi?: boolean; session?: ClientSession },
+    database?: string,
+    ref?: string,
+    type?: string
   ): Promise<any> {
     this.ensureInitialized();
 
     try {
-      const collection: Collection<T> = this.db!.collection<T>(collectionName);
+      const db = this.getDatabase(this.resolveDatabase({ database, ref, type }));
+      const collection: Collection<T> = db.collection<T>(collectionName);
       const updateOptions: any = {};
       if (options?.upsert !== undefined) updateOptions.upsert = options.upsert;
       if (options?.session) updateOptions.session = options.session;
@@ -1048,12 +1104,16 @@ export class SimpleMongoHelper {
   async delete<T extends Document = Document>(
     collectionName: string,
     filter: Filter<T>,
-    options?: { multi?: boolean }
+    options?: { multi?: boolean },
+    database?: string,
+    ref?: string,
+    type?: string
   ): Promise<any> {
     this.ensureInitialized();
 
     try {
-      const collection: Collection<T> = this.db!.collection<T>(collectionName);
+      const db = this.getDatabase(this.resolveDatabase({ database, ref, type }));
+      const collection: Collection<T> = db.collection<T>(collectionName);
       
       if (options?.multi) {
         const result = await collection.deleteMany(filter);
@@ -1076,12 +1136,16 @@ export class SimpleMongoHelper {
    */
   async countDocuments<T extends Document = Document>(
     collectionName: string,
-    query?: Filter<T>
+    query?: Filter<T>,
+    database?: string,
+    ref?: string,
+    type?: string
   ): Promise<number> {
     this.ensureInitialized();
 
     try {
-      const collection: Collection<T> = this.db!.collection<T>(collectionName);
+      const db = this.getDatabase(this.resolveDatabase({ database, ref, type }));
+      const collection: Collection<T> = db.collection<T>(collectionName);
       const count = await collection.countDocuments(query || {});
       return count;
     } catch (error) {
@@ -1095,11 +1159,12 @@ export class SimpleMongoHelper {
    * @returns Estimated number of documents
    * @throws Error if not initialized or if count fails
    */
-  async estimatedDocumentCount(collectionName: string): Promise<number> {
+  async estimatedDocumentCount(collectionName: string, database?: string, ref?: string, type?: string): Promise<number> {
     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;
     } catch (error) {
@@ -1116,12 +1181,16 @@ export class SimpleMongoHelper {
    */
   async aggregate<T extends Document = Document>(
     collectionName: string,
-    pipeline: Document[]
+    pipeline: Document[],
+    database?: string,
+    ref?: string,
+    type?: string
   ): Promise<T[]> {
     this.ensureInitialized();
 
     try {
-      const collection: Collection<T> = this.db!.collection<T>(collectionName);
+      const db = this.getDatabase(this.resolveDatabase({ database, ref, type }));
+      const collection: Collection<T> = db.collection<T>(collectionName);
       const results = await collection.aggregate<T>(pipeline).toArray();
       return results;
     } catch (error) {
@@ -1140,12 +1209,16 @@ export class SimpleMongoHelper {
   async createIndex(
     collectionName: string,
     indexSpec: IndexSpecification,
-    options?: CreateIndexesOptions
+    options?: CreateIndexesOptions,
+    database?: string,
+    ref?: string,
+    type?: string
   ): Promise<string> {
     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;
     } catch (error) {
@@ -1160,11 +1233,12 @@ export class SimpleMongoHelper {
    * @returns Result object
    * @throws Error if not initialized or if index drop fails
    */
-  async dropIndex(collectionName: string, indexName: string): Promise<any> {
+  async dropIndex(collectionName: string, indexName: string, database?: string, ref?: string, type?: string): Promise<any> {
     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;
     } catch (error) {
@@ -1178,11 +1252,12 @@ export class SimpleMongoHelper {
    * @returns Array of index information
    * @throws Error if not initialized or if listing fails
    */
-  async listIndexes(collectionName: string): Promise<Document[]> {
+  async listIndexes(collectionName: string, database?: string, ref?: string, type?: string): Promise<Document[]> {
     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;
     } catch (error) {
@@ -1244,7 +1319,7 @@ export class SimpleMongoHelper {
    */
   async loadByRef<T extends Document = Document>(
     ref: string,
-    options?: PaginationOptions & { session?: ClientSession }
+    options?: PaginationOptions & { session?: ClientSession; database?: string; ref?: string; type?: string }
   ): Promise<WithId<T>[] | PaginatedResult<T>> {
     this.ensureInitialized();
     
@@ -1257,9 +1332,13 @@ export class SimpleMongoHelper {
       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: Collection<T> = this.db!.collection<T>(inputConfig.collection);
+    const collection: Collection<T> = db.collection<T>(inputConfig.collection);
     const filter = inputConfig.query || {};
     const session = options?.session;
     
@@ -1323,15 +1402,22 @@ export class SimpleMongoHelper {
     options?: {
       fieldName?: string;
       unique?: boolean;
+      database?: string;
+      ref?: string;
+      type?: string;
     }
   ): Promise<EnsureSignatureIndexResult> {
     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
@@ -1397,6 +1483,9 @@ export class SimpleMongoHelper {
     options?: {
       session?: ClientSession;
       ensureIndex?: boolean;
+      database?: string;
+      ref?: string;
+      type?: string;
     }
   ): Promise<WriteByRefResult> {
     this.ensureInitialized();
@@ -1415,6 +1504,9 @@ export 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: WriteByRefResult = {
       inserted: 0,
@@ -1424,7 +1516,8 @@ export class SimpleMongoHelper {
     };
     
     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') {
@@ -1590,6 +1683,9 @@ export 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: WriteStageResult = {
@@ -1608,7 +1704,7 @@ export class SimpleMongoHelper {
             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) {
@@ -1646,6 +1742,9 @@ export class SimpleMongoHelper {
       onUnmatched1 = 'include',
       onUnmatched2 = 'include',
       session,
+      database,
+      ref,
+      type,
     } = options;
 
     // Determine join behavior from joinType or fallback to onUnmatched flags
@@ -1689,9 +1788,10 @@ export class SimpleMongoHelper {
     };
 
     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: any = {};
       if (session) {
@@ -1982,22 +2082,109 @@ export class SimpleMongoHelper {
     }
   }
 
+  /**
+   * Registers automatic cleanup handlers for process exit events.
+   * This ensures connections are closed gracefully when the application terminates.
+   * Uses a global registry to handle multiple instances without conflicts.
+   * @internal
+   */
+  private registerCleanup(): void {
+    if (this.cleanupRegistered) {
+      return;
+    }
+    this.cleanupRegistered = true;
+
+    // Global registry for all SimpleMongoHelper instances
+    const globalRegistry = (global as any).__nxMongoHelperInstances || new Set<SimpleMongoHelper>();
+    (global as any).__nxMongoHelperInstances = globalRegistry;
+    globalRegistry.add(this);
+
+    // Register global cleanup handlers only once
+    if (!(global as any).__nxMongoCleanupRegistered) {
+      (global as any).__nxMongoCleanupRegistered = true;
+
+      if (typeof process !== 'undefined') {
+        const cleanupAll = async (signal?: string) => {
+          const instances = (global as any).__nxMongoHelperInstances as Set<SimpleMongoHelper>;
+          if (!instances || instances.size === 0) {
+            return;
+          }
+
+          // Cleanup all instances in parallel with timeout
+          const cleanupPromises = Array.from(instances).map(async (instance: SimpleMongoHelper) => {
+            try {
+              // Use the public disconnect method, but with timeout protection
+              const timeout = new Promise((_, reject) => 
+                setTimeout(() => reject(new Error('Disconnect timeout')), 5000)
+              );
+              
+              await Promise.race([
+                instance.disconnect(),
+                timeout
+              ]).catch(() => {
+                // Ignore timeout errors during automatic cleanup
+              });
+            } catch (error) {
+              // Silently ignore errors during automatic cleanup
+            }
+          });
+
+          await Promise.all(cleanupPromises).catch(() => {
+            // Ignore errors during cleanup
+          });
+        };
+
+        // Graceful shutdown signals
+        process.once('SIGINT', () => {
+          cleanupAll('SIGINT').finally(() => {
+            process.exit(0);
+          });
+        });
+
+        process.once('SIGTERM', () => {
+          cleanupAll('SIGTERM').finally(() => {
+            process.exit(0);
+          });
+        });
+
+        // Before exit (allows async cleanup)
+        process.once('beforeExit', () => {
+          cleanupAll('beforeExit');
+        });
+
+        // Note: We don't handle uncaughtException/unhandledRejection here
+        // as those should be handled by the application, not the library
+        // The beforeExit handler will still clean up connections
+      }
+    }
+  }
+
   /**
    * Closes the MongoDB connection and cleans up resources.
-   * @throws Error if disconnect fails
+   * This method is called automatically on process exit, but can also be called manually.
+   * @throws Error if disconnect fails (only when called manually, not during automatic cleanup)
    */
   async disconnect(): Promise<void> {
+    if (this.isDisconnecting) {
+      return;
+    }
+
     if (!this.isInitialized || !this.client) {
       return;
     }
 
+    this.isDisconnecting = true;
+
     try {
       await this.client.close();
       this.client = null;
       this.db = null;
       this.isInitialized = false;
     } catch (error) {
+      this.isDisconnecting = false;
       throw new Error(`Failed to disconnect: ${error instanceof Error ? error.message : String(error)}`);
+    } finally {
+      this.isDisconnecting = false;
     }
   }
 
@@ -2024,20 +2211,118 @@ export class SimpleMongoHelper {
   }
 
   /**
-   * 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/'
    */
-  private extractDatabaseName(connectionString: string): string {
+  private stripDatabaseFromConnectionString(connectionString: string): string {
     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
+   */
+  private resolveDatabase(options?: { database?: string; ref?: string; type?: string }): string | undefined {
+    // 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
+   */
+  private getDatabase(databaseName?: string): Db {
+    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
+   */
+  public getDatabaseByName(databaseName?: string, ref?: string, type?: string): Db {
+    return this.getDatabase(this.resolveDatabase({ database: databaseName, ref, type }));
   }
 }