@ti-engine/core 1.3.1 → 1.3.3

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 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.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
+* feat(localization): add an option to the `getLabel` method to provide the language code to use for localization. If not provided, the system will use the language code from the `localization.language` setting
+* feat(localization)!: change the default structure of system labels from `labels.general.[...]` to `system.[...]`
+* refactor(localization): add typedefs and JSDoc structure for the objects used in localization
+* refactor(exceptions): refactor and fix various JSDoc descriptions
+* refactor(auditing): change the type name of `LogEntry` to `TiLogEntry` and fix some JSDoc descriptions
+* fix(exceptions): fix an issue which caused the exception to disregard the `description` value sent in the constructor and use the default one instead
+* fix(config): fix an issue with the `TI_LOCALIZATION_LABELS_PATH` variable not respecting that the underlying setting expected an array. Now it is expected to be a single path and it will be wrapped into an array automatically
+* 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

package/README.md

@@ -397,7 +397,7 @@ GCLOUD_PROJECT_ID (Alpha)
 LOCALIZATION_LABELS_PATH
 : JSON path `localization.labelsPath`, type `Array<string>`, default `[]`
 : ENV variable `TI_LOCALIZATION_LABELS_PATH`
-: This setting holds a list of paths to custom `.json` files containing additional localization information. By default, the framework also provides such a file with english texts that can be customized further. All additional JSONs in these files have to follow the rules and structure of the `localization` module.
+: This setting holds a list of paths to custom `.json` files containing additional localization information. By default, the framework also provides such a file with english texts that can be customized further. All additional JSONs in these files have to follow the rules and structure of the `localization` module. The ENV variable currently supports providing only a single custom path.
 
 LOCALIZATION_LANGUAGE
 : JSON path `localization.language`, type `string`, default `en`
@@ -501,20 +501,18 @@ OPERATION_MODE
 
 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):
