@ti-engine/core 1.3.1 → 1.3.5

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