@ti-engine/core 1.3.10 → 1.3.12

package/CHANGELOG.md

@@ -2,26 +2,46 @@
 
 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.3.12
+
+* feat(exceptions): add new exception code `E_COM_SERVICE_EXEC_FAILED`
+* feat(localization): add new public method `getAllLabels`
+* feat(localization): use new `deepFreeze` method to freeze all label trees
+* feat(tools): add new public method `deepFreeze` for freezing an object and all its sub-objects recursively
+* feat(config): use new `deepFreeze` method to freeze all configuration settings
+* docs: add more information about the `localization` module in `README.md` file
+* build(npm): update npm dependencies to their latest versions
+
+## Version 1.3.11
+
+* feat(tools): add `arrayUniques` method to the tools module that helps extract only the unique array values
+* fix(start instance): fix `undefined` instance ID in the log message about starting the instance
+
 ## Version 1.3.10
+
 * chore: fix various minor issues reported by the linter
 * build(npm): add more information and options to the `package.json` file
 * docs: add some JSDoc descriptions to classes and methods
 
 ## Version 1.3.9
+
 * feat(exceptions): add new exception code `E_GEN_NOT_INITIALIZED`
 * docs: fix image links in the `README.md` file
 
 ## Version 1.3.8
+
 * fix(tester): fix the relative paths of various files in the tester service. The configuration now assumes that the working directory is the root of the tester package instead of the repository itself
 * build(npm): update npm dependencies to their latest versions
 * docs: fix some outdated information in the `README.md` file and add some more details
 
 ## Version 1.3.7
+
 * feat(exceptions): add new exception code `E_SEC_UNRECOGNIZED_AUTH_METHOD`
 * fix(config): fix potential issue with `TI_GCLOUD_ENABLED` parsing as boolean
 * docs: adjust some of the JSDoc descriptions and definitions
 
 ## Version 1.3.6
+
 * feat(exceptions): add new exception code `E_GEN_INVALID_ARGUMENT_TYPE`
 * feat(exceptions): add public enum with all HTTP codes exported as `httpCode` and typedef `TiHttpCode`. Use it as the type for the `httpCode` exception property
 * feat(tools): add `description` property to enum objects
@@ -37,19 +57,23 @@ This document will contain the list of changes made to the framework. The format
 * build(npm)!: bump the minimum supported Node.js version to 18.0.0
 
 ## Version 1.3.5
+
 * fix(redis integration): fix a duplicated log entry on connection ready event if multiple observers are registered
 * feat(service caller)!: change log level of error result in `process` method from `ERROR` to `DEBUG`. Implementers are expected to handle this and decide if the error should be propagated further or not
 * docs: update and fix various issues with the `README.md` file
 
 ## Version 1.3.4
+
 * fix(service instance): fix the way `ServiceConfiguration` is propagated via child classes and remove unnecessary defaults. Also update the relevant JSDoc
 
 ## Version 1.3.3
+
 * feat(exceptions): add new parameter `includeData` to `Exception.asJSON` method which allows the exclusion of the data parameter from the returned JSON
 * feat(exceptions): remove several excessive exception codes that were unlikely to be used
 * fix(localization): add several missing exception labels
 
 ## Version 1.3.2
+
 * feat(exceptions): add a set of new exception codes for the needs of any wrapping `web-server` standard communication
 * feat(exception)!: change the default prefix path for exception labels to `system.exceptions.`
 * feat(localization): add an Enum list of all language codes based on ISO 639-1 standard
@@ -63,6 +87,7 @@ This document will contain the list of changes made to the framework. The format
 * fix(auditing): fix a potential problem with setting the log entry reporter from an ENV variable; instead, the system will now use the `ServiceInstance.instanceID` property
 
 ## Version 1.3.1
+
 * feat(service caller): refactor the entire service call execution flow for clarity and better performance
 * feat(service caller): create a new private class `ServiceCallProcessor` to handle individual service calls in a contained scope
 * feat(message observer): add new property `priority` to the message observer class. It is used to determine the order in which the observers are notified about the messages
@@ -73,6 +98,7 @@ This document will contain the list of changes made to the framework. The format
 * fix(redis integration): fix an issue which was setting the client status to `DISCONNECTED` during a normal shut down procedure
 
 ## Version 1.3.0
+
 * feat(redis integration)!: change `reconnectOnError` behavior to also resubmit the failed command in case the error was of type `READONLY`
 * feat(redis integration): improve the reliability and usage of the event notification mechanism for connection observers
 * feat(redis integration): implement listener to the `end` event on Redis connection to capture when connection can no longer be recovered
@@ -86,25 +112,31 @@ This document will contain the list of changes made to the framework. The format
 * fix(redis integration): fix broken event propagation on `disrupted` events to some connection observers
 
 ## Version 1.2.5
+
 * feat(cache): extend method `expireValue` to work with has set fields as well
 
 ## 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
 * fix(default message sender): add missing initialization of the memory cache on enable
