nx-mongo 3.6.0 → 3.8.0

package/README.md

@@ -1,6 +1,6 @@
 # nx-mongo
 
-**Version:** 3.6.0
+**Version:** 3.8.0
 
 A lightweight, feature-rich MongoDB helper library for Node.js and TypeScript. Provides a simple, intuitive API for common MongoDB operations with built-in retry logic, pagination, transactions, config-driven ref mapping, and signature-based deduplication.
 
@@ -31,24 +31,39 @@ npm install nx-mongo
 ```typescript
 import { SimpleMongoHelper } from 'nx-mongo';
 
-const helper = new SimpleMongoHelper('mongodb://localhost:27017/my-database');
+// Connection string: database name is ignored/stripped automatically
+// Use base connection string: mongodb://localhost:27017/
+const helper = new SimpleMongoHelper('mongodb://localhost:27017/');
 
 // Initialize connection
 await helper.initialize();
 
-// Insert a document
+// Insert a document (defaults to 'admin' database)
 await helper.insert('users', {
   name: 'John Doe',
   email: 'john@example.com',
   age: 30
 });
 
-// Find documents
+// Insert into a specific database
+await helper.insert('users', {
+  name: 'Jane Doe',
+  email: 'jane@example.com',
+  age: 28
+}, {}, 'mydb'); // Specify database name
+
+// Find documents from 'admin' database (default)
 const users = await helper.loadCollection('users');
 
+// Find documents from specific database
+const mydbUsers = await helper.loadCollection('users', {}, undefined, 'mydb');
+
 // Find one document
 const user = await helper.findOne('users', { email: 'john@example.com' });
 
+// Find from specific database
+const mydbUser = await helper.findOne('users', { email: 'jane@example.com' }, undefined, 'mydb');
+
 // Update document
 await helper.update(
   'users',
@@ -56,6 +71,15 @@ await helper.update(
   { $set: { age: 31 } }
 );
 
+// Update in specific database
+await helper.update(
+  'users',
+  { email: 'jane@example.com' },
+  { $set: { age: 29 } },
+  undefined,
+  'mydb'
+);
+
 // Delete document
 await helper.delete('users', { email: 'john@example.com' });
 
@@ -63,6 +87,8 @@ await helper.delete('users', { email: 'john@example.com' });
 await helper.disconnect();
 ```
 
+**Note:** The connection string database name (if present) is automatically stripped. All operations default to the `'admin'` database unless you specify a different database name as the last parameter.
+
 ## API Reference
 
 ### Constructor
@@ -72,7 +98,8 @@ new SimpleMongoHelper(connectionString: string, retryOptions?: RetryOptions)
 ```
 
 **Parameters:**
-- `connectionString` - MongoDB connection string
+- `connectionString` - MongoDB base connection string (database name is automatically stripped if present)
+  - Example: `'mongodb://localhost:27017/'` or `'mongodb://localhost:27017/admin'` (both work the same)
 - `retryOptions` (optional) - Retry configuration
   - `maxRetries?: number` - Maximum retry attempts (default: 3)
   - `retryDelay?: number` - Initial retry delay in ms (default: 1000)
@@ -80,12 +107,15 @@ new SimpleMongoHelper(connectionString: string, retryOptions?: RetryOptions)
 
 **Example:**
 ```typescript
