nx-mongo 3.6.0 → 3.8.1

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: {
@@ -616,7 +652,8 @@ export class SimpleMongoHelper {
   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,
@@ -733,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)
@@ -769,81 +805,123 @@ export class SimpleMongoHelper {
         }
       }
       
-      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: string | number | undefined;
+      
+      if (error instanceof Error) {
+        errorMessage = error.message || 'Unknown error';
+        errorName = error.name || 'Error';
+        // Check for MongoDB-specific error properties
+        const mongoError = error as any;
+        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 as any;
+        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
         }
       };
     }
@@ -864,9 +942,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) {
@@ -897,12 +974,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);
 
@@ -954,12 +1035,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) {
@@ -987,12 +1072,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)) {
@@ -1020,12 +1109,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;
@@ -1053,12 +1146,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);
@@ -1081,12 +1178,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) {
@@ -1100,11 +1201,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) {
@@ -1121,12 +1223,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) {
@@ -1145,12 +1251,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) {
@@ -1165,11 +1275,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) {
@@ -1183,11 +1294,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) {
@@ -1249,7 +1361,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();
     
@@ -1262,9 +1374,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;
     
@@ -1328,15 +1444,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
@@ -1402,6 +1525,9 @@ export class SimpleMongoHelper {
     options?: {
       session?: ClientSession;
       ensureIndex?: boolean;
+      database?: string;
+      ref?: string;
+      type?: string;
     }
   ): Promise<WriteByRefResult> {
     this.ensureInitialized();
@@ -1420,6 +1546,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,
@@ -1429,7 +1558,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') {
@@ -1595,6 +1725,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 = {
@@ -1613,7 +1746,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) {
@@ -1651,6 +1784,9 @@ export class SimpleMongoHelper {
       onUnmatched1 = 'include',
       onUnmatched2 = 'include',
       session,
+      database,
+      ref,
+      type,
     } = options;
 
     // Determine join behavior from joinType or fallback to onUnmatched flags
@@ -1694,9 +1830,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) {
@@ -2116,20 +2253,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 }));
+  }
 }