nx-mongo 3.6.0 → 3.8.1

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 } }>`
@@ -103,9 +133,26 @@ Tests the MongoDB connection and returns detailed error information if it fails.
 ```typescript
 const result = await helper.testConnection();
 if (!result.success) {
-  console.error('Connection test failed:', result.error?.message);
-  console.error('Details:', result.error?.details);
-  // Handle error based on result.error?.type
+  console.error('Connection test failed!');
+  console.error('Error Type:', result.error?.type);
+  console.error('Error Message:', result.error?.message);
+  console.error('Error Details:', result.error?.details);
+  
+  // Handle error based on type
+  switch (result.error?.type) {
+    case 'connection_failed':
+      console.error('Cannot connect to MongoDB server. Check if server is running.');
+      // On Windows, try using 127.0.0.1 instead of localhost
+      break;
+    case 'authentication_failed':
+      console.error('Invalid credentials. Check username and password.');
+      break;
+    case 'invalid_connection_string':
+      console.error('Connection string format is invalid.');
+      break;
+    default:
+      console.error('Unknown error occurred.');
+  }
 } else {
   console.log('Connection test passed!');
   await helper.initialize();
@@ -120,6 +167,12 @@ if (!result.success) {
 - `config_error` - Configuration issues
 - `unknown` - Unexpected error
 
+**Troubleshooting Tips:**
+- **Windows users**: If using `localhost` fails, try `127.0.0.1` instead (e.g., `mongodb://127.0.0.1:27017/`) to avoid IPv6 resolution issues
+- **Connection timeout**: Verify MongoDB is running and accessible on the specified host and port
+- **Connection refused**: Check if MongoDB is listening on the correct port (default: 27017)
+- **Authentication failed**: Verify username and password in the connection string
+
 #### `initialize(): Promise<void>`
 
 Establishes MongoDB connection with automatic retry logic. Must be called before using other methods.
@@ -144,7 +197,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 +208,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 +216,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 +237,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 +256,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 +266,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 +299,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 +340,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 +379,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 +557,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 +583,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 +607,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 +629,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 +712,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 +765,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 +876,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 +886,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 +917,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 +1517,29 @@ Contributions are welcome! Please feel free to submit a Pull Request.
 
 ## Changelog
 
+### 3.8.1
+- **Fixed `testConnection()` error reporting bug**: Improved error extraction from MongoDB error objects to prevent `[object Object]` display
+- Enhanced error handling to extract MongoDB-specific error properties (`code`, `codeName`, `errmsg`)
+- Added Windows-specific troubleshooting hints for localhost connection issues (suggests using `127.0.0.1` instead of `localhost`)
+- Improved error messages with error codes and types for better debugging
+- Updated documentation with better error handling examples
+
+### 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