@ti-engine/core 1.3.13 → 1.4.1

package/utils/config.js

@@ -1,201 +1,104 @@
-/*
- * 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-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/>.
-*/
-
-const _ = require( "lodash" );
-const tools = require( "#tools" );
-
-/**
- * @typedef {string} EnvironmentVariable
- */
-
-/**
- * @typedef {NodeJS.Process} Environment
- * @property {ProcessEnv} env
- * @property {EnvironmentVariable} env.TI_GCLOUD_API_KEY
- * @property {EnvironmentVariable} env.TI_GCLOUD_ENABLED
- * @property {EnvironmentVariable} env.TI_GCLOUD_PROJECT_ID
- * @property {EnvironmentVariable} env.TI_INSTANCE_CLASS
- * @property {EnvironmentVariable} env.TI_INSTANCE_CONFIG
- * @property {EnvironmentVariable} env.TI_INSTANCE_ID
- * @property {EnvironmentVariable} env.TI_INSTANCE_NAME
- * @property {EnvironmentVariable} env.TI_AUDITING_LOG_CONSOLE_ENABLED
- * @property {EnvironmentVariable} env.TI_AUDITING_LOG_DETAILS
- * @property {EnvironmentVariable} env.TI_AUDITING_LOG_MIN_LEVEL
- * @property {EnvironmentVariable} env.TI_AUDITING_LOG_USES_JSON
- * @property {EnvironmentVariable} env.TI_LOCALIZATION_LABELS_PATH
- * @property {EnvironmentVariable} env.TI_LOCALIZATION_LANGUAGE
- * @property {EnvironmentVariable} env.TI_MEMORY_CACHE_AUTH_KEY
- * @property {EnvironmentVariable} env.TI_MEMORY_CACHE_REDIS_DB
- * @property {EnvironmentVariable} env.TI_MEMORY_CACHE_REDIS_HOST
- * @property {EnvironmentVariable} env.TI_MEMORY_CACHE_REDIS_PORT
- * @property {EnvironmentVariable} env.TI_MEMORY_CACHE_RETRY_MAX_ATTEMPTS
- * @property {EnvironmentVariable} env.TI_MEMORY_CACHE_RETRY_MAX_INTERVAL
- * @property {EnvironmentVariable} env.TI_MEMORY_CACHE_USER
- * @property {EnvironmentVariable} env.TI_MESSAGE_EXCHANGE_SECURITY_HASH_ENABLED
- * @property {EnvironmentVariable} env.TI_MESSAGE_EXCHANGE_SECURITY_HASH_KEY
- * @property {EnvironmentVariable} env.TI_MESSAGE_EXCHANGE_TRACE_LOG_ENABLED
- */
-
-/**
- * @typedef {string} CronString
- */
-
-/**
- * @typedef {Object} SettingsMain
- * @property {SettingsAuditing} auditing
- * @property {SettingsGcloudIntegration} gcloudIntegration
- * @property {SettingsLocalization} localization
- * @property {SettingsMemoryCache} memoryCache
- * @property {SettingsMessageExchange} messageExchange
- * @property {SettingsServiceConfig} serviceConfig
- * @property {string} operationMode
- */
-
-/**
- * @typedef {Object} SettingsAuditing
- * @property {boolean} logConsoleEnabled
- * @property {boolean} logDetails
- * @property {TiLogSeverity} logMinLevel
- * @property {boolean} logUsesJSON
- */
-
-/**
- * @typedef {Object} SettingsGcloudIntegration
- * @property {string} apiKey
- * @property {string} projectID
- */
-
-/**
- * @typedef {Object} SettingsLocalization
- * @property {Array<string>} labelsPath
- * @property {TiLocalizationLanguage} language
- */
-
-/**
- * @typedef {Object} SettingsMemoryCache
- * @property {string} authKey
- * @property {number} redisDB
- * @property {string} redisHost
- * @property {number} redisPort
- * @property {number} retryMaxAttempts
- * @property {number} retryMaxInterval
- * @property {string} user
- */
-
-/**
- * @typedef {Object} SettingsMessageExchange
- * @property {string} messageQueuePrefix
- * @property {string} messageStore
- * @property {boolean} securityHashEnabled
- * @property {string} securityHashKey
- * @property {number} traceExpirationTime
- * @property {boolean} traceLogEnabled
- * @property {string} traceRepository
- */
-
-/**
- * @typedef {Object} SettingsServiceConfig
- * @property {number} executionTimeout
- * @property {string} healthCheckAddress
- * @property {CronString} healthCheckInterval
- * @property {number} healthCheckTimeout
- * @property {string} serviceRegistryAddress
- */
-
-/**
- * Enum for listing all system settings.
- *
- * @readonly
- * @enum {string} Keys of this ENUM are strings.
- * @typedef {string} TiSetting
- */
-const settingsEnum = tools.enum( {
-    AUDITING_LOG_CONSOLE_ENABLED: [ "auditing.logConsoleEnabled", "logConsoleEnabled", "" ],
-    AUDITING_LOG_DETAILS: [ "auditing.logDetails", "logDetails", "" ],
-    AUDITING_LOG_MIN_LEVEL: [ "auditing.logMinLevel", "logMinLevel", "" ],
-    AUDITING_LOG_USES_JSON: [ "auditing.logUsesJSON", "logUsesJSON", "" ],
-    GCLOUD_API_KEY: [ "gcloudIntegration.apiKey", "apiKey", "" ],
-    GCLOUD_PROJECT_ID: [ "gcloudIntegration.projectID", "projectID", "" ],
-    LOCALIZATION_LABELS_PATH: [ "localization.labelsPath", "labelsPath", "" ],
-    LOCALIZATION_LANGUAGE: [ "localization.language", "language", "" ],
-    MEMORY_CACHE_AUTH_KEY: [ "memoryCache.authKey", "authKey", "" ],
-    MEMORY_CACHE_REDIS_DB: [ "memoryCache.redisDB", "redisDB", "" ],
-    MEMORY_CACHE_REDIS_HOST: [ "memoryCache.redisHost", "redisHost", "" ],
-    MEMORY_CACHE_REDIS_PORT: [ "memoryCache.redisPort", "redisPort", "" ],
-    MEMORY_CACHE_RETRY_MAX_ATTEMPTS: [ "memoryCache.retryMaxAttempts", "retryMaxAttempts", "" ],
-    MEMORY_CACHE_RETRY_MAX_INTERVAL: [ "memoryCache.retryMaxInterval", "retryMaxInterval", "" ],
-    MEMORY_CACHE_USER: [ "memoryCache.user", "user", "" ],
-    MESSAGE_EXCHANGE_QUEUE_PREFIX: [ "messageExchange.messageQueuePrefix", "messageQueuePrefix", "" ],
-    MESSAGE_EXCHANGE_MESSAGE_STORE: [ "messageExchange.messageStore", "messageStore", "" ],
-    MESSAGE_EXCHANGE_SECURITY_HASH_ENABLED: [ "messageExchange.securityHashEnabled", "securityHashEnabled", "" ],
-    MESSAGE_EXCHANGE_SECURITY_HASH_KEY: [ "messageExchange.securityHashKey", "securityHashKey", "" ],
-    MESSAGE_EXCHANGE_TRACE_EXPIRATION_TIME: [ "messageExchange.traceExpirationTime", "traceExpirationTime", "" ],
-    MESSAGE_EXCHANGE_TRACE_LOG_ENABLED: [ "messageExchange.traceLogEnabled", "traceLogEnabled", "" ],
-    MESSAGE_EXCHANGE_TRACE_REPOSITORY: [ "messageExchange.traceRepository", "traceRepository", "" ],
-    SERVICE_EXECUTION_TIMEOUT: [ "serviceConfig.executionTimeout", "executionTimeout", "" ],
-    SERVICE_HEALTH_CHECK_ADDRESS: [ "serviceConfig.healthCheckAddress", "healthCheckAddress", "" ],
-    SERVICE_HEALTH_CHECK_INTERVAL: [ "serviceConfig.healthCheckInterval", "healthCheckInterval", "" ],
-    SERVICE_HEALTH_CHECK_TIMEOUT: [ "serviceConfig.healthCheckTimeout", "healthCheckTimeout", "" ],
-    SERVICE_REGISTRY_ADDRESS: [ "serviceConfig.serviceRegistryAddress", "serviceRegistryAddress", "" ],
-    OPERATION_MODE: [ "operationMode", "operationMode", "" ]
-} );
-
-module.exports.setting = settingsEnum;
-
-/** @type {SettingsMain} */
-const settings = require( "#settings" );
-
-// 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;
-    settings.auditing.logMinLevel = ( process.env.TI_AUDITING_LOG_MIN_LEVEL !== undefined ) ? process.env.TI_AUDITING_LOG_MIN_LEVEL : settings.auditing.logMinLevel;
-    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.language = ( process.env.TI_LOCALIZATION_LANGUAGE !== undefined ) ? process.env.TI_LOCALIZATION_LANGUAGE : settings.localization.language;
-}
-if ( settings.memoryCache ) {
-    settings.memoryCache.authKey = ( process.env.TI_MEMORY_CACHE_AUTH_KEY !== undefined ) ? process.env.TI_MEMORY_CACHE_AUTH_KEY : settings.memoryCache.authKey;
-    settings.memoryCache.redisDB = ( process.env.TI_MEMORY_CACHE_REDIS_DB !== undefined ) ? Number( process.env.TI_MEMORY_CACHE_REDIS_DB ) : settings.memoryCache.redisDB;
-    settings.memoryCache.redisHost = ( process.env.TI_MEMORY_CACHE_REDIS_HOST !== undefined ) ? process.env.TI_MEMORY_CACHE_REDIS_HOST : settings.memoryCache.redisHost;
-    settings.memoryCache.redisPort = ( process.env.TI_MEMORY_CACHE_REDIS_PORT !== undefined ) ? Number( process.env.TI_MEMORY_CACHE_REDIS_PORT ) : settings.memoryCache.redisPort;
-    settings.memoryCache.retryMaxAttempts = ( process.env.TI_MEMORY_CACHE_RETRY_MAX_ATTEMPTS !== undefined ) ? Number( process.env.TI_MEMORY_CACHE_RETRY_MAX_ATTEMPTS ) : settings.memoryCache.retryMaxAttempts;
-    settings.memoryCache.retryMaxInterval = ( process.env.TI_MEMORY_CACHE_RETRY_MAX_INTERVAL !== undefined ) ? Number( process.env.TI_MEMORY_CACHE_RETRY_MAX_INTERVAL ) : settings.memoryCache.retryMaxInterval;
-    settings.memoryCache.user = ( process.env.TI_MEMORY_CACHE_USER !== undefined ) ? process.env.TI_MEMORY_CACHE_USER : settings.memoryCache.user;
-}
-if ( settings.messageExchange ) {
-    settings.messageExchange.securityHashEnabled = ( process.env.TI_MESSAGE_EXCHANGE_SECURITY_HASH_ENABLED !== undefined ) ? tools.toBool( process.env.TI_MESSAGE_EXCHANGE_SECURITY_HASH_ENABLED ) : settings.messageExchange.securityHashEnabled;
-    settings.messageExchange.securityHashKey = ( process.env.TI_MESSAGE_EXCHANGE_SECURITY_HASH_KEY !== undefined ) ? process.env.TI_MESSAGE_EXCHANGE_SECURITY_HASH_KEY : settings.messageExchange.securityHashKey;
-    settings.messageExchange.traceLogEnabled = ( process.env.TI_MESSAGE_EXCHANGE_TRACE_LOG_ENABLED !== undefined ) ? tools.toBool( process.env.TI_MESSAGE_EXCHANGE_TRACE_LOG_ENABLED ) : settings.messageExchange.traceLogEnabled;
-}
-
-// Make sure GCloud is enabled before trying to set it up:
-if ( tools.toBool( process.env.TI_GCLOUD_ENABLED ) === true && settings.gcloudIntegration ) {
-    settings.gcloudIntegration.apiKey = ( process.env.TI_GCLOUD_API_KEY !== undefined ) ? process.env.TI_GCLOUD_API_KEY : settings.gcloudIntegration.apiKey;
-    settings.gcloudIntegration.projectID = ( process.env.TI_GCLOUD_PROJECT_ID !== undefined ) ? process.env.TI_GCLOUD_PROJECT_ID : settings.gcloudIntegration.projectID;
-}
-
-settings.operationMode = process.env.NODE_ENV || settings.operationMode;
-
-// Prevent further modifications to the settings object:
-tools.deepFreeze( settings );
-
-/**
- * A standard getter method for fetching a setting.
- *
- * @method
- * @param {string|TiSetting} setting Specifies either a dot-separated JSON path of the setting, or is a Setting from the settings enum.
- * @param {*} [defaultValue] The default value to be returned if the setting is not found in the current configuration.
- * @returns {*}
- * @public
- */
-module.exports.getSetting = ( setting, defaultValue ) => {
-    return _.get( settings, setting, defaultValue );
+/*
+ * 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-2026 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/>.
+*/
+
+const _ = require( "lodash" );
+const tools = require( "#tools" );
+
+/**
+ * Enum for listing all system settings.
+ *
+ * @readonly
+ * @enum {string} Keys of this ENUM are strings.
+ * @typedef {string} TiSetting
+ */
+const settingsEnum = tools.enum( {
+    AUDITING_LOG_CONSOLE_ENABLED: [ "auditing.logConsoleEnabled", "logConsoleEnabled", "" ],
+    AUDITING_LOG_DETAILS: [ "auditing.logDetails", "logDetails", "" ],
+    AUDITING_LOG_MIN_LEVEL: [ "auditing.logMinLevel", "logMinLevel", "" ],
+    AUDITING_LOG_USES_JSON: [ "auditing.logUsesJSON", "logUsesJSON", "" ],
+    GCLOUD_API_KEY: [ "gcloudIntegration.apiKey", "apiKey", "" ],
+    GCLOUD_PROJECT_ID: [ "gcloudIntegration.projectID", "projectID", "" ],
+    LOCALIZATION_LABELS_PATH: [ "localization.labelsPath", "labelsPath", "" ],
+    LOCALIZATION_LANGUAGE: [ "localization.language", "language", "" ],
+    MEMORY_CACHE_AUTH_KEY: [ "memoryCache.authKey", "authKey", "" ],
+    MEMORY_CACHE_REDIS_DB: [ "memoryCache.redisDB", "redisDB", "" ],
+    MEMORY_CACHE_REDIS_HOST: [ "memoryCache.redisHost", "redisHost", "" ],
+    MEMORY_CACHE_REDIS_PORT: [ "memoryCache.redisPort", "redisPort", "" ],
+    MEMORY_CACHE_RETRY_MAX_ATTEMPTS: [ "memoryCache.retryMaxAttempts", "retryMaxAttempts", "" ],
+    MEMORY_CACHE_RETRY_MAX_INTERVAL: [ "memoryCache.retryMaxInterval", "retryMaxInterval", "" ],
+    MEMORY_CACHE_USER: [ "memoryCache.user", "user", "" ],
+    MESSAGE_EXCHANGE_QUEUE_PREFIX: [ "messageExchange.messageQueuePrefix", "messageQueuePrefix", "" ],
+    MESSAGE_EXCHANGE_MESSAGE_STORE: [ "messageExchange.messageStore", "messageStore", "" ],
+    MESSAGE_EXCHANGE_SECURITY_HASH_ENABLED: [ "messageExchange.securityHashEnabled", "securityHashEnabled", "" ],
+    MESSAGE_EXCHANGE_SECURITY_HASH_KEY: [ "messageExchange.securityHashKey", "securityHashKey", "" ],
+    MESSAGE_EXCHANGE_TRACE_EXPIRATION_TIME: [ "messageExchange.traceExpirationTime", "traceExpirationTime", "" ],
+    MESSAGE_EXCHANGE_TRACE_LOG_ENABLED: [ "messageExchange.traceLogEnabled", "traceLogEnabled", "" ],
+    MESSAGE_EXCHANGE_TRACE_REPOSITORY: [ "messageExchange.traceRepository", "traceRepository", "" ],
+    SERVICE_EXECUTION_TIMEOUT: [ "serviceConfig.executionTimeout", "executionTimeout", "" ],
+    SERVICE_HEALTH_CHECK_ADDRESS: [ "serviceConfig.healthCheckAddress", "healthCheckAddress", "" ],
+    SERVICE_HEALTH_CHECK_INTERVAL: [ "serviceConfig.healthCheckInterval", "healthCheckInterval", "" ],
+    SERVICE_HEALTH_CHECK_TIMEOUT: [ "serviceConfig.healthCheckTimeout", "healthCheckTimeout", "" ],
+    SERVICE_REGISTRY_ADDRESS: [ "serviceConfig.serviceRegistryAddress", "serviceRegistryAddress", "" ],
+    OPERATION_MODE: [ "operationMode", "operationMode", "" ]
+} );
+module.exports.setting = settingsEnum;
+
+/** @type {SettingsMain} */
+const settings = require( "#settings" );
+
+// 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;
+    settings.auditing.logMinLevel = ( process.env.TI_AUDITING_LOG_MIN_LEVEL !== undefined ) ? process.env.TI_AUDITING_LOG_MIN_LEVEL : settings.auditing.logMinLevel;
+    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.split( "," ).map( ( p ) => p.trim() ).filter( Boolean )
+        : settings.localization.labelsPath;
+    settings.localization.language = ( process.env.TI_LOCALIZATION_LANGUAGE !== undefined ) ? process.env.TI_LOCALIZATION_LANGUAGE : settings.localization.language;
+}
+if ( settings.memoryCache ) {
+    settings.memoryCache.authKey = ( process.env.TI_MEMORY_CACHE_AUTH_KEY !== undefined ) ? process.env.TI_MEMORY_CACHE_AUTH_KEY : settings.memoryCache.authKey;
+    settings.memoryCache.redisDB = ( process.env.TI_MEMORY_CACHE_REDIS_DB !== undefined ) ? Number( process.env.TI_MEMORY_CACHE_REDIS_DB ) : settings.memoryCache.redisDB;
+    settings.memoryCache.redisHost = ( process.env.TI_MEMORY_CACHE_REDIS_HOST !== undefined ) ? process.env.TI_MEMORY_CACHE_REDIS_HOST : settings.memoryCache.redisHost;
+    settings.memoryCache.redisPort = ( process.env.TI_MEMORY_CACHE_REDIS_PORT !== undefined ) ? Number( process.env.TI_MEMORY_CACHE_REDIS_PORT ) : settings.memoryCache.redisPort;
+    settings.memoryCache.retryMaxAttempts = ( process.env.TI_MEMORY_CACHE_RETRY_MAX_ATTEMPTS !== undefined ) ? Number( process.env.TI_MEMORY_CACHE_RETRY_MAX_ATTEMPTS ) : settings.memoryCache.retryMaxAttempts;
+    settings.memoryCache.retryMaxInterval = ( process.env.TI_MEMORY_CACHE_RETRY_MAX_INTERVAL !== undefined ) ? Number( process.env.TI_MEMORY_CACHE_RETRY_MAX_INTERVAL ) : settings.memoryCache.retryMaxInterval;
+    settings.memoryCache.user = ( process.env.TI_MEMORY_CACHE_USER !== undefined ) ? process.env.TI_MEMORY_CACHE_USER : settings.memoryCache.user;
+}
+if ( settings.messageExchange ) {
+    settings.messageExchange.securityHashEnabled = ( process.env.TI_MESSAGE_EXCHANGE_SECURITY_HASH_ENABLED !== undefined ) ? tools.toBool( process.env.TI_MESSAGE_EXCHANGE_SECURITY_HASH_ENABLED ) : settings.messageExchange.securityHashEnabled;
+    settings.messageExchange.securityHashKey = ( process.env.TI_MESSAGE_EXCHANGE_SECURITY_HASH_KEY !== undefined ) ? process.env.TI_MESSAGE_EXCHANGE_SECURITY_HASH_KEY : settings.messageExchange.securityHashKey;
+    settings.messageExchange.traceLogEnabled = ( process.env.TI_MESSAGE_EXCHANGE_TRACE_LOG_ENABLED !== undefined ) ? tools.toBool( process.env.TI_MESSAGE_EXCHANGE_TRACE_LOG_ENABLED ) : settings.messageExchange.traceLogEnabled;
+}
+
+// Make sure GCloud is enabled before trying to set it up:
+if ( tools.toBool( process.env.TI_GCLOUD_ENABLED ) === true && settings.gcloudIntegration ) {
+    settings.gcloudIntegration.apiKey = ( process.env.TI_GCLOUD_API_KEY !== undefined ) ? process.env.TI_GCLOUD_API_KEY : settings.gcloudIntegration.apiKey;
+    settings.gcloudIntegration.projectID = ( process.env.TI_GCLOUD_PROJECT_ID !== undefined ) ? process.env.TI_GCLOUD_PROJECT_ID : settings.gcloudIntegration.projectID;
+}
+
+settings.operationMode = process.env.NODE_ENV || settings.operationMode;
+
+// Prevent further modifications to the settings object:
+tools.deepFreeze( settings );
+
+/**
+ * A standard getter method for fetching a setting.
+ *
+ * @method
+ * @param {string|TiSetting} setting Specifies either a dot-separated JSON path of the setting, or is a Setting from the settings enum.
+ * @param {*} [defaultValue] The default value to be returned if the setting is not found in the current configuration.
+ * @returns {*}
+ * @public
+ */
+module.exports.getSetting = ( setting, defaultValue ) => {
+    return _.get( settings, setting, defaultValue );
 };

