@ti-engine/core 1.2.4 → 1.3.3

package/integrations/redis-integration.js

@@ -28,6 +28,7 @@ let cacheCommandsEnum = tools.enum( {
     HASH_GET: [ "hget", "hash get", "https://redis.io/docs/latest/commands/hget/" ],
     HASH_GET_ALL: [ "hgetall", "hash get all", "https://redis.io/docs/latest/commands/hgetall/" ],
     HASH_REMOVE: [ "hdel", "hash remove", "https://redis.io/docs/latest/commands/hdel/" ],
+    HASH_EXPIRE: [ "hexpire", "hash expire", "https://redis.io/docs/latest/commands/hexpire/" ],
     HASH_SET: [ "hset", "", "https://redis.io/docs/latest/commands/hset/" ],
     HASH_SET_MANY: [ "hmset", "(deprecated) use HSET with multiple fields", "https://redis.io/docs/latest/commands/hmset/" ],
     IS_SET_MEMBER: [ "sismember", "", "https://redis.io/docs/latest/commands/sismember/" ],
@@ -43,6 +44,21 @@ let cacheCommandsEnum = tools.enum( {
     UNION_OF_SETS: [ "sunion", "union of sets", "https://redis.io/docs/latest/commands/sunion/" ]
 } );
 
+/**
+ * Enum for listing all client statuses.
+ *
+ * @readonly
+ * @enum {number}
+ */
+let clientStatusEnum = tools.enum( {
+    UNINITIALIZED: [ 0, "uninitialized", "Redis client is offline and not yet initialized." ],
+    CONNECTED: [ 1, "connected", "Redis client is connected and online." ],
+    CONNECTING: [ 2, "connecting", "Redis client is connecting to server." ],
+    DISRUPTED: [ 3, "disrupted", "Redis client is temporarily disconnected from server due to a disruption." ],
+    SHUTTING_DOWN: [ 4, "shutting down", "Redis client is shutting down." ],
+    DISCONNECTED: [ 5, "disconnected", "Redis client is permanently disconnected from server." ]
+} );
+
 /**
  * Enum for listing the Redis key override modes.
  *
@@ -63,6 +79,10 @@ module.exports.cacheCommands = cacheCommandsEnum;
  * @typedef {string} TiRedisOverrideMode
  */
 module.exports.cacheOverrideMode = cacheOverrideModeEnum;
+/**
+ * @typedef {number} TiRedisClientStatus
+ */
+module.exports.clientStatus = clientStatusEnum;
 
 /**
  * Used to create a Redis Cache client.
@@ -76,6 +96,7 @@ module.exports.cacheOverrideMode = cacheOverrideModeEnum;
 class RedisClient {
 
     #clientIdentifier;
+    #clientStatus = clientStatusEnum.UNINITIALIZED;
     #retryMaxInterval = 1000;
     #retryMaxAttempts = undefined;
     #redisConnection = undefined;
@@ -118,6 +139,17 @@ class RedisClient {
         return this.#redisClientID;
     }
 
+    /**
+     * Used to return the Redis client status.
+     *
+     * @property
+     * @returns {number}
+     * @public
+     */
+    get clientStatus() {
+        return this.#clientStatus;
+    }
+
     /**
      * Used to return the Redis server version.
      *
@@ -167,12 +199,6 @@ class RedisClient {
                 } ).then( ( clientID ) => {
                     // Store the client ID:
                     this.#redisClientID = clientID;
-
-                    // Notify all connection observers about the initialization success:
-                    _.forEach( this.#connectionObservers, ( connectionObservers ) => {
-                        connectionObservers.onConnectionRecovered( this.#clientIdentifier );
-                    } );
-
                     resolve();
                 } ).catch( ( error ) => {
                     reject( exceptions.raise( error ) );
@@ -359,6 +385,7 @@ class RedisClient {
     shutDown( timeoutMs = 1000 ) {
         return new Promise( ( resolve ) => {
             let finished = false;
+            this.#clientStatus = clientStatusEnum.SHUTTING_DOWN;
             const done = () => {
                 if ( !finished ) {
                     finished = true;
@@ -403,7 +430,8 @@ class RedisClient {
      * @param {number} defaultDB
      * @param {number} [retryMaxIntervalMs=1000] Optional max backoff interval.
      * @param {number|undefined} [retryMaxAttempts=undefined] Optional max (re)connection attempts before abort.
-     * @public
+     * @returns {Promise}
+     * @private
      */
     #setupClient( host, port, authKey, user, defaultDB, retryMaxIntervalMs, retryMaxAttempts ) {
         return new Promise( ( resolve, reject ) => {
@@ -412,19 +440,22 @@ class RedisClient {
                 this.#retryMaxAttempts = retryMaxAttempts;
 
                 let retryStrategy = ( attempt ) => {
-                    let result = Math.min( attempt * 50, this.#retryMaxInterval );
-
+                    let retryInterval = Math.min( attempt * 50, this.#retryMaxInterval );
                     if ( this.#retryMaxAttempts != null && attempt > this.#retryMaxAttempts ) {
                         logger.log( "In Redis retry strategy: reached max attempts for command retry. Aborting...", logger.logSeverity.WARNING, { attempts: attempt } );
-                        result = exceptions.raise( exceptions.exceptionCode.E_COM_RETRY_ATTEMPTS_EXCEEDED );
+                        retryInterval = exceptions.raise( exceptions.exceptionCode.E_COM_RETRY_ATTEMPTS_EXCEEDED );
                     }
-
-                    return result;
+                    return retryInterval;
                 };
 
                 let reconnectOnError = ( error ) => {
                     logger.log( `In Redis reconnect on error strategy: ${ error.message }`, logger.logSeverity.ERROR, error );
-                    return !!error.message.includes( "READONLY" );
+                    if ( error.message.includes( "READONLY" ) ) {
+                        // Returning 2 will also resubmit the failed command:
+                        return 2;
+                    } else {
+                        return 0;
+                    }
                 };
 
                 let options = {
@@ -441,22 +472,33 @@ class RedisClient {
 
                 /** @type Redis */
                 this.#redisConnection = new Redis( options );
+                this.#clientStatus = clientStatusEnum.CONNECTING;
+
+                this.#redisConnection.once( "ready", () => {
+                    this.#clientStatus = clientStatusEnum.CONNECTED;
+                    this.#notifyConnectionObservers();
+
+                    this.#redisConnection.on( "ready", () => {
+                        this.#clientStatus = clientStatusEnum.CONNECTED;
+                        this.#notifyConnectionObservers();
+                    } );
 
-                this.#redisConnection.on( "ready", () => {
-                    logger.log( `Connection to Redis server ${ host }:${ port } (re)established by client '${ this.identifier }' and is ready to be used.`, logger.logSeverity.INFO );
                     resolve();
                 } );
                 this.#redisConnection.on( "error", ( error ) => {
+                    this.#clientStatus = clientStatusEnum.DISRUPTED;
                     logger.log( `Error received in Redis client '${ this.identifier }'.`, logger.logSeverity.ERROR, error );
-
-                    // Notify all connection observers about this event:
-                    _.forEach( this.#connectionObservers, ( connectionObservers ) => {
-                        connectionObservers.onConnectionDisrupted( this.#clientIdentifier );
-                    } );
+                    this.#notifyConnectionObservers();
+                } );
+                this.#redisConnection.on( "reconnecting", ( retryInterval ) => {
+                    this.#clientStatus = clientStatusEnum.CONNECTING;
+                    logger.log( `Client '${ this.identifier }' reconnecting to Redis server after ${ retryInterval } ms.`, logger.logSeverity.DEBUG );
                 } );
-                this.#redisConnection.on( "reconnecting", ( info ) => {
-                    if ( info.attempt > 1 ) {
-                        logger.log( `Client '${ this.identifier }' reconnecting to Redis server after ${ info.delay } ms. This is attempt ${ info.attempt }.`, logger.logSeverity.DEBUG );
+                this.#redisConnection.on( "end", () => {
+                    if ( this.#clientStatus !== clientStatusEnum.SHUTTING_DOWN ) {
+                        this.#clientStatus = clientStatusEnum.DISCONNECTED;
+                        logger.log( `Client '${ this.identifier }' cannot reconnect to Redis server and has been shut down.`, logger.logSeverity.WARNING );
+                        this.#notifyConnectionObservers();
                     }
                 } );
             } catch ( error ) {
@@ -465,10 +507,31 @@ class RedisClient {
         } );
     }
 
