@ti-engine/core 1.2.0 → 1.2.4

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 This document will contain the list of changes made to the framework. The format is based on the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification.
 
+## Version 1.2.4
+* feat(cache): expose the cache module as export in `package.json`
+* feat(cache): add method `hashDeleteField` to remove a hash-set field. This implements the `hdel` Redis command
+* fix(tools): optimize method `stringifyJSON` not to call unnecessary decycling of the value if it's not an object
+* fix(cache): replace `hmset` with `hset` Redis command in both methods that set hash-set values. Also remove unnecessary `_.isObjectLike` call in `hashSetFields` method
+
+## Version 1.2.3
+* feat(start instance): add support for providing a custom path to the `.env` file to be used at service startup as process argument. Accepted arguments are `--env`, `--env-file`, `--dotenv`, `--dotenv-path`, and `-e`. The path itself should be relative to the working directory and should include the file name
+
+## Version 1.2.2
+* feat(start instance): change package `dotenv` to `@dotenvx/dotenvx` for loading of ENV variables. The new package supports encrypting the ENV variables. For more information see https://dotenvx.com/docs/
+
+## Version 1.2.1
+* feat(localization): add support for adding custom labels to the localization system. These have to follow the same format as the system labels
+* docs: add section about localization to the `README.md` file
+
 ## Version 1.2.0
 * feat(config)!: change the setting `localization.labelsPath` to be an array of strings. It can now be used to supply any additional custom labels in one or more files to the framework
 * feat(message memory cache): implement graceful exception handling during shut down procedure in `receiveMessage` and `sendMessage` methods

package/README.md

@@ -497,4 +497,24 @@ OPERATION_MODE
 
 ## Advanced topics
 
-Under development...
+### Localization
+
+The **ti-engine** framework provides a localization mechanism that allows you to translate labels into localized text. The framework comes with a default set of labels that can be found in the `localization` module. You can add your own custom labels to this set by providing one or more JSON files with the same structure as the default one (see below). The path to these files should be specified in the `LOCALIZATION_LABELS_PATH` setting. On startup, the framework will load all the JSON files and merge them into a single repository.
+
+The following is an example of a custom localization file (the names in brackets can be replaced with your own values):
+
+```json
+{
+  "labels": {
+    "[category]": {
+      "[sub-category]": {
+        "[label]": {
+          "en": "[localized label text]"
+        }
+      }
+    }
+  }
+}
+```
+
+The individual languages are specified with a two-letter code. The default language is `en` (English). If you want to use a different language, you can set the `LOCALIZATION_LANGUAGE` setting to the desired language code.

package/bin/localization/labels.json

