@ti-engine/core 1.3.5 → 1.3.6

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 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.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,11 @@
 # 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)
+
 Flexible framework for the creation of microservices with [node.js](https://nodejs.org/).
 
 ## Introduction
@@ -27,7 +33,7 @@ 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:
@@ -320,9 +326,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 +337,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,102 @@
-{
-  "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."
+      },
+      "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.6",
   "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,8 +47,7 @@
   },
   "dependencies": {
     "blake2": "^5.0.0",
-    "@dotenvx/dotenvx": "^1.49.0",
-    "fs-extra": "^11.3.1",
+    "@dotenvx/dotenvx": "^1.49.1",
     "lodash": "^4.17.21",
     "node-schedule": "^2.1.1",
     "ioredis": "^5.7.0"
@@ -62,6 +61,6 @@
     "url": "git+https://github.com/Belleal/ti-engine.git"
   },
   "engines": {
-    "node": ">=14.17.0"
+    "node": ">=18.0.0"
   }
 }

package/utils/exceptions.js

@@ -25,6 +25,7 @@ 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." ],
@@ -53,11 +54,89 @@ 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." ]
 } );
 
+/**
+ * Enum for listing all HTTP codes.
+ *
+ * @readonly
+ * @enum {number}
+ */
+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." ]
+} );
+
 /**
  * @typedef {number} TiExceptionCode
  */
 module.exports.exceptionCode = exceptionCodeEnum;
 
+/**
+ * @typedef {number} TiHttpCode
+ */
+module.exports.httpCode = httpCodeEnum;
+
 const labelPath = "system.exceptions.";
 
 /**
@@ -68,28 +147,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.#description = description || exceptionCodeEnum.description( exceptionCode );
         this.#data = data || {};
     }
 
@@ -121,7 +199,7 @@ class Exception {
      * HTTP error code if relevant.
      *
      * @property
-     * @returns {number}
+     * @returns {TiHttpCode}
      * @public
      */
     get httpCode() {
@@ -132,11 +210,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 +274,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 +305,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 );
+                } );
         }
     }