+The following is an example of a custom localization file. The names in brackets can be replaced with your own values. The depth of the three is unlimited and can be used to create a hierarchy of labels.
 
 ```json
 {
-  "labels": {
-    "[category]": {
-      "[sub-category]": {
-        "[label]": {
-          "en": "[localized label text]"
-        }
+  "[category]": {
+    "[sub-category]": {
+      "[label]": {
+        "[language code]": "[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.
+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.

package/bin/localization/labels.json

@@ -1,65 +1,99 @@
-{
-  "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."
-        }
-      }
-    }
-  }
+{
+  "system": {
+    "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."
+      },
+      "3006": {
+        "en": "The message receiver instance is currently unavailable."
+      },
+      "3007": {
+        "en": "The message exchange is irrevocably broken and cannot be used any longer."
+      },
+      "3010": {
+        "en": "Connection retry attempts exceeded the configured limit."
+      },
+      "4000": {
+        "en": "The request method is not recognized or not supported."
+      },
+      "4001": {
+        "en": "The request URI is not recognized or not supported."
+      },
+      "4002": {
+        "en": "The request body is not recognized or not supported."
+      },
+      "4003": {
+        "en": "The request query is not recognized or not supported."
+      },
+      "4004": {
+        "en": "The request headers are not recognized or not supported."
+      },
+      "4005": {
+        "en": "The request parameters are not recognized or not supported."
+      },
+      "4006": {
+        "en": "The request format is not recognized or not supported."
+      },
+      "4007": {
+        "en": "The request content type is not recognized or not supported."
+      },
+      "4008": {
+        "en": "The request content length is not recognized or not supported."
+      },
+      "4009": {
+        "en": "The request content encoding is not recognized or not supported."
+      }
+    }
+  }
 }

package/components/auditing.js

@@ -11,9 +11,10 @@ const tools = require( "#tools" );
 const logger = require( "#logger" );
 const config = require( "#config" );
 const gcloud = require( "#gcloud-integration" );
+const ServiceInstance = require( "#service-instance" );
 
 /**
- * @typedef {Object} LogEntry
+ * @typedef {Object} TiLogEntry
  * @property {string} _id Unique identifier that can be used to identify the document in a NoSQL database.
  * @property {TiLogSeverity} severity The log severity level.
  * @property {string} thread The categorization of the log message.
@@ -59,19 +60,19 @@ class Auditing {
      */
     log( message, severity = logger.logSeverity.DEFAULT, thread = "main", data = {} ) {
         try {
-            // log entries bellow the min allowed level will be ignored:
+            // Log entries below the minimum allowed level will be directly ignored:
             if ( severity >= config.getSetting( config.setting.AUDITING_LOG_MIN_LEVEL ) ) {
-                // obscure any passwords that might have landed in the data object;
-                // also make sure to convert a potential Error object to a JSON:
+                // Obscure any passwords that might have landed in the data object;
+                // Also make sure to convert a potential Error object to a JSON:
                 let copyOfData = ( config.getSetting( config.setting.AUDITING_LOG_DETAILS ) === true ) ? _.cloneDeep( data ) : undefined;
                 let logEntry = Auditing.#createLogEntry( severity, thread, message, copyOfData );
 
-                // make sure there is a console available:
+                // Make sure there is a console available (especially important for Cloud or containerized environments):
                 if ( config.getSetting( config.setting.AUDITING_LOG_CONSOLE_ENABLED ) === true && console ) {
                     Auditing.#logToConsole( logEntry );
                 }
 
-                // if this is an actual error, then send it to GCloud error reporting system as well:
+                // If this is an actual error, then send it to GCloud error reporting system as well:
                 if ( logEntry.severity >= logger.logSeverity.WARNING && data instanceof Error && gcloud.isEnabled() ) {
                     gcloud.reportError( data );
                 }
@@ -91,14 +92,14 @@ class Auditing {
      * @param {string} thread
      * @param {string} message
      * @param {Object} data
-     * @returns {LogEntry}
+     * @returns {TiLogEntry}
      * @private
      */
     static #createLogEntry( severity, thread, message, data ) {
         let currentDate = new Date();
         let logDate = tools.getUTCDateString( currentDate );
         let logTime = tools.getUTCTimeString( currentDate, true );
-        let reporter = process.env.TI_INSTANCE_ID;
+        let reporter = ServiceInstance.instanceID;
 
         return {
             _id: `${ logDate }-${ logTime }-${ thread }-${ reporter }-${ logger.getSeverityName( severity ) }-${ tools.getUUID() }`,
@@ -112,13 +113,13 @@ class Auditing {
     }
 
     /**
-     * Used to write the log entries to the system console (i.e. STD OUT and STD ERR).
+     * Used to write the log entries to the system console (i.e., STD OUT and STD ERR).
      * <br/>
      * NOTE: There was an issue in previous Node versions with console that can crash the application if the number of
-     *    outputs exceeds several thousands per second. To be monitored and adjusted as necessary!
+     * outputs exceeds several thousands per second. To be monitored and adjusted as necessary!
      *
      * @method
-     * @param {LogEntry} logEntry
+     * @param {TiLogEntry} logEntry
      * @private
      */
     static #logToConsole( logEntry ) {
@@ -140,7 +141,7 @@ class Auditing {
      * Used to format a log entry for the Node console.
      *
      * @method
-     * @param {LogEntry} logEntry
+     * @param {TiLogEntry} logEntry
      * @returns {string}
      * @private
      */
@@ -153,7 +154,7 @@ class Auditing {
      * Used to format a log entry data payload for the Node console.
      *
      * @method
-     * @param {LogEntry} logEntry
+     * @param {TiLogEntry} logEntry
      * @returns {string}
      * @private
      */

package/components/service-caller.js

@@ -48,7 +48,7 @@ const messageDispatcher = require( "#message-dispatcher" );
 
 /**
  * @typedef {Object} ServiceCallResult
- * @property {Object|undefined} exception If there was exception during the service call processing, it will be set here. Otherwise, it will be 'undefined'.
+ * @property {Exception|undefined} exception If there was exception during the service call processing, it will be set here. Otherwise, it will be 'undefined'.
  * @property {boolean} isSuccessful A flag indicating if this service call can be considered successful or not.
  * @property {Object|string|undefined} payload The payload containing the results from the service call processing. If a string, it is ID of the payload in the memory cache instead.
  */
@@ -293,7 +293,7 @@ class ServiceCaller extends MessageObserver {
      * @public
      */
     executeServiceCall( serviceAddress, serviceParams, serviceExecContext ) {
-        return new Promise( ( resolve, reject ) => {
+        return new Promise( ( resolve ) => {
             let processor = new ServiceCallProcessor( serviceAddress, serviceParams, serviceExecContext );
             this.#addProcessor( processor.messageID, processor );
             processor.process().then( ( serviceCallResult ) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ti-engine/core",
-  "version": "1.3.1",
+  "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/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." ],
@@ -39,16 +39,18 @@ let 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_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_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." ]
 } );
 
 /**
@@ -56,6 +58,8 @@ let exceptionCodeEnum = tools.enum( {
  */
 module.exports.exceptionCode = exceptionCodeEnum;
 
+const labelPath = "system.exceptions.";
+
 /**
  * Represents an exception.
  *
@@ -84,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 || {};
     }
 
@@ -94,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() {
@@ -105,8 +109,8 @@ class Exception {
     /**
      * Identifier code of the exception type.
      *
-     * @method
-     * @return {TiExceptionCode}
+     * @property
+     * @returns {TiExceptionCode}
      * @public
      */
     get code() {
@@ -116,8 +120,8 @@ class Exception {
     /**
      * HTTP error code if relevant.
      *
-     * @method
-     * @return {number}
+     * @property
+     * @returns {number}
      * @public
      */
     get httpCode() {
@@ -127,7 +131,7 @@ class Exception {
     /**
      * HTTP error code if relevant.
      *
-     * @method
+     * @property
      * @param {number} httpCode
      * @public
      */
@@ -138,8 +142,8 @@ class Exception {
     /**
      * Localized label identifier.
      *
-     * @method
-     * @return {string}
+     * @property
+     * @returns {string}
      * @public
      */
     get label() {
@@ -149,8 +153,8 @@ class Exception {
     /**
      * Description or additional technical information that is NOT localized.
      *
-     * @method
-     * @return {string}
+     * @property
+     * @returns {string}
      * @public
      */
     get description() {
@@ -160,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() {
@@ -171,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
      */
@@ -183,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
         };
     }
 }
@@ -203,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
@@ -226,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 );
     }
 
@@ -243,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
  */

package/utils/localization.js

@@ -6,38 +6,275 @@
  * You should have received a copy of the GNU General Public License along with this program. If not, see <https://www.gnu.org/licenses/>.
 */
 
+const path = require( "node:path" );
 const _ = require( "lodash" );
-const path = require( "path" );
-const labels = require( "#labels" );
 const config = require( "#config" );
-const logger = require( '#logger' );
-const exceptions = require( '#exceptions' );
+const tools = require( "#tools" );
 
 const defaultEmptyLabel = "!!! label not found !!!";
 
+/**
+ * Enum for defining a localization language based on the ISO 639-1 language code.
+ *
+ * @readonly
+ * @enum {string}
+ */
+const localizationLanguageEnum = tools.enum( {
+    // A:
+    ABKHAZIAN: [ "ab", "Abkhazian", "Abkhazian" ],
+    AFAR: [ "aa", "Afar", "Afar" ],
+    AFRIKAANS: [ "af", "Afrikaans", "Afrikaans" ],
+    AKAN: [ "ak", "Akan", "Akan" ],
+    ALBANIAN: [ "sq", "Albanian", "Albanian" ],
+    AMHARIC: [ "am", "Amharic", "Amharic" ],
+    ARABIC: [ "ar", "Arabic", "Arabic" ],
+    ARAGONESE: [ "an", "Aragonese", "Aragonese" ],
+    ARMENIAN: [ "hy", "Armenian", "Armenian" ],
+    ASSAMESE: [ "as", "Assamese", "Assamese" ],
+    AVARIC: [ "av", "Avaric", "Avaric" ],
+    AVESTAN: [ "ae", "Avestan", "Avestan" ],
+    AYMARA: [ "ay", "Aymara", "Aymara" ],
+    AZERBAIJANI: [ "az", "Azerbaijani", "Azerbaijani" ],
+    // B:
+    BAMBARA: [ "bm", "Bambara", "Bambara" ],
+    BASHKIR: [ "ba", "Bashkir", "Bashkir" ],
+    BASQUE: [ "eu", "Basque", "Basque" ],
+    BELARUSIAN: [ "be", "Belarusian", "Belarusian" ],
+    BENGALI: [ "bn", "Bengali", "Bengali" ],
+    BIHARI_LANGUAGES: [ "bh", "Bihari languages", "Bihari languages" ],
+    BISLAMA: [ "bi", "Bislama", "Bislama" ],
+    BOSNIAN: [ "bs", "Bosnian", "Bosnian" ],
+    BRETON: [ "br", "Breton", "Breton" ],
+    BULGARIAN: [ "bg", "Bulgarian", "Bulgarian" ],
+    BURMESE: [ "my", "Burmese", "Burmese" ],
+    // C:
+    CATALAN: [ "ca", "Catalan", "Catalan" ],
+    CENTRAL_KHMER: [ "km", "Central Khmer", "Central Khmer" ],
+    CHAMORRO: [ "ch", "Chamorro", "Chamorro" ],
+    CHECHEN: [ "ce", "Chechen", "Chechen" ],
+    CHICHEWA: [ "ny", "Chichewa", "Chichewa" ],
+    CHINESE: [ "zh", "Chinese", "Chinese" ],
+    CHURCH_SLAVIC: [ "cu", "Church Slavic", "Church Slavic" ],
+    CHUVASH: [ "cv", "Chuvash", "Chuvash" ],
+    CORNISH: [ "kw", "Cornish", "Cornish" ],
+    CORSICAN: [ "co", "Corsican", "Corsican" ],
+    CREE: [ "cr", "Cree", "Cree" ],
+    CROATIAN: [ "hr", "Croatian", "Croatian" ],
+    CZECH: [ "cs", "Czech", "Czech" ],
+    // D:
+    DANISH: [ "da", "Danish", "Danish" ],
+    DIVEHI: [ "dv", "Divehi", "Divehi" ],
+    DUTCH: [ "nl", "Dutch", "Dutch" ],
+    DZONGKHA: [ "dz", "Dzongkha", "Dzongkha" ],
+    // E:
+    ENGLISH: [ "en", "English", "English" ],
+    ESPERANTO: [ "eo", "Esperanto", "Esperanto" ],
+    ESTONIAN: [ "et", "Estonian", "Estonian" ],
+    EWE: [ "ee", "Ewe", "Ewe" ],
+    // F:
+    FAROESE: [ "fo", "Faroese", "Faroese" ],
+    FIJIAN: [ "fj", "Fijian", "Fijian" ],
+    FINNISH: [ "fi", "Finnish", "Finnish" ],
+    FRENCH: [ "fr", "French", "French" ],
+    FULAH: [ "ff", "Fulah", "Fulah" ],
+    FRISIAN_WESTERN: [ "fy", "Western Frisian", "Western Frisian" ],
+    // G:
+    GAELIC_SCOTTISH: [ "gd", "Scottish Gaelic", "Scottish Gaelic" ],
+    GALICIAN: [ "gl", "Galician", "Galician" ],
+    GANDA: [ "lg", "Ganda", "Ganda" ],
+    GEORGIAN: [ "ka", "Georgian", "Georgian" ],
+    GERMAN: [ "de", "German", "German" ],
+    GREEK_MODERN: [ "el", "Greek, Modern (1453–)", "Greek, Modern (1453–)" ],
+    GUARANI: [ "gn", "Guarani", "Guarani" ],
+    GUJARATI: [ "gu", "Gujarati", "Gujarati" ],
+    // H:
+    HAITIAN: [ "ht", "Haitian", "Haitian" ],
+    HAUSA: [ "ha", "Hausa", "Hausa" ],
+    HEBREW: [ "he", "Hebrew", "Hebrew" ],
+    HERERO: [ "hz", "Herero", "Herero" ],
+    HINDI: [ "hi", "Hindi", "Hindi" ],
+    HIRI_MOTU: [ "ho", "Hiri Motu", "Hiri Motu" ],
+    HUNGARIAN: [ "hu", "Hungarian", "Hungarian" ],
+    // I:
+    ICELANDIC: [ "is", "Icelandic", "Icelandic" ],
+    IDO: [ "io", "Ido", "Ido" ],
+    IGBO: [ "ig", "Igbo", "Igbo" ],
+    INTERLINGUA: [ "ia", "Interlingua", "Interlingua" ],
+    INTERLINGUE: [ "ie", "Interlingue", "Interlingue" ],
+    INDONESIAN: [ "id", "Indonesian", "Indonesian" ],
+    INUKTITUT: [ "iu", "Inuktitut", "Inuktitut" ],
+    INUPIAQ: [ "ik", "Inupiaq", "Inupiaq" ],
+    IRISH: [ "ga", "Irish", "Irish" ],
+    ITALIAN: [ "it", "Italian", "Italian" ],
+    // J:
+    JAPANESE: [ "ja", "Japanese", "Japanese" ],
+    JAVANESE: [ "jv", "Javanese", "Javanese" ],
+    // K:
+    KALAALLISUT: [ "kl", "Kalaallisut", "Kalaallisut" ],
+    KANNADA: [ "kn", "Kannada", "Kannada" ],
+    KASHMIRI: [ "ks", "Kashmiri", "Kashmiri" ],
+    KAZAKH: [ "kk", "Kazakh", "Kazakh" ],
+    KIKUYU: [ "ki", "Kikuyu", "Kikuyu" ],
+    KINYARWANDA: [ "rw", "Kinyarwanda", "Kinyarwanda" ],
+    KIRGHIZ: [ "ky", "Kirghiz", "Kirghiz" ],
+    KOMI: [ "kv", "Komi", "Komi" ],
+    KONGO: [ "kg", "Kongo", "Kongo" ],
+    KOREAN: [ "ko", "Korean", "Korean" ],
+    KUANYAMA: [ "kj", "Kuanyama", "Kuanyama" ],
+    KURDISH: [ "ku", "Kurdish", "Kurdish" ],
+    // L:
+    LAO: [ "lo", "Lao", "Lao" ],
+    LATIN: [ "la", "Latin", "Latin" ],
+    LATVIAN: [ "lv", "Latvian", "Latvian" ],
+    LIMBURGAN: [ "li", "Limburgan", "Limburgan" ],
+    LINGALA: [ "ln", "Lingala", "Lingala" ],
+    LITHUANIAN: [ "lt", "Lithuanian", "Lithuanian" ],
+    LUBA_KATANGA: [ "lu", "Luba-Katanga", "Luba-Katanga" ],
+    LUXEMBOURGISH: [ "lb", "Luxembourgish", "Luxembourgish" ],
+    // M:
+    MACEDONIAN: [ "mk", "Macedonian", "Macedonian" ],
+    MALAGASY: [ "mg", "Malagasy", "Malagasy" ],
+    MALAY: [ "ms", "Malay", "Malay" ],
+    MALAYALAM: [ "ml", "Malayalam", "Malayalam" ],
+    MALTESE: [ "mt", "Maltese", "Maltese" ],
+    MANX: [ "gv", "Manx", "Manx" ],
+    MAORI: [ "mi", "Maori", "Maori" ],
+    MARATHI: [ "mr", "Marathi", "Marathi" ],
+    MARSHALLESE: [ "mh", "Marshallese", "Marshallese" ],
+    MONGOLIAN: [ "mn", "Mongolian", "Mongolian" ],
+    // N:
+    NAURU: [ "na", "Nauru", "Nauru" ],
+    NAVAJO: [ "nv", "Navajo", "Navajo" ],
+    NDEBELE_NORTH: [ "nd", "North Ndebele", "North Ndebele" ],
+    NDEBELE_SOUTH: [ "nr", "South Ndebele", "South Ndebele" ],
+    NDONGA: [ "ng", "Ndonga", "Ndonga" ],
+    NEPALI: [ "ne", "Nepali", "Nepali" ],
+    NORTHERN_SAMI: [ "se", "Northern Sami", "Northern Sami" ],
+    NORWEGIAN: [ "no", "Norwegian", "Norwegian" ],
+    NORWEGIAN_BOKMAL: [ "nb", "Norwegian Bokmål", "Norwegian Bokmål" ],
+    NORWEGIAN_NYNORSK: [ "nn", "Norwegian Nynorsk", "Norwegian Nynorsk" ],
+    // O:
+    OCCITAN: [ "oc", "Occitan", "Occitan" ],
+    OJIBWA: [ "oj", "Ojibwa", "Ojibwa" ],
+    ORIYA: [ "or", "Oriya", "Oriya" ],
+    OROMO: [ "om", "Oromo", "Oromo" ],
+    OSSETIAN: [ "os", "Ossetian", "Ossetian" ],
+    // P:
+    PANJABI: [ "pa", "Panjabi", "Panjabi" ],
+    PALI: [ "pi", "Pali", "Pali" ],
+    PASHTO: [ "ps", "Pashto", "Pashto" ],
+    POLISH: [ "pl", "Polish", "Polish" ],
+    PORTUGUESE: [ "pt", "Portuguese", "Portuguese" ],
+    // Q:
+    QUECHUA: [ "qu", "Quechua", "Quechua" ],
+    // R:
+    ROMANIAN: [ "ro", "Romanian", "Romanian" ],
+    ROMANSH: [ "rm", "Romansh", "Romansh" ],
+    RUNDI: [ "rn", "Rundi", "Rundi" ],
+    RUSSIAN: [ "ru", "Russian", "Russian" ],
+    // S:
+    SANGO: [ "sg", "Sango", "Sango" ],
+    SANSKRIT: [ "sa", "Sanskrit", "Sanskrit" ],
+    SARDINIAN: [ "sc", "Sardinian", "Sardinian" ],
+    SERBIAN: [ "sr", "Serbian", "Serbian" ],
+    SHONA: [ "sn", "Shona", "Shona" ],
+    SINDHI: [ "sd", "Sindhi", "Sindhi" ],
+    SINHALA: [ "si", "Sinhala", "Sinhala" ],
+    SLOVAK: [ "sk", "Slovak", "Slovak" ],
+    SLOVENIAN: [ "sl", "Slovenian", "Slovenian" ],
+    SOMALI: [ "so", "Somali", "Somali" ],
+    SOTHO_SOUTHERN: [ "st", "Southern Sotho", "Southern Sotho" ],
+    SPANISH: [ "es", "Spanish", "Spanish" ],
+    SUNDANESE: [ "su", "Sundanese", "Sundanese" ],
+    SWAHILI: [ "sw", "Swahili", "Swahili" ],
+    SWATI: [ "ss", "Swati", "Swati" ],
+    SWEDISH: [ "sv", "Swedish", "Swedish" ],
+    // T:
+    TAGALOG: [ "tl", "Tagalog", "Tagalog" ],
+    TAHITIAN: [ "ty", "Tahitian", "Tahitian" ],
+    TAJIK: [ "tg", "Tajik", "Tajik" ],
+    TAMIL: [ "ta", "Tamil", "Tamil" ],
+    TATAR: [ "tt", "Tatar", "Tatar" ],
+    TELUGU: [ "te", "Telugu", "Telugu" ],
+    THAI: [ "th", "Thai", "Thai" ],
+    TIBETAN: [ "bo", "Tibetan", "Tibetan" ],
+    TIGRINYA: [ "ti", "Tigrinya", "Tigrinya" ],
+    TONGA: [ "to", "Tonga", "Tonga" ],
+    TSONGA: [ "ts", "Tsonga", "Tsonga" ],
+    TSWANA: [ "tn", "Tswana", "Tswana" ],
+    TURKISH: [ "tr", "Turkish", "Turkish" ],
+    TURKMEN: [ "tk", "Turkmen", "Turkmen" ],
+    TWI: [ "tw", "Twi", "Twi" ],
+    // U:
+    UIGHUR: [ "ug", "Uighur", "Uighur" ],
+    UKRAINIAN: [ "uk", "Ukrainian", "Ukrainian" ],
+    URDU: [ "ur", "Urdu", "Urdu" ],
+    UZBEK: [ "uz", "Uzbek", "Uzbek" ],
+    // V:
+    VENDA: [ "ve", "Venda", "Venda" ],
+    VIETNAMESE: [ "vi", "Vietnamese", "Vietnamese" ],
+    VOLAPUK: [ "vo", "Volapük", "Volapük" ],
+    // W:
+    WALLON: [ "wa", "Walloon", "Walloon" ],
+    WELSH: [ "cy", "Welsh", "Welsh" ],
+    WOLOF: [ "wo", "Wolof", "Wolof" ],
+    // X:
+    XHOSA: [ "xh", "Xhosa", "Xhosa" ],
+    // Y:
+    YIDDISH: [ "yi", "Yiddish", "Yiddish" ],
+    YORUBA: [ "yo", "Yoruba", "Yoruba" ],
+    // Z:
+    ZHUANG: [ "za", "Zhuang", "Zhuang" ],
+    ZULU: [ "zu", "Zulu", "Zulu" ]
+} );
+
+/**
+ * @typedef {string} TiLocalizationLanguage
+ */
+module.exports.localizationLanguage = localizationLanguageEnum;
+
+/**
+ * The key of this object is the language code, and the value is the textual representation of the label.
+ *
+ * @typedef {Object<TiLocalizationLanguage, string>} TiLocalizedLabel
+ */
+
+/**
+ * A nested labels tree where intermediate nodes are objects and leaf nodes are language-to-text maps.
+ *
+ * @typedef {Object<string, TiLocalizedLabel | TiLabelsTree>} TiLabelsTree
+ */
+
+/**
+ * @typedef {Object} TiLabels
+ * @property {TiLabelsTree} labels
+ */
+
+/** @type {TiLabels} */
+const labels = require( "#labels" );
+
 // Load any custom labels defined in the configuration:
-try {
-    const labelsPaths = config.getSetting( config.setting.LOCALIZATION_LABELS_PATH );
+const labelsPaths = config.getSetting( config.setting.LOCALIZATION_LABELS_PATH );
+if ( labelsPaths && _.isArray( labelsPaths ) && labelsPaths.length > 0 ) {
     _.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 TiLabels object:
 Object.freeze( labels );
 
 /**
- * Used to return the textual value for a label based on the current system language.
+ * Used to return the textual value for a label based on the current system language by default or the specified language code if provided.
  *
  * @method
  * @param {string} label This should be a dot-separated JSON path string.
+ * @param {TiLocalizationLanguage} [language] The language code to use for the lookup. If not provided, the current system language will be used.
  * @returns {string}
  * @public
  */
-module.exports.getLabel = ( label ) => {
-    return _.get( labels, label + "." + config.getSetting( config.setting.LOCALIZATION_LANGUAGE ), defaultEmptyLabel );
+module.exports.getLabel = ( label, language ) => {
+    return _.get( labels, label + "." + ( ( language ) ? language : config.getSetting( config.setting.LOCALIZATION_LANGUAGE ) ), defaultEmptyLabel );
 };

package/utils/logger.js

@@ -17,7 +17,7 @@ const localization = require( "#localization" );
  * @readonly
  * @enum {number}
  */
-let logSeverityEnum = tools.enum( {
+const logSeverityEnum = tools.enum( {
     DEFAULT: [ 0, "default", "The log entry has no assigned severity level." ],
     DEBUG: [ 100, "debug", "Debug or trace information." ],
     INFO: [ 200, "info", "Routine information, such as ongoing status or performance." ],
@@ -46,7 +46,7 @@ module.exports.getSeverityName = ( severity ) => {
 };
 
 /**
- * Used to extract information from an Exception and convert it to loggable data object.
+ * Used to extract information from an Exception and convert it to a loggable data object.
  *
  * @method
  * @param {Exception} exception
@@ -62,7 +62,7 @@ const exceptionToLog = ( exception ) => {
 };
 
 /**
- * Used to generate and store a log entry in the active cache.
+ * Used to generate and store a new log entry via the active {@link Auditing} instance.
  *
  * @method
  * @param {string} message The primary log message.

package/utils/tools.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/>.
@@ -8,7 +8,7 @@
 
 const _ = require( "lodash" );
 const fs = require( "fs-extra" );
-const crypto = require( "crypto" );
+const crypto = require( "node:crypto" );
 
 /**
  * @typedef {Object} TiEnumValue