+    /**
+     * Used to notify all connection observers about the current connection state.
+     *
+     * @method
+     * @private
+     */
+    #notifyConnectionObservers() {
+        // Notify all connection observers about the event:
+        _.forEach( this.#connectionObservers, ( connectionObservers ) => {
+            if ( this.#clientStatus === clientStatusEnum.CONNECTED ) {
+                logger.log( `Connection to Redis server ${ this.#redisConnection.options.host }:${ this.#redisConnection.options.port } (re)established by client '${ this.identifier }' and is ready to be used.`, logger.logSeverity.INFO );
+                connectionObservers.onConnectionRecovered( this.#clientIdentifier );
+            } else if ( this.#clientStatus === clientStatusEnum.DISRUPTED ) {
+                connectionObservers.onConnectionDisrupted( this.#clientIdentifier );
+            } else if ( this.#clientStatus === clientStatusEnum.DISCONNECTED ) {
+                connectionObservers.onConnectionLost( this.#clientIdentifier );
+            }
+        } );
+    }
+
     /**
      * Used to fetch and store Redis server information.
      *
      * @method
+     * @returns {Promise}
      * @private
      */
     #fetchServerInfo() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ti-engine/core",
-  "version": "1.2.4",
+  "version": "1.3.3",
   "description": "The ti-engine is an open source, free to use—both for personal and commercial projects—framework for the creation of microservice-based solutions using node.js.",
   "author": "Boris Kostadinov <kostadinov.boris@gmail.com>",
   "license": "GPL-3.0-or-later",

package/utils/cache.js

@@ -124,6 +124,22 @@ class CommonMemoryCache extends ConnectionObserver {
         }
     }
 