+// Database name in connection string is ignored/stripped
 const helper = new SimpleMongoHelper(
-  'mongodb://localhost:27017/my-db',
+  'mongodb://localhost:27017/', // or 'mongodb://localhost:27017/admin'
   { maxRetries: 5, retryDelay: 2000 }
 );
 ```
 
+**Important:** The database name in the connection string is automatically stripped. All operations default to the `'admin'` database unless you specify a different database name per operation.
+
 ### Connection Methods
 
 #### `testConnection(): Promise<{ success: boolean; error?: { type: string; message: string; details?: string } }>`
@@ -144,7 +174,7 @@ await helper.disconnect();
 
 ### Query Methods
 
-#### `loadCollection<T>(collectionName: string, query?: Filter<T>, options?: PaginationOptions): Promise<WithId<T>[] | PaginatedResult<T>>`
+#### `loadCollection<T>(collectionName: string, query?: Filter<T>, options?: PaginationOptions, database?: string): Promise<WithId<T>[] | PaginatedResult<T>>`
 
 Loads documents from a collection with optional query filter and pagination.
 
@@ -155,6 +185,7 @@ Loads documents from a collection with optional query filter and pagination.
   - `page?: number` - Page number (1-indexed)
   - `limit?: number` - Documents per page
   - `sort?: Sort` - Sort specification
+- `database` (optional) - Database name (defaults to `'admin'`)
 
 **Returns:**
 - Without pagination: `WithId<T>[]`
@@ -162,9 +193,12 @@ Loads documents from a collection with optional query filter and pagination.
 
 **Examples:**
 ```typescript
-// Load all documents
+// Load all documents from 'admin' database (default)
 const allUsers = await helper.loadCollection('users');
 
+// Load from specific database
+const mydbUsers = await helper.loadCollection('users', {}, undefined, 'mydb');
+
 // Load with query
 const activeUsers = await helper.loadCollection('users', { active: true });
 
