nx-mongo 3.6.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: {
@@ -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)
@@ -864,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) {
@@ -897,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);
 
@@ -954,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) {
@@ -987,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)) {
@@ -1020,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;
@@ -1053,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);
@@ -1081,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) {
@@ -1100,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) {
@@ -1121,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) {
@@ -1145,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) {
@@ -1165,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) {
@@ -1183,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) {
@@ -1249,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();
     
@@ -1262,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;
     
@@ -1328,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
@@ -1402,6 +1483,9 @@ export class SimpleMongoHelper {
     options?: {
       session?: ClientSession;
       ensureIndex?: boolean;
+      database?: string;
+      ref?: string;
+      type?: string;
     }
   ): Promise<WriteByRefResult> {
     this.ensureInitialized();
@@ -1420,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,
@@ -1429,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') {
@@ -1595,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 = {
@@ -1613,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) {
@@ -1651,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
@@ -1694,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) {
@@ -2116,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 }));
   }
 }