package/utils/exceptions.js

@@ -29,6 +29,7 @@ const exceptionCodeEnum = tools.enum( {
     E_GEN_INVALID_ARGUMENT_TYPE: [ 1007, "invalid argument type", "The provided argument is not of the expected type." ],
     E_GEN_NOT_INITIALIZED: [ 1008, "not initialized", "The invoked framework component is not initialized." ],
     E_GEN_UNALLOWED_OVERRIDE: [ 1009, "unallowed override", "Attempt to override a protected or private method or property detected." ],
+    E_GEN_NOT_IMPLEMENTED: [ 1010, "not implemented", "The requested functionality is not yet implemented." ],
     /** 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." ],
@@ -56,9 +57,11 @@ const exceptionCodeEnum = tools.enum( {
     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." ]
+    E_WEB_INVALID_REQUEST_CONTENT_ENCODING: [ 4009, "invalid request content encoding", "The request content encoding is not recognized or not supported." ],
+    /** Application exceptions - codes under 5xxx */
+    E_APP_RESOURCE_NOT_FOUND: [ 5004, "resource not found", "The requested resource cannot be found. See details for more information." ],
+    E_APP_SERVICE_ERROR: [ 5005, "app service error", "The application service encountered an error. See details for more information." ]
 } );
-
 module.exports.exceptionCode = exceptionCodeEnum;
 
 /**
@@ -134,18 +137,17 @@ const httpCodeEnum = tools.enum( {
     C_510: [ 510, "Not Extended", "Further extensions to the request are required for the server to fulfil it." ],
     C_511: [ 511, "Network Authentication Required", "The client needs to authenticate to gain network access. Intended for use by intercepting proxies used to control access to the network." ]
 } );
-
 module.exports.httpCode = httpCodeEnum;
 
 const labelPath = "system.exceptions.";
 
 /**
- * Represents an exception.
+ * Represents an any-purpose exception.
  *
- * @class Exception
+ * @class TiException
  * @public
  */