@@ -117,21 +149,25 @@ This document will contain the list of changes made to the framework. The format
 * fix(service executor)!: change the individual service registration process to ensure service registration does actually happen before the service provider finishes its initialization
 
 ## Version 1.1.10
+
 * fix(cache): fix redis client creation sequence. It is now created inside the constructor as intended. It still needs to be initialized explicitly using the `initialize` method.
 
 ## Version 1.1.9
+
 * feat(redis integration)!: change the way the `redis` client is initialized. Instead of happening automatically on class instantiation, it is now initialized on demand using the `initialize` method.
 * feat(cache): change the way the main cache instance is initialized in compliance with the new redis integration
 * feat(message memory cache)!: change the way the message memory cache is initialized in compliance with the new redis integration. The `initialize` method needs to be called explicitly to initialize the cache instance before it can be used.
 * fix(message dispatcher): fix the way the `messageExchange` is initialized in the `MessageDispatcher` class (was not returning a promise)
 
 ## Version 1.1.8
+
 * feat(auditing): change export of the singleton class in an `instance` variable for consistency and clarity
 * feat(message dispatcher): change export of the singleton class in an `instance` variable for consistency and clarity
 * feat(cache): change export of the singleton class in an `instance` variable for consistency and clarity
 * feat(service executor): implement service registration retry policy
 
 ## Version 1.1.7
+
 * feat(start instance): add support for the detection of `SIGBREAK` events and graceful shutdown on Windows
 * feat(service instance)!: prevent the initialization of multiple `ServiceInstance` within the same process
 * feat(message tracer)!: covert to singleton instance and add initialization method
@@ -141,6 +177,7 @@ This document will contain the list of changes made to the framework. The format
 * fix(redis integration): update links to official commands documentation
 
 ## Version 1.1.6
+
 * feat(start instance): add fail-fast mode as default behavior on promise unhandled rejections
 * feat(start instance): implement functionality to derive safe default service domain name when none is provided in the configuration
 * feat(config): add support for new ENV variable `TI_FAIL_FAST_ON_UNHANDLED_OFF` that controls the fail-fast mode

package/README.md