@@ -1,65 +1,65 @@
-{
-  "labels": {
-    "general": {
-      "exceptions": {
-        "0": {
-          "en": "Unidentified error encountered or unrecognized exception code provided."
-        },
-        "1000": {
-          "en": "Error thrown by internal JS source."
-        },
-        "1001": {
-          "en": "Attempt to construct an abstract class detected."
-        },
-        "1002": {
-          "en": "Attempt to call an abstract method detected."
-        },
-        "1003": {
-          "en": "Invalid or no service domain name provided at microservice startup."
-        },
-        "1004": {
-          "en": "The system cache required for proper engine operation is unavailable."
-        },
-        "1005": {
-          "en": "The provided service handler is not a proper function."
-        },
-        "1006": {
-          "en": "The requested feature is not supported by current configuration or version."
-        },
-        "2000": {
-          "en": "Invalid authorization token provided."
-        },
-        "2001": {
-          "en": "Invalid or expired session encountered."
-        },
-        "2002": {
-          "en": "Attempt for unauthorized access detected."
-        },
-        "2003": {
-          "en": "The system detected tampering with the message received via message exchange."
-        },
-        "3000": {
-          "en": "General error during cross-application communication."
-        },
-        "3001": {
-          "en": "The message sender instance is currently unavailable."
-        },
-        "3002": {
-          "en": "The execution of a service could not complete within the allowed timeout."
-        },
-        "3003": {
-          "en": "The specified service is not found in the service registry."
-        },
-        "3004": {
-          "en": "The specified service is not found in the service definition interface."
-        },
-        "3005": {
-          "en": "No handler found in the interface for the specified service or service version."
-        },
-        "3010": {
-          "en": "Connection retry attempts exceeded the configured limit."
-        }
-      }
-    }
-  }
+{
+  "labels": {
+    "general": {
+      "exceptions": {
+        "0": {
+          "en": "Unidentified error encountered or unrecognized exception code provided."
+        },
+        "1000": {
+          "en": "Error thrown by internal JS source."
+        },
+        "1001": {
+          "en": "Attempt to construct an abstract class detected."
+        },
+        "1002": {
+          "en": "Attempt to call an abstract method detected."
+        },
+        "1003": {
+          "en": "Invalid or no service domain name provided at microservice startup."
+        },
+        "1004": {
+          "en": "The system cache required for proper engine operation is unavailable."
+        },
+        "1005": {
+          "en": "The provided service handler is not a proper function."
+        },
+        "1006": {
+          "en": "The requested feature is not supported by current configuration or version."
+        },
+        "2000": {
+          "en": "Invalid authorization token provided."
+        },
+        "2001": {
+          "en": "Invalid or expired session encountered."
+        },
+        "2002": {
+          "en": "Attempt for unauthorized access detected."
+        },
+        "2003": {
+          "en": "The system detected tampering with the message received via message exchange."
+        },
+        "3000": {
+          "en": "General error during cross-application communication."
+        },
+        "3001": {
+          "en": "The message sender instance is currently unavailable."
+        },
+        "3002": {
+          "en": "The execution of a service could not complete within the allowed timeout."
+        },
+        "3003": {
+          "en": "The specified service is not found in the service registry."
+        },
+        "3004": {
+          "en": "The specified service is not found in the service definition interface."
+        },
+        "3005": {
+          "en": "No handler found in the interface for the specified service or service version."
+        },
+        "3010": {
+          "en": "Connection retry attempts exceeded the configured limit."
+        }
+      }
+    }
+  }
 }

package/bin/start-instance.js

@@ -11,7 +11,28 @@
 const path = require( "path" );
 
 // Load any ENV variables defined in a .env file - before including any framework files:
-require( "dotenv" ).config( { path: path.join( process.cwd(), ".env" ) } );
+// - If an env file path is provided via process arguments, use it; otherwise, default to CWD/.env
+const envFilePath = ( () => {
+    let envPath = path.join( process.cwd(), ".env" );
+    try {
+        const argv = Array.isArray( process.argv ) ? process.argv.slice( 2 ) : [];
+        const aliases = [ "--env", "--env-file", "--dotenv", "--dotenv-path", "-e" ];
+        for ( const key of aliases ) {
+            const idx = argv.indexOf( key );
+            if ( idx !== -1 && idx + 1 < argv.length ) {
+                const value = argv[ idx + 1 ];
+                if ( typeof value === "string" && !value.startsWith( "-" ) ) {
+                    envPath = path.join( process.cwd(), value.trim() );
+                    break;
+                }
+            }
+        }
+    } catch {
+    }
+    return envPath;
+} )();
+
+require( "@dotenvx/dotenvx" ).config( { path: envFilePath } );
 
 const tools = require( "#tools" );
 const logger = require( "#logger" );
@@ -36,7 +57,7 @@ const defaultNameFromClass = ( () => {
 
 process.env.TI_INSTANCE_NAME = process.env.TI_INSTANCE_NAME || defaultNameFromClass;
 
-// Configure the process error handlers:
+// Configure the process termination handlers to ensure a graceful shutdown:
 
 /**
  * Will be used to gracefully shut down the instance.
@@ -75,6 +96,8 @@ process.on( "SIGBREAK", () => {
     shutDownInstance( 0 );
 } );
 
+// Configure the process general error handlers:
+
 process.on( "unhandledRejection", ( reason ) => {
     // Check if the fail-fast behavior has been forcefully disabled:
     const failFastDisabled = tools.toBool( process.env.TI_FAIL_FAST_ON_UNHANDLED_OFF || "" );

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@ti-engine/core",
-  "version": "1.2.0",
+  "version": "1.2.4",
   "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",
   "exports": {
     ".": "./bin/start-instance.js",
+    "./cache": "./utils/cache.js",
     "./exceptions": "./utils/exceptions.js",
     "./localization": "./utils/localization.js",
     "./logger": "./utils/logger.js",
@@ -46,7 +47,7 @@
   },
   "dependencies": {
     "blake2": "^5.0.0",
-    "dotenv": "^17.2.1",
+    "@dotenvx/dotenvx": "^1.49.0",
     "fs-extra": "^11.3.1",
     "lodash": "^4.17.21",
     "node-schedule": "^2.1.1",

package/utils/cache.js

@@ -508,7 +508,7 @@ class CommonMemoryCache extends ConnectionObserver {
     hashSetField( key, name, value ) {
         return new Promise( ( resolve, reject ) => {
             if ( this.#isOperational === true ) {
-                let commandHashSetField = [ redis.cacheCommands.HASH_SET_MANY, key, name, tools.stringifyJSON( value ) ];
+                let commandHashSetField = [ redis.cacheCommands.HASH_SET, key, name, tools.stringifyJSON( value ) ];
                 this.#redisClient.executeCommands( [ commandHashSetField ] ).then( () => {
                     resolve();
                 } ).catch( ( error ) => {
@@ -535,10 +535,10 @@ class CommonMemoryCache extends ConnectionObserver {
     hashSetFields( key, fields ) {
         return new Promise( ( resolve, reject ) => {
             if ( this.#isOperational === true ) {
-                let commandHashSetFields = [ redis.cacheCommands.HASH_SET_MANY, key ];
+                let commandHashSetFields = [ redis.cacheCommands.HASH_SET, key ];
                 _.forEach( fields, ( field ) => {
                     commandHashSetFields.push( field.name );
-                    commandHashSetFields.push( _.isObjectLike( field.value ) ? tools.stringifyJSON( field.value ) : field.value );
+                    commandHashSetFields.push( tools.stringifyJSON( field.value ) );
                 } );
                 this.#redisClient.executeCommands( [ commandHashSetFields ] ).then( () => {
                     resolve();
@@ -576,6 +576,31 @@ class CommonMemoryCache extends ConnectionObserver {
         } );
     }
 
+    /**
+     * Used to remove a single field from a hash.
+     *
+     * @method
+     * @param {string} key
+     * @param {string} field
+     * @return {Promise<boolean>} Will return 'true' if the field was removed, 'false' otherwise.
+     * @public
+     */
+    hashDeleteField( key, field ) {
+        return new Promise( ( resolve, reject ) => {
+            if ( this.#isOperational === true ) {
+                let commandHashGetField = [ redis.cacheCommands.HASH_REMOVE, key, field ];
+                this.#redisClient.executeCommands( [ commandHashGetField ] ).then( ( results ) => {
+                    results = results[ 0 ];
+                    resolve( ( results && results.length > 1 ) ? tools.toBool( results[ 1 ] ) : false );
+                } ).catch( ( error ) => {
+                    reject( error );
+                } );
+            } else {
+                reject( exceptions.raise( exceptions.exceptionCode.E_GEN_SYSTEM_CACHE_UNAVAILABLE ) );
+            }
+        } );
+    }
+
     /**
      * Used to store a JSON variable.
      * <br/>

package/utils/exceptions.js

@@ -248,4 +248,4 @@ module.exports.raise = ( source, data, exceptionID ) => {
  */
 module.exports.isException = ( object ) => {
     return ( object instanceof Exception );
-};
+};