-class Exception {
+class TiException {
 
     #id;
     #code;
@@ -266,7 +268,7 @@ class Exception {
     }
 
     /**
-     * Extracts the essential information about the Exception and returns it as JSON.
+     * Extracts the essential information about the {@link TiException} and returns it as JSON.
      *
      * @method
      * @param {boolean} [includeData=true] Whether to include the data property in the output.
@@ -292,38 +294,48 @@ class Exception {
 
 /**
  * Used to raise an exception from the provided source.
+ * <br/>
+ * NOTE: Custom numeric exception IDs are not supported when 'httpCode' is omitted!
  *
  * @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 {Error|TiExceptionCode|TiException} source Could be a standard JS Error, an ExceptionCode, or another TiException (in which case it will be raised further).
  * @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}
+ * @param {string} [exceptionID=undefined] Should be used only in cases when we have a recognizable exception ID beforehand. Should not be entered otherwise!
+ * @param {TiHttpCode} [httpCode=undefined] An optional HTTP code in case this exception needs to be propagated to a web-application frontend. If provided, this will
+ * override any preexisting HTTP code in 'source'!
+ * @returns {TiException}
  * @public
  */
-module.exports.raise = ( source, data, exceptionID ) => {
-    /** @type Exception */
+module.exports.raise = ( source, data, exceptionID = undefined, httpCode = undefined ) => {
+    /** @type TiException */
     let exception;
 
+    // Support flexible argument passing: if exceptionID is a number (likely an HTTP code) and httpCode is missing, swap them:
+    if ( typeof exceptionID === "number" && httpCode === undefined ) {
+        httpCode = exceptionID;
+        exceptionID = undefined;
+    }
+
     if ( source instanceof Error ) {
-        exception = new Exception( exceptionID || tools.getUUID(), exceptionCodeEnum.E_GEN_JS_INTERNAL_ERROR, tools.errorToJSON( source ) );
-    } else if ( source instanceof Exception ) {
+        exception = new TiException( exceptionID || tools.getUUID(), exceptionCodeEnum.E_GEN_JS_INTERNAL_ERROR, tools.errorToJSON( source ) );
+    } else if ( source instanceof TiException ) {
         exception = source;
     } else if ( _.isString( source ) ) {
-        exception = new Exception( exceptionID || tools.getUUID(), exceptionCodeEnum.E_GEN_JS_INTERNAL_ERROR, {
+        exception = new TiException( exceptionID || tools.getUUID(), exceptionCodeEnum.E_GEN_JS_INTERNAL_ERROR, {
             message: source
         } );
     } else if ( _.isObjectLike( source ) ) {
-        exception = new Exception(
+        exception = new TiException(
             exceptionID || ( source.id || tools.getUUID() ),
             source.code || exceptionCodeEnum.E_GEN_JS_INTERNAL_ERROR,
             source.data,
             source.description
         );
-        if ( httpCodeEnum.contains( source.httpCode ) ) {
+        if ( source.httpCode && httpCodeEnum.contains( source.httpCode ) ) {
             exception.httpCode = source.httpCode;
         }
     } else {
-        exception = new Exception( exceptionID || tools.getUUID(), ( exceptionCodeEnum.contains( source ) ) ? source : exceptionCodeEnum.E_UNKNOWN_ERROR );
+        exception = new TiException( exceptionID || tools.getUUID(), ( exceptionCodeEnum.contains( source ) ) ? source : exceptionCodeEnum.E_UNKNOWN_ERROR );
     }
 
     // Merge the default exception data with the additional one if it's provided:
@@ -336,11 +348,15 @@ module.exports.raise = ( source, data, exceptionID ) => {
         exception.data = tools.decycle( exception.data );
     }
 
+    if ( httpCode && httpCodeEnum.contains( httpCode ) ) {
+        exception.httpCode = httpCode;
+    }
+
     return exception;
 };
 
 /**
- * Verifies if the passed object is an Exception.
+ * Verifies if the passed object is a {@link TiException}.
  *
  * @method
  * @param {*} object
@@ -348,5 +364,5 @@ module.exports.raise = ( source, data, exceptionID ) => {
  * @public
  */
 module.exports.isException = ( object ) => {
-    return ( object instanceof Exception );
+    return ( object instanceof TiException );
 };

package/utils/localization.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-2025 Boris Kostadinov <kostadinov.boris@gmail.com>
+ * Copyright © 2021-2026 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/>.
@@ -18,6 +18,7 @@ const defaultEmptyLabel = "!!! label not found !!!";
  *
  * @readonly
  * @enum {string}
+ * @typedef {string} TiLocalizationLanguage
  */
 const localizationLanguageEnum = tools.enum( {
     // A:
@@ -227,24 +228,8 @@ const localizationLanguageEnum = tools.enum( {
     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
- */
-
 /** @type {TiLabelsTree} */
 const labels = require( "#labels" );
 

package/utils/logger.js

@@ -16,6 +16,7 @@ const localization = require( "#localization" );
  *
  * @readonly
  * @enum {number}
+ * @typedef {number} TiLogSeverity
  */
 const logSeverityEnum = tools.enum( {
     DEFAULT: [ 0, "default", "The log entry has no assigned severity level." ],
@@ -28,10 +29,6 @@ const logSeverityEnum = tools.enum( {
     ALERT: [ 700, "alert", "A person must take an action immediately." ],
     EMERGENCY: [ 800, "emergency", "One or more systems are unusable." ]
 } );
-
-/**
- * @typedef {number} TiLogSeverity
- */
 module.exports.logSeverity = logSeverityEnum;
 
 /**
@@ -46,10 +43,10 @@ module.exports.getSeverityName = ( severity ) => {
 };
 
 /**
- * Used to extract information from an Exception and convert it to a loggable data object.
+ * Used to extract information from a {@link TiException} and convert it to a loggable data object.
  *
  * @method
- * @param {Exception} exception
+ * @param {TiException} exception
  * @returns {{description, details: (*|undefined), exceptionID}}
  * @private
  */
@@ -66,8 +63,8 @@ const exceptionToLog = ( exception ) => {
  *
  * @method
  * @param {string} message The primary log message.
- * @param {TiLogSeverity} [level=DEFAULT] The log severity level. If the current log filtering setting is higher than this then the log entry will be ignored.
- * @param {Object|Error|Exception} [data={}] Optional JSON data containing details of the log entry.
+ * @param {TiLogSeverity} [level=DEFAULT] The log severity level. If the current log filtering setting is higher than this, then the log entry will be ignored.
+ * @param {Object|Error|TiException} [data={}] Optional JSON data containing details of the log entry.
  * @param {string} [thread='main'] The logging thread to which the log entry belongs.
  * @public
  */

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-2025 Boris Kostadinov <kostadinov.boris@gmail.com>
+ * Copyright © 2021-2026 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/>.
@@ -9,21 +9,6 @@
 const _ = require( "lodash" );
 const crypto = require( "node:crypto" );
 
-/**
- * @typedef {Object} TiEnumValue
- * @property {number|string} value
- * @property {string} name
- * @property {string} [description]
- */
-
-/**
- * @typedef {Object} TiEnum
- * @property {Object.<number|string,TiEnumValue>} properties
- * @property {function( (number|string), [string] ): (string|undefined)} name
- * @property {function( (number|string), [string] ): (string|undefined)} description
- * @property {function( (number|string) ): boolean} contains
- */
-
 /**
  * Used to generate and return new UUID.
  *
@@ -41,7 +26,7 @@ module.exports.getUUID = () => {
  * @method
  * @param {Object} object
  * @param {WeakSet} [seen]
- * @return {Object}
+ * @returns {Object}
  * @public
  */
 module.exports.deepFreeze = ( object, seen = new WeakSet() ) => {
@@ -367,7 +352,7 @@ module.exports.decycle = ( object, replacer ) => {
  * replaced with references to the value found by the PATH. This will restore cycles. The object will be mutated.
  *
  * The eval function is used to locate the values described by a PATH. The root object is kept in a $ variable. A
- * regular expression is used to assure that the PATH is extremely well-formed. The regexp contains nested quantifiers.
+ * regular expression is used to ensure that the PATH is extremely well-formed. The regexp contains nested quantifiers.
  * That has been known to have extremely bad performance problems on some browsers for very long strings. A PATH is
  * expected to be reasonably short. A PATH is allowed to belong to a very restricted subset of Goessner's JSONPath.
  *
@@ -455,7 +440,7 @@ module.exports.isJsonString = ( string ) => {
 };
 
 /**
- * Use this to parse any JSON string into JSON object for internal system purposes as it ensures to restore any
+ * Use this to parse any JSON string into a JSON object for internal system purposes as it ensures to restore any
  * circular dependencies obscured with 'stringifyJSON'.
  *
  * @method
@@ -474,7 +459,7 @@ module.exports.parseJSON = ( value ) => {
 
 /**
  * Use this to decompose a JSON object into a sorted string. The values will be ordered alphabetically and combined with
- * their keys, where applicable, starting from the bottom and moving up. Null or undefined values will be ignored and
+ * their keys, where applicable, starting from the bottom and moving up. Null or undefined values will be ignored, and
  * their keys will not be included in the final string.
  *
  * @param {Object} input