@mimik/mongooser 3.0.2 → 4.0.0

package/.claude/settings.local.json

@@ -0,0 +1,9 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npx eslint index.js --no-error-on-unmatched-pattern)",
+      "Bash(npx eslint index.js)",
+      "Bash(node -e \"const p = JSON.parse\\(require\\(''fs''\\).readFileSync\\(''node_modules/globals/package.json'',''utf8''\\)\\); console.log\\(p.version\\)\")"
+    ]
+  }
+}

package/.husky/pre-commit

@@ -1,4 +1,2 @@
 #!/bin/sh
-. "$(dirname "$0")/_/husky.sh"
-
 npm run commit-ready

package/.husky/pre-push

@@ -1,4 +1,2 @@
 #!/bin/sh
-. "$(dirname "$0")/_/husky.sh"
-
 npm run test

package/README.md

@@ -7,72 +7,91 @@ import mongodb from '@mimik/mongooser';
 ```
 
 * [mongooser](#module_mongooser)
-    * _async_
-        * [~validate()](#module_mongooser..validate) ⇒ <code>Promise</code>
-    * _sync_
-        * [~getKMSProviders()](#module_mongooser..getKMSProviders) ⇒ <code>object</code>
-        * [~initializeSync(autoEncryption)](#module_mongooser..initializeSync) ⇒ <code>object</code>
-        * [~replicat()](#module_mongooser..replicat) ⇒ <code>boolean</code>
+    * [module.exports(config)](#exp_module_mongooser--module.exports) ⇒ <code>object</code> ⏏
+        * _async_
+            * [~validate()](#module_mongooser--module.exports..validate) ⇒ <code>Promise</code>
+        * _sync_
+            * [~getKMSProviders()](#module_mongooser--module.exports..getKMSProviders) ⇒ <code>object</code>
+            * [~initializeSync()](#module_mongooser--module.exports..initializeSync) ⇒ <code>object</code>
+            * [~replicaSet()](#module_mongooser--module.exports..replicaSet) ⇒ <code>boolean</code>
 
-<a name="module_mongooser..validate"></a>
+<a name="exp_module_mongooser--module.exports"></a>
 
-### mongooser~validate() ⇒ <code>Promise</code>
+### module.exports(config) ⇒ <code>object</code> ⏏
+Creates a MongoDB connection manager for mimik microservices.
+
+**Kind**: Exported function  
+**Returns**: <code>object</code> - Object with methods: initializeSync, validate, replicaSet, getKMSProviders.  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| config | <code>object</code> | Service configuration object. |
+| config.mongoSettings | <code>object</code> | MongoDB connection settings. |
+| config.mongoSettings.url | <code>string</code> | MongoDB connection URL. |
+| config.mongoSettings.options | <code>object</code> | Mongoose connection options. Must include `heartbeatFrequencyMS`. |
+| [config.mongoSettings.password] | <code>string</code> | MongoDB password (masked in production logs). |
+| config.mongoSettings.reconnectOffset | <code>number</code> | Reconnect offset in seconds. |
+| config.mongoSettings.connectTimeout | <code>number</code> | Connection timeout in seconds. |
+| config.mongoSettings.validationCheck | <code>number</code> | Validation check delay in milliseconds. |
+| config.nodeEnvironment | <code>string</code> | Current node environment (e.g. 'production'). |
+| [config.encryption] | <code>object</code> | Encryption settings for client-side field level encryption. |
+| [config.encryption.set] | <code>string</code> | Set to 'on' to enable auto-encryption. |
+| [config.encryption.kmsProvider] | <code>string</code> | KMS provider type ('local' or 'aws'). |
+| [config.encryption.localMasterKey] | <code>string</code> | Base64-encoded local master key. |
+| [config.encryption.aws] | <code>object</code> | AWS KMS provider settings. |
+| [config.encryption.database] | <code>string</code> | Database name for key vault. |
+| [config.encryption.keyVaultTable] | <code>string</code> | Collection name for key vault. |
+
+<a name="module_mongooser--module.exports..validate"></a>
+
+#### module.exports~validate() ⇒ <code>Promise</code>
 Database connection validation.
 
-**Kind**: inner method of [<code>mongooser</code>](#module_mongooser)  
-**Returns**: <code>Promise</code> - .  
+**Kind**: inner method of [<code>module.exports</code>](#exp_module_mongooser--module.exports)  
+**Returns**: <code>Promise</code> - Resolves to null on success.  
 **Category**: async  
 **Throws**:
 
-- <code>Promise</code> Will throw an error if the database connection is not `connected`.
+- <code>Error</code> Will throw an error if the database connection is not `connected`.
 
 Will exit 1 if the connection request times out and the connection state is not `connected`.
 
 **Requires**: <code>module:@mimik/sumologic-winston-logger</code>  
-**Fulfil**:  Return `null`.  
-<a name="module_mongooser..getKMSProviders"></a>
+<a name="module_mongooser--module.exports..getKMSProviders"></a>
 
-### mongooser~getKMSProviders() ⇒ <code>object</code>
+#### module.exports~getKMSProviders() ⇒ <code>object</code>
 AutoEncryption KMSProvider.
 
-**Kind**: inner method of [<code>mongooser</code>](#module_mongooser)  
+**Kind**: inner method of [<code>module.exports</code>](#exp_module_mongooser--module.exports)  
 **Returns**: <code>object</code> - The KMSProviders object.
 
-Will return the kmsProvider settings for the service.  
+Will return the kmsProvider settings for the service.
+Requires `config.encryption` to be provided to the factory.  
 **Category**: sync  
-<a name="module_mongooser..initializeSync"></a>
+**Throws**:
+
+- <code>TypeError</code> If encryption config was not provided to the factory.
+
+<a name="module_mongooser--module.exports..initializeSync"></a>
 
-### mongooser~initializeSync(autoEncryption) ⇒ <code>object</code>
+#### module.exports~initializeSync() ⇒ <code>object</code>
 Database initialization.
 
-**Kind**: inner method of [<code>mongooser</code>](#module_mongooser)  
-**Returns**: <code>object</code> - The database object.
-
-The autoEncryption has the following strucuture:
-``` javascript
- {
-   "keyVaultClient" : <object>,
-   "keyVaultNamespace": <string>, // namespace for the keyvault collection
-   "kmsProviders": <object>, // KeyManager service settings
-   "schemaMap": <object>, // json object for defining encryption schema
-   "bypassAutoEncryption": <boolean>
- }
-```
-Check MongoDB documentation for more details. https://docs.mongodb.com/manual/reference/method/Mongo/#clientsidefieldlevelencryptionoptions
+**Kind**: inner method of [<code>module.exports</code>](#exp_module_mongooser--module.exports)  
+**Returns**: <code>object</code> - The mongoose database object. Connection is established asynchronously in the background.
+
+When encryption is enabled, configures auto-encryption by setting `keyVaultNamespace` and `kmsProviders`
+on the mongoose connection options.
+Check MongoDB documentation for the full autoEncryption specification: https://docs.mongodb.com/manual/reference/method/Mongo/#clientsidefieldlevelencryptionoptions
 
 Will exit 1 if the connection request generates an error or the connection state is `disconnected` or `disconnecting`.  
 **Category**: sync  
-**Requires**: <code>module:sumologic-winston-logger</code>  
-
-| Param | Type | Description |
-| --- | --- | --- |
-| autoEncryption | <code>object</code> | Encryption settings for mongo connection. |
-
-<a name="module_mongooser..replicat"></a>
+**Requires**: <code>module:@mimik/sumologic-winston-logger</code>  
+<a name="module_mongooser--module.exports..replicaSet"></a>
 
-### mongooser~replicat() ⇒ <code>boolean</code>
+#### module.exports~replicaSet() ⇒ <code>boolean</code>
 Indicates if the replica is set.
 
-**Kind**: inner method of [<code>mongooser</code>](#module_mongooser)  
+**Kind**: inner method of [<code>module.exports</code>](#exp_module_mongooser--module.exports)  
 **Returns**: <code>boolean</code> - `True` if replica is set, `False` if not.  
 **Category**: sync  

package/eslint.config.js

@@ -1,3 +1,4 @@
+import globals from 'globals';
 import importPlugin from 'eslint-plugin-import';
 import js from '@eslint/js';
 import processDoc from '@mimik/eslint-plugin-document-env';
@@ -10,6 +11,9 @@ const MAX_LINES_IN_FUNCTION = 150;
 const MAX_STATEMENTS_IN_FUNCTION = 45;
 const MIN_KEYS_IN_OBJECT = 10;
 const MAX_COMPLEXITY = 30;
+const ECMA_VERSION = 'latest';
+const MAX_DEPTH = 6;
+const ALLOWED_CONSTANTS = [0, 1, -1];
 
 export default [
   {
@@ -23,18 +27,18 @@ export default [
       processDoc,
     },
     languageOptions: {
-      ecmaVersion: 2022,
+      ecmaVersion: ECMA_VERSION,
       globals: {
-        console: 'readonly',
-        describe: 'readonly',
-        it: 'readonly',
-        require: 'readonly',
+        ...globals.mocha,
+        ...globals.nodeBuiltin,
       },
       sourceType: 'module',
     },
     rules: {
       '@stylistic/brace-style': ['warn', 'stroustrup', { allowSingleLine: true }],
       '@stylistic/line-comment-position': ['off'],
+      '@stylistic/max-len': ['warn', MAX_LENGTH_LINE, { ignoreComments: true, ignoreStrings: true, ignoreRegExpLiterals: true }],
+      '@stylistic/quotes': ['warn', 'single'],
       '@stylistic/semi': ['error', 'always'],
       'capitalized-comments': ['off'],
       'complexity': ['error', MAX_COMPLEXITY],
@@ -44,20 +48,23 @@ export default [
       'import/no-unresolved': ['error', { amd: true, caseSensitiveStrict: true, commonjs: true }],
       'init-declarations': ['off'],
       'linebreak-style': ['off'],
-      'max-len': ['warn', MAX_LENGTH_LINE, { ignoreComments: true }],
-      'max-lines': ['warn', { max: MAX_LINES_IN_FILES, skipComments: true }],
-      'max-lines-per-function': ['warn', { max: MAX_LINES_IN_FUNCTION, skipComments: true }],
+      'max-depth': ['error', MAX_DEPTH],
+      'max-len': ['off'],
+      'max-lines': ['warn', { max: MAX_LINES_IN_FILES, skipComments: true, skipBlankLines: true }],
+      'max-lines-per-function': ['warn', { max: MAX_LINES_IN_FUNCTION, skipComments: true, skipBlankLines: true }],
       'max-params': ['error', MAX_FUNCTION_PARAMETERS],
       'max-statements': ['warn', MAX_STATEMENTS_IN_FUNCTION],
-      'no-confusing-arrow': ['off'], // arrow isnt confusing
+      'no-confusing-arrow': ['off'],
       'no-inline-comments': ['off'],
+      'no-magic-numbers': ['error', { ignore: ALLOWED_CONSTANTS, enforceConst: true, detectObjects: true }],
       'no-process-env': ['error'],
       'no-ternary': ['off'],
       'no-undefined': ['off'],
       'one-var': ['error', 'never'],
       'processDoc/validate-document-env': ['error'],
-      'quotes': ['warn', 'single'],
-      'sort-keys': ['error', 'asc', { caseSensitive: true, minKeys: MIN_KEYS_IN_OBJECT, natural: false }],
+      'quotes': ['off'],
+      'sort-imports': ['error', { allowSeparatedGroups: true }],
+      'sort-keys': ['error', 'asc', { caseSensitive: true, minKeys: MIN_KEYS_IN_OBJECT, natural: false, allowLineSeparatedGroups: true }],
     },
   },
 ];

package/index.js

@@ -7,11 +7,10 @@ import {
   setInterval,
 } from 'timers';
 import { Buffer } from 'buffer';
-import Promise from 'bluebird';
 import { getCorrelationId } from '@mimik/request-helper';
 import logger from '@mimik/sumologic-winston-logger';
 import mongoose from 'mongoose';
-import replace from 'lodash.replace';
+import { setTimeout } from 'node:timers/promises';
 
 /**
  * @module mongooser
@@ -20,7 +19,6 @@ import replace from 'lodash.replace';
  */
 
 const type = 'mongo';
-const correlationId = getCorrelationId(`${type}-database-start`);
 
 const DISCONNECTED = 0;
 const CONNECTED = 1;
@@ -29,21 +27,45 @@ const DISCONNECTING = 3;
 const ISSUE_EXIT = 1;
 const MILLI_SEC = 1000;
 
-let fatal = false;
-
+/**
+ * Creates a MongoDB connection manager for mimik microservices.
+ *
+ * @param {object} config - Service configuration object.
+ * @param {object} config.mongoSettings - MongoDB connection settings.
+ * @param {string} config.mongoSettings.url - MongoDB connection URL.
+ * @param {object} config.mongoSettings.options - Mongoose connection options. Must include `heartbeatFrequencyMS`.
+ * @param {string} [config.mongoSettings.password] - MongoDB password (masked in production logs).
+ * @param {number} config.mongoSettings.reconnectOffset - Reconnect offset in seconds.
+ * @param {number} config.mongoSettings.connectTimeout - Connection timeout in seconds.
+ * @param {number} config.mongoSettings.validationCheck - Validation check delay in milliseconds.
+ * @param {string} config.nodeEnvironment - Current node environment (e.g. 'production').
+ * @param {object} [config.encryption] - Encryption settings for client-side field level encryption.
+ * @param {string} [config.encryption.set] - Set to 'on' to enable auto-encryption.
+ * @param {string} [config.encryption.kmsProvider] - KMS provider type ('local' or 'aws').
+ * @param {string} [config.encryption.localMasterKey] - Base64-encoded local master key.
+ * @param {object} [config.encryption.aws] - AWS KMS provider settings.
+ * @param {string} [config.encryption.database] - Database name for key vault.
+ * @param {string} [config.encryption.keyVaultTable] - Collection name for key vault.
+ * @return {object} Object with methods: initializeSync, validate, replicaSet, getKMSProviders.
+ */
 export default (config) => {
   const { mongoSettings, encryption } = config;
   const { options } = mongoSettings;
+  const correlationId = getCorrelationId(`${type}-database-start`);
+  let fatal = false;
+  let listenersRegistered = false;
 
   /**
-     * AutoEncryption KMSProvider.
-     *
-     * @function getKMSProviders
-     * @category sync
-     * @return {object} The KMSProviders object.
-     *
-     * Will return the kmsProvider settings for the service.
-     */
+   * AutoEncryption KMSProvider.
+   *
+   * @function getKMSProviders
+   * @category sync
+   * @return {object} The KMSProviders object.
+   *
+   * Will return the kmsProvider settings for the service.
+   * Requires `config.encryption` to be provided to the factory.
+   * @throws {TypeError} If encryption config was not provided to the factory.
+   */
   const getKMSProviders = () => {
     const kmsProviders = {};
     const provider = encryption.kmsProvider.toLowerCase();
@@ -60,45 +82,39 @@ export default (config) => {
   /**
    * Database initialization.
    *
-   * @requires sumologic-winston-logger
+   * @requires @mimik/sumologic-winston-logger
    *
-   * @param {object} autoEncryption - Encryption settings for mongo connection.
+   * @function initializeSync
    * @category sync
-   * @return {object} The database object.
+   * @return {object} The mongoose database object. Connection is established asynchronously in the background.
    *
-   * The autoEncryption has the following strucuture:
-   * ``` javascript
-   *  {
-   *    "keyVaultClient" : <object>,
-   *    "keyVaultNamespace": <string>, // namespace for the keyvault collection
-   *    "kmsProviders": <object>, // KeyManager service settings
-   *    "schemaMap": <object>, // json object for defining encryption schema
-   *    "bypassAutoEncryption": <boolean>
-   *  }
-   *```
-   * Check MongoDB documentation for more details. https://docs.mongodb.com/manual/reference/method/Mongo/#clientsidefieldlevelencryptionoptions
+   * When encryption is enabled, configures auto-encryption by setting `keyVaultNamespace` and `kmsProviders`
+   * on the mongoose connection options.
+   * Check MongoDB documentation for the full autoEncryption specification: https://docs.mongodb.com/manual/reference/method/Mongo/#clientsidefieldlevelencryptionoptions
    *
    * Will exit 1 if the connection request generates an error or the connection state is `disconnected` or `disconnecting`.
    */
   const initializeSync = () => {
     let interval;
-
-    if (encryption.set === 'on') {
-      options.autoEncryption = {
-        keyVaultNamespace: `${encryption.database}.${encryption.keyVaultTable}`,
-        kmsProviders: getKMSProviders(),
-      };
-    }
+    const connectOptions = encryption?.set === 'on'
+      ? {
+          ...options,
+          autoEncryption: {
+            keyVaultNamespace: `${encryption.database}.${encryption.keyVaultTable}`,
+            kmsProviders: getKMSProviders(),
+          },
+        }
+      : options;
 
     if (mongoose.connection.readyState === DISCONNECTED && !fatal) {
       if (isProd(config.nodeEnvironment) && mongoSettings.password) {
         const mongoSettingsClone = { ...mongoSettings };
 
-        mongoSettingsClone.url = replace(mongoSettingsClone.url, mongoSettings.password, MASK);
+        mongoSettingsClone.url = mongoSettingsClone.url.replace(mongoSettings.password, MASK);
         logger.info('creating a database connection', { type, settings: mongoSettingsClone }, correlationId);
       }
       else logger.info('creating a database connection', { type, settings: mongoSettings }, correlationId);
-      mongoose.connect(mongoSettings.url, options)
+      mongoose.connect(mongoSettings.url, connectOptions)
         .then(() => mongoose)
         .catch((error) => {
           fatal = true;
@@ -108,21 +124,24 @@ export default (config) => {
         });
     }
 
-    mongoose.connection.on('disconnected', () => {
-      interval = setInterval(() => {
-        const state = mongoose.connection.readyState;
-
-        if ((state === DISCONNECTED || state === DISCONNECTING) && !fatal) {
-          fatal = true;
-          logger.error('Fatal error: Could not connect to database', { type, error: state }, correlationId);
-          clearInterval(interval);
-          logger.flushAndExit(ISSUE_EXIT);
-        }
-      }, (options.heartbeatFrequencyMS + (mongoSettings.reconnectOffset * MILLI_SEC)));
-    });
-    mongoose.connection.on('connected', () => {
-      if (interval) clearInterval(interval);
-    });
+    if (!listenersRegistered) {
+      listenersRegistered = true;
+      mongoose.connection.on('disconnected', () => {
+        interval = setInterval(() => {
+          const state = mongoose.connection.readyState;
+
+          if ((state === DISCONNECTED || state === DISCONNECTING) && !fatal) {
+            fatal = true;
+            logger.error('Fatal error: Could not connect to database', { type, error: state }, correlationId);
+            clearInterval(interval);
+            logger.flushAndExit(ISSUE_EXIT);
+          }
+        }, (connectOptions.heartbeatFrequencyMS + (mongoSettings.reconnectOffset * MILLI_SEC)));
+      });
+      mongoose.connection.on('connected', () => {
+        if (interval) clearInterval(interval);
+      });
+    }
     return mongoose;
   };
 
@@ -134,9 +153,8 @@ export default (config) => {
    *
    * @function validate
    * @category async
-   * @returns {Promise}.
-   * @fulfil {} Return `null`.
-   * @throws {Promise} Will throw an error if the database connection is not `connected`.
+   * @returns {Promise} Resolves to null on success.
+   * @throws {Error} Will throw an error if the database connection is not `connected`.
    *
    * Will exit 1 if the connection request times out and the connection state is not `connected`.
    */
@@ -152,18 +170,20 @@ export default (config) => {
         clearInterval(interval);
         logger.flushAndExit(ISSUE_EXIT);
       }
-    }, mongoSettings.connectTimeout * MILLI_SEC); // convert in seconds
+    }, mongoSettings.connectTimeout * MILLI_SEC); // convert to milliseconds
 
-    return Promise.delay(mongoSettings.validationCheck).then(() => {
+    return setTimeout(mongoSettings.validationCheck).then(() => {
       const state = mongoose.connection.readyState;
 
       if (state === DISCONNECTED || state === DISCONNECTING) {
+        clearInterval(interval);
         const error = new Error(`connection not established: ${mongoose.connection.readyState}`);
 
         logger.error('database connection error', { type, error }, correlationId);
         throw error;
       }
       if (state === CONNECTING) {
+        clearInterval(interval);
         return validate();
       }
       clearInterval(interval);
@@ -176,11 +196,11 @@ export default (config) => {
    *
    * Indicates if the replica is set.
    *
-   * @function replicat
+   * @function replicaSet
    * @category sync
    * @return {boolean} `True` if replica is set, `False` if not.
    */
-  const replicat = () => {
+  const replicaSet = () => {
     const isReplicaSet = Boolean(mongoose.connection.client.s.options.replicaSet);
     return isReplicaSet;
   };
@@ -188,7 +208,7 @@ export default (config) => {
   return {
     initializeSync,
     validate,
-    replicat,
+    replicaSet,
     getKMSProviders,
   };
 };

package/package.json

@@ -1,26 +1,21 @@
 {
   "name": "@mimik/mongooser",
-  "version": "3.0.2",
+  "version": "4.0.0",
   "description": "Helper for setting up mongodb using mongoose for mimik microservices",
   "main": "./index.js",
   "type": "module",
+  "exports": "./index.js",
   "engines": {
-    "node": ">=12.0.0"
+    "node": ">=24.0.0"
   },
   "scripts": {
     "lint": "eslint . --no-error-on-unmatched-pattern",
     "docs": "jsdoc2md index.js > README.md",
     "test": "echo \"Error: no test specified\" && exit 0",
-    "test-ci": "echo \"Error: no test specified\" && exit 0",
+    "test-ci": "c8 --reporter=lcov --reporter=text npm test",
     "prepublishOnly": "npm run docs && npm run lint && npm run test-ci",
     "commit-ready": "npm run docs && npm run lint && npm run test-ci"
   },
-  "husky": {
-    "hooks": {
-      "pre-commit": "npm run commit-ready",
-      "pre-push": "npm run test"
-    }
-  },
   "keywords": [
     "mimik",
     "microservice"
@@ -32,20 +27,20 @@
     "url": "https://bitbucket.org/mimiktech/mongooser"
   },
   "dependencies": {
-    "@mimik/lib-filters": "^2.0.4",
-    "@mimik/request-helper": "^2.0.2",
-    "@mimik/sumologic-winston-logger": "^2.0.3",
-    "bluebird": "3.7.2",
-    "lodash.replace": "4.1.4",
-    "mongoose": "8.16.4"
+    "@mimik/lib-filters": "^2.0.7",
+    "@mimik/request-helper": "^2.0.5",
+    "@mimik/sumologic-winston-logger": "^2.1.14",
+    "mongoose": "9.2.2"
   },
   "devDependencies": {
-    "@eslint/js": "9.31.0",
+    "@eslint/js": "9.39.3",
     "@mimik/eslint-plugin-document-env": "^2.0.8",
-    "@stylistic/eslint-plugin": "5.2.0",
-    "eslint": "9.31.0",
+    "@stylistic/eslint-plugin": "5.9.0",
+    "c8": "11.0.0",
+    "eslint": "9.39.3",
     "eslint-plugin-import": "2.32.0",
+    "globals": "17.3.0",
     "husky": "9.1.7",
-    "jsdoc-to-markdown": "9.1.2"
+    "jsdoc-to-markdown": "9.1.3"
   }
 }

package/.nycrc

@@ -1,4 +0,0 @@
-{
-  "exclude": ["gulpfile.js"],
-  "reporter": ["lcov", "text"]
-}