package/utils/localization.js

@@ -8,16 +8,26 @@
 
 const _ = require( "lodash" );
 const path = require( "path" );
+const labels = require( "#labels" );
 const config = require( "#config" );
+const logger = require( '#logger' );
+const exceptions = require( '#exceptions' );
 
-// const labelsPath = path.normalize( path.join( process.cwd(), config.getSetting( config.setting.LOCALIZATION_LABELS_PATH ) ) );
-// const labels = require( labelsPath );
-const labels = require( "#labels" );
 const defaultEmptyLabel = "!!! label not found !!!";
 
-// TODO: Add functionality to import additional custom labels.
+// Load any custom labels defined in the configuration:
+try {
+    const labelsPaths = config.getSetting( config.setting.LOCALIZATION_LABELS_PATH );
+    _.forEach( labelsPaths, ( labelsPath ) => {
+        let filePath = path.normalize( path.join( process.cwd(), labelsPath ) );
+        let fileLabels = require( filePath );
+        _.merge( labels, fileLabels );
+    } );
+} catch ( error ) {
+    logger.log( `Error while trying to load custom labels.`, logger.logSeverity.ERROR, exceptions.raise( error ) );
+}
 
-// prevent further modifications to the labels object:
+// Prevent further modifications to the labels object:
 Object.freeze( labels );
 
 /**

package/utils/tools.js

@@ -319,8 +319,7 @@ module.exports.retrocycle = ( $ ) => {
  * @public
  */
 module.exports.stringifyJSON = ( value ) => {
-    let transformed = module.exports.decycle( value );
-    return _.isObjectLike( transformed ) ? JSON.stringify( _.toPlainObject( transformed ) ) : value;
+    return _.isObjectLike( value ) ? JSON.stringify( _.toPlainObject( module.exports.decycle( value ) ) ) : value;
 };
 
 /**
@@ -537,4 +536,4 @@ class RetryPolicy {
 
 }
 
-module.exports.RetryPolicy = RetryPolicy;
+module.exports.RetryPolicy = RetryPolicy;