@ti-engine/core 1.3.5 → 1.3.8

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 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.8
+* fix(tester): fix the relative paths of various files in the tester service. The configuration now assumes that the working directory is the root of the tester package instead of the repository itself
+* build(npm): update npm dependencies to their latest versions
+* docs: fix some outdated information in the `README.md` file and add some more details
+
+## Version 1.3.7
+* feat(exceptions): add new exception code `E_SEC_UNRECOGNIZED_AUTH_METHOD`
+* fix(config): fix potential issue with `TI_GCLOUD_ENABLED` parsing as boolean
+* docs: adjust some of the JSDoc descriptions and definitions
+
+## Version 1.3.6
+* feat(exceptions): add new exception code `E_GEN_INVALID_ARGUMENT_TYPE`
+* feat(exceptions): add public enum with all HTTP codes exported as `httpCode` and typedef `TiHttpCode`. Use it as the type for the `httpCode` exception property
+* feat(tools): add `description` property to enum objects
+* feat(tools): add `contains` property to enum objects
+* feat(tools)!: change enum factory behavior to create a copy of the seed object instead of modifying it (may break code relying on seed object mutation)
+* refactor(exceptions): invalid `httpCode` inputs are coerced to `undefined`; `Exception.asJSON` includes `httpCode` only when defined
+* refactor(tools): deprecate method `getEnumName` in favor of `enum.name`; removal planned for 1.4.0
+* refactor(tools)!: remove method `createCSVFile` as it is unnecessary for the framework's operation. It also eliminates the dependency from `fs-extra` package
+* refactor(tools)!: disallow reserved keys as enum names; make enum properties non-enumerable and freeze the enum object to enforce immutability (may affect code relying on enumeration/extension)
+* fix(tools): fix a bug in the `RetryPolicy` class that caused the `maxAttempts` property to be ignored
+* build(npm): update npm dependencies to their latest versions
+* build(npm): remove `fs-extra` package as it is not used by the framework
+* build(npm)!: bump the minimum supported Node.js version to 18.0.0
+
 ## Version 1.3.5
 * fix(redis integration): fix a duplicated log entry on connection ready event if multiple observers are registered
 * feat(service caller)!: change log level of error result in `process` method from `ERROR` to `DEBUG`. Implementers are expected to handle this and decide if the error should be propagated further or not

package/README.md

@@ -1,5 +1,13 @@
 # ti-engine core
 