@@ -180,9 +214,16 @@ const result = await helper.loadCollection('users', {}, {
 // result.totalPages - total pages
 // result.hasNext - has next page
 // result.hasPrev - has previous page
+
+// Load with pagination from specific database
+const mydbResult = await helper.loadCollection('users', {}, {
+  page: 1,
+  limit: 10,
+  sort: { createdAt: -1 }
+}, 'mydb');
 ```
 
-#### `findOne<T>(collectionName: string, query: Filter<T>, options?: { sort?: Sort; projection?: Document }): Promise<WithId<T> | null>`
+#### `findOne<T>(collectionName: string, query: Filter<T>, options?: { sort?: Sort; projection?: Document }, database?: string): Promise<WithId<T> | null>`
 
 Finds a single document in a collection.
 
@@ -192,6 +233,7 @@ Finds a single document in a collection.
 - `options` (optional) - Find options
   - `sort?: Sort` - Sort specification
   - `projection?: Document` - Field projection
+- `database` (optional) - Database name (defaults to `'admin'`)
 
 **Example:**
 ```typescript
@@ -201,7 +243,7 @@ const latestUser = await helper.findOne('users', {}, { sort: { createdAt: -1 } }
 
 ### Insert Methods
 
-#### `insert<T>(collectionName: string, data: T | T[], options?: { session?: ClientSession }): Promise<any>`
+#### `insert<T>(collectionName: string, data: T | T[], options?: { session?: ClientSession }, database?: string): Promise<any>`
 
 Inserts one or more documents into a collection.
 
@@ -234,7 +276,7 @@ await session.withTransaction(async () => {
 
 ### Update Methods
 
-#### `update<T>(collectionName: string, filter: Filter<T>, updateData: UpdateFilter<T>, options?: { upsert?: boolean; multi?: boolean; session?: ClientSession }): Promise<any>`
+#### `update<T>(collectionName: string, filter: Filter<T>, updateData: UpdateFilter<T>, options?: { upsert?: boolean; multi?: boolean; session?: ClientSession }, database?: string): Promise<any>`
 
 Updates documents in a collection.
 
@@ -275,7 +317,7 @@ await helper.update(
 
 ### Delete Methods
 
-#### `delete<T>(collectionName: string, filter: Filter<T>, options?: { multi?: boolean }): Promise<any>`
+#### `delete<T>(collectionName: string, filter: Filter<T>, options?: { multi?: boolean }, database?: string): Promise<any>`
 
 Deletes documents from a collection.
 
@@ -314,6 +356,7 @@ Merges two collections into a new target collection using various strategies (in
 - `onUnmatched1` - (Deprecated: use `joinType` instead) What to do with unmatched records from collection 1: 'include' | 'skip' (default: 'include')
 - `onUnmatched2` - (Deprecated: use `joinType` instead) What to do with unmatched records from collection 2: 'include' | 'skip' (default: 'include')
 - `session` - Optional transaction session
+- `database` - Optional database name (defaults to `'admin'`)
 
 **Returns:**
 ```typescript
@@ -491,10 +534,15 @@ const result6 = await helper.mergeCollections({
 
 ### Count Methods
 
-#### `countDocuments<T>(collectionName: string, query?: Filter<T>): Promise<number>`
+#### `countDocuments<T>(collectionName: string, query?: Filter<T>, database?: string): Promise<number>`
 
 Counts documents matching a query (accurate count).
 
+**Parameters:**
+- `collectionName` - Name of the collection
+- `query` (optional) - MongoDB query filter
+- `database` (optional) - Database name (defaults to `'admin'`)
+
 **Example:**
 ```typescript
 const userCount = await helper.countDocuments('users');
@@ -512,10 +560,15 @@ const estimatedCount = await helper.estimatedDocumentCount('users');
 
 ### Aggregation Methods
 
-#### `aggregate<T>(collectionName: string, pipeline: Document[]): Promise<T[]>`
+#### `aggregate<T>(collectionName: string, pipeline: Document[], database?: string): Promise<T[]>`
 
 Runs an aggregation pipeline on a collection.
 
+**Parameters:**
+- `collectionName` - Name of the collection
+- `pipeline` - Array of aggregation pipeline stages
+- `database` (optional) - Database name (defaults to `'admin'`)
+
 **Example:**
 ```typescript
 const result = await helper.aggregate('orders', [
@@ -531,10 +584,16 @@ const result = await helper.aggregate('orders', [
 
 ### Index Methods
 
-#### `createIndex(collectionName: string, indexSpec: IndexSpecification, options?: CreateIndexesOptions): Promise<string>`
+#### `createIndex(collectionName: string, indexSpec: IndexSpecification, options?: CreateIndexesOptions, database?: string): Promise<string>`
 
 Creates an index on a collection.
 
+**Parameters:**
+- `collectionName` - Name of the collection
+- `indexSpec` - Index specification
+- `options` (optional) - Index creation options
+- `database` (optional) - Database name (defaults to `'admin'`)
+
 **Example:**
 ```typescript
 // Simple index
@@ -547,19 +606,28 @@ await helper.createIndex('users', { email: 1 }, { unique: true });
 await helper.createIndex('users', { email: 1, createdAt: -1 });
 ```
 
-#### `dropIndex(collectionName: string, indexName: string): Promise<any>`
+#### `dropIndex(collectionName: string, indexName: string, database?: string): Promise<any>`
 
 Drops an index from a collection.
 
+**Parameters:**
+- `collectionName` - Name of the collection
+- `indexName` - Name of the index to drop
+- `database` (optional) - Database name (defaults to `'admin'`)
+
 **Example:**
 ```typescript
 await helper.dropIndex('users', 'email_1');
 ```
 
-#### `listIndexes(collectionName: string): Promise<Document[]>`
+#### `listIndexes(collectionName: string, database?: string): Promise<Document[]>`
 
 Lists all indexes on a collection.
 
+**Parameters:**
+- `collectionName` - Name of the collection
+- `database` (optional) - Database name (defaults to `'admin'`)
+
 **Example:**
 ```typescript
 const indexes = await helper.listIndexes('users');
@@ -621,6 +689,11 @@ interface HelperConfig {
     uniqueIndexKeys?: string[];  // Unique index keys (default: ["provider","key"])
     provider?: string;           // Default provider namespace for this helper instance
   };
+  databases?: Array<{
+    ref: string;                 // Reference identifier
+    type: string;                // Type identifier
+    database: string;            // Database name to use
+  }>;
 }
 ```
 
@@ -669,15 +742,101 @@ Sets or updates the configuration for ref-based operations.
 helper.useConfig(config);
 ```
 
+### Database Selection via Ref/Type Map
+
+The helper supports config-driven database selection using `ref` and `type` parameters. This allows you to map logical identifiers to database names without hardcoding them in your application code.
+
+**Configuration:**
+
+```typescript
+const config = {
+  // ... inputs, outputs, etc.
+  databases: [
+    { ref: "app1", type: "production", database: "app1_prod" },
+    { ref: "app1", type: "staging", database: "app1_staging" },
+    { ref: "app2", type: "production", database: "app2_prod" },
+    { ref: "app2", type: "staging", database: "app2_staging" },
+  ]
+};
+```
+
+**Usage in CRUD Operations:**
+
+All CRUD operations now support optional `ref` and `type` parameters for automatic database resolution:
+
+```typescript
+// Priority 1: Direct database parameter (highest priority)
+await helper.insert('users', { name: 'John' }, {}, 'mydb');
+
+// Priority 2: Using ref + type (exact match)
+await helper.insert('users', { name: 'John' }, {}, undefined, 'app1', 'production');
+// Resolves to 'app1_prod' database
+
+// Priority 3: Using ref alone (must have exactly one match)
+await helper.insert('users', { name: 'John' }, {}, undefined, 'app1');
+// Throws error if multiple matches found
+
+// Priority 4: Using type alone (must have exactly one match)
+await helper.insert('users', { name: 'John' }, {}, undefined, undefined, 'production');
+// Throws error if multiple matches found
+```
+
+**Database Resolution Priority:**
+
+1. **Direct `database` parameter** - If provided, it's used immediately (highest priority)
+2. **`ref` + `type`** - If both provided, finds exact match in databases map
+3. **`ref` alone** - If only ref provided, finds entries matching ref (must be exactly one)
+4. **`type` alone** - If only type provided, finds entries matching type (must be exactly one)
+5. **Default** - If none provided, defaults to `'admin'` database
+
+**Error Handling:**
+
+- If no match found: throws error with descriptive message
+- If multiple matches found: throws error suggesting to use additional parameter to narrow down
+
+**Example:**
+
+```typescript
+const config = {
+  databases: [
+    { ref: "tenant1", type: "prod", database: "tenant1_prod" },
+    { ref: "tenant1", type: "dev", database: "tenant1_dev" },
+    { ref: "tenant2", type: "prod", database: "tenant2_prod" },
+  ]
+};
+
+const helper = new SimpleMongoHelper('mongodb://localhost:27017/', undefined, config);
+await helper.initialize();
+
+// Use ref + type for exact match
+await helper.insert('users', { name: 'John' }, {}, undefined, 'tenant1', 'prod');
+// Uses 'tenant1_prod' database
+
+// Use ref alone (only works if exactly one match)
+// This would throw error because tenant1 has 2 matches (prod and dev)
+// await helper.insert('users', { name: 'John' }, {}, undefined, 'tenant1');
+
+// Use type alone (only works if exactly one match)
+// This would throw error because 'prod' has 2 matches (tenant1 and tenant2)
+// await helper.insert('users', { name: 'John' }, {}, undefined, undefined, 'prod');
+```
+
 ### Ref-based Operations
 
-#### `loadByRef<T>(ref: string, options?: PaginationOptions & { session?: ClientSession }): Promise<WithId<T>[] | PaginatedResult<T>>`
+#### `loadByRef<T>(ref: string, options?: PaginationOptions & { session?: ClientSession; database?: string; ref?: string; type?: string }): Promise<WithId<T>[] | PaginatedResult<T>>`
 
 Loads data from a collection using a ref name from the configuration.
 
 **Parameters:**
 - `ref` - Application-level reference name (must exist in config.inputs)
 - `options` (optional) - Pagination and session options
+  - `page?: number` - Page number (1-indexed)
+  - `limit?: number` - Documents per page
+  - `sort?: Sort` - Sort specification
+  - `session?: ClientSession` - Transaction session
+  - `database?: string` - Database name (defaults to `'admin'`)
+  - `ref?: string` - Optional ref for database resolution
+  - `type?: string` - Optional type for database resolution
 
 **Example:**
 
@@ -694,7 +853,7 @@ const result = await helper.loadByRef('topology', {
 });
 ```
 
-#### `writeByRef(ref: string, documents: any[], options?: { session?: ClientSession; ensureIndex?: boolean }): Promise<WriteByRefResult>`
+#### `writeByRef(ref: string, documents: any[], options?: { session?: ClientSession; ensureIndex?: boolean; database?: string; ref?: string; type?: string }): Promise<WriteByRefResult>`
 
 Writes documents to a collection using a ref name from the configuration. Supports signature-based deduplication and append/replace modes.
 
@@ -704,6 +863,9 @@ Writes documents to a collection using a ref name from the configuration. Suppor
 - `options` (optional) - Write options
   - `session?: ClientSession` - Transaction session
   - `ensureIndex?: boolean` - Whether to ensure signature index exists (default: true)
+  - `database?: string` - Database name (defaults to `'admin'`)
+  - `ref?: string` - Optional ref for database resolution
+  - `type?: string` - Optional type for database resolution
 
 **Returns:**
 
@@ -732,6 +894,15 @@ await helper.writeByRef('prioritizedPaths', prioritizedDocs);
 
 Writes documents to a collection and optionally marks a stage as complete atomically. See the [Progress Tracking](#progress-tracking) section for details and examples.
 
+**Parameters:**
+- `ref` - Application-level reference name (must exist in config.outputs)
+- `documents` - Array of documents to write
+- `options` (optional) - Write and completion options
+  - `session?: ClientSession` - Transaction session
+  - `ensureIndex?: boolean` - Whether to ensure signature index exists (default: true)
+  - `database?: string` - Database name (defaults to `'admin'`)
+  - `complete?: object` - Stage completion information (optional)
+
 **Example:**
 
 ```typescript
@@ -1323,6 +1494,22 @@ Contributions are welcome! Please feel free to submit a Pull Request.
 
 ## Changelog
 
+### 3.8.0
+- **Database selection via ref/type map**: Added config-driven database selection using `ref` and `type` parameters
+- Added `databases` array to `HelperConfig` for mapping ref/type combinations to database names
+- All CRUD operations now support optional `ref` and `type` parameters for automatic database resolution
+- Database resolution priority: direct `database` parameter > `ref` + `type` > `ref` alone > `type` alone
+- Throws descriptive errors when no match or multiple matches found in database map
+- Updated Progress API to support database resolution via ref/type
+- Updated `loadByRef`, `writeByRef`, `writeStage`, and `mergeCollections` to support database map resolution
+
+### 3.7.0
+- **Separated database from connection string**: Database name is now specified per operation, not in connection string
+- **Multi-database support**: All operations accept optional `database` parameter (defaults to `'admin'`)
+- Connection string database name is automatically stripped if present (e.g., `mongodb://localhost:27017/admin` becomes `mongodb://localhost:27017/`)
+- Updated all methods (`insert`, `update`, `delete`, `loadCollection`, `findOne`, `countDocuments`, `aggregate`, `createIndex`, `dropIndex`, `listIndexes`, `writeByRef`, `loadByRef`, `mergeCollections`, `writeStage`, and progress API) to support per-operation database selection
+- **Breaking change**: No backward compatibility - all code must be updated to use new database parameter
+
 ### 3.6.0
 - **Automatic connection cleanup**: Connections now automatically close on app exit (SIGINT, SIGTERM, beforeExit)
 - **Multi-instance support**: Global registry handles multiple `SimpleMongoHelper` instances gracefully

package/dist/simpleMongoHelper.d.ts

@@ -40,6 +40,11 @@ export interface HelperConfig {
         uniqueIndexKeys?: string[];
         provider?: string;
     };
+    databases?: Array<{
+        ref: string;
+        type: string;
+        database: string;
+    }>;
 }
 export interface WriteByRefResult {
     inserted: number;
@@ -75,6 +80,9 @@ export interface StageRecord extends StageIdentity {
 }
 export type ProgressSessionOptions = {
     session?: ClientSession;
+    database?: string;
+    ref?: string;
+    type?: string;
 };
 export interface ProgressAPI {
     isCompleted(key: string, options?: ProgressSessionOptions & {
@@ -101,6 +109,9 @@ export interface ProgressAPI {
 export interface WriteStageOptions {
     ensureIndex?: boolean;
     session?: ClientSession;
+    database?: string;
+    ref?: string;
+    type?: string;
     complete?: {
         key: string;
         process?: string;
@@ -126,6 +137,9 @@ export interface MergeCollectionsOptions {
     onUnmatched1?: 'include' | 'skip';
     onUnmatched2?: 'include' | 'skip';
     session?: ClientSession;
+    database?: string;
+    ref?: string;
+    type?: string;
 }
 export interface MergeCollectionsResult {
     merged: number;
@@ -207,7 +221,7 @@ export declare class SimpleMongoHelper {
      * @returns Array of documents matching the query or paginated result
      * @throws Error if not initialized or if query fails
      */
-    loadCollection<T extends Document = Document>(collectionName: string, query?: Filter<T>, options?: PaginationOptions): Promise<WithId<T>[] | PaginatedResult<T>>;
+    loadCollection<T extends Document = Document>(collectionName: string, query?: Filter<T>, options?: PaginationOptions, database?: string, ref?: string, type?: string): Promise<WithId<T>[] | PaginatedResult<T>>;
     /**
      * Finds a single document in a collection.
      * @param collectionName - Name of the collection to query
@@ -219,7 +233,7 @@ export declare class SimpleMongoHelper {
     findOne<T extends Document = Document>(collectionName: string, query: Filter<T>, options?: {
         sort?: Sort;
         projection?: Document;
-    }): Promise<WithId<T> | null>;
+    }, database?: string, ref?: string, type?: string): Promise<WithId<T> | null>;
     /**
      * Inserts data into a collection.
      * @param collectionName - Name of the collection to insert into
@@ -230,7 +244,7 @@ export declare class SimpleMongoHelper {
      */
     insert<T extends Document = Document>(collectionName: string, data: OptionalUnlessRequiredId<T> | OptionalUnlessRequiredId<T>[], options?: {
         session?: ClientSession;
-    }): Promise<any>;
+    }, database?: string, ref?: string, type?: string): Promise<any>;
     /**
      * Updates records in a collection.
      * @param collectionName - Name of the collection to update
@@ -244,7 +258,7 @@ export declare class SimpleMongoHelper {
         upsert?: boolean;
         multi?: boolean;
         session?: ClientSession;
-    }): Promise<any>;
+    }, database?: string, ref?: string, type?: string): Promise<any>;
     /**
      * Deletes documents from a collection.
      * @param collectionName - Name of the collection to delete from
@@ -255,7 +269,7 @@ export declare class SimpleMongoHelper {
      */
     delete<T extends Document = Document>(collectionName: string, filter: Filter<T>, options?: {
         multi?: boolean;
-    }): Promise<any>;
+    }, database?: string, ref?: string, type?: string): Promise<any>;
     /**
      * Counts documents in a collection matching a query.
      * @param collectionName - Name of the collection to count
@@ -263,14 +277,14 @@ export declare class SimpleMongoHelper {
      * @returns Number of documents matching the query
      * @throws Error if not initialized or if count fails
      */
-    countDocuments<T extends Document = Document>(collectionName: string, query?: Filter<T>): Promise<number>;
+    countDocuments<T extends Document = Document>(collectionName: string, query?: Filter<T>, database?: string, ref?: string, type?: string): Promise<number>;
     /**
      * Gets an estimated document count for a collection (faster but less accurate).
      * @param collectionName - Name of the collection to count
      * @returns Estimated number of documents
      * @throws Error if not initialized or if count fails
      */
-    estimatedDocumentCount(collectionName: string): Promise<number>;
+    estimatedDocumentCount(collectionName: string, database?: string, ref?: string, type?: string): Promise<number>;
     /**
      * Runs an aggregation pipeline on a collection.
      * @param collectionName - Name of the collection to aggregate
@@ -278,7 +292,7 @@ export declare class SimpleMongoHelper {
      * @returns Array of aggregated results
      * @throws Error if not initialized or if aggregation fails
      */
-    aggregate<T extends Document = Document>(collectionName: string, pipeline: Document[]): Promise<T[]>;
+    aggregate<T extends Document = Document>(collectionName: string, pipeline: Document[], database?: string, ref?: string, type?: string): Promise<T[]>;
     /**
      * Creates an index on a collection.
      * @param collectionName - Name of the collection
@@ -287,7 +301,7 @@ export declare class SimpleMongoHelper {
      * @returns Index name
      * @throws Error if not initialized or if index creation fails
      */
-    createIndex(collectionName: string, indexSpec: IndexSpecification, options?: CreateIndexesOptions): Promise<string>;
+    createIndex(collectionName: string, indexSpec: IndexSpecification, options?: CreateIndexesOptions, database?: string, ref?: string, type?: string): Promise<string>;
     /**
      * Drops an index from a collection.
      * @param collectionName - Name of the collection
@@ -295,14 +309,14 @@ export declare class SimpleMongoHelper {
      * @returns Result object
      * @throws Error if not initialized or if index drop fails
      */
-    dropIndex(collectionName: string, indexName: string): Promise<any>;
+    dropIndex(collectionName: string, indexName: string, database?: string, ref?: string, type?: string): Promise<any>;
     /**
      * Lists all indexes on a collection.
      * @param collectionName - Name of the collection
      * @returns Array of index information
      * @throws Error if not initialized or if listing fails
      */
-    listIndexes(collectionName: string): Promise<Document[]>;
+    listIndexes(collectionName: string, database?: string, ref?: string, type?: string): Promise<Document[]>;
     /**
      * Starts a new client session for transactions.
      * @returns Client session
@@ -325,6 +339,9 @@ export declare class SimpleMongoHelper {
      */
     loadByRef<T extends Document = Document>(ref: string, options?: PaginationOptions & {
         session?: ClientSession;
+        database?: string;
+        ref?: string;
+        type?: string;
     }): Promise<WithId<T>[] | PaginatedResult<T>>;
     /**
      * Ensures a unique index exists on the _sig field for signature-based deduplication.
@@ -338,6 +355,9 @@ export declare class SimpleMongoHelper {
     ensureSignatureIndex(collectionName: string, options?: {
         fieldName?: string;
         unique?: boolean;
+        database?: string;
+        ref?: string;
+        type?: string;
     }): Promise<EnsureSignatureIndexResult>;
     /**
      * Writes documents to a collection using a ref name from the configuration.
@@ -353,6 +373,9 @@ export declare class SimpleMongoHelper {
     writeByRef(ref: string, documents: any[], options?: {
         session?: ClientSession;
         ensureIndex?: boolean;
+        database?: string;
+        ref?: string;
+        type?: string;
     }): Promise<WriteByRefResult>;
     /**
      * Writes documents to a collection using a ref name and optionally marks a stage as complete.
@@ -400,10 +423,40 @@ export declare class SimpleMongoHelper {
      */
     getDb(): Db;
     /**
-     * Extracts database name from MongoDB connection string.
-     * @param connectionString - MongoDB connection string
-     * @returns Database name or 'test' as default
+     * Strips database name from MongoDB connection string, returning base connection string.
+     * @param connectionString - MongoDB connection string (may include database name)
+     * @returns Base connection string without database name
+     * @example
+     * stripDatabaseFromConnectionString('mongodb://localhost:27017/admin')
+     * // Returns: 'mongodb://localhost:27017/'
+     */
+    private stripDatabaseFromConnectionString;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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
      */
-    private extractDatabaseName;
+    getDatabaseByName(databaseName?: string, ref?: string, type?: string): Db;
 }
 //# sourceMappingURL=simpleMongoHelper.d.ts.map