@edirect/mongo 11.0.47 → 11.0.49

package/README.md

@@ -1,13 +1,249 @@
-# @edirect/config
+# @edirect/mongo
 
-The EDirectInsure Mongo Module.
+> NestJS global module for MongoDB connections with Mongoose, including AWS IAM (IRSA) authentication support.
+
+This package provides a plug-and-play NestJS module that manages a Mongoose connection to MongoDB. It reads connection configuration from the environment via `@edirect/config`, automatically applies AWS IAM credential rotation when the `MONGODB-AWS` auth mechanism is detected, and tunes connection-pool settings for non-production environments. The resulting `Mongoose` instance is exposed under the `MONGO_CONNECTION` injection token and is available globally across the application.
+
+## Features
+
+- Single-import global NestJS module (`MongoModule`)
+- Automatic AWS IAM / IRSA credential rotation via `@aws-sdk/credential-providers`
+- Supports both `MONGO_URL` and `MONGODB_URI` environment variables (priority: `MONGO_URL`)
+- Conservative connection-pool defaults for development and test environments
+- `getConnection` utility for building connection parameters outside NestJS DI
+- `MONGO_CONNECTION` injection token for direct `Mongoose` instance injection
 
 ## Installation
 
-```shell
-$ npm i --save @edirect/mongo
+```bash
+npm install @edirect/mongo
 ```
 
+## Configuration
+
+### Environment Variables
+
+| Variable                      | Type     | Default | Description                                                                        |
+| ----------------------------- | -------- | ------- | ---------------------------------------------------------------------------------- |
+| `MONGO_URL`                   | `string` | —       | Primary MongoDB connection string (takes precedence over `MONGODB_URI`).           |
+| `MONGODB_URI`                 | `string` | —       | Fallback MongoDB connection string.                                                |
+| `NODE_ENV`                    | `string` | —       | Runtime environment. When `production` or `live`, pool tuning is disabled.         |
+| `MONGODB_AWS_ROLE_ARN`        | `string` | —       | **AWS IAM auth only.** ARN of the IAM role to assume via STS.                      |
+| `AWS_WEB_IDENTITY_TOKEN_FILE` | `string` | —       | **AWS IAM auth only.** Path to the Kubernetes service-account token file for IRSA. |
+
+> At least one of `MONGO_URL` or `MONGODB_URI` must be set, or the module will throw at startup.
+
 ## Usage
 
-Import MongoModule on AppModule (app.module.ts)
+### Basic Setup
+
+```typescript
+// app.module.ts
+import { Module } from '@nestjs/common';
+import { MongoModule } from '@edirect/mongo';
+
+@Module({
+  imports: [MongoModule],
+})
+export class AppModule {}
+```
+
+### Injecting the Mongoose Connection
+
+Use the `MONGO_CONNECTION` token to inject the raw Mongoose instance anywhere in your application:
+
+```typescript
+import { Injectable, Inject } from '@nestjs/common';
+import { MONGO_CONNECTION } from '@edirect/mongo';
+import mongoose from 'mongoose';
+
+@Injectable()
+export class DatabaseService {
+  constructor(
+    @Inject(MONGO_CONNECTION) private readonly connection: mongoose.Mongoose
+  ) {}
+
+  isConnected(): boolean {
+    return this.connection.connection.readyState === 1;
+  }
+}
+```
+
+### Registering Mongoose Models
+
+After importing `MongoModule`, register your schemas as model providers in feature modules:
+
+```typescript
+import { Module } from '@nestjs/common';
+import { getModelToken } from 'mongoose';
+import { MONGO_CONNECTION } from '@edirect/mongo';
+import { PolicySchema } from './policy.schema';
+
+@Module({
+  providers: [
+    {
+      provide: getModelToken('Policy'),
+      useFactory: (connection: mongoose.Mongoose) =>
+        connection.model('Policy', PolicySchema),
+      inject: [MONGO_CONNECTION],
+    },
+  ],
+  exports: [getModelToken('Policy')],
+})
+export class PolicyModule {}
+```
+
+### Standard Username/Password Connection
+
+```dotenv
+# .production.env
+MONGO_URL=mongodb://username:password@mongo-host:27017/mydb?authSource=admin
+```
+
+### AWS IAM (IRSA/EKS) Connection
+
+For EKS workloads with IRSA enabled, set the following environment variables:
+
+```dotenv
+MONGO_URL=mongodb+srv://cluster.example.com/mydb?authMechanism=MONGODB-AWS
+MONGODB_AWS_ROLE_ARN=arn:aws:iam::123456789012:role/my-mongo-role
+AWS_WEB_IDENTITY_TOKEN_FILE=/var/run/secrets/eks.amazonaws.com/serviceaccount/token
+```
+
+The module will automatically rotate credentials using `@aws-sdk/credential-providers` `fromNodeProviderChain`.
+
+### Using `getConnection` Programmatically
+
+```typescript
+import { getConnection } from '@edirect/mongo';
+import { ConfigService } from '@edirect/config';
+
+const config = new ConfigService();
+const connectionParams = getConnection(config);
+// Returns mongoose connection parameters object
+
+const connection = await mongoose.createConnection(
+  connectionParams.uri,
+  connectionParams.options
+);
+```
+
+### Connection Pool Sizing
+
+The module automatically adjusts pool settings based on `NODE_ENV`:
+
+| `NODE_ENV`            | Behavior                                             |
+| --------------------- | ---------------------------------------------------- |
+| `production` / `live` | Default Mongoose pool settings                       |
+| anything else         | Conservative pool settings (reduced for development) |
+
+## API Reference
+
+### `MongoModule`
+
+A global `@Module()` with no configuration options. Import it once in your root `AppModule`.
+
+```typescript
+import { MongoModule } from '@edirect/mongo';
+```
+
+### `getConnection(configService: ConfigService): MongoConnectionParams`
+
+Utility function that resolves the MongoDB connection string from `ConfigService` and returns the connection parameters.
+
+| Parameter       | Type            | Description                                     |
+| --------------- | --------------- | ----------------------------------------------- |
+| `configService` | `ConfigService` | Instance of `@edirect/config`'s `ConfigService` |
+
+**Returns:** Object containing the resolved URI and Mongoose connection options.
+
+**Throws:** If neither `MONGO_URL` nor `MONGODB_URI` is set in the environment.
+
+### `MONGO_CONNECTION`
+
+Injection token (`string`) for the Mongoose instance. Use with `@Inject(MONGO_CONNECTION)`.
+
+### `MongoProviders`
+
+Array of NestJS providers that wires the `MONGO_CONNECTION` token. Used internally by `MongoModule`.
+
+## Examples
+
+### Complete AppModule with Mongoose Model
+
+```typescript
+// app.module.ts
+import { Module } from '@nestjs/common';
+import { MongoModule } from '@edirect/mongo';
+import { PolicyModule } from './policy/policy.module';
+
+@Module({
+  imports: [MongoModule, PolicyModule],
+})
+export class AppModule {}
+```
+
+```typescript
+// policy/policy.module.ts
+import { Module } from '@nestjs/common';
+import mongoose, { Schema } from 'mongoose';
+import { MONGO_CONNECTION } from '@edirect/mongo';
+import { PolicyService } from './policy.service';
+
+const PolicySchema = new Schema({
+  policyNumber: String,
+  premium: Number,
+  startDate: Date,
+});
+
+@Module({
+  providers: [
+    {
+      provide: 'POLICY_MODEL',
+      useFactory: (conn: mongoose.Mongoose) =>
+        conn.model('Policy', PolicySchema),
+      inject: [MONGO_CONNECTION],
+    },
+    PolicyService,
+  ],
+  exports: [PolicyService],
+})
+export class PolicyModule {}
+```
+
+```typescript
+// policy/policy.service.ts
+import { Injectable, Inject } from '@nestjs/common';
+import { Model } from 'mongoose';
+
+@Injectable()
+export class PolicyService {
+  constructor(
+    @Inject('POLICY_MODEL') private readonly policyModel: Model<any>
+  ) {}
+
+  findAll() {
+    return this.policyModel.find().exec();
+  }
+}
+```
+
+### Health Check
+
+```typescript
+import { Injectable, Inject } from '@nestjs/common';
+import { MONGO_CONNECTION } from '@edirect/mongo';
+import mongoose from 'mongoose';
+
+@Injectable()
+export class HealthService {
+  constructor(
+    @Inject(MONGO_CONNECTION) private readonly mongo: mongoose.Mongoose
+  ) {}
+
+  isHealthy(): boolean {
+    // readyState: 0=disconnected, 1=connected, 2=connecting, 3=disconnecting
+    return this.mongo.connection.readyState === 1;
+  }
+}
+```

package/dist/README.md

@@ -1,13 +1,249 @@
-# @edirect/config
+# @edirect/mongo
 
-The EDirectInsure Mongo Module.
+> NestJS global module for MongoDB connections with Mongoose, including AWS IAM (IRSA) authentication support.
+
+This package provides a plug-and-play NestJS module that manages a Mongoose connection to MongoDB. It reads connection configuration from the environment via `@edirect/config`, automatically applies AWS IAM credential rotation when the `MONGODB-AWS` auth mechanism is detected, and tunes connection-pool settings for non-production environments. The resulting `Mongoose` instance is exposed under the `MONGO_CONNECTION` injection token and is available globally across the application.
+
+## Features
+
+- Single-import global NestJS module (`MongoModule`)
+- Automatic AWS IAM / IRSA credential rotation via `@aws-sdk/credential-providers`
+- Supports both `MONGO_URL` and `MONGODB_URI` environment variables (priority: `MONGO_URL`)
+- Conservative connection-pool defaults for development and test environments
+- `getConnection` utility for building connection parameters outside NestJS DI
+- `MONGO_CONNECTION` injection token for direct `Mongoose` instance injection
 
 ## Installation
 
-```shell
-$ npm i --save @edirect/mongo
+```bash
+npm install @edirect/mongo
 ```
 