+![GitHub top language](https://img.shields.io/github/languages/top/Belleal/ti-engine)
+![CodeRabbit Pull Request Reviews](https://img.shields.io/coderabbit/prs/github/Belleal/ti-engine)
+![npms.io (scoped package)](https://img.shields.io/npms-io/maintenance-score/%40ti-engine/core)
+![npms.io (scoped package)](https://img.shields.io/npms-io/popularity-score/%40ti-engine/core)
+![npms.io (scoped package)](https://img.shields.io/npms-io/quality-score/%40ti-engine/core)
+
+![Logo](https://github.com/Belleal/ti-engine/blob/master/packages/core/docs/ti-engine-icon.ico)
+
 Flexible framework for the creation of microservices with [node.js](https://nodejs.org/).
 
 ## Introduction
@@ -27,15 +35,10 @@ Being a messaging system, the **ti-engine** relies on a message broker for the a
 
 To run the basic **ti-engine** framework, you will need a couple of things:
 
-* A local [node.js installation](https://nodejs.org/en/download/) with a minimum version of **14.17.0**
+* A local [node.js installation](https://nodejs.org/en/download/) with a minimum version of **18.0.0**
 * A local or remote [Redis cache installation](https://redis.io/download) with a minimum version of **5.0.14**
 
-If you are working under Windows 10+ OS and you need to install Redis, take a look at this [guide](https://redis.com/blog/redis-on-windows-10/). You could also use [Redis Cloud](https://app.redislabs.com/) for development as it offers a free basic account. You can configure your connection to a remote Redis server using the following ENV variables:
-
-* `TI_MEMORY_CACHE_AUTH_KEY` can be used to provide the Redis password if there is any at all.
-* `TI_MEMORY_CACHE_REDIS_DB` can be used to specify the Redis DB you want to use. Make sure to set the correct number as, for example, Redis Cloud only uses DB `0`.
-* `TI_MEMORY_CACHE_REDIS_HOST` can be used to provide the remote host. This can be an IP or URL depending on your setup.
-* `TI_MEMORY_CACHE_REDIS_PORT` can be used to provide the remote port. By default, Redis uses `6379` however many implementations might use a custom port that needs to be specified in the connection settings.
+If you are working under Windows 10+ OS and you need to install Redis, take a look at this [guide](https://redis.com/blog/redis-on-windows-10/). You could also use [Redis Cloud](https://app.redislabs.com/) for development as it offers a free basic account.
 
 To get the framework itself, use the command `npm install @ti-engine/core`. And to include it directly in your package.json dependencies execute `npm install @ti-engine/core --save-prod`.
 
@@ -44,13 +47,15 @@ To get the framework itself, use the command `npm install @ti-engine/core`. And
 To start using the **ti-engine**, you will have to make sure that all prerequisites are available and operational. However, before we get to the fun part, you need to also consider a couple of crucial things while working with this framework:
 
 1. The runtime configuration of the framework can be customized using ENV variables. These can be provided to node.js in all the standard ways, but there is also an option to include an `.env` file.
-2. It loads your framework-related custom scripts and files dynamically, but it always assumes their provided paths are relative to the _current working directory_ (i.e., it uses `process.cwd()` to resolve the file paths). Be mindful of that whenever you declare file paths in the various settings.
+2. It loads your framework-related custom scripts and files dynamically, but it always assumes their provided paths are relative to the _current working directory_ (i.e., it uses `process.cwd()` to resolve the file paths). Be mindful of that whenever you declare relative file paths in the various settings.
+
+### Running the tester module
 
 Once you have everything else ready, you should download the **ti-engine** tester module with the command `npm install @ti-engine/tester`. The tester module packages an example microservice that shows the basic approach for using the framework. To make sure everything is working properly, you should try and start the tester service:
 
 1. Open a command prompt and navigate to the directory of the tester module; it should be something like that:
    `[path to your project]/node_modules/@ti-engine/tester`
-2. Execute the following command `node ../core/bin/start-instance.js`. Keep in mind that the working directory for the node process has to be the one specified in point 1. Otherwise, you'll get errors that certain files cannot be found and loaded.
+2. Execute the following command `node ../core/bin/start-instance.js`. Keep in mind that the working directory for the node process has to be the one specified in point 1. Otherwise, you'll get errors that certain files cannot be found and loaded. Also, this configuration assumes that you have an unprotected local Redis server running on the default port. If you have a different setup, you can provide the host and port via ENV variables. We'll cover that in the section [Configuring for a remote Redis server](#configuring-for-a-remote-redis-server).
 3. If everything was done properly, you should see the following output:
 
 ```text
@@ -80,20 +85,21 @@ At the start of the output log, you can see a `NOTICE` that tells you a couple o
 * The instance name - in this case `ti-tester-service`. In the terminology of the framework, this is also known as a _service domain name_.
 * The _instance identifier_. It is an uuid string with a `ti-` prefix, that is generated by the framework at process start. It can and will be used to trace the messages during their movement through the microservice ecosystem. But more on that later.
 
-The following five `INFO` lines inform you about the successful connections to Redis. The default configuration assumes that your Redis is running on localhost and uses the default port. If you have a different setup, you can provide the host and port via ENV variables. We'll cover that in the section [Using the framework](#using-the-framework).
+The following five `INFO` lines inform you about the successful connections to Redis. Remember, the default configuration assumes that your Redis is running on localhost, requires no password, and uses the default port.
 
 Following that come a couple of `INFO` lines that inform you about the microservice interface state. The framework starts with the process of _business services_ registration within the service domain of the microservice `ti-tester-service` and successfully adds two such services. The necessary information for this is read from a JSON config file included in the package. We'll get into more details on what this all means in the section [Creating a microservice](#creating-a-microservice).
 
 Once the initialization sequence has completed, the framework informs you that the microservice instance has started successfully with a `NOTICE` entry.
 
-If the framework encountered an error during initialization instead, you would see something like this instead:
+NOTE: If the framework encountered an error during initialization, you would see something like this instead:
 
 ```text
 [timestamp]: [instance-id] - notice - Starting new instance of type 'ti-tester-service' with instance ID '[instance-id]'.
 [timestamp]: [instance-id] - alert - Error detected in the instance startup script!
+   » [information about the error]
 ```
 
-Finally, you should see a sequence of test execution statements with their results in JSON format. These are the results of three business service calls that are part of the default tester microservice. The final `NOTICE` should indicate that all three tests have been completed successfully.
+Finally, you should see a sequence of test execution statements with their results in JSON format. These are the results of three business service calls that are part of the default tester microservice. The final `NOTICE` should indicate that all three tests out of three have been completed successfully.
 
 You can now kill the node process which should show you the following two lines:
 
@@ -108,6 +114,18 @@ The tester module gets its starting configuration from an `.env` file included i
 
 Before moving on, also take a good look at the file `bin/start-instance.js`. It should give you an idea of how the process of starting and stopping a microservice operates. In most cases this file should be enough as a starting script for your **ti-engine** based microservice applications. You can, of course, create your own starting script, but then you'll have to consider all necessary steps to properly handle the microservice instance.
 
+### Configuring for a remote Redis server
+
+You can configure your connection to a remote Redis server using the following ENV variables:
+
+* `TI_MEMORY_CACHE_AUTH_KEY` can be used to provide the Redis password if there is any at all.
+* `TI_MEMORY_CACHE_REDIS_DB` can be used to specify the Redis DB you want to use. Make sure to set the correct number as, for example, Redis Cloud only uses DB `0`.
+* `TI_MEMORY_CACHE_REDIS_HOST` can be used to provide the remote host. This can be an IP or URL depending on your setup.
+* `TI_MEMORY_CACHE_REDIS_PORT` can be used to provide the remote port. By default, Redis uses `6379` however many implementations might use a custom port that needs to be specified in the connection settings.
+* `TI_MEMORY_CACHE_USER` can be used to specify the Redis username if this is supported by your Redis implementation.
+
+The easiest way to configure these variables is to edit the `.env` file included in the package. You might have to do that if you want to run the tester module successfully with a remote Redis server.
+
 ## Architecture
 
 The architectural approach for the **ti-engine** is done in _tiers_ with lower tiers being unaware of the tiers above them. The framework prefers a high level of abstraction in all its tiers and provides many options for customization and extension. While the language is JavaScript, the structuring of the framework follows the OOP principles, and you will find a lot of abstract classes and methods that require you to implement them. These are always marked with the `@abstract` annotation but if you happen to miss one, the framework will raise an `E_GEN_ABSTRACT_METHOD_CALL` exception when you try to use it in your solution.
@@ -132,7 +150,7 @@ For now, take a look at the following diagram:
 
 It shows the standard flow of a message exchange between one sender and _n_ identical message receivers. The sender splits each message into an _envelope_ and a _payload_, then stores the payload in the shared cache and enqueues the envelope in the requests (destination) queue. Receivers can subscribe to that queue to fetch enqueued messages and process their contents. During the fetch sequence a receiver assembles the full message by getting the payload from the storage. This process is depicted by the blue flow lines.
 
-After the processing is done, the message payload is modified, and the receiver sends the message back to the original sender using the same mechanism. It again splits the message into an envelope and a payload, stores the payload in the storage and enqueues the envelope in the sender response (source) queue. The sender will then assemble the message back and process the contained results. This process is depicted by the red flow lines.
+After the processing is done, the message payload is modified, and the receiver sends the message back to the original sender using the same mechanism. It again splits the message into an envelope and a payload, stores the payload in the storage, and enqueues the envelope in the sender response (source) queue. The sender will then assemble the message back and process the contained results. This process is depicted by the red flow lines.
 
 In this scenario the framework uses _Redis lists_ as queues for the message envelopes and _Redis hash_ as message payload storage. The splitting between envelope and payload is done to avoid unnecessary transportation of potentially large volumes of operational data between the microservices. Other message brokers might use a slightly different approach, but they should still adhere to the same logical flow.
 
@@ -163,15 +181,15 @@ This tier comprises the actual implementation of your application. Its structure
 * It needs to take care of any type of stateful behavior like user sessions or transactions.
 * It needs to act as the primary interface between users and your application, thus handling access management and user interactions.
 
-Depending on the type of software you are building, tier 3 can be an API Gateway, a Web application, backend for a Mobile application or anything like that.
+Depending on the type of software you are building, tier 3 can be an API Gateway, a Web application, backend for a Mobile application, or anything like that.
 
 ## Creating a microservice
 
 Now let's walk through the process of creating a microservice with **ti-engine**. We'll start with analyzing the contents of the tester module. Then we'll proceed with creating a new microservice that can call one of the business services in the default `ti-tester-service`.
 
-### The ti-tester microservice
+### Deconstructing the ti-tester microservice
 
-If you managed to execute the initial framework test as explained in the [Getting started](#getting-started) section, you should already be familiar with the default tester microservice. Here we'll dissect its contents even further.
+If you managed to execute the initial framework test as explained in the [Running the tester module](#running-the-tester-module) section, you should already be familiar with the default ti-tester microservice. Here we'll dissect its contents even further.
 
 Let's take a look at the files and file structure first (only relevant items are shown):
 
@@ -181,6 +199,7 @@ bin
   ↳ v1
     ↳ service1.js
     ↳ service2.js
+  ↳ more-labels.json
   ↳ tester-service.js
   ↳ tester-service.json
 .env
@@ -189,43 +208,45 @@ package.json
 
 You don't have to follow the exact same folder structure as most of the paths can be defined via ENV parameters and in the configuration file. However, having a good clean structure helps when organizing your work in more complex projects.
 
-In the default tester microservice all application files are located inside the `bin` folder. Outside you have only the `package.json` and the `.env` files which can be considered more of a configuration for the node process rather than part of the application itself. Nevertheless, let's start with them:
+In the tester module all application files are located inside the `bin` folder. Outside you have only the `package.json` and the `.env` files which can be considered more of a configuration for the node process rather than part of the application itself. Nevertheless, let's start with them:
 
 #### package.json contents
 
 ```json
 {
   "name": "@ti-engine/tester",
-  "version": "...",
-  "description": "...",
-  "author": "...",
-  "license": "ISC",
+  "version": "[tester module version]",
+  "description": "[tester module description]",
+  "author": "[tester module author]",
+  "license": "GPL-3.0-or-later",
   "dependencies": {
     "@ti-engine/core": "latest"
   },
   "engines": {
-    "node": ">=14.17.0"
+    "node": "[min required node version]"
   }
 }
 ```
 
-Apart from the standard information properties there are only two important entries here: `"@ti-engine/core": "latest"` and `"node": ">=14.17.0"`. The dependency on the core of the framework is set to `latest`, but as with any other npm library you should set this to a specific version when releasing on production. The minimum node version should also reflect the minimum requirements of your application and can be adjusted accordingly, but it should not go below the minimum version required by **ti-engine**.
+Apart from the standard information properties there are only two important entries here: `"@ti-engine/core": "[min required core version]"` and `"node": "[min required node version]"`. The dependency on the core of the framework is set to `latest`, but as with any other npm library you should set this to a specific version when releasing on production. The minimum node version should also reflect the minimum requirements of your application and can be adjusted accordingly, but it should not go below the minimum version required by the **ti-engine** itself.
 
 #### .env contents
 
 ```text
+TI_INSTANCE_NAME=ti-tester-service
 TI_INSTANCE_CLASS=bin/tester-service.js
 TI_INSTANCE_CONFIG=bin/tester-service.json
-TI_INSTANCE_NAME=tester-service
 TI_AUDITING_LOG_MIN_LEVEL=200
+TI_LOCALIZATION_LABELS_PATH=bin/more-labels.json
 ```
 
-The ENV initialization file provides the minimal settings for the proper tester microservice operation. The first three are usually _mandatory_ for every microservice you create, while the last is provided for the needs of the tester demonstration. Let's review them and see what they do:
+The ENV initialization file provides the minimal settings for the proper tester microservice operation. The first three are usually _mandatory_ for every microservice you create, while the last two are provided for the needs of the tester demonstration. Let's review them and see what they do:
 
-* `TI_INSTANCE_CLASS` specifies the relative path to the implementation of the `ServiceInstance` framework class—in this case a `ServiceProvider`. As stated above, the path is relative to the working directory of the `node` process. This variable is mandatory for every microservice you create with the **ti-engine**. If it is not provided, the microservice won't be able to start at all, and you will get an exception.
-* `TI_INSTANCE_CONFIG` specifies the relative path to the configuration data for the microservice. We'll delve into the specific settings below. Technically, you can omit this variable, and the microservice will still start successfully with an empty configuration. There are very few cases, however, where this would be applicable.
 * `TI_INSTANCE_NAME` is the _service domain_ name provided for the microservice. It has to be _unique_ in the context of the microservice ecosystem. If not provided, the framework will attempt to extract this information from the name of the implementation file. That is not a recommended approach, though, as it might cause hard to identify errors later.
-* `TI_AUDITING_LOG_MIN_LEVEL` specifies the minimum log level that should be sent to the log output stream. With a setting of `200` (corresponding to INFO) we filter out all `DEFAULT(0)` and `DEBUG(100)` entries as we don't need them for the tester microservice.
+* `TI_INSTANCE_CLASS` specifies the relative path to the implementation of the `ServiceInstance` framework class—in this case a `ServiceProvider`. As stated above, the path is relative to the working directory of the `node.js` process. This variable is mandatory for every microservice you create with the **ti-engine**. If it is not provided, the microservice won't be able to start at all, and you will get an exception.
+* `TI_INSTANCE_CONFIG` specifies the relative path to the configuration data for the microservice. We'll delve into the specific settings below. Technically, you can omit this variable, and the microservice will still start successfully with an empty configuration. There are very few cases, however, where this would be applicable.
+* `TI_AUDITING_LOG_MIN_LEVEL` specifies the minimum log level that should be sent to the log output stream. With a setting of `200` (corresponding to `INFO`) we filter out all `DEFAULT (0)` and `DEBUG (100)` entries as we don't need them for the tester microservice.
+* `TI_LOCALIZATION_LABELS_PATH` specifies the relative path to the additional localization labels file. This is optional and can be omitted if you don't need custom labels for your microservice.
 
 You can find the full list of available ENV variables and what they do below in [Using the framework](#using-the-framework) section.
 
@@ -236,10 +257,13 @@ Now let's look inside the `bin` folder. The two files there are the ones specifi
 * Method `onStart` overrides the base one from the parent class and is invoked automatically by the framework once initialization of the microservice is complete. In this case the method invokes the execution of the test sequence just once, and then the microservice remains dormant but active.
 * Method `reportHealthy` overrides but essentially just calls the same base method. Its only purpose here is to draw your attention to its existence and the possibility to implement your own health status reporting functionality if you want.
 * Method `verifyAccess` also overrides the base method and shows a very basic example of how to implement user access verification on business service level. Each time a service in the `ti-tester-service` is called, the framework will trigger this method and will only allow processing if there is a non-undefined value inside the `authToken` variable.
-* Method `#executeTests` is a custom private method that contains the test sequence itself. It is called by the `onStart` method just once per microservice start. Inside you can see two examples of calling a business service—in both cases the tester microservice is calling itself. In a more practical situation, however, these calls would be directed towards other service domains.
+* Method `#executeTests` is a custom private method that contains the test execution sequence itself. It is called by the `onStart` method just once per microservice start.
+* Method `#assertService` is an assertion wrapper around a standard service call request. Inside it, you can see how a business service is invoked and how the results should be handled.
 
 The file `tester-service.json` contains framework configuration for the tester microservice. It will be automatically loaded inside the `ServiceInstance` class during initialization and will already be available inside the `onStart` method for usage. In this case the configuration is related to the two business services that will be provided by the microservice. More on this topic will be covered in the section [Using the framework](#using-the-framework). For now pay attention to the `serviceFile` parameter and that it once again provides a relative path to the actual file containing the business logic.
 
+The file `more-labels.json` contains one additional localization label for the tester microservice and is only used to demonstrate how to add custom labels to the microservice. For more information on localization, see the section [Localization](#localization).
+
 The final two files are located in `bin/services/v1/` folder. They contain the definitions and business logic of the two business services that will be loaded at initialization time and provided by the tester microservice. In this case `service1.js` contains a basic service that returns the current timestamp. The `service2.js` file contains a slightly more complex example of a service calling another service (in this case `service1`) before also returning two timestamps taken at the beginning and end of execution. Pay attention to the way the methods inside are declared and exported as this is the proper way to do this while using the **ti-engine** framework. Once again, we'll delve into the details and specifics of creating business services in the section [Using the framework](#using-the-framework).
 
 ### Creating your own microservice
@@ -247,9 +271,9 @@ The final two files are located in `bin/services/v1/` folder. They contain the d
 Now that we've seen the structure of the tester microservice, let's create a new one and make it call `service2`. Let's use the same file structure as for the tester. Create a folder `my-service` and in it create a `package.json` file. Make sure to include a dependency to `"@ti-engine/core": "latest"` in it. After that create a `.env` file and add the following entries in it:
 
 ```text
+TI_INSTANCE_NAME=my-service
 TI_INSTANCE_CLASS=bin/my-service.js
 TI_INSTANCE_CONFIG=bin/my-service.json
-TI_INSTANCE_NAME=my-service
 TI_AUDITING_LOG_MIN_LEVEL=200
 ```
 
@@ -320,9 +344,9 @@ Now let's start the new microservice with `node .\node_modules\@ti-engine\core\b
 
 ```text
 [timestamp]: [instance-id] - notice - Starting new instance of type 'my-service' with instance ID '[instance-id]'.
-[timestamp]: [instance-id] - info - Connection to Redis server 127.0.0.1:6379 (re)established by client 'connection-msg-responses-in' and is ready to be used.
-[timestamp]: [instance-id] - info - Connection to Redis server 127.0.0.1:6379 (re)established by client 'connection-msg-requests-out' and is ready to be used.
-[timestamp]: [instance-id] - info - Connection to Redis server 127.0.0.1:6379 (re)established by client 'system-cache' and is ready to be used.
+[timestamp]: [instance-id] - info - Connection to Redis server '127.0.0.1:6379' established by client 'system-cache' and is ready to be used.
+[timestamp]: [instance-id] - info - Connection to Redis server '127.0.0.1:6379' established by client 'connection-msg-responses-in' and is ready to be used.
+[timestamp]: [instance-id] - info - Connection to Redis server '127.0.0.1:6379' established by client 'connection-msg-requests-out' and is ready to be used.
 ```
 
 If you haven't started anything else, this is all you should see at this point.
@@ -331,10 +355,10 @@ Now without exiting this node process, let's start the original tester microserv
 
 ```text
 ...
-[timestamp]: [instance-id] - notice - Execution of service2 result:
-   » {"isSuccessful":true,"payload":{"s1Timestamp":[timestamp],"s2TimestampStart":[timestamp],"s2TimestampEnd":[timestamp]}}
 [timestamp]: [instance-id] - notice - Instance [instance-id] started successfully.
    » {"nodeVersion":[node-version]}
+[timestamp]: [instance-id] - notice - Execution of service2 result:
+   » {"isSuccessful":true,"payload":{"s1Timestamp":[timestamp],"s2TimestampStart":[timestamp],"s2TimestampEnd":[timestamp]}}
 ```
 
 This means the service call processing was successful and a result was returned to `my-service`. Because we made the receiving of the result blocking and part of the initialization sequence, the new microservice did not report successful startup until it received that response from `ti-tester-service`.

package/bin/localization/labels.json

@@ -1,99 +1,105 @@
-{
-  "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."
-      }
-    }
-  }
+{
+  "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."
+      },
+      "1007": {
+        "en": "The provided argument is not of the expected type."
+      },
+      "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."
+      },
+      "2004": {
+        "en": "The requested authentication method is not recognized or supported."
+      },
+      "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/exchange/message-dispatcher.js

@@ -95,8 +95,8 @@ class MessageDispatcher {
             retry.onFailedAttempt( ( error ) => {
                 logger.log( `Failed to send message request with chain ID: ${ message.chainID }`, logger.logSeverity.WARNING, error );
             } );
-            retry.onRetry( ( attempt ) => {
-                logger.log( `Retrying to send message response with chain ID: ${ message.chainID }. This is attempt ${ attempt }...`, logger.logSeverity.NOTICE );
+            retry.onRetry( ( attempt, error ) => {
+                logger.log( `Retrying to send message response with chain ID: ${ message.chainID }. This is attempt ${ attempt }...`, logger.logSeverity.NOTICE, ( error ) ? { error: tools.errorToJSON( error ) } : undefined );
             } );
 
             messageTracer.instance.recordTraceEntry( message, messageTracer.messageType.MESSAGE_REQUEST, messageTracer.dispatchEvent.SENT, messageTracer.messageState.PENDING );
@@ -125,8 +125,8 @@ class MessageDispatcher {
             retry.onFailedAttempt( ( error ) => {
                 logger.log( `Failed to send message response with chain ID: ${ message.chainID }`, logger.logSeverity.WARNING, error );
             } );
-            retry.onRetry( ( attempt ) => {
-                logger.log( `Retrying to send message response with chain ID: ${ message.chainID }. This is attempt ${ attempt }...`, logger.logSeverity.NOTICE );
+            retry.onRetry( ( attempt, error ) => {
+                logger.log( `Retrying to send message response with chain ID: ${ message.chainID }. This is attempt ${ attempt }...`, logger.logSeverity.NOTICE, ( error ) ? { error: tools.errorToJSON( error ) } : undefined );
             } );
 
             messageTracer.instance.recordTraceEntry( message, messageTracer.messageType.MESSAGE_RESPONSE, messageTracer.dispatchEvent.SENT, messageTracer.messageState.PROCESSED );

package/components/exchange/message-tracer.js

@@ -30,6 +30,7 @@ const cache = require( "#cache" );
 const traceRoot = {
     trace: []
 };
+const UNKNOWN_TOKEN = "UNKNOWN";
 
 /**
  * Enum for listing message types.
@@ -155,12 +156,12 @@ class MessageTracer {
         /** @type TiTraceEntry */
         let traceEntry = {
             chainID: message.chainID,
-            dispatchEvent: tools.getEnumName( dispatchEventEnum, dispatchEvent ),
+            dispatchEvent: dispatchEventEnum.name( dispatchEvent, UNKNOWN_TOKEN ),
             fromAddress: ( messageType === messageTypeEnum.MESSAGE_REQUEST ) ? source : destination,
             messageID: message.messageID,
             messageSnapshot: messageSnapshot,
-            messageState: tools.getEnumName( messageStateEnum, messageState ),
-            messageType: tools.getEnumName( messageTypeEnum, messageType ),
+            messageState: messageStateEnum.name( messageState, UNKNOWN_TOKEN ),
+            messageType: messageTypeEnum.name( messageType, UNKNOWN_TOKEN ),
             toAddress: ( messageType === messageTypeEnum.MESSAGE_REQUEST ) ? destination : source,
             traceTimestamp: currentDate.getTime(),
             traceID: tools.getUUID()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ti-engine/core",
-  "version": "1.3.5",
+  "version": "1.3.8",
   "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",
@@ -47,11 +47,10 @@
   },
   "dependencies": {
     "blake2": "^5.0.0",
-    "@dotenvx/dotenvx": "^1.49.0",
-    "fs-extra": "^11.3.1",
+    "@dotenvx/dotenvx": "^1.51.0",
     "lodash": "^4.17.21",
     "node-schedule": "^2.1.1",
-    "ioredis": "^5.7.0"
+    "ioredis": "^5.8.0"
   },
   "optionalDependencies": {
     "@google-cloud/error-reporting": "^3.0.5",
@@ -62,6 +61,6 @@
     "url": "git+https://github.com/Belleal/ti-engine.git"
   },
   "engines": {
-    "node": ">=14.17.0"
+    "node": ">=18.0.0"
   }
 }

package/utils/config.js

@@ -112,6 +112,7 @@ const tools = require( "#tools" );
  *
  * @readonly
  * @enum {string} Keys of this ENUM are strings.
+ * @typedef {string} TiSetting
  */
 const settingsEnum = tools.enum( {
     AUDITING_LOG_CONSOLE_ENABLED: [ "auditing.logConsoleEnabled", "logConsoleEnabled", "" ],
@@ -144,9 +145,6 @@ const settingsEnum = tools.enum( {
     OPERATION_MODE: [ "operationMode", "operationMode", "" ]
 } );
 
-/**
- * @typedef {string} TiSetting
- */
 module.exports.setting = settingsEnum;
 
 /** @type {SettingsMain} */
@@ -165,11 +163,11 @@ if ( settings.localization ) {
 }
 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 ) ? process.env.TI_MEMORY_CACHE_REDIS_DB : settings.memoryCache.redisDB;
+    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 ) ? process.env.TI_MEMORY_CACHE_REDIS_PORT : settings.memoryCache.redisPort;
-    settings.memoryCache.retryMaxAttempts = ( process.env.TI_MEMORY_CACHE_RETRY_MAX_ATTEMPTS !== undefined ) ? process.env.TI_MEMORY_CACHE_RETRY_MAX_ATTEMPTS : settings.memoryCache.retryMaxAttempts;
-    settings.memoryCache.retryMaxInterval = ( process.env.TI_MEMORY_CACHE_RETRY_MAX_INTERVAL !== undefined ) ? process.env.TI_MEMORY_CACHE_RETRY_MAX_INTERVAL : settings.memoryCache.retryMaxInterval;
+    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 ) {
@@ -178,8 +176,8 @@ if ( settings.messageExchange ) {
     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 ( process.env.TI_GCLOUD_ENABLED === true && settings.gcloudIntegration ) {
+// 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;
 }

package/utils/exceptions.js

@@ -14,6 +14,7 @@ const tools = require( "#tools" );
  *
  * @readonly
  * @enum {number}
+ * @typedef {number} TiExceptionCode
  */
 const exceptionCodeEnum = tools.enum( {
     E_UNKNOWN_ERROR: [ 0, "unknown error", "Unidentified error encountered or unrecognized exception code provided." ],
@@ -25,11 +26,13 @@ const 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." ],
+    E_GEN_INVALID_ARGUMENT_TYPE: [ 1007, "invalid argument type", "The provided argument is not of the expected type." ],
     /** 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." ],
     E_SEC_MESSAGE_TAMPERING_DETECTED: [ 2003, "message tampering detected", "The system detected tampering with the message received via message exchange." ],
+    E_SEC_UNRECOGNIZED_AUTH_METHOD: [ 2004, "unrecognized auth method", "The requested authentication method is not recognized or supported." ],
     /** Cross-Application Communication exceptions - codes under 3xxx */
     E_COM_GENERAL_ERROR: [ 3000, "general communication error", "General error during cross-application communication." ],
     E_COM_MESSAGE_SENDER_UNAVAILABLE: [ 3001, "message sender unavailable", "The message sender instance is currently unavailable." ],
@@ -53,10 +56,83 @@ const exceptionCodeEnum = tools.enum( {
     E_WEB_INVALID_REQUEST_CONTENT_ENCODING: [ 4009, "invalid request content encoding", "The request content encoding is not recognized or not supported." ]
 } );
 
+module.exports.exceptionCode = exceptionCodeEnum;
+
 /**
- * @typedef {number} TiExceptionCode
+ * Enum for listing all HTTP codes.
+ *
+ * @readonly
+ * @enum {number}
+ * @typedef {number} TiHttpCode
  */
-module.exports.exceptionCode = exceptionCodeEnum;
+const httpCodeEnum = tools.enum( {
+    /** 1xx informational response */
+    C_100: [ 100, "Continue", "The server has received the request headers and the client should proceed to send the request body." ],
+    C_101: [ 101, "Switching Protocols", "The requester has asked the server to switch protocols and the server has agreed to do so." ],
+    C_102: [ 102, "Processing", "This code indicates that the server has received and is processing the request, but no response is available yet." ],
+    C_103: [ 103, "Early Hints", "Used to return some response headers before final HTTP message." ],
+    /** 2xx success */
+    C_200: [ 200, "OK", "Standard response for successful HTTP requests." ],
+    C_201: [ 201, "Created", "The request has been fulfilled, resulting in the creation of a new resource." ],
+    C_202: [ 202, "Accepted", "The request has been accepted for processing, but the processing has not been completed." ],
+    C_203: [ 203, "Non-Authoritative Information", "The server is a transforming proxy that received a 200 OK from its origin, but is returning a modified version of the origin's response." ],
+    C_204: [ 204, "No Content", "The server successfully processed the request, and is not returning any content." ],
+    C_205: [ 205, "Reset Content", "The server successfully processed the request, asks that the requester reset its document view, and is not returning any content." ],
+    C_206: [ 206, "Partial Content", "The server is delivering only part of the resource (byte serving) due to a range header sent by the client." ],
+    C_207: [ 207, "Multi-Status", "The message body that follows is by default an XML message and can contain a number of separate response codes, depending on how many sub-requests were made." ],
+    C_208: [ 208, "Already Reported", "The members of a DAV binding have already been enumerated in a preceding part of the (multistatus) response, and are not being included again." ],
+    C_226: [ 226, "IM Used", "The server has fulfilled a request for the resource, and the response is a representation of the result of one or more instance-manipulations applied to the current instance." ],
+    /** 3xx redirection */
+    C_300: [ 300, "Multiple Choices", "Indicates multiple options for the resource from which the client may choose." ],
+    C_301: [ 301, "Moved Permanently", "This and all future requests should be directed to the given URI." ],
+    C_302: [ 302, "Found", "Tells the client to look at (browse to) another URL." ],
+    C_303: [ 303, "See Other", "The response to the request can be found under another URI using the GET method." ],
+    C_304: [ 304, "Not Modified", "Indicates that the resource has not been modified since the version specified by the request headers If-Modified-Since or If-None-Match." ],
+    C_307: [ 307, "Temporary Redirect", "In this case, the request should be repeated with another URI; however, future requests should still use the original URI." ],
+    C_308: [ 308, "Permanent Redirect", "This and all future requests should be directed to the given URI. 308 parallels the behavior of 301, but does not allow the HTTP method to change." ],
+    /** 4xx client errors */
+    C_400: [ 400, "Bad Request", "The server cannot or will not process the request due to an apparent client error." ],
+    C_401: [ 401, "Unauthorized", "Similar to 403 Forbidden, but specifically for use when authentication is required and has failed or has not yet been provided." ],
+    C_403: [ 403, "Forbidden", "The request contained valid data and was understood by the server, but the server is refusing action. This may be due to the user not having the necessary permissions for a resource or needing an account of some sort, or attempting a prohibited action." ],
+    C_404: [ 404, "Not Found", "The requested resource could not be found but may be available in the future. Subsequent requests by the client are permissible." ],
+    C_405: [ 405, "Method Not Allowed", "A request method is not supported for the requested resource; for example, a GET request on a form that requires data to be presented via POST, or a PUT request on a read-only resource." ],
+    C_406: [ 406, "Not Acceptable", "The requested resource is capable of generating only content not acceptable according to the Accept headers sent in the request." ],
+    C_407: [ 407, "Proxy Authentication Required", "The client must first authenticate itself with the proxy." ],
+    C_408: [ 408, "Request Timeout", "The server timed out waiting for the request." ],
+    C_409: [ 409, "Conflict", "Indicates that the request could not be processed because of conflict in the current state of the resource, such as an edit conflict between multiple simultaneous updates." ],
+    C_410: [ 410, "Gone", "Indicates that the resource requested was previously in use but is no longer available and will not be available again." ],
+    C_411: [ 411, "Length Required", "The request did not specify the length of its content, which is required by the requested resource." ],
+    C_412: [ 412, "Precondition Failed", "The server does not meet one of the preconditions that the requester put on the request header fields." ],
+    C_413: [ 413, "Payload Too Large", "The request is larger than the server is willing or able to process." ],
+    C_414: [ 414, "URI Too Long", "The URI provided was too long for the server to process." ],
+    C_415: [ 415, "Unsupported Media Type", "The request entity has a media type which the server or resource does not support." ],
+    C_416: [ 416, "Range Not Satisfiable", "The client has asked for a portion of the file (byte serving), but the server cannot supply that portion." ],
+    C_417: [ 417, "Expectation Failed", "The server cannot meet the requirements of the Expect request-header field." ],
+    C_421: [ 421, "Misdirected Request", "The request was directed at a server that is not able to produce a response (for example because of connection reuse)." ],
+    C_422: [ 422, "Unprocessable Content", "The request was well-formed (i.e., syntactically correct) but could not be processed." ],
+    C_423: [ 423, "Locked", "The resource that is being accessed is locked." ],
+    C_424: [ 424, "Failed Dependency", "The request failed because it depended on another request and that request failed." ],
+    C_425: [ 425, "Too Early", "Indicates that the server is unwilling to risk processing a request that might be replayed." ],
+    C_426: [ 426, "Upgrade Required", "The client should switch to a different protocol such as TLS/1.3, given in the Upgrade header field." ],
+    C_428: [ 428, "Precondition Required", "The origin server requires the request to be conditional." ],
+    C_429: [ 429, "Too Many Requests", "The user has sent too many requests in a given amount of time. Intended for use with rate-limiting schemes." ],
+    C_431: [ 431, "Request Header Fields Too Large", "The server is unwilling to process the request because either an individual header field, or all the header fields collectively, are too large." ],
+    C_451: [ 451, "Unavailable For Legal Reasons", "A server operator has received a legal demand to deny access to a resource or to a set of resources that includes the requested resource." ],
+    /** 5xx server errors */
+    C_500: [ 500, "Internal Server Error", "A generic error message, given when an unexpected condition was encountered and no more specific message is suitable." ],
+    C_501: [ 501, "Not Implemented", "The server either does not recognize the request method, or it lacks the ability to fulfil the request." ],
+    C_502: [ 502, "Bad Gateway", "The server was acting as a gateway or proxy and received an invalid response from the upstream server." ],
+    C_503: [ 503, "Service Unavailable", "The server cannot handle the request (because it is overloaded or down for maintenance)." ],
+    C_504: [ 504, "Gateway Timeout", "The server was acting as a gateway or proxy and did not receive a timely response from the upstream server." ],
+    C_505: [ 505, "HTTP Version Not Supported", "The server does not support the HTTP version used in the request." ],
+    C_506: [ 506, "Variant Also Negotiates", "Transparent content negotiation for the request results in a circular reference." ],
+    C_507: [ 507, "Insufficient Storage", "The server is unable to store the representation needed to complete the request." ],
+    C_508: [ 508, "Loop Detected", "The server detected an infinite loop while processing the request." ],
+    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.";
 
@@ -68,28 +144,27 @@ const labelPath = "system.exceptions.";
  */
 class Exception {
 
-    #id = undefined;
-    #code = undefined;
-    #httpCode = undefined;
-    #label = undefined;
-    #description = undefined;
-    #data = undefined;
+    #id;
+    #code;
+    #httpCode;
+    #label;
+    #description;
+    #data;
 
     /**
      * @constructor
      * @param {string} id The unique ID to be assigned to this exception.
      * @param {TiExceptionCode} exceptionCode An unique exception identifier. If this is not recognized, the default error code will be used instead.
-     * @param {Object} [data] Any additional data to insert into the exception.
-     * @param {string} [description] Description of the exception.
+     * @param {Object} [data={}] Any additional data to insert into the exception.
+     * @param {string} [description=undefined] Description of the exception.
      */
     constructor( id, exceptionCode, data, description ) {
-        exceptionCode = ( exceptionCodeEnum.properties[ exceptionCode ] ) ? exceptionCode : module.exports.exceptionCode.E_UNKNOWN_ERROR;
+        exceptionCode = exceptionCodeEnum.contains( exceptionCode ) ? exceptionCode : exceptionCodeEnum.E_UNKNOWN_ERROR;
 
         this.#id = id;
         this.#code = exceptionCode;
-        this.#httpCode = undefined;
-        this.#label = labelPath + exceptionCode;
-        this.#description = description || exceptionCodeEnum.properties[ exceptionCode ].description;
+        this.#label = labelPath + String( exceptionCode );
+        this.#description = description || exceptionCodeEnum.description( exceptionCode );
         this.#data = data || {};
     }
 
@@ -121,7 +196,7 @@ class Exception {
      * HTTP error code if relevant.
      *
      * @property
-     * @returns {number}
+     * @returns {TiHttpCode}
      * @public
      */
     get httpCode() {
@@ -132,11 +207,15 @@ class Exception {
      * HTTP error code if relevant.
      *
      * @property
-     * @param {number} httpCode
+     * @param {TiHttpCode} httpCode
      * @public
      */
     set httpCode( httpCode ) {
-        this.#httpCode = httpCode;
+        if ( httpCodeEnum.contains( httpCode ) ) {
+            this.#httpCode = httpCode;
+        } else {
+            this.#httpCode = undefined;
+        }
     }
 
     /**
@@ -192,14 +271,19 @@ class Exception {
      * @public
      */
     asJSON( includeData = true ) {
-        return {
+        let json = {
             id: this.id,
             code: this.code,
-            httpCode: this.httpCode,
             label: this.label,
-            description: this.description,
-            data: ( includeData === true ) ? this.data : undefined
+            description: this.description
         };
+        if ( this.#httpCode !== undefined ) {
+            json.httpCode = this.#httpCode;
+        }
+        if ( includeData === true ) {
+            json.data = this.#data;
+        }
+        return json;
     }
 }
 
@@ -218,17 +302,25 @@ module.exports.raise = ( source, data, exceptionID ) => {
     let exception;
 
     if ( source instanceof Error ) {
-        exception = new Exception( exceptionID || tools.getUUID(), module.exports.exceptionCode.E_GEN_JS_INTERNAL_ERROR, tools.errorToJSON( source ) );
+        exception = new Exception( exceptionID || tools.getUUID(), exceptionCodeEnum.E_GEN_JS_INTERNAL_ERROR, tools.errorToJSON( source ) );
     } else if ( source instanceof Exception ) {
         exception = source;
     } else if ( _.isString( source ) ) {
-        exception = new Exception( exceptionID || tools.getUUID(), module.exports.exceptionCode.E_GEN_JS_INTERNAL_ERROR, {
+        exception = new Exception( exceptionID || tools.getUUID(), exceptionCodeEnum.E_GEN_JS_INTERNAL_ERROR, {
             message: source
         } );
     } else if ( _.isObjectLike( source ) ) {
-        exception = new Exception( exceptionID || ( source.id || tools.getUUID() ), source.code || module.exports.exceptionCode.E_GEN_JS_INTERNAL_ERROR, source.data, source.description );
+        exception = new Exception(
+            exceptionID || ( source.id || tools.getUUID() ),
+            source.code || exceptionCodeEnum.E_GEN_JS_INTERNAL_ERROR,
+            source.data,
+            source.description
+        );
+        if ( httpCodeEnum.contains( source.httpCode ) ) {
+            exception.httpCode = source.httpCode;
+        }
     } else {
-        exception = new Exception( exceptionID || tools.getUUID(), ( exceptionCodeEnum.properties[ source ] ) ? source : module.exports.exceptionCode.E_UNKNOWN_ERROR );
+        exception = new Exception( exceptionID || tools.getUUID(), ( exceptionCodeEnum.contains( source ) ) ? source : exceptionCodeEnum.E_UNKNOWN_ERROR );
     }
 
     // Merge the default exception data with the additional one if it's provided:

package/utils/logger.js

@@ -42,7 +42,7 @@ module.exports.logSeverity = logSeverityEnum;
  * @returns {string}
  */
 module.exports.getSeverityName = ( severity ) => {
-    return tools.getEnumName( logSeverityEnum, severity, "unknown" );
+    return logSeverityEnum.name( severity, "unknown" );
 };
 
 /**

package/utils/tools.js

@@ -7,19 +7,21 @@
 */
 
 const _ = require( "lodash" );
-const fs = require( "fs-extra" );
 const crypto = require( "node:crypto" );
 
 /**
  * @typedef {Object} TiEnumValue
  * @property {number|string} value
  * @property {string} name
- * @property {string} description
+ * @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
  */
 
 /**
@@ -38,38 +40,113 @@ module.exports.getUUID = () => {
  *
  * @method
  * @param {Object} seed
- * @returns {Object}
+ * @returns {Object} This is a {@link TiEnum} object. Setting the proper reference here would unfortunately break IDE support.
  * @public
  */
 module.exports.enum = ( seed ) => {
-    let properties = {};
+    const enumObject = Object.create( null );
+    const properties = Object.create( null );
+    const reserved = new Set( [ "properties", "name", "description", "contains", "__proto__", "prototype", "constructor" ] );
 
     _.forOwn( seed, ( value, key ) => {
-        if ( value instanceof Array ) {
-            seed[ key ] = value[ 0 ];
-            properties[ value[ 0 ] ] = {
-                value: value[ 0 ],
-                name: value[ 1 ],
-                description: value[ 2 ]
-            };
+        if ( !reserved.has( key ) ) {
+            if ( Array.isArray( value ) ) {
+                enumObject[ key ] = value[ 0 ];
+                properties[ value[ 0 ] ] = {
+                    value: value[ 0 ],
+                    name: value[ 1 ],
+                    description: value[ 2 ]
+                };
+            } else {
+                enumObject[ key ] = value;
+                properties[ value ] = {
+                    value: value,
+                    name: key
+                };
+            }
+        }
+    } );
+    Object.values( properties ).forEach( Object.freeze );
+    Object.freeze( properties );
+
+    /**
+     * Used to get the name of an {@link TiEnumValue} if such value exists.
+     *
+     * @method
+     * @param {number|string} value
+     * @param {string} [placeholder=undefined] If provided it will be returned when the enum value does not have a name defined.
+     * @returns {string|undefined}
+     * @public
+     */
+    const name = ( value, placeholder = undefined ) => {
+        return ( properties[ value ] ) ? properties[ value ].name : placeholder;
+    };
+
+    /**
+     * Used to get the description of an {@link TiEnumValue} if such value exists.
+     *
+     * @method
+     * @param {number|string} value
+     * @param {string} [placeholder=undefined] If provided it will be returned when the enum value does not have a description defined.
+     * @returns {string|undefined}
+     * @public
+     */
+    const description = ( value, placeholder = undefined ) => {
+        if ( !properties[ value ] ) {
+            return placeholder;
         } else {
-            properties[ value ] = {
-                value: value,
-                name: key.toLowerCase(),
-                description: ""
-            };
+            return ( properties[ value ].description !== undefined ) ? properties[ value ].description : placeholder;
+        }
+    };
+
+    /**
+     * Used to check if the provided value is contained in the provided {@link TiEnum} list.
+     *
+     * @method
+     * @param {number|string} value
+     * @returns {boolean}
+     * @public
+     */
+    const contains = ( value ) => {
+        return !!( properties[ value ] );
+    };
+
+    Object.defineProperties( enumObject, {
+        contains: {
+            enumerable: false,
+            configurable: false,
+            writable: false,
+            value: contains
+        },
+        description: {
+            enumerable: false,
+            configurable: false,
+            writable: false,
+            value: description
+        },
+        name: {
+            enumerable: false,
+            configurable: false,
+            writable: false,
+            value: name
+        },
+        properties: {
+            enumerable: false,
+            configurable: false,
+            writable: false,
+            value: properties
         }
     } );
-    seed.properties = properties;
+    Object.freeze( enumObject );
 
-    Object.freeze( seed );
-    return seed;
+    return enumObject;
 };
 
 /**
  * Used to get the name of an {@link TiEnum} value if such exists.
  *
  * @method
+ * @deprecated Use the 'name' property of the provided {@link TiEnum} instead.
  * @param {TiEnum} enumList
  * @param {number|string} enumValue
  * @param {string} [placeholder=undefined] If provided it will be returned when the enum value does not have a name defined.
@@ -81,7 +158,7 @@ module.exports.getEnumName = ( enumList, enumValue, placeholder = undefined ) =>
 };
 
 /**
- * Convert an Error to JSON object.
+ * Convert an Error to a JSON object.
  * <br/>
  * NOTE: If the value provided is not an error, then it will just be cloned.
  *
@@ -123,7 +200,7 @@ module.exports.toBool = ( value ) => {
 };
 
 /**
- * Will return UTC date string in format YYYY-MM-DD from the provided date.
+ * Will return a UTC date string in format YYYY-MM-DD from the provided date.
  *
  * @method
  * @param {Date} date
@@ -131,15 +208,14 @@ module.exports.toBool = ( value ) => {
  * @public
  */
 module.exports.getUTCDateString = ( date ) => {
-    let year = date.getUTCFullYear();
-    let month = ( "00" + ( date.getUTCMonth() + 1 ) ).match( /\d{2}$/ );
-    let day = ( "00" + date.getUTCDate() ).match( /\d{2}$/ );
-
-    return String( year + "-" + month + "-" + day );
+    const year = date.getUTCFullYear();
+    const month = String( date.getUTCMonth() + 1 ).padStart( 2, "0" );
+    const day = String( date.getUTCDate() ).padStart( 2, "0" );
+    return `${ year }-${ month }-${ day }`;
 };
 
 /**
- * Will return UTC time string in format hh:mm:ss.MMM from the provided date.
+ * Will return a UTC time string in format hh:mm:ss, or hh:mm:ss.MMM when useMilliseconds is true.
  *
  * @method
  * @param {Date} date
@@ -147,13 +223,12 @@ module.exports.getUTCDateString = ( date ) => {
  * @returns {string}
  * @public
  */
-module.exports.getUTCTimeString = ( date, useMilliseconds ) => {
-    let hours = ( "00" + date.getUTCHours() ).match( /\d{2}$/ );
-    let minutes = ( "00" + date.getUTCMinutes() ).match( /\d{2}$/ );
-    let seconds = ( "00" + date.getUTCSeconds() ).match( /\d{2}$/ );
-    let milliseconds = ( "000" + date.getUTCMilliseconds() ).match( /\d{3}$/ );
-
-    return String( hours + ":" + minutes + ":" + seconds + ( ( useMilliseconds ) ? "." + milliseconds : "" ) );
+module.exports.getUTCTimeString = ( date, useMilliseconds = false ) => {
+    const hours = String( date.getUTCHours() ).padStart( 2, "0" );
+    const minutes = String( date.getUTCMinutes() ).padStart( 2, "0" );
+    const seconds = String( date.getUTCSeconds() ).padStart( 2, "0" );
+    const milliseconds = useMilliseconds ? `${ String( date.getUTCMilliseconds() ).padStart( 3, "0" ) }` : "";
+    return `${ hours }:${ minutes }:${ seconds }${ useMilliseconds ? `.${ milliseconds }` : "" }`;
 };
 
 /**
@@ -181,7 +256,7 @@ module.exports.getUTCTimeString = ( date, useMilliseconds ) => {
  *
  * @method
  * @param {Object} object
- * @param {function} [replacer]
+ * @param {function( Object ): Object} [replacer]
  * @returns {Object}
  * @public
  */
@@ -315,7 +390,7 @@ module.exports.retrocycle = ( $ ) => {
  *
  * @method
  * @param {Object} value
- * @return {string}
+ * @returns {string|*}
  * @public
  */
 module.exports.stringifyJSON = ( value ) => {
@@ -345,7 +420,7 @@ module.exports.isJsonString = ( string ) => {
  *
  * @method
  * @param {string} value
- * @return {Object}
+ * @returns {Object|string}
  * @public
  */
 module.exports.parseJSON = ( value ) => {
@@ -364,7 +439,7 @@ module.exports.parseJSON = ( value ) => {
  *
  * @param {Object} input
  * @recursion
- * @return {string|null}
+ * @returns {string|null}
  * @public
  */
 module.exports.decomposeJSON = ( input ) => {
@@ -399,50 +474,6 @@ module.exports.decomposeJSON = ( input ) => {
     return decomposed;
 };
 
-/**
- * Used to create a CSV file from the provided data.
- *
- * @method
- * @param {Object[]} data
- * @param {string} filePath
- * @param {string} fileName
- * @return {Promise}
- * @public
- */
-module.exports.createCSVFile = ( data, filePath, fileName ) => {
-    return new Promise( ( resolve, reject ) => {
-        let fileData = "";
-        if ( data && data.length > 0 ) {
-            let keys = [];
-            _.forOwn( data[ 0 ], ( value, key ) => {
-                keys.push( key );
-            } );
-            keys.sort();
-
-            _.forEach( keys, ( key, idx ) => {
-                fileData += key + ( ( idx < keys.length - 1 ) ? "," : "" );
-            } );
-            fileData += "\n";
-
-            _.forEach( data, ( entry ) => {
-                _.forEach( keys, ( key, idx ) => {
-                    fileData += entry[ key ] + ( ( idx < keys.length - 1 ) ? "," : "" );
-                } );
-                fileData += "\n";
-            } );
-        }
-
-        fs.ensureDir( filePath ).then( () => {
-            const fullPath = filePath + "/" + Date.now() + "-" + fileName + ".csv";
-            return fs.appendFile( fullPath, fileData );
-        } ).then( () => {
-            resolve();
-        } ).catch( ( error ) => {
-            reject( error );
-        } );
-    } );
-};
-
 /**
  * Used to create retry policy for the execution of an operation.
  *
@@ -457,8 +488,12 @@ class RetryPolicy {
 
     /**
      * @constructor
+     * @param {number} maxAttempts The maximum number of attempts to execute the operation.
      */
     constructor( maxAttempts ) {
+        if ( !Number.isInteger( maxAttempts ) || maxAttempts < 1 ) {
+            throw new TypeError( "maxAttempts must be a positive integer" );
+        }
         this.#maxAttempts = maxAttempts;
     }
 
@@ -468,13 +503,13 @@ class RetryPolicy {
      * Used to start execution of the provided operation.
      *
      * @method
-     * @param {Object} context The context in which the operation will be executed (i.e. this reference).
-     * @param {function} operation Operation to be executed; has to return a Promise.
-     * @param {Array} params The arguments to be provided to the operation upon execution.
+     * @param {Object} context The context in which the operation will be executed (i.e., this reference).
+     * @param {function( ...* ): Promise<*>} operation Operation to be executed; must return a Promise.
+     * @param {Array<*>} [params=[]] The arguments to be provided to the operation upon execution.
      * @returns {Promise}
      * @public
      */
-    execute( context, operation, params ) {
+    execute( context, operation, params = [] ) {
         return this.#retry( context, operation, params, 1, undefined );
     }
 
@@ -495,7 +530,7 @@ class RetryPolicy {
      * Used to register a method that will be automatically called on each execution retry (after the initial one).
      *
      * @method
-     * @param {function( number )} action The current attempt number will be provided as an argument.
+     * @param {function( number, (Error|undefined) )} action The current attempt and last error are provided.
      * @public
      */
     onRetry( action ) {
@@ -511,8 +546,8 @@ class RetryPolicy {
      *
      * @method
      * @param {Object} context
-     * @param {function} operation
-     * @param {Array} params
+     * @param {function( ...* ): Promise<*>} operation Operation to be executed; must return a Promise.
+     * @param {Array<*>} params The arguments to be provided to the operation upon execution.
      * @param {number} attempt
      * @param {Error} error
      * @returns {Promise}
@@ -523,14 +558,25 @@ class RetryPolicy {
             return Promise.reject( error );
         } else {
             if ( attempt > 1 && this.#onRetry ) {
-                this.#onRetry( attempt );
-            }
-            return operation.apply( context, params ).catch( error => {
-                if ( this.#onFailedAttempt ) {
-                    this.#onFailedAttempt( error );
+                try {
+                    this.#onRetry( attempt, error );
+                } catch ( _ ) { /* ignore observer errors */
                 }
-                return this.#retry( context, operation, params, ( attempt - 1 ), error );
-            } );
+            }
+            return Promise
+                .resolve()
+                .then( () => {
+                    return operation.apply( context, params );
+                } )
+                .catch( ( error ) => {
+                    if ( this.#onFailedAttempt ) {
+                        try {
+                            this.#onFailedAttempt( error );
+                        } catch ( _ ) { /* ignore observer errors */
+                        }
+                    }
+                    return this.#retry( context, operation, params, ( attempt + 1 ), error );
+                } );
         }
     }