{"_id":"@abstraks-dev/mongodb-connection","_rev":"6-e94af1b080dd8404f4685974abeb611f","name":"@abstraks-dev/mongodb-connection","dist-tags":{"latest":"1.1.6"},"versions":{"1.0.0":{"name":"@abstraks-dev/mongodb-connection","version":"1.0.0","keywords":["mongodb","mongoose","connection","lambda","aws","caching"],"author":{"name":"Abstraks"},"license":"MIT","_id":"@abstraks-dev/mongodb-connection@1.0.0","maintainers":[{"name":"abstraks-dev","email":"contactabstraks@gmail.com"}],"homepage":"https://github.com/Abstraks-co/shared-modules#readme","bugs":{"url":"https://github.com/Abstraks-co/shared-modules/issues"},"dist":{"shasum":"01d4f030c9f1c17f67b2c1c7c232cd9fde2bc4eb","tarball":"https://registry.npmjs.org/@abstraks-dev/mongodb-connection/-/mongodb-connection-1.0.0.tgz","fileCount":5,"integrity":"sha512-UXzk7YHNAkHGSRtWFy7eqV+PRuXN4QyG0fJKPjQvdUAERacD7qSDnb2/yim43ob/2rPOJHmyLYc3H8k84Foi8A==","signatures":[{"sig":"MEUCIQDJiygjwQQYD+x1Mj1EsCRF4bi0RUQQMsuAvdyMVOE56wIgGPDGtYdt8t8RquMsDsgIOuyYiKbVfwoYKhpinfgsR9M=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":22077},"main":"src/index.js","type":"module","gitHead":"8aa41df62a281863efc707a08e35120b759f358e","scripts":{"test":"NODE_OPTIONS=--experimental-vm-modules jest"},"_npmUser":{"name":"abstraks-dev","email":"contactabstraks@gmail.com"},"repository":{"url":"git+https://github.com/Abstraks-co/shared-modules.git","type":"git","directory":"packages/mongodb-connection"},"_npmVersion":"10.8.2","description":"MongoDB connection manager with caching and middleware for Lambda functions","directories":{},"_nodeVersion":"20.19.5","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^29.7.0","mongoose":"^8.13.0","@jest/globals":"^29.7.0"},"peerDependencies":{"mongoose":"^8.13.0"},"_npmOperationalInternal":{"tmp":"tmp/mongodb-connection_1.0.0_1763506081231_0.3367118530767419","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@abstraks-dev/mongodb-connection","version":"1.0.1","keywords":["mongodb","mongoose","connection","lambda","aws","caching"],"author":{"name":"Abstraks"},"license":"MIT","_id":"@abstraks-dev/mongodb-connection@1.0.1","maintainers":[{"name":"abstraks-dev","email":"contactabstraks@gmail.com"}],"homepage":"https://github.com/Abstraks-co/shared-modules#readme","bugs":{"url":"https://github.com/Abstraks-co/shared-modules/issues"},"dist":{"shasum":"359bc8e29eb3474fc7e13a1758331034f4df4026","tarball":"https://registry.npmjs.org/@abstraks-dev/mongodb-connection/-/mongodb-connection-1.0.1.tgz","fileCount":5,"integrity":"sha512-4MhLN2IUUDmW1QmeagXls0KqQW/OLevTlXamn7d05Lfo2jcOX8Wm+rXDf7+XcNIkIe/lJbDvJbb1OELGQjF/6w==","signatures":[{"sig":"MEUCICvQSXr4Xkyys00Az/0zXv2dXHUV8Hx2Ljd5+qVBdNqrAiEAsL/uhvm77rKVYCBdNK5wZ/lOHGeJueethk0DABsj47s=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":22077},"main":"src/index.js","type":"module","gitHead":"2b247a175ceba75cf8a499d613edc07eaebcb147","scripts":{"test":"NODE_OPTIONS=--experimental-vm-modules jest"},"_npmUser":{"name":"abstraks-dev","email":"contactabstraks@gmail.com"},"repository":{"url":"git+https://github.com/Abstraks-co/shared-modules.git","type":"git","directory":"packages/mongodb-connection"},"_npmVersion":"10.8.2","description":"MongoDB connection manager with caching and middleware for Lambda functions","directories":{},"_nodeVersion":"20.19.5","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^29.7.0","mongoose":"^8.13.0","@jest/globals":"^29.7.0"},"peerDependencies":{"mongoose":"^8.13.0"},"_npmOperationalInternal":{"tmp":"tmp/mongodb-connection_1.0.1_1763657700064_0.4742903968950385","host":"s3://npm-registry-packages-npm-production"}},"1.1.3":{"name":"@abstraks-dev/mongodb-connection","version":"1.1.3","keywords":["mongodb","mongoose","connection","lambda","aws","caching"],"author":{"name":"Abstraks"},"license":"MIT","_id":"@abstraks-dev/mongodb-connection@1.1.3","maintainers":[{"name":"abstraks-dev","email":"contactabstraks@gmail.com"}],"homepage":"https://github.com/Abstraks-co/shared-modules#readme","bugs":{"url":"https://github.com/Abstraks-co/shared-modules/issues"},"dist":{"shasum":"1bb0fd6d784d917346be3c6877b0796f435b428e","tarball":"https://registry.npmjs.org/@abstraks-dev/mongodb-connection/-/mongodb-connection-1.1.3.tgz","fileCount":5,"integrity":"sha512-BxaXOKURScz+l+q9GiaG7tdu2T2mJmYwRNcg9CbClam+OCWomS399jD18z1hksHTFYbxaVLIij07VMSTad09cQ==","signatures":[{"sig":"MEUCIQD2+QWertYz4Q3RunLU26Ssup+bJRkviwKPdfPadURZ2gIgZllXbNukWvdmu+IYav6stx5X+WelsJCWQ9NT/YMaZbg=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":27296},"main":"src/index.js","type":"module","gitHead":"99f1b295f36fa0e869467f51fc81767d2ea47206","scripts":{"test":"NODE_OPTIONS=--experimental-vm-modules jest"},"_npmUser":{"name":"abstraks-dev","email":"contactabstraks@gmail.com"},"repository":{"url":"git+https://github.com/Abstraks-co/shared-modules.git","type":"git","directory":"packages/mongodb-connection"},"_npmVersion":"10.8.2","description":"MongoDB connection manager with caching and middleware for Lambda functions","directories":{},"_nodeVersion":"20.20.2","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^29.7.0","mongoose":"^8.13.0","@jest/globals":"^29.7.0"},"peerDependencies":{"mongoose":"^8.13.0"},"_npmOperationalInternal":{"tmp":"tmp/mongodb-connection_1.1.3_1776279230460_0.15953946490798776","host":"s3://npm-registry-packages-npm-production"}},"1.1.4":{"name":"@abstraks-dev/mongodb-connection","version":"1.1.4","keywords":["mongodb","mongoose","connection","lambda","aws","caching"],"author":{"name":"Abstraks"},"license":"MIT","_id":"@abstraks-dev/mongodb-connection@1.1.4","maintainers":[{"name":"abstraks-dev","email":"contactabstraks@gmail.com"}],"homepage":"https://github.com/Abstraks-co/shared-modules#readme","bugs":{"url":"https://github.com/Abstraks-co/shared-modules/issues"},"dist":{"shasum":"968e1a9ffd405ef4d40ed390e63f12d8da3fe742","tarball":"https://registry.npmjs.org/@abstraks-dev/mongodb-connection/-/mongodb-connection-1.1.4.tgz","fileCount":5,"integrity":"sha512-PK9nRkT6XphZhnsJBmojBGxfsjT8c7VNUJVlaoDcwggYbOlHMwCra0vtUJhN5R/IYrNNzpsMpYnldtcB3F9bFw==","signatures":[{"sig":"MEUCIQCq1aZ5o2S9Xa7iSoZ42fwaMStngKNbHBYf0ZrHPVKegQIgRJi9Ha8ND/DBkEA9UiTuV2M6X4Dh09p/zSHkSH7S0kE=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":28577},"main":"src/index.js","type":"module","gitHead":"0dc384b69937fdebece0e3b6ee58e8bd62dab771","scripts":{"test":"NODE_OPTIONS=--experimental-vm-modules jest"},"_npmUser":{"name":"abstraks-dev","email":"contactabstraks@gmail.com"},"repository":{"url":"git+https://github.com/Abstraks-co/shared-modules.git","type":"git","directory":"packages/mongodb-connection"},"_npmVersion":"10.8.2","description":"MongoDB connection manager with caching and middleware for Lambda functions","directories":{},"_nodeVersion":"20.20.2","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^29.7.0","mongoose":"^8.13.0","@jest/globals":"^29.7.0"},"peerDependencies":{"mongoose":"^8.13.0"},"_npmOperationalInternal":{"tmp":"tmp/mongodb-connection_1.1.4_1776888832292_0.8965416882395074","host":"s3://npm-registry-packages-npm-production"}},"1.1.5":{"name":"@abstraks-dev/mongodb-connection","version":"1.1.5","keywords":["mongodb","mongoose","connection","lambda","aws","caching"],"author":{"name":"Abstraks"},"license":"MIT","_id":"@abstraks-dev/mongodb-connection@1.1.5","maintainers":[{"name":"abstraks-dev","email":"contactabstraks@gmail.com"}],"homepage":"https://github.com/Abstraks-co/shared-modules#readme","bugs":{"url":"https://github.com/Abstraks-co/shared-modules/issues"},"dist":{"shasum":"6d441c92da5ac1a2ed266b86edc3ff16d089ad7f","tarball":"https://registry.npmjs.org/@abstraks-dev/mongodb-connection/-/mongodb-connection-1.1.5.tgz","fileCount":5,"integrity":"sha512-qvslxrlMPavPBe8pO+JtOUx3DoOTtffhpRqlKM2yRGzcCVtbI10Ha1dgqImRT05LJEni4vJ0xn/yYM26qwVL8w==","signatures":[{"sig":"MEYCIQDCsOjF+udGICqxOmu4VgE1C/srKEpV6zieY1076ZuYhwIhAI8HmhMT6ScTlyckrAvCEjuE/84MYTY+Bh8ixGNCdn9B","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":28577},"main":"src/index.js","type":"module","gitHead":"a90f9fab64c14f8c4991ada4623dce95e4dcf794","scripts":{"test":"NODE_OPTIONS=--experimental-vm-modules jest"},"_npmUser":{"name":"abstraks-dev","email":"contactabstraks@gmail.com"},"repository":{"url":"git+https://github.com/Abstraks-co/shared-modules.git","type":"git","directory":"packages/mongodb-connection"},"_npmVersion":"10.8.2","description":"MongoDB connection manager with caching and middleware for Lambda functions","directories":{},"_nodeVersion":"20.20.2","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^29.7.0","mongoose":"^8.13.0","@jest/globals":"^29.7.0"},"peerDependencies":{"mongoose":"^8.13.0"},"_npmOperationalInternal":{"tmp":"tmp/mongodb-connection_1.1.5_1780618183427_0.055942755209274386","host":"s3://npm-registry-packages-npm-production"}},"1.1.6":{"name":"@abstraks-dev/mongodb-connection","version":"1.1.6","description":"MongoDB connection manager with caching and middleware for Lambda functions","main":"src/index.js","type":"module","scripts":{"test":"NODE_OPTIONS=--experimental-vm-modules jest"},"keywords":["mongodb","mongoose","connection","lambda","aws","caching"],"author":{"name":"Abstraks"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/Abstraks-co/shared-modules.git","directory":"packages/mongodb-connection"},"peerDependencies":{"mongoose":"^8.13.0"},"devDependencies":{"@jest/globals":"^29.7.0","jest":"^29.7.0","mongoose":"^8.13.0"},"publishConfig":{"access":"public"},"_id":"@abstraks-dev/mongodb-connection@1.1.6","gitHead":"5fa4ad643d0c4799af56cf97bbb6fd9c936254e0","bugs":{"url":"https://github.com/Abstraks-co/shared-modules/issues"},"homepage":"https://github.com/Abstraks-co/shared-modules#readme","_nodeVersion":"20.20.2","_npmVersion":"10.8.2","dist":{"integrity":"sha512-vWeyIMqGpC6RN+PXwIvpiTjVMTK/rbSns9aFDdBOoelSyMUSF00hkVIpqMFn2C3lIS/jPxCFdi0PE668TbC/NA==","shasum":"8b7d5a2ccd2d3c0f0a41f9b1171fa727658283a4","tarball":"https://registry.npmjs.org/@abstraks-dev/mongodb-connection/-/mongodb-connection-1.1.6.tgz","fileCount":5,"unpackedSize":28577,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCICpi3aQ1HfMOHVoPqvSP3mz03o/Vtohh+eEGxa9GVQJiAiAYqzWmK4qnBq6JIpIIh9n83Y7KbtSNjbZp1eNbp6cTpg=="}]},"_npmUser":{"name":"abstraks-dev","email":"contactabstraks@gmail.com"},"directories":{},"maintainers":[{"name":"abstraks-dev","email":"contactabstraks@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mongodb-connection_1.1.6_1780621458745_0.20804287755656192"},"_hasShrinkwrap":false}},"time":{"created":"2025-11-18T22:48:01.114Z","modified":"2026-06-05T01:04:18.987Z","1.0.0":"2025-11-18T22:48:01.410Z","1.0.1":"2025-11-20T16:55:00.275Z","1.1.3":"2026-04-15T18:53:50.633Z","1.1.4":"2026-04-22T20:13:52.484Z","1.1.5":"2026-06-05T00:09:43.551Z","1.1.6":"2026-06-05T01:04:18.889Z"},"bugs":{"url":"https://github.com/Abstraks-co/shared-modules/issues"},"author":{"name":"Abstraks"},"license":"MIT","homepage":"https://github.com/Abstraks-co/shared-modules#readme","keywords":["mongodb","mongoose","connection","lambda","aws","caching"],"repository":{"type":"git","url":"git+https://github.com/Abstraks-co/shared-modules.git","directory":"packages/mongodb-connection"},"description":"MongoDB connection manager with caching and middleware for Lambda functions","maintainers":[{"name":"abstraks-dev","email":"contactabstraks@gmail.com"}],"readme":"# @abstraks-dev/mongodb-connection\n\nMongoDB connection management for AWS Lambda functions with automatic caching, Secrets Manager integration, and middleware support.\n\n## Features\n\n- 🔄 **Automatic Connection Caching** - Reuses connections across Lambda invocations\n- 🔐 **AWS Secrets Manager Integration** - Securely fetch MongoDB URI from Secrets Manager\n- 🛡️ **Environment-aware** - Supports dev/prod environments\n- 🎯 **Lambda Middleware** - Easy-to-use middleware pattern for Lambda handlers\n- 📊 **Connection Statistics** - Monitor connection health and status\n- ⚡ **Performance Optimized** - Minimizes cold starts with efficient caching\n\n## Installation\n\n```bash\nnpm install @abstraks-dev/mongodb-connection mongoose\n```\n\n**Required Peer Dependencies:**\n\n- `mongoose` - MongoDB ODM\n\n## Quick Start\n\n### Basic Usage\n\n```javascript\nimport { createMongoDBConnection } from '@abstraks-dev/mongodb-connection';\nimport { getSecret } from './secrets.js'; // Your Secrets Manager helper\n\n// Create connection instance\nconst { connection, connectDB, withDBConnection } = createMongoDBConnection(\n\t'auth', // service name\n\tgetSecret, // secret retrieval function\n);\n\n// Connect manually\nawait connectDB();\n\n// Use in Lambda handler with middleware\nconst myHandler = async (event, context, callback) => {\n\t// MongoDB is already connected by middleware\n\tconst users = await User.find();\n\treturn { statusCode: 200, body: JSON.stringify(users) };\n};\n\nexport const handler = withDBConnection(myHandler);\n```\n\n### Direct URI Usage\n\n```javascript\nimport { createSimpleConnection } from '@abstraks-dev/mongodb-connection';\n\nconst { connection, connectDB } = createSimpleConnection(\n\t'auth', // service name (used in logs)\n\t'mongodb://localhost:27017/mydb',\n);\n\nawait connectDB();\n```\n\n## API Reference\n\n### `createMongoDBConnection(serviceName, getSecret, options)`\n\nFactory function that creates a MongoDB connection with helpers.\n\n**Parameters:**\n\n- `serviceName` (string, required) - Service name for Secrets Manager lookup\n- `getSecret` (function, required) - Async function to retrieve secrets: `(secretName, key) => Promise<string>`\n- `options` (object, optional):\n  - `mongoURI` - Direct MongoDB URI (bypasses Secrets Manager)\n  - `environment` - Environment name (default: `process.env.ENVIRONMENT || 'dev'`)\n\n**Returns:**\n\n```javascript\n{\n  connection: MongoDBConnection,\n  connectDB: () => Promise<MongooseClient>,\n  withDBConnection: (handler) => WrappedHandler\n}\n```\n\n**Example:**\n\n```javascript\n// auth/service/helpers/connectDB.js\nimport { createMongoDBConnection } from '@abstraks-dev/mongodb-connection';\nimport { getSecret } from './secrets.js';\n\nexport const { connection, connectDB, withDBConnection } =\n\tcreateMongoDBConnection('auth', getSecret);\n```\n\n### `createSimpleConnection(serviceName, mongoURI)`\n\nFactory function for simple connections with direct URI.\n\n**Parameters:**\n\n- `serviceName` (string, required) - Service identifier used in connection logs\n- `mongoURI` (string, required) - MongoDB connection string (`mongodb://...` or `mongodb+srv://...`)\n\n**Returns:**\n\n```javascript\n{\n  connection: MongoDBConnection,\n  connectDB: () => Promise<MongooseClient>\n}\n```\n\n**Example:**\n\n```javascript\nimport { createSimpleConnection } from '@abstraks-dev/mongodb-connection';\n\nconst { connectDB } = createSimpleConnection(\n\t'auth',\n\tprocess.env.MONGO_URI || 'mongodb://localhost:27017/dev',\n);\n\nawait connectDB();\n```\n\n### `MongoDBConnection` Class\n\nCore connection manager class.\n\n#### Constructor\n\n```javascript\nnew MongoDBConnection(options);\n```\n\n**Options:**\n\n- `serviceName` (string, required) - Service name\n- `getSecret` (function, optional) - Secret retrieval function\n- `mongoURI` (string, optional) - Direct MongoDB URI\n- `environment` (string, optional) - Environment name (default: 'dev')\n\n#### Methods\n\n##### `connect(): Promise<MongooseClient>`\n\nConnects to MongoDB. Automatically caches connection across Lambda invocations.\n\n```javascript\nconst client = await connection.connect();\n```\n\n**Connection Priority:**\n\n1. Direct `mongoURI` option\n2. `process.env.MONGO_URI`\n3. Secrets Manager lookup using `serviceName` and `environment`\n\n**Throws:**\n\n- Error if no MongoDB URI found\n- Error if connection fails\n\n##### `disconnect(): Promise<void>`\n\nDisconnects from MongoDB and clears cache.\n\n```javascript\nawait connection.disconnect();\n```\n\n##### `isConnected(): boolean`\n\nChecks if connection is active.\n\n```javascript\nif (connection.isConnected()) {\n\tconsole.log('Connected!');\n}\n```\n\n##### `getConnection(): MongooseClient | null`\n\nReturns cached Mongoose client or null.\n\n```javascript\nconst client = connection.getConnection();\n```\n\n##### `getConnectionState(): number`\n\nReturns Mongoose connection state:\n\n- `0` = disconnected\n- `1` = connected\n- `2` = connecting\n- `3` = disconnecting\n\n```javascript\nconst state = connection.getConnectionState();\n```\n\n##### `getStats(): object`\n\nReturns connection statistics.\n\n```javascript\nconst stats = connection.getStats();\n// {\n//   serviceName: 'auth',\n//   environment: 'dev',\n//   isConnected: true,\n//   readyState: 1,\n//   hasCache: true\n// }\n```\n\n## Usage Patterns\n\n### Pattern 1: Lambda Middleware (Recommended)\n\nThe easiest way to use with Lambda functions:\n\n```javascript\n// helpers/connectDB.js\nimport { createMongoDBConnection } from '@abstraks-dev/mongodb-connection';\nimport { getSecret } from './secrets.js';\n\nexport const { withDBConnection } = createMongoDBConnection('auth', getSecret);\n\n// lambdas/getUser.js\nimport { withDBConnection } from '../helpers/connectDB.js';\nimport User from '../models/User.js';\n\nconst getUserHandler = async (event, context, callback) => {\n\t// MongoDB connected automatically\n\tconst user = await User.findById(event.pathParameters.id);\n\n\tcallback(null, {\n\t\tstatusCode: 200,\n\t\tbody: JSON.stringify(user),\n\t});\n};\n\nexport const handler = withDBConnection(getUserHandler);\n```\n\n**Benefits:**\n\n- Automatic connection before handler runs\n- Proper error handling with Lambda responses\n- Works with both callback and return patterns\n\n### Pattern 2: Manual Connection\n\nFor more control over connection timing:\n\n```javascript\nimport { createMongoDBConnection } from '@abstraks-dev/mongodb-connection';\nimport { getSecret } from './secrets.js';\n\nconst { connectDB } = createMongoDBConnection('social', getSecret);\n\nexport const handler = async (event, context) => {\n\ttry {\n\t\t// Connect when needed\n\t\tawait connectDB();\n\n\t\t// Your logic here\n\t\tconst posts = await Post.find();\n\n\t\treturn {\n\t\t\tstatusCode: 200,\n\t\t\tbody: JSON.stringify(posts),\n\t\t};\n\t} catch (error) {\n\t\treturn {\n\t\t\tstatusCode: 500,\n\t\t\tbody: JSON.stringify({ error: error.message }),\n\t\t};\n\t}\n};\n```\n\n### Pattern 3: Shared Instance\n\nShare connection across multiple files:\n\n```javascript\n// helpers/db.js\nimport { createMongoDBConnection } from '@abstraks-dev/mongodb-connection';\nimport { getSecret } from './secrets.js';\n\nexport const { connection, connectDB, withDBConnection } =\n\tcreateMongoDBConnection('media', getSecret);\n\n// controllers/media.controllers.js\nimport { connection } from '../helpers/db.js';\n\nexport async function getMediaStats() {\n\t// Check connection state\n\tif (!connection.isConnected()) {\n\t\tawait connection.connect();\n\t}\n\n\treturn await Media.countDocuments();\n}\n\n// lambdas/getMedia.js\nimport { withDBConnection } from '../helpers/db.js';\n\nconst handler = async (event) => {\n\t// Connection managed by middleware\n\tconst media = await Media.find();\n\treturn { statusCode: 200, body: JSON.stringify(media) };\n};\n\nexport default withDBConnection(handler);\n```\n\n## Environment Configuration\n\n### Development\n\n```javascript\n// Use local MongoDB or environment variable\nprocess.env.MONGO_URI = 'mongodb://localhost:27017/auth-dev';\n\nconst { connectDB } = createMongoDBConnection('auth', getSecret, {\n\tenvironment: 'dev',\n});\n```\n\n### Production\n\n```javascript\n// Use AWS Secrets Manager\n// Creates connection that will fetch from:\n// Secret: \"auth-prod\"\n// Key: \"MONGO_URI\"\n\nconst { connectDB } = createMongoDBConnection('auth', getSecret, {\n\tenvironment: 'prod',\n});\n```\n\n### Direct URI\n\n```javascript\n// Bypass Secrets Manager entirely\nconst { connectDB } = createMongoDBConnection('auth', getSecret, {\n\tmongoURI: 'mongodb://your-cluster.mongodb.net/production',\n});\n```\n\n## URI Validation\n\n`connect()` validates and sanitizes the MongoDB URI before connecting. This catches common configuration mistakes early with clear error messages.\n\n**Sanitization (automatic):**\n\n- Trims leading and trailing whitespace\n- Strips wrapping single or double quotes (common copy-paste artifact from `.env` files and Secrets Manager)\n\n**Validation:**\n\n- URI must be a non-empty string\n- URI must start with `mongodb://` or `mongodb+srv://`\n- Invalid URIs throw immediately with an error that identifies the source (env var, Secrets Manager, or direct option) without leaking credentials\n\n```javascript\n// These are all handled automatically:\nprocess.env.MONGO_URI = '  mongodb+srv://cluster.example.net/db  '; // whitespace trimmed\nprocess.env.MONGO_URI = '\"mongodb+srv://cluster.example.net/db\"'; // quotes stripped\n\n// These throw with a clear error:\nprocess.env.MONGO_URI = 'cluster.example.net/db'; // missing protocol\nprocess.env.MONGO_URI = ''; // empty string\n```\n\n## Diagnostic Logging\n\nConnection lifecycle events are logged with a consistent `[mongodb-connection] <service>:` prefix, making it easy to filter in CloudWatch or other log aggregators.\n\n**What is logged:**\n\n- URI source — whether the URI came from a direct option, `process.env.MONGO_URI`, or Secrets Manager\n- Hostname only — extracted from the URI for debugging; **credentials are never logged**\n- Connection state — `readyState`, cache hits, successful connections, and failures\n\n**Example log output:**\n\n```\n[mongodb-connection] auth: connect() called, env=prod, readyState=0\n[mongodb-connection] auth: connecting via process.env.MONGO_URI, host=cluster0.abc123.mongodb.net\n[mongodb-connection] auth: connected successfully (prod)\n```\n\n## Error Handling\n\nThe library throws descriptive errors for common issues:\n\n```javascript\ntry {\n\tawait connectDB();\n} catch (error) {\n\tif (error.message.includes('MONGO_URI not found')) {\n\t\tconsole.error('MongoDB URI not configured');\n\t} else if (error.message.includes('missing mongodb://')) {\n\t\tconsole.error(\n\t\t\t'URI has wrong format — must start with mongodb:// or mongodb+srv://',\n\t\t);\n\t} else if (error.message.includes('Error connecting')) {\n\t\tconsole.error('Connection failed:', error);\n\t}\n}\n```\n\n## Migration from Service-Specific Code\n\n### Before (Duplicated in each service)\n\n```javascript\n// auth/service/helpers/connectDB.js\nimport mongoose from 'mongoose';\nimport { getSecret } from './secrets.js';\n\nmongoose.set('strictQuery', false);\nlet cachedClient = null;\n\nexport const connectDB = async () => {\n\tif (cachedClient && mongoose.connection.readyState === 1) {\n\t\treturn cachedClient;\n\t}\n\n\tconst environment = process.env.ENVIRONMENT || 'dev';\n\tconst mongoURI =\n\t\tprocess.env.MONGO_URI ||\n\t\t(await getSecret(`auth-${environment}`, 'MONGO_URI'));\n\n\tif (!mongoURI) {\n\t\tthrow new Error(`MONGO_URI not found`);\n\t}\n\n\tconst client = await mongoose.connect(mongoURI);\n\tcachedClient = client;\n\treturn client;\n};\n```\n\n### After (Using shared module)\n\n```javascript\n// auth/service/helpers/connectDB.js\nimport { createMongoDBConnection } from '@abstraks-dev/mongodb-connection';\nimport { getSecret } from './secrets.js';\n\nexport const { connection, connectDB, withDBConnection } =\n\tcreateMongoDBConnection('auth', getSecret);\n```\n\n**Savings:** ~30 lines of code → 3 lines\n\n## Best Practices\n\n### 1. Reuse Connection Instances\n\n```javascript\n// ✅ Good - Create once, reuse everywhere\n// helpers/db.js\nexport const { connectDB, withDBConnection } = createMongoDBConnection(...);\n\n// ❌ Bad - Creates new instance each time\nexport function getConnection() {\n  return createMongoDBConnection(...);\n}\n```\n\n### 2. Use Middleware for Lambda Handlers\n\n```javascript\n// ✅ Good - Automatic connection management\nexport const handler = withDBConnection(async (event) => {\n\t// Connection guaranteed\n});\n\n// ❌ Okay but more verbose\nexport const handler = async (event) => {\n\tawait connectDB();\n\t// Connection manual\n};\n```\n\n### 3. Check Connection State for Background Jobs\n\n```javascript\n// ✅ Good - Verify before long-running operations\nasync function processQueue() {\n\tif (!connection.isConnected()) {\n\t\tawait connection.connect();\n\t}\n\n\t// Process items\n}\n```\n\n### 4. Handle Secrets Manager Errors\n\n```javascript\n// ✅ Good - Graceful error handling\ntry {\n\tawait connectDB();\n} catch (error) {\n\tconsole.error('Failed to connect:', error);\n\t// Fallback or alert\n}\n```\n\n## Testing\n\n### Mocking in Tests\n\n```javascript\nimport { jest } from '@jest/globals';\n\n// Mock mongoose\nconst mockMongoose = {\n\tset: jest.fn(),\n\tconnect: jest.fn(),\n\tdisconnect: jest.fn(),\n\tconnection: { readyState: 0 },\n};\n\njest.unstable_mockModule('mongoose', () => ({ default: mockMongoose }));\n\n// Mock secret retrieval\nconst mockGetSecret = jest\n\t.fn()\n\t.mockResolvedValue('mongodb://localhost:27017/test');\n\n// Import and test\nconst { connectDB } = await import('@abstraks-dev/mongodb-connection');\nconst connection = createMongoDBConnection('test', mockGetSecret);\n```\n\n## Troubleshooting\n\n### \"MONGO_URI not found\" Error\n\n**Cause:** No MongoDB URI found in any source\n\n**Solutions:**\n\n1. Set `process.env.MONGO_URI`\n2. Ensure Secrets Manager has correct secret name format: `{serviceName}-{environment}`\n3. Pass direct URI via options: `{ mongoURI: '...' }`\n\n### Connection Cached from Previous Lambda\n\n**Cause:** Connection reuse across invocations (this is intentional for performance)\n\n**Solution:** This is expected behavior. Connection is automatically reused. If you need to force reconnect:\n\n```javascript\nawait connection.disconnect();\nawait connection.connect();\n```\n\n### Mongoose StrictQuery Warnings\n\n**Cause:** Mongoose version differences\n\n**Solution:** The library automatically sets `mongoose.set('strictQuery', false)`. No action needed.\n\n## Performance Considerations\n\n- **Cold Start:** First connection takes ~500ms\n- **Warm Start:** Cached connection is instant (<1ms)\n- **Memory:** ~10MB per connection (Mongoose overhead)\n- **Invocations:** Connection persists across Lambda invocations in same container\n\n## License\n\nMIT\n\n## Related Packages\n\n- [`@abstraks/lambda-responses`](../lambda-responses) - Standardized Lambda response helpers\n- [`@abstraks/api-key-auth`](../api-key-auth) - API key authentication with SSM\n- [`@abstraks/jwt-auth`](https://www.npmjs.com/package/@abstraks/jwt-auth) - JWT authentication utilities\n\n## Support\n\nFor issues and questions:\n\n- [GitHub Issues](https://github.com/Abstraks-co/shared-modules/issues)\n- [Documentation](https://github.com/Abstraks-co/shared-modules)\n","readmeFilename":"README.md"}