+## Configuration
+
+### Environment Variables
+
+| Variable                      | Type     | Default | Description                                                                        |
+| ----------------------------- | -------- | ------- | ---------------------------------------------------------------------------------- |
+| `MONGO_URL`                   | `string` | —       | Primary MongoDB connection string (takes precedence over `MONGODB_URI`).           |
+| `MONGODB_URI`                 | `string` | —       | Fallback MongoDB connection string.                                                |
+| `NODE_ENV`                    | `string` | —       | Runtime environment. When `production` or `live`, pool tuning is disabled.         |
+| `MONGODB_AWS_ROLE_ARN`        | `string` | —       | **AWS IAM auth only.** ARN of the IAM role to assume via STS.                      |
+| `AWS_WEB_IDENTITY_TOKEN_FILE` | `string` | —       | **AWS IAM auth only.** Path to the Kubernetes service-account token file for IRSA. |
+
+> At least one of `MONGO_URL` or `MONGODB_URI` must be set, or the module will throw at startup.
+
 ## Usage
 
-Import MongoModule on AppModule (app.module.ts)
+### Basic Setup
+
+```typescript
+// app.module.ts
+import { Module } from '@nestjs/common';
+import { MongoModule } from '@edirect/mongo';
+
+@Module({
+  imports: [MongoModule],
+})
+export class AppModule {}
+```
+
+### Injecting the Mongoose Connection
+
+Use the `MONGO_CONNECTION` token to inject the raw Mongoose instance anywhere in your application:
+
+```typescript
+import { Injectable, Inject } from '@nestjs/common';
+import { MONGO_CONNECTION } from '@edirect/mongo';
+import mongoose from 'mongoose';
+
+@Injectable()
+export class DatabaseService {
+  constructor(
+    @Inject(MONGO_CONNECTION) private readonly connection: mongoose.Mongoose
+  ) {}
+
+  isConnected(): boolean {
+    return this.connection.connection.readyState === 1;
+  }
+}
+```
+
+### Registering Mongoose Models
+
+After importing `MongoModule`, register your schemas as model providers in feature modules:
+
+```typescript
+import { Module } from '@nestjs/common';
+import { getModelToken } from 'mongoose';
+import { MONGO_CONNECTION } from '@edirect/mongo';
+import { PolicySchema } from './policy.schema';
+
+@Module({
+  providers: [
+    {
+      provide: getModelToken('Policy'),
+      useFactory: (connection: mongoose.Mongoose) =>
+        connection.model('Policy', PolicySchema),
+      inject: [MONGO_CONNECTION],
+    },
+  ],
+  exports: [getModelToken('Policy')],
+})
+export class PolicyModule {}
+```
+
+### Standard Username/Password Connection
+
+```dotenv
+# .production.env
+MONGO_URL=mongodb://username:password@mongo-host:27017/mydb?authSource=admin
+```
+
+### AWS IAM (IRSA/EKS) Connection
+
+For EKS workloads with IRSA enabled, set the following environment variables:
+
+```dotenv
+MONGO_URL=mongodb+srv://cluster.example.com/mydb?authMechanism=MONGODB-AWS
+MONGODB_AWS_ROLE_ARN=arn:aws:iam::123456789012:role/my-mongo-role
+AWS_WEB_IDENTITY_TOKEN_FILE=/var/run/secrets/eks.amazonaws.com/serviceaccount/token
+```
+
+The module will automatically rotate credentials using `@aws-sdk/credential-providers` `fromNodeProviderChain`.
+
+### Using `getConnection` Programmatically
+
+```typescript
+import { getConnection } from '@edirect/mongo';
+import { ConfigService } from '@edirect/config';
+
+const config = new ConfigService();
+const connectionParams = getConnection(config);
+// Returns mongoose connection parameters object
+
+const connection = await mongoose.createConnection(
+  connectionParams.uri,
+  connectionParams.options
+);
+```
+
+### Connection Pool Sizing
+
+The module automatically adjusts pool settings based on `NODE_ENV`:
+
+| `NODE_ENV`            | Behavior                                             |
+| --------------------- | ---------------------------------------------------- |
+| `production` / `live` | Default Mongoose pool settings                       |
+| anything else         | Conservative pool settings (reduced for development) |
+
+## API Reference
+
+### `MongoModule`
+
+A global `@Module()` with no configuration options. Import it once in your root `AppModule`.
+
+```typescript
+import { MongoModule } from '@edirect/mongo';
+```
+
+### `getConnection(configService: ConfigService): MongoConnectionParams`
+
+Utility function that resolves the MongoDB connection string from `ConfigService` and returns the connection parameters.
+
+| Parameter       | Type            | Description                                     |
+| --------------- | --------------- | ----------------------------------------------- |
+| `configService` | `ConfigService` | Instance of `@edirect/config`'s `ConfigService` |
+
+**Returns:** Object containing the resolved URI and Mongoose connection options.
+
+**Throws:** If neither `MONGO_URL` nor `MONGODB_URI` is set in the environment.
+
+### `MONGO_CONNECTION`
+
+Injection token (`string`) for the Mongoose instance. Use with `@Inject(MONGO_CONNECTION)`.
+
+### `MongoProviders`
+
+Array of NestJS providers that wires the `MONGO_CONNECTION` token. Used internally by `MongoModule`.
+
+## Examples
+
+### Complete AppModule with Mongoose Model
+
+```typescript
+// app.module.ts
+import { Module } from '@nestjs/common';
+import { MongoModule } from '@edirect/mongo';
+import { PolicyModule } from './policy/policy.module';
+
+@Module({
+  imports: [MongoModule, PolicyModule],
+})
+export class AppModule {}
+```
+
+```typescript
+// policy/policy.module.ts
+import { Module } from '@nestjs/common';
+import mongoose, { Schema } from 'mongoose';
+import { MONGO_CONNECTION } from '@edirect/mongo';
+import { PolicyService } from './policy.service';
+
+const PolicySchema = new Schema({
+  policyNumber: String,
+  premium: Number,
+  startDate: Date,
+});
+
+@Module({
+  providers: [
+    {
+      provide: 'POLICY_MODEL',
+      useFactory: (conn: mongoose.Mongoose) =>
+        conn.model('Policy', PolicySchema),
+      inject: [MONGO_CONNECTION],
+    },
+    PolicyService,
+  ],
+  exports: [PolicyService],
+})
+export class PolicyModule {}
+```
+
+```typescript
+// policy/policy.service.ts
+import { Injectable, Inject } from '@nestjs/common';
+import { Model } from 'mongoose';
+
+@Injectable()
+export class PolicyService {
+  constructor(
+    @Inject('POLICY_MODEL') private readonly policyModel: Model<any>
+  ) {}
+
+  findAll() {
+    return this.policyModel.find().exec();
+  }
+}
+```
+
+### Health Check
+
+```typescript
+import { Injectable, Inject } from '@nestjs/common';
+import { MONGO_CONNECTION } from '@edirect/mongo';
+import mongoose from 'mongoose';
+
+@Injectable()
+export class HealthService {
+  constructor(
+    @Inject(MONGO_CONNECTION) private readonly mongo: mongoose.Mongoose
+  ) {}
+
+  isHealthy(): boolean {
+    // readyState: 0=disconnected, 1=connected, 2=connecting, 3=disconnecting
+    return this.mongo.connection.readyState === 1;
+  }
+}
+```

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edirect/mongo",
-  "version": "11.0.46",
+  "version": "11.0.48",
   "main": "./dist/src/index.js",
   "types": "./dist/src/index.d.ts",
   "exports": {
@@ -16,12 +16,11 @@
     "dist"
   ],
   "dependencies": {
-    "@aws-sdk/credential-providers": "^3.975.0",
-    "@edirect/config": "^11.0.46",
-    "@nestjs/common": "^11.1.12",
-    "aws4": "^1.13.2",
-    "mongodb": "^7.0.0",
-    "mongoose": "^9.1.5",
+    "@aws-sdk/credential-providers": "^3.1006.0",
+    "@edirect/config": "^11.0.48",
+    "@nestjs/common": "^11.1.16",
+    "mongodb": "^7.1.0",
+    "mongoose": "^9.3.0",
     "tslib": "^2.8.1"
   },
   "type": "commonjs"

