nx-mongo 3.5.0 → 3.8.0

package/README.md

@@ -1,6 +1,6 @@
 # nx-mongo
 
-**Version:** 3.5.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.
 
@@ -9,6 +9,7 @@ A lightweight, feature-rich MongoDB helper library for Node.js and TypeScript. P
 - ✅ **Simple API** - Easy-to-use methods for common MongoDB operations
 - ✅ **TypeScript Support** - Full TypeScript support with type safety
 - ✅ **Connection Retry** - Automatic retry with exponential backoff
+- ✅ **Automatic Cleanup** - Connections automatically close on app exit (SIGINT, SIGTERM, etc.)
 - ✅ **Pagination** - Built-in pagination support with metadata
 - ✅ **Transactions** - Full transaction support for multi-operation consistency
 - ✅ **Aggregation** - Complete aggregation pipeline support
@@ -30,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',
@@ -55,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' });
 
@@ -62,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
@@ -71,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)
@@ -79,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 } }>`
@@ -129,15 +160,21 @@ await helper.initialize();
 
 #### `disconnect(): Promise<void>`
 
-Closes the MongoDB connection and cleans up resources.
+Closes the MongoDB connection and cleans up resources. **Note:** Connections are automatically closed when your application exits (handles SIGINT, SIGTERM, and beforeExit events), so manual disconnection is optional but recommended for explicit cleanup.
 
 ```typescript
 await helper.disconnect();
 ```
 
+**Automatic Cleanup:**
+- Connections are automatically closed when the Node.js process receives `SIGINT` (Ctrl+C) or `SIGTERM` signals
+- All `SimpleMongoHelper` instances are cleaned up in parallel with a 5-second timeout
+- Multiple instances are handled gracefully through a global registry
+- Manual `disconnect()` is still recommended for explicit cleanup in your code
+
 ### 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.
 
@@ -148,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>[]`
@@ -155,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 });
 
@@ -173,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.
 
@@ -185,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
@@ -194,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.
 
@@ -227,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.
 
@@ -268,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.
 
@@ -307,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
@@ -484,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');
@@ -505,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', [
@@ -524,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
@@ -540,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');
@@ -614,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
+  }>;
 }
 ```
 
@@ -662,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:**
 
@@ -687,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.
 
@@ -697,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:**
 
@@ -725,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
@@ -1300,10 +1478,11 @@ try {
    await helper.createIndex('users', { email: 1 }, { unique: true });
    ```
 
-5. **Always disconnect when done:**
+5. **Disconnect when done (optional but recommended):**
    ```typescript
    await helper.disconnect();
    ```
+   **Note:** Connections automatically close on app exit (SIGINT/SIGTERM), but explicit disconnection is recommended for better control and immediate cleanup.
 
 ## License
 
@@ -1315,6 +1494,28 @@ 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
+- **Timeout protection**: 5-second timeout prevents hanging during automatic cleanup
+- Connections are properly managed and cleaned up even if users forget to call `disconnect()`
+
 ### 3.5.0
 - Enhanced `mergeCollections()` with SQL-style join types (`inner`, `left`, `right`, `outer`)
 - **Multiple match handling**: Now creates multiple rows when keys have duplicates (SQL-style behavior)