+    /**
+     * Needs to be invoked by the connection handler when the connection is irrevocably lost.
+     *
+     * @method
+     * @param {string} identifier The identifier of the observed connection.
+     * @override
+     * @public
+     */
+    onConnectionLost( identifier ) {
+        if ( identifier === this.#connectionIdentifier ) {
+            this.#isOperational = false;
+            // TODO: implement forced shut down of the service instance instead of crashing it outright
+            throw exceptions.raise( exceptions.exceptionCode.E_GEN_SYSTEM_CACHE_UNAVAILABLE );
+        }
+    }
+
     /**
      * Used to register a new {@link ConnectionObserver} for events related to the underlying Redis connection state.
      *
@@ -317,13 +333,19 @@ class CommonMemoryCache extends ConnectionObserver {
      * @method
      * @param {string} key
      * @param {number} seconds
+     * @param {string} [name] If you need to expire a field in a hash set instead, provide the name of the set here.
      * @returns {Promise<number>} This will resolve with the seconds as provided initially by the caller.
      * @public
      */
-    expireValue( key, seconds ) {
+    expireValue( key, seconds, name ) {
         return new Promise( ( resolve, reject ) => {
             if ( this.#isOperational === true ) {
-                let commandExpire = [ redis.cacheCommands.EXPIRE, key, seconds ];
+                let commandExpire = [];
+                if ( name ) {
+                    commandExpire = [ redis.cacheCommands.HASH_EXPIRE, name, seconds, "FIELDS", 1, key ];
+                } else {
+                    commandExpire = [ redis.cacheCommands.EXPIRE, key, seconds ];
+                }
                 this.#redisClient.executeCommands( [ commandExpire ] ).then( () => {
                     resolve( seconds );
                 } ).catch( ( error ) => {

package/utils/config.js

@@ -73,7 +73,7 @@ const tools = require( "#tools" );
 /**
  * @typedef {Object} SettingsLocalization
  * @property {Array<string>} labelsPath
- * @property {string} language
+ * @property {TiLocalizationLanguage} language
  */
 
 /**
@@ -113,7 +113,7 @@ const tools = require( "#tools" );
  * @readonly
  * @enum {string} Keys of this ENUM are strings.
  */
-let settingsEnum = tools.enum( {
+const settingsEnum = tools.enum( {
     AUDITING_LOG_CONSOLE_ENABLED: [ "auditing.logConsoleEnabled", "logConsoleEnabled", "" ],
     AUDITING_LOG_DETAILS: [ "auditing.logDetails", "logDetails", "" ],
     AUDITING_LOG_MIN_LEVEL: [ "auditing.logMinLevel", "logMinLevel", "" ],
@@ -152,7 +152,7 @@ module.exports.setting = settingsEnum;
 /** @type {SettingsMain} */
 const settings = require( "#settings" );
 
-// override remaining settings with ENV variables (if provided):
+// Override the remaining settings with ENV variables (if provided):
 if ( settings.auditing ) {
     settings.auditing.logConsoleEnabled = ( process.env.TI_AUDITING_LOG_CONSOLE_ENABLED !== undefined ) ? tools.toBool( process.env.TI_AUDITING_LOG_CONSOLE_ENABLED ) : settings.auditing.logConsoleEnabled;
     settings.auditing.logDetails = ( process.env.TI_AUDITING_LOG_DETAILS !== undefined ) ? tools.toBool( process.env.TI_AUDITING_LOG_DETAILS ) : settings.auditing.logDetails;
@@ -160,7 +160,7 @@ if ( settings.auditing ) {
     settings.auditing.logUsesJSON = ( process.env.TI_AUDITING_LOG_USES_JSON !== undefined ) ? tools.toBool( process.env.TI_AUDITING_LOG_USES_JSON ) : settings.auditing.logUsesJSON;
 }
 if ( settings.localization ) {
-    settings.localization.labelsPath = ( process.env.TI_LOCALIZATION_LABELS_PATH !== undefined ) ? process.env.TI_LOCALIZATION_LABELS_PATH : settings.localization.labelsPath;
+    settings.localization.labelsPath = ( process.env.TI_LOCALIZATION_LABELS_PATH !== undefined ) ? [ process.env.TI_LOCALIZATION_LABELS_PATH ] : settings.localization.labelsPath;
     settings.localization.language = ( process.env.TI_LOCALIZATION_LANGUAGE !== undefined ) ? process.env.TI_LOCALIZATION_LANGUAGE : settings.localization.language;
 }
 if ( settings.memoryCache ) {
@@ -186,7 +186,7 @@ if ( process.env.TI_GCLOUD_ENABLED === true && settings.gcloudIntegration ) {
 
 settings.operationMode = process.env.NODE_ENV || settings.operationMode;
 
-// prevent further modifications to the settings object:
+// Prevent further modifications to the settings object:
 Object.freeze( settings );
 
 /**

package/utils/exceptions.js

@@ -1,6 +1,6 @@
 /*
  * The ti-engine is an open source, free to use—both for personal and commercial projects—framework for the creation of microservice-based solutions using node.js.
- * Copyright © 2021-2023 Boris Kostadinov <kostadinov.boris@gmail.com>
+ * Copyright © 2021-2025 Boris Kostadinov <kostadinov.boris@gmail.com>
  * This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
  * This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
  * You should have received a copy of the GNU General Public License along with this program. If not, see <https://www.gnu.org/licenses/>.
@@ -15,7 +15,7 @@ const tools = require( "#tools" );
  * @readonly
  * @enum {number}
  */
-let exceptionCodeEnum = tools.enum( {
+const exceptionCodeEnum = tools.enum( {
     E_UNKNOWN_ERROR: [ 0, "unknown error", "Unidentified error encountered or unrecognized exception code provided." ],
     /** General exceptions - codes under 1xxx */
     E_GEN_JS_INTERNAL_ERROR: [ 1000, "js internal error", "Error thrown by internal JS source." ],
@@ -25,7 +25,7 @@ let exceptionCodeEnum = tools.enum( {
     E_GEN_SYSTEM_CACHE_UNAVAILABLE: [ 1004, "system cache unavailable", "The system cache required for proper engine operation is unavailable." ],
     E_GEN_BAD_SERVICE_HANDLER: [ 1005, "bad service handler", "The provided service handler is not a proper function." ],
     E_GEN_FEATURE_UNSUPPORTED: [ 1006, "feature unsupported", "The requested feature is not supported by current configuration or version." ],
-    /** Security & Administration related exceptions - codes under 2xxx */
+    /** Security & Administration exceptions - codes under 2xxx */
     E_SEC_INVALID_AUTH_TOKEN: [ 2000, "invalid auth token", "Invalid authorization token provided." ],
     E_SEC_INVALID_EXPIRED_SESSION: [ 2001, "invalid or expired session", "Invalid or expired session encountered." ],
     E_SEC_UNAUTHORIZED_ACCESS: [ 2002, "unauthorized access", "Attempt for unauthorized access detected." ],
@@ -38,16 +38,19 @@ let exceptionCodeEnum = tools.enum( {
     E_COM_SERVICE_NOT_FOUND: [ 3004, "service not found", "The specified service is not found in the service definition interface." ],
     E_COM_SERVICE_HANDLER_NOT_FOUND: [ 3005, "service handler not found", "No handler found in the interface for the specified service or service version." ],
     E_COM_MESSAGE_RECEIVER_UNAVAILABLE: [ 3006, "message receiver unavailable", "The message receiver instance is currently unavailable." ],
-    // E_COM_UNRECOGNIZED_API_URL: [ 301, "unrecognized api url", "Attempt to access unrecognized or invalid API URL." ],
-    // E_COM_MISSING_REQUIRED_ARGUMENTS: [ 302, "missing required arguments", "Attempt to execute operation without all required arguments." ],
-    // E_COM_UNRECOGNIZED_RESPONSE_STRUCTURE: [ 303, "unrecognized response structure", "The received response has unrecognized structure and cannot be parsed or examined." ],
-    // E_COM_RECEIVED_ERROR_RESPONSE: [ 304, "received error response", "The received response indicates error in the external system." ],
-    // E_COM_JSON_RPC_DATA_INVALID: [ 305, "json rpc data invalid", "The JSON RPC 2.0 data being verified is not valid." ],
-    // E_COM_NO_OPEN_CONNECTION: [ 306, "no open connection", "Attempting to do communication request while there is no open connection available." ],
-    // E_COM_REQUEST_ERROR_RESPONSE: [ 307, "received error response", "The received response indicates error in the external system." ],
-    // E_COM_CONNECTION_TIMEOUT: [ 308, "connection timeout", "Attempting to do communication request but request timeout." ],
-    // E_COM_INVALID_API_MAPPING: [ 309, "invalid api mapping", "Attempt to access API URL without proper controller mapping." ],
-    E_COM_RETRY_ATTEMPTS_EXCEEDED: [ 3010, "retry attempts exceeded", "Connection retry attempts exceeded the configured limit." ]
+    E_COM_MESSAGE_EXCHANGE_BROKEN: [ 3007, "message exchange broken", "The message exchange is irrevocably broken and cannot be used any longer." ],
+    E_COM_RETRY_ATTEMPTS_EXCEEDED: [ 3010, "retry attempts exceeded", "Connection retry attempts exceeded the configured limit." ],
+    /** Web server exceptions - codes under 4xxx */
+    E_WEB_INVALID_REQUEST_METHOD: [ 4000, "invalid request method", "The request method is not recognized or not supported." ],
+    E_WEB_INVALID_REQUEST_URI: [ 4001, "invalid request uri", "The request URI is not recognized or not supported." ],
+    E_WEB_INVALID_REQUEST_BODY: [ 4002, "invalid request body", "The request body is not recognized or not supported." ],
+    E_WEB_INVALID_REQUEST_QUERY: [ 4003, "invalid request query", "The request query is not recognized or not supported." ],
+    E_WEB_INVALID_REQUEST_HEADERS: [ 4004, "invalid request headers", "The request headers are not recognized or not supported." ],
+    E_WEB_INVALID_REQUEST_PARAMETERS: [ 4005, "invalid request parameters", "The request parameters are not recognized or not supported." ],
+    E_WEB_INVALID_REQUEST_FORMAT: [ 4006, "invalid request format", "The request format is not recognized or not supported." ],
+    E_WEB_INVALID_REQUEST_CONTENT_TYPE: [ 4007, "invalid request content type", "The request content type is not recognized or not supported." ],
+    E_WEB_INVALID_REQUEST_CONTENT_LENGTH: [ 4008, "invalid request content length", "The request content length is not recognized or not supported." ],
+    E_WEB_INVALID_REQUEST_CONTENT_ENCODING: [ 4009, "invalid request content encoding", "The request content encoding is not recognized or not supported." ]
 } );
 
 /**
@@ -55,6 +58,8 @@ let exceptionCodeEnum = tools.enum( {
  */
 module.exports.exceptionCode = exceptionCodeEnum;
 
+const labelPath = "system.exceptions.";
+
 /**
  * Represents an exception.
  *
@@ -83,8 +88,8 @@ class Exception {
         this.#id = id;
         this.#code = exceptionCode;
         this.#httpCode = undefined;
-        this.#label = "labels.general.exceptions." + exceptionCode;
-        this.#description = exceptionCodeEnum.properties[ exceptionCode ].description;
+        this.#label = labelPath + exceptionCode;
+        this.#description = description || exceptionCodeEnum.properties[ exceptionCode ].description;
         this.#data = data || {};
     }
 
@@ -93,8 +98,8 @@ class Exception {
     /**
      * Unique identifier of the exception instance. Can be used for tracing problems with customer support cases.
      *
-     * @method
-     * @return {string}
+     * @property
+     * @returns {string}
      * @public
      */
     get id() {
@@ -104,8 +109,8 @@ class Exception {
     /**
      * Identifier code of the exception type.
      *
-     * @method
-     * @return {TiExceptionCode}
+     * @property
+     * @returns {TiExceptionCode}
      * @public
      */
     get code() {
@@ -115,8 +120,8 @@ class Exception {
     /**
      * HTTP error code if relevant.
      *
-     * @method
-     * @return {number}
+     * @property
+     * @returns {number}
      * @public
      */
     get httpCode() {
@@ -126,7 +131,7 @@ class Exception {
     /**
      * HTTP error code if relevant.
      *
-     * @method
+     * @property
      * @param {number} httpCode
      * @public
      */
@@ -137,8 +142,8 @@ class Exception {
     /**
      * Localized label identifier.
      *
-     * @method
-     * @return {string}
+     * @property
+     * @returns {string}
      * @public
      */
     get label() {
@@ -148,8 +153,8 @@ class Exception {
     /**
      * Description or additional technical information that is NOT localized.
      *
-     * @method
-     * @return {string}
+     * @property
+     * @returns {string}
      * @public
      */
     get description() {
@@ -159,8 +164,8 @@ class Exception {
     /**
      * JSON containing any additional data that has relevance for the exception. Can be converted JavaScript {@link Error} object as well.
      *
-     * @method
-     * @return {Object}
+     * @property
+     * @returns {Object}
      * @public
      */
     get data() {
@@ -170,7 +175,7 @@ class Exception {
     /**
      * JSON containing any additional data that has relevance for the exception. Can be converted JavaScript {@link Error} object as well.
      *
-     * @method
+     * @property
      * @param {Object} data
      * @public
      */
@@ -182,17 +187,18 @@ class Exception {
      * Extracts the essential information about the Exception and returns it as JSON.
      *
      * @method
+     * @param {boolean} [includeData=true] Whether to include the data property in the output.
      * @returns {Object}
      * @public
      */
-    asJSON() {
+    asJSON( includeData = true ) {
         return {
             id: this.id,
             code: this.code,
             httpCode: this.httpCode,
             label: this.label,
             description: this.description,
-            data: this.data
+            data: ( includeData === true ) ? this.data : undefined
         };
     }
 }
@@ -202,7 +208,7 @@ class Exception {
  *
  * @method
  * @param {Error|TiExceptionCode|Exception} source Could be a standard JS Error, an ExceptionCode, or another Exception (in which case it will be raised further).
- * @param {Object} [data] Additional JSON data that can accompany the exception. If more data is added on subsequent Raise calls, it will be merged with the existing one.
+ * @param {Object} [data] Additional JSON data that can go with the exception. If more data is added on later Raise calls, it will be merged with the existing one.
  * @param {string} [exceptionID] Should be used only in cases when we have a recognizable exception ID beforehand. Should not be entered otherwise!
  * @returns {Exception}
  * @public
@@ -225,13 +231,13 @@ module.exports.raise = ( source, data, exceptionID ) => {
         exception = new Exception( exceptionID || tools.getUUID(), ( exceptionCodeEnum.properties[ source ] ) ? source : module.exports.exceptionCode.E_UNKNOWN_ERROR );
     }
 
-    // merge the default exception data with the additional one, if it's provided:
+    // Merge the default exception data with the additional one if it's provided:
     if ( data ) {
         exception.data = _.mergeWith( ( exception.data || {} ), _.cloneDeep( data ), ( objValue, srcValue ) => {
             return ( _.isArray( objValue ) ) ? objValue.concat( srcValue ) : undefined;
         } );
 
-        // make sure to eliminate any circular dependencies inside the data object (these should never be needed for an error description):
+        // Make sure to eliminate any circular dependencies inside the data object (these should never be needed for an error description):
         exception.data = tools.decycle( exception.data );
     }
 
@@ -242,7 +248,7 @@ module.exports.raise = ( source, data, exceptionID ) => {
  * Verifies if the passed object is an Exception.
  *
  * @method
- * @param object
+ * @param {*} object
  * @returns {boolean}
  * @public
  */