package/dist/src/mongo.providers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mongo.providers.d.ts","sourceRoot":"","sources":["../../src/mongo.providers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAW,cAAc,EAAY,MAAM,UAAU,CAAC;AAC7D,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAShD,wBAAsB,aAAa,CAAC,aAAa,EAAE,aAAa;;;GAoB/D;AAED,eAAO,MAAM,cAAc,EAAE,QAAQ,EAcpC,CAAC"}
+{"version":3,"file":"mongo.providers.d.ts","sourceRoot":"","sources":["../../src/mongo.providers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAW,cAAc,EAAY,MAAM,UAAU,CAAC;AAC7D,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAsB,aAAa,EAAE,MAAM,iBAAiB,CAAC;AASpE,wBAAsB,aAAa,CAAC,aAAa,EAAE,aAAa;;;GAmB/D;AAED,eAAO,MAAM,cAAc,EAAE,QAAQ,EAcpC,CAAC"}

package/dist/src/mongo.providers.js

@@ -10,7 +10,7 @@ const mongoUrl = (configService) => configService.get('MONGO_URL') ?? configServ
 async function getConnection(configService) {
     const connectionString = mongoUrl(configService);
     if (!connectionString)
-        throw new Error('MongoDB connection string is not defined');
+        throw new config_1.ConfigMissingError('MONGO_URL');
     const options = {};
     // Always use dynamic AWS credential provider for MongoDB-AWS mechanism
     if ((connectionString ?? '').includes('MONGODB-AWS')) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edirect/mongo",
-  "version": "11.0.47",
+  "version": "11.0.49",
   "packageScope": "@edirect",
   "main": "./dist/src/index.js",
   "types": "./dist/src/index.d.ts",
@@ -17,13 +17,12 @@
     "dist"
   ],
   "dependencies": {
-    "@aws-sdk/credential-providers": "^3.975.0",
-    "@nestjs/common": "^11.1.12",
-    "aws4": "^1.13.2",
-    "mongodb": "^7.0.0",
-    "mongoose": "^9.1.5",
+    "@aws-sdk/credential-providers": "^3.1006.0",
+    "@nestjs/common": "^11.1.16",
+    "mongodb": "^7.1.0",
+    "mongoose": "^9.3.0",
     "tslib": "^2.8.1",
-    "@edirect/config": "11.0.47"
+    "@edirect/config": "11.0.49"
   },
   "nx": {
     "name": "@edirect/mongo",