@@ -544,4 +544,6 @@ The following is an example of a custom localization file. The names in brackets
 }
 ```
 
-The individual languages are specified with a two-letter code according to ISO 639-1. 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.
+The individual languages are specified with a two-letter code according to ISO 639-1. 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.
+
+If you want to localize the system labels of the framework, you can do so by providing a custom localization file with the same structure as the default one but containing only the languages you want to add. For example, the default English label for `E_UNKNOWN_ERROR` is found in JSON path `system.exceptions.0.en`. To add an entry for German, your file needs to contain a `system.exceptions.0.de` property. The localization module will handle the rest. You can use the same approach to modify the existing English labels as well. The full list of system labels is found in the `bin/localization/labels.json` file. Avoid modifying the default file since it might get overwritten by future updates.

package/bin/localization/labels.json

@@ -70,6 +70,9 @@
       "3007": {
         "en": "The message exchange is irrevocably broken and cannot be used any longer."
       },
+      "3008": {
+        "en": "The execution of a service reported a failure. This might be a business logic error or a system error."
+      },
       "3010": {
         "en": "Connection retry attempts exceeded the configured limit."
       },

package/bin/start-instance.js

@@ -121,8 +121,6 @@ process.on( "uncaughtException", ( error ) => {
 
 // Start the instance:
 try {
-    logger.log( `Starting new instance of type '${ process.env.TI_INSTANCE_NAME }' with instance ID '${ process.env.TI_INSTANCE_ID }'.`, logger.logSeverity.NOTICE );
-
     const serviceConstructor = require( path.join( process.cwd(), process.env.TI_INSTANCE_CLASS ) );
     const serviceConfigPath = process.env.TI_INSTANCE_CONFIG;
     /** @type ServiceConfiguration */
@@ -144,6 +142,7 @@ try {
     };
 
     if ( mainInstance.isServiceInstance ) {
+        logger.log( `Starting new instance of type '${ process.env.TI_INSTANCE_NAME }' with instance ID '${ process.env.TI_INSTANCE_ID }'.`, logger.logSeverity.NOTICE );
         mainInstance.start().catch( ( error ) => {
             logger.log( `Error detected during instance '${ process.env.TI_INSTANCE_ID }' startup!`, logger.logSeverity.ALERT, error );
             setImmediate( () => process.exit( 1 ) );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ti-engine/core",
-  "version": "1.3.10",
+  "version": "1.3.12",
   "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.",
   "keywords": [
     "microservices",
@@ -59,7 +59,7 @@
   "dependencies": {
     "@dotenvx/dotenvx": "^1.51.0",
     "blake2": "^5.0.0",
-    "ioredis": "^5.8.0",
+    "ioredis": "^5.8.2",
     "lodash": "^4.17.21",
     "node-schedule": "^2.1.1"
   },

package/utils/config.js

@@ -185,7 +185,7 @@ if ( tools.toBool( process.env.TI_GCLOUD_ENABLED ) === true && settings.gcloudIn
 settings.operationMode = process.env.NODE_ENV || settings.operationMode;
 
 // Prevent further modifications to the settings object:
-Object.freeze( settings );
+tools.deepFreeze( settings );
 
 /**
  * A standard getter method for fetching a setting.

package/utils/exceptions.js

@@ -43,6 +43,7 @@ const exceptionCodeEnum = tools.enum( {
     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_MESSAGE_EXCHANGE_BROKEN: [ 3007, "message exchange broken", "The message exchange is irrevocably broken and cannot be used any longer." ],
+    E_COM_SERVICE_EXEC_FAILED: [ 3008, "service exec failed", "The execution of a service reported a failure. This might be a business logic error or a system error." ],
     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." ],

package/utils/localization.js

@@ -245,12 +245,7 @@ module.exports.localizationLanguage = localizationLanguageEnum;
  * @typedef {Object<string, TiLocalizedLabel | TiLabelsTree>} TiLabelsTree
  */
 
-/**
- * @typedef {Object} TiLabels
- * @property {TiLabelsTree} labels
- */
-
-/** @type {TiLabels} */
+/** @type {TiLabelsTree} */
 const labels = require( "#labels" );
 
 // Load any custom labels defined in the configuration:
@@ -264,7 +259,7 @@ if ( labelsPaths && _.isArray( labelsPaths ) && labelsPaths.length > 0 ) {
 }
 
 // Prevent further modifications to the TiLabels object:
-Object.freeze( labels );
+tools.deepFreeze( labels );
 
 /**
  * Used to return the textual value for a label based on the current system language by default or the specified language code if provided.
@@ -277,4 +272,43 @@ Object.freeze( labels );
  */
 module.exports.getLabel = ( label, language ) => {
     return _.get( labels, label + "." + ( ( language ) ? language : config.getSetting( config.setting.LOCALIZATION_LANGUAGE ) ), defaultEmptyLabel );
+};
+
+const labelsCacheByLanguage = new Map();
+
+/**
+ * Used to return the entire labels tree.
+ * <br/>
+ * NOTE: The result will be a modified copy of the label tree that has no "language" end-nodes and keeps only the appropriate labels for the requested language.
+ * For example, if the original JSON path is "path.to.label.language", the returned path will be just "path.to.label" corresponding to the text label.
+ *
+ * @method
+ * @param {TiLocalizationLanguage} [language] The language code to use for the lookup. If not provided, the current system language will be used.
+ * @returns {TiLabelsTree}
+ * @public
+ */
+module.exports.getAllLabels = ( language ) => {
+    const usedLanguage = language || config.getSetting( config.setting.LOCALIZATION_LANGUAGE );
+
+    if ( labelsCacheByLanguage.has( usedLanguage ) ) {
+        return labelsCacheByLanguage.get( usedLanguage );
+    } else {
+        const labelsByLanguage = _.cloneDeepWith( labels, ( value ) => {
+            if ( _.isPlainObject( value ) ) {
+                const values = Object.values( value );
+                const isLeaf = values.length > 0 && values.every( v => _.isString( v ) || _.isNil( v ) );
+                if ( isLeaf ) {
+                    // Return only the desired language or default placeholder if missing:
+                    return _.get( value, usedLanguage, defaultEmptyLabel );
+                }
+            } else {
+                // Return undefined to let lodash handle default deep cloning for non-leaves:
+                return undefined;
+            }
+        } );
+
+        tools.deepFreeze( labelsByLanguage );
+        labelsCacheByLanguage.set( usedLanguage, labelsByLanguage );
+        return labelsByLanguage;
+    }
 };

package/utils/tools.js

@@ -35,6 +35,27 @@ module.exports.getUUID = () => {
     return crypto.randomUUID( { disableEntropyCache: true } );
 };
 
+/**
+ * Used to deep-freeze an object.
+ *
+ * @method
+ * @param {Object} object
+ * @param {WeakSet} [seen]
+ * @return {Object}
+ * @public
+ */
+module.exports.deepFreeze = ( object, seen = new WeakSet() ) => {
+    if ( object === null || typeof object !== "object" || seen.has( object ) ) {
+        return object;
+    } else {
+        seen.add( object );
+        _.forOwn( object, ( value ) => {
+            module.exports.deepFreeze( value, seen );
+        } );
+        return Object.freeze( object );
+    }
+};
+
 /**
  * Used to create a custom Enum list.
  *
@@ -199,6 +220,24 @@ module.exports.toBool = ( value ) => {
     return result;
 };
 
+/**
+ * Used to fetch only the unique values from the provided array.
+ * <br/>
+ * Note: For objects and arrays, uniqueness is determined by reference equality. Primitives are compared by their value.
+ *
+ * @method
+ * @param {Array} array
+ * @returns {Array}
+ * @throws {TypeError} If the provided parameter is not an array
+ * @public
+ */
+module.exports.arrayUniques = ( array ) => {
+    if ( !Array.isArray( array ) ) {
+        throw new TypeError( "Expected an array" );
+    }
+    return [ ...new Set( array ) ];
+};
+
 /**
  * Will return a UTC date string in format YYYY-MM-DD from the provided date.
  *