@ti-engine/core 1.2.0 → 1.2.3

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 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.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,6 +1,6 @@
 {
   "name": "@ti-engine/core",
-  "version": "1.2.0",
+  "version": "1.2.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",
@@ -46,7 +46,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/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 );
 
 /**