@edirect/mongo 11.0.62 → 11.0.64

package/dist/README.md

@@ -0,0 +1,249 @@
+# @edirect/mongo
+
+> 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
+
+```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
+
+### 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

@@ -0,0 +1,27 @@
+{
+  "name": "@edirect/mongo",
+  "version": "11.0.64",
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/src/index.js",
+      "default": "./dist/src/index.js",
+      "require": "./dist/src/index.js",
+      "types": "./dist/src/index.d.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@aws-sdk/credential-providers": "^3.1112.0",
+    "@edirect/config": "^11.0.64",
+    "@nestjs/common": "^11.2.1",
+    "mongodb": "^7.5.0",
+    "mongoose": "^9.9.3",
+    "tslib": "^2.8.1"
+  },
+  "type": "commonjs"
+}

package/dist/src/aws.d.ts

@@ -0,0 +1,5 @@
+import { AWSCredentials } from 'mongodb';
+export declare const MONGODB_AWS_ROLE_ARN: string | undefined;
+export declare const AWS_WEB_IDENTITY_TOKEN_FILE: string | undefined;
+export declare function getMongoAwsCredentialProvider(): () => Promise<AWSCredentials>;
+//# sourceMappingURL=aws.d.ts.map

package/dist/src/aws.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aws.d.ts","sourceRoot":"","sources":["../../src/aws.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAKzC,eAAO,MAAM,oBAAoB,oBAAmC,CAAC;AACrE,eAAO,MAAM,2BAA2B,oBACC,CAAC;AAI1C,wBAAgB,6BAA6B,IAAI,MAAM,OAAO,CAAC,cAAc,CAAC,CAY7E"}

package/dist/src/aws.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AWS_WEB_IDENTITY_TOKEN_FILE = exports.MONGODB_AWS_ROLE_ARN = void 0;
+exports.getMongoAwsCredentialProvider = getMongoAwsCredentialProvider;
+const credential_providers_1 = require("@aws-sdk/credential-providers");
+// Environment variables required for IRSA/EKS role assumption authentication:
+//   MONGODB_AWS_ROLE_ARN: the AWS IAM Role ARN to assume
+//   AWS_WEB_IDENTITY_TOKEN_FILE: path to serviceAccount token (set by kubelet when IRSA is enabled)
+exports.MONGODB_AWS_ROLE_ARN = process.env.MONGODB_AWS_ROLE_ARN;
+exports.AWS_WEB_IDENTITY_TOKEN_FILE = process.env.AWS_WEB_IDENTITY_TOKEN_FILE;
+// A dynamic credentials provider for the MongoDB driver that will always fetch fresh AWS credentials (using IRSA+STS)
+// ALWAYS use this as the value of AWS_CREDENTIAL_PROVIDER in authMechanismProperties. Never embed static keys/tokens in the URI.
+function getMongoAwsCredentialProvider() {
+    if (!exports.MONGODB_AWS_ROLE_ARN || !exports.AWS_WEB_IDENTITY_TOKEN_FILE) {
+        throw new Error('[mongo] MONGODB_AWS_ROLE_ARN or AWS_WEB_IDENTITY_TOKEN_FILE are not set. ' +
+            'These are required for AWS IAM auth (IRSA, STS assume role), and must be set in the environment!');
+    }
+    // This permanently produces a rotating credentials chain using the specified roleArn, IRSA, and web identity token
+    const credentialChain = (0, credential_providers_1.fromNodeProviderChain)({
+        roleArn: exports.MONGODB_AWS_ROLE_ARN,
+    });
+    return () => credentialChain();
+}

package/dist/src/index.d.ts

@@ -0,0 +1,3 @@
+export * from './mongo.module';
+export { getConnection } from './mongo.providers';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/src/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getConnection = void 0;
+const tslib_1 = require("tslib");
+tslib_1.__exportStar(require("./mongo.module"), exports);
+var mongo_providers_1 = require("./mongo.providers");
+Object.defineProperty(exports, "getConnection", { enumerable: true, get: function () { return mongo_providers_1.getConnection; } });

package/dist/src/mongo.module.d.ts

@@ -0,0 +1,3 @@
+export declare class MongoModule {
+}
+//# sourceMappingURL=mongo.module.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"mongo.module.d.ts","sourceRoot":"","sources":["../../src/mongo.module.ts"],"names":[],"mappings":"AAKA,qBAMa,WAAW;CAAG"}

package/dist/src/mongo.module.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MongoModule = void 0;
+const tslib_1 = require("tslib");
+const config_1 = require("@edirect/config");
+const common_1 = require("@nestjs/common");
+const mongo_providers_1 = require("./mongo.providers");
+let MongoModule = class MongoModule {
+};
+exports.MongoModule = MongoModule;
+exports.MongoModule = MongoModule = tslib_1.__decorate([
+    (0, common_1.Global)(),
+    (0, common_1.Module)({
+        imports: [config_1.ConfigModule],
+        providers: [...mongo_providers_1.MongoProviders],
+        exports: [...mongo_providers_1.MongoProviders],
+    })
+], MongoModule);

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

@@ -0,0 +1,9 @@
+import { ConnectOptions } from 'mongoose';
+import { Provider } from '@nestjs/common';
+import { ConfigService } from '@edirect/config';
+export declare function getConnection(configService: ConfigService): Promise<{
+    uri: string;
+    options: ConnectOptions;
+}>;
+export declare const MongoProviders: Provider[];
+//# sourceMappingURL=mongo.providers.d.ts.map

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

@@ -0,0 +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,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

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MongoProviders = void 0;
+exports.getConnection = getConnection;
+const mongoose_1 = require("mongoose");
+const config_1 = require("@edirect/config");
+const aws_1 = require("./aws");
+const isNotProductionOrLive = (nodeEnv) => nodeEnv !== 'production' && nodeEnv !== 'live';
+const mongoUrl = (configService) => configService.get('MONGO_URL') ?? configService.get('MONGODB_URI');
+async function getConnection(configService) {
+    const connectionString = mongoUrl(configService);
+    if (!connectionString)
+        throw new config_1.ConfigMissingError('MONGO_URL');
+    const options = {};
+    // Always use dynamic AWS credential provider for MongoDB-AWS mechanism
+    if ((connectionString ?? '').includes('MONGODB-AWS')) {
+        options.authMechanismProperties = {
+            // This will provide rotating, always-fresh AWS credentials via IRSA
+            AWS_CREDENTIAL_PROVIDER: (0, aws_1.getMongoAwsCredentialProvider)(),
+        };
+    }
+    // Pool sizing for dev/test only
+    if (isNotProductionOrLive(configService.get('NODE_ENV'))) {
+        options.minPoolSize = 0;
+        options.maxPoolSize = 10;
+    }
+    return { uri: connectionString, options };
+}
+exports.MongoProviders = [
+    {
+        provide: 'MONGO_CONNECTION',
+        useFactory: async (configService) => {
+            const { uri, options } = await getConnection(configService);
+            try {
+                return await (0, mongoose_1.connect)(uri, options);
+            }
+            catch (err) {
+                console.error('[mongo] Failed to connect to MongoDB:', err);
+                throw err;
+            }
+        },
+        inject: [config_1.ConfigService],
+    },
+];

package/dist/tsconfig.lib.tsbuildinfo

@@ -0,0 +1 @@
+{"version":"5.9.3"}

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@edirect/mongo",
-  "version": "11.0.62",
+  "version": "11.0.64",
+  "packageScope": "@edirect",
   "main": "./dist/src/index.js",
   "types": "./dist/src/index.d.ts",
   "exports": {
@@ -17,11 +18,27 @@
   ],
   "dependencies": {
     "@aws-sdk/credential-providers": "^3.1112.0",
-    "@edirect/config": "^11.0.62",
     "@nestjs/common": "^11.2.1",
     "mongodb": "^7.5.0",
     "mongoose": "^9.9.3",
-    "tslib": "^2.8.1"
+    "tslib": "^2.8.1",
+    "@edirect/config": "11.0.64"
   },
-  "type": "commonjs"
-}
+  "nx": {
+    "name": "@edirect/mongo",
+    "targets": {
+      "build": {
+        "executor": "@nx/js:tsc",
+        "options": {
+          "main": "{workspaceRoot}/packages/edirect-mongo/src/index.ts",
+          "tsConfig": "{workspaceRoot}/packages/edirect-mongo/tsconfig.lib.json",
+          "outputPath": "{workspaceRoot}/packages/edirect-mongo/dist",
+          "assets": [
+            "{workspaceRoot}/packages/edirect-mongo/package.json",
+            "{workspaceRoot}/packages/edirect-mongo/README.md"
+          ]
+        }
+      }
+    }
+  }
+}