@ti-engine/core 1.3.13 → 1.6.0

package/components/exchange/message-sender.js

@@ -1,6 +1,6 @@
 /*
  * The ti-engine is an open source, free to use—both for personal and commercial projects—framework for the creation of microservice-based solutions using node.js.
- * Copyright © 2021-2023 Boris Kostadinov <kostadinov.boris@gmail.com>
+ * Copyright © 2021-2026 Boris Kostadinov <kostadinov.boris@gmail.com>
  * This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
  * This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
  * You should have received a copy of the GNU General Public License along with this program. If not, see <https://www.gnu.org/licenses/>.
@@ -23,7 +23,7 @@ class MessageSender extends MessageHandler {
     /**
      * @constructor
      * @param {string} identifier An identifier for this message handler. Should be unique in the context of the message exchange.
-     * @throws {Exception.E_GEN_ABSTRACT_CLASS_INIT} If this class is instantiated directly.
+     * @throws {TiException.E_GEN_ABSTRACT_CLASS_INIT} If this class is instantiated directly.
      */
     constructor( identifier ) {
         super( identifier );

package/components/exchange/message-tracer.js

@@ -1,6 +1,6 @@
 /*
  * The ti-engine is an open source, free to use—both for personal and commercial projects—framework for the creation of microservice-based solutions using node.js.
- * Copyright © 2021-2025 Boris Kostadinov <kostadinov.boris@gmail.com>
+ * Copyright © 2021-2026 Boris Kostadinov <kostadinov.boris@gmail.com>
  * This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
  * This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
  * You should have received a copy of the GNU General Public License along with this program. If not, see <https://www.gnu.org/licenses/>.
@@ -13,20 +13,6 @@ const logger = require( "#logger" );
 const exceptions = require( "#exceptions" );
 const cache = require( "#cache" );
 
-/**
- * @typedef {Object} TiTraceEntry
- * @property {string} chainID
- * @property {string} dispatchEvent
- * @property {string} fromAddress
- * @property {string} messageID
- * @property {Object} messageSnapshot
- * @property {string} messageState
- * @property {string} messageType
- * @property {string} toAddress
- * @property {string} traceID
- * @property {number} traceTimestamp
- */
-
 const traceRoot = {
     trace: []
 };
@@ -37,15 +23,12 @@ const UNKNOWN_TOKEN = "UNKNOWN";
  *
  * @readonly
  * @enum {number}
+ * @typedef {number} TiMessageType
  */
 let messageTypeEnum = tools.enum( {
     MESSAGE_REQUEST: [ 1000, "REQUEST", "" ],
     MESSAGE_RESPONSE: [ 1001, "RESPONSE", "" ]
 } );
-
-/**
- * @typedef {number} TiMessageType
- */
 module.exports.messageType = messageTypeEnum;
 
 /**
@@ -53,6 +36,7 @@ module.exports.messageType = messageTypeEnum;
  *
  * @readonly
  * @enum {number}
+ * @typedef {number} TiDispatchEvent
  */
 let dispatchEventEnum = tools.enum( {
     DELIVERED: [ 1100, "DELIVERED", "When message delivery is confirmed." ],
@@ -60,10 +44,6 @@ let dispatchEventEnum = tools.enum( {
     RECEIVED: [ 1102, "RECEIVED", "When message was received." ],
     SENT: [ 1103, "SENT", "When message was sent." ]
 } );
-
-/**
- * @typedef {number} TiDispatchEvent
- */
 module.exports.dispatchEvent = dispatchEventEnum;
 
 /**
@@ -71,15 +51,12 @@ module.exports.dispatchEvent = dispatchEventEnum;
  *
  * @readonly
  * @enum {number}
+ * @typedef {number} TiMessageState
  */
 let messageStateEnum = tools.enum( {
     PENDING: [ 1200, "PENDING", "" ],
     PROCESSED: [ 1201, "PROCESSED", "" ]
 } );
-
-/**
- * @typedef {number} TiMessageState
- */
 module.exports.messageState = messageStateEnum;
 
 /**

package/components/service-caller.js

@@ -1,6 +1,6 @@
 /*
  * The ti-engine is an open source, free to use—both for personal and commercial projects—framework for the creation of microservice-based solutions using node.js.
- * Copyright © 2021-2025 Boris Kostadinov <kostadinov.boris@gmail.com>
+ * Copyright © 2021-2026 Boris Kostadinov <kostadinov.boris@gmail.com>
  * This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
  * This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
  * You should have received a copy of the GNU General Public License along with this program. If not, see <https://www.gnu.org/licenses/>.
@@ -14,45 +14,6 @@ const config = require( "#config" );
 const cache = require( "#cache" );
 const messageDispatcher = require( "#message-dispatcher" );
 
-/**
- * @typedef {Object} ServiceAddress
- * @property {string} serviceAlias A valid service alias.
- * @property {string} serviceDomainName A valid service domain name.
- * @property {number|undefined} serviceVersion Optional service version. If not provided, the latest version will be assumed as a target.
- */
-
-/**
- * @typedef {Object} ServiceExecContext
- * @property {string|undefined} authToken A valid authentication token that initialized the service call (if applicable).
- * @property {ServiceCallPredecessor|undefined} previousServiceCall The previous service call in the execution chain (if such exists).
- */
-
-/**
- * @typedef {Message} ServiceCallPredecessor
- * @property {string} predecessor The {@link Message.messageID} of the predecessor in the service call tree.
- * @property {ServiceAddress} serviceAddress The address of the service that has to process the service call.
- * @property {Object|undefined} serviceParams The named params to be provided to the API service.
- */
-
-/**
- * @typedef {ServiceCallPredecessor} ServiceCall
- * @property {string} authToken A valid authentication token that initialized the service call.
- * @property {number} createdOn A unix timestamp taken at creation time of the service call.
- * @property {number} executionTime The total execution time of this service call in milliseconds.
- * @property {Object|undefined} exception If there was exception during the service call processing, it will be set here. Otherwise, it will be 'undefined'.
- * @property {number|undefined} finishedOn A unix timestamp taken at finish time of the service call.
- * @property {boolean} isCompleted Flag to indicate if this service call has been completed.
- * @property {boolean|undefined} isSuccessful A flag indicating if this service call can be considered successful or not. Will be 'undefined' until the service call is processed.
- * @property {string[]} successors The service call IDs of the successors in the service call tree.
- */
-
-/**
- * @typedef {Object} ServiceCallResult
- * @property {Exception|undefined} exception If there was exception during the service call processing, it will be set here. Otherwise, it will be 'undefined'.
- * @property {boolean} isSuccessful A flag indicating if this service call can be considered successful or not.
- * @property {Object|string|undefined} payload The payload containing the results from the service call processing. If a string, it is ID of the payload in the memory cache instead.
- */
-
 /**
  * Used to assemble and prepare a new {@link ServiceCall} object.
  *

package/components/service-consumer.js

@@ -33,7 +33,7 @@ class ServiceConsumer extends ServiceInstance {
      * @constructor
      * @param {string} serviceDomainName The service domain name for this service instance.
      * @param {ServiceConfiguration} [serviceConfig] The JSON configuration for this service.
-     * @throws {Exception.E_GEN_ABSTRACT_CLASS_INIT} If this class is instantiated directly.
+     * @throws {TiException.E_GEN_ABSTRACT_CLASS_INIT} If this class is instantiated directly.
      */
     constructor( serviceDomainName, serviceConfig ) {
         super( serviceDomainName, serviceConfig );

package/components/service-executor.js

@@ -1,6 +1,6 @@
 /*
  * The ti-engine is an open source, free to use—both for personal and commercial projects—framework for the creation of microservice-based solutions using node.js.
- * Copyright © 2021-2023 Boris Kostadinov <kostadinov.boris@gmail.com>
+ * Copyright © 2021-2026 Boris Kostadinov <kostadinov.boris@gmail.com>
  * This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
  * This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
  * You should have received a copy of the GNU General Public License along with this program. If not, see <https://www.gnu.org/licenses/>.
@@ -15,21 +15,6 @@ const config = require( "#config" );
 const cache = require( "#cache" );
 const messageDispatcher = require( "#message-dispatcher" );
 
-/**
- * @typedef {Object} ServiceDefinition
- * @property {string} serviceAlias Service alias.
- * @property {string} serviceFile The JS file containing the service itself. This has to be exposed via package.json import structure!
- * @property {number} [serviceVersion] Service version.
- */
-
-/**
- * @typedef {Object.<string, ServiceInterfaceVersion>} ServiceInterface
- */
-
-/**
- * @typedef {Object.<number, ServiceHandlerMethod>} ServiceInterfaceVersion
- */
-
 /**
  * @callback VerifyAccessMethod
  * @param {string} authToken

package/components/service-instance.js

@@ -1,6 +1,6 @@
 /*
  * The ti-engine is an open source, free to use—both for personal and commercial projects—framework for the creation of microservice-based solutions using node.js.
- * Copyright © 2021-2025 Boris Kostadinov <kostadinov.boris@gmail.com>
+ * Copyright © 2021-2026 Boris Kostadinov <kostadinov.boris@gmail.com>
  * This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
  * This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
  * You should have received a copy of the GNU General Public License along with this program. If not, see <https://www.gnu.org/licenses/>.
@@ -15,11 +15,6 @@ const exceptions = require( "#exceptions" );
 const cache = require( "#cache" );
 const messageDispatcher = require( "#message-dispatcher" );
 
-/**
- * @typedef {Object} ServiceConfiguration
- * @property {ServiceDefinition[]} [services] A list of service definitions to be registered with the {@link ServiceProvider}.
- */
-
 /**
  * Abstract class used to define a Service Instance behavior.
  * <br/>
@@ -43,8 +38,8 @@ class ServiceInstance {
      * @constructor
      * @param {string} serviceDomainName The service domain name for this service instance.
      * @param {ServiceConfiguration} [serviceConfig={ services: [] }] The JSON configuration for this service.
-     * @throws {Exception.E_GEN_ABSTRACT_CLASS_INIT} If this class is instantiated directly.
-     * @throws {Exception.E_GEN_FEATURE_UNSUPPORTED} If multiple instances are started in the same process.
+     * @throws {TiException.E_GEN_ABSTRACT_CLASS_INIT} If this class is instantiated directly.
+     * @throws {TiException.E_GEN_FEATURE_UNSUPPORTED} If multiple instances are started in the same process.
      */
     constructor( serviceDomainName, serviceConfig = { services: [] } ) {
         // Ensure this abstract class cannot be instantiated:
@@ -143,7 +138,7 @@ class ServiceInstance {
      * <br/>
      * NOTE: This method will be invoked automatically.
      * <br/>
-     * NOTE: If you need to add more onStart logic you can override this method but make sure to call it in the
+     * NOTE: If you need to add more onStart logic, you can override this method but make sure to call it in the
      * overriding method using: super.onStart()
      *
      * @method

package/components/service-provider.js

@@ -1,6 +1,6 @@
 /*
  * The ti-engine is an open source, free to use—both for personal and commercial projects—framework for the creation of microservice-based solutions using node.js.
- * Copyright © 2021-2025 Boris Kostadinov <kostadinov.boris@gmail.com>
+ * Copyright © 2021-2026 Boris Kostadinov <kostadinov.boris@gmail.com>
  * This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
  * This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
  * You should have received a copy of the GNU General Public License along with this program. If not, see <https://www.gnu.org/licenses/>.
@@ -38,7 +38,7 @@ class ServiceProvider extends ServiceConsumer {
      * @constructor
      * @param {string} serviceDomainName The service domain name for this service instance.
      * @param {ServiceConfiguration} [serviceConfig] The JSON configuration for this service.
-     * @throws {Exception.E_GEN_ABSTRACT_CLASS_INIT} If this class is instantiated directly.
+     * @throws {TiException.E_GEN_ABSTRACT_CLASS_INIT} If this class is instantiated directly.
      */
     constructor( serviceDomainName, serviceConfig ) {
         super( serviceDomainName, serviceConfig );
@@ -56,7 +56,7 @@ class ServiceProvider extends ServiceConsumer {
      * <br/>
      * NOTE: This method will be invoked automatically.
      * <br/>
-     * NOTE: If you need to add more onStart logic you can override this method but make sure to call it in the
+     * NOTE: If you need to add more onStart logic, you can override this method but make sure to call it in the
      * overriding method using: super.onStart()
      *
      * @method
@@ -88,7 +88,7 @@ class ServiceProvider extends ServiceConsumer {
      * <br/>
      * NOTE: This method will be invoked automatically.
      * <br/>
-     * NOTE: If you need to add more onStop logic you can override this method but make sure to call it in the
+     * NOTE: If you need to add more onStop logic, you can override this method but make sure to call it in the
      * overriding method using: super.onStop()
      *
      * @method
@@ -110,7 +110,7 @@ class ServiceProvider extends ServiceConsumer {
      * Used to report health status of the service instance for external monitoring.
      * This is a scheduled job that will be executed at SERVICE_HEALTH_CHECK_INTERVAL time.
      * <br/>
-     * NOTE: By default this method will update a Redis key with an expiration timer. You can override this
+     * NOTE: By default, this method will update a Redis key with an expiration timer. You can override this
      * functionality with something custom like calling an HTTP endpoint.
      *
      * @method
@@ -204,13 +204,14 @@ class ServiceProvider extends ServiceConsumer {
                 let promises = [];
                 _.forEach( serviceDefinitions, ( serviceDefinition ) => {
                     // NOTE: we are not going to interrupt the service interface loading if one of the services fails to load or is not found!
-                    // If this happens, a corresponding log entry will be created but the loading process will continue. Therefore, the following
-                    // promise will always resolve (unless a programming error occurs in it, of course).
+                    // If this happens, a corresponding log entry will be created, but the loading process will continue. Therefore, the following
+                    // promise will always be resolved (unless a programming error occurs in it, of course).
                     let registrationPromise = ( serviceDefinition, defaultServiceHandler ) => {
                         return new Promise( ( resolve ) => {
                             this.registerService( serviceDefinition, defaultServiceHandler ).then( () => {
                                 resolve( true );
-                            } ).catch( () => {
+                            } ).catch( ( error ) => {
+                                logger.log( `Service registration failed for '${ serviceDefinition?.serviceAlias || "unknown-service" }'.`, logger.logSeverity.ERROR, error );
                                 resolve( false );
                             } );
                         } );

package/integrations/redis-integration.js

@@ -1,6 +1,6 @@
 /*
  * The ti-engine is an open source, free to use—both for personal and commercial projects—framework for the creation of microservice-based solutions using node.js.
- * Copyright © 2021-2025 Boris Kostadinov <kostadinov.boris@gmail.com>
+ * Copyright © 2021-2026 Boris Kostadinov <kostadinov.boris@gmail.com>
  * This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
  * This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
  * You should have received a copy of the GNU General Public License along with this program. If not, see <https://www.gnu.org/licenses/>.
@@ -18,6 +18,7 @@ const _ = require( "lodash" );
  *
  * @readonly
  * @enum {string}
+ * @typedef {string} TiRedisCommand
  */
 let cacheCommandsEnum = tools.enum( {
     ADD_TO_SET: [ "sadd", "add to set", "https://redis.io/docs/latest/commands/sadd/" ],
@@ -34,6 +35,8 @@ let cacheCommandsEnum = tools.enum( {
     IS_SET_MEMBER: [ "sismember", "", "https://redis.io/docs/latest/commands/sismember/" ],
     JSON_ARRAY_APPEND: [ "json.arrappend", "", "https://redis.io/docs/latest/commands/json.arrappend/" ],
     JSON_GET: [ "json.get", "", "https://redis.io/docs/latest/commands/json.get/" ],
+    JSON_MERGE: [ "json.merge", "", "https://redis.io/docs/latest/commands/json.merge/" ],
+    JSON_MGET: [ "json.mget", "", "https://redis.io/docs/latest/commands/json.mget/" ],
     JSON_SET: [ "json.set", "", "https://redis.io/docs/latest/commands/json.set/" ],
     KEYS: [ "keys", "(warning: O(N), use SCAN where possible)", "https://redis.io/docs/latest/commands/keys/" ],
     LIST_PUSH: [ "lpush", "list push", "https://redis.io/docs/latest/commands/lpush/" ],
@@ -43,12 +46,14 @@ let cacheCommandsEnum = tools.enum( {
     SET_VALUE: [ "set", "set value", "https://redis.io/docs/latest/commands/set/" ],
     UNION_OF_SETS: [ "sunion", "union of sets", "https://redis.io/docs/latest/commands/sunion/" ]
 } );
+module.exports.cacheCommands = cacheCommandsEnum;
 
 /**
  * Enum for listing all client statuses.
  *
  * @readonly
  * @enum {number}
+ * @typedef {number} TiRedisClientStatus
  */
 let clientStatusEnum = tools.enum( {
     UNINITIALIZED: [ 0, "uninitialized", "Redis client is offline and not yet initialized." ],
@@ -58,31 +63,21 @@ let clientStatusEnum = tools.enum( {
     SHUTTING_DOWN: [ 4, "shutting down", "Redis client is shutting down." ],
     DISCONNECTED: [ 5, "disconnected", "Redis client is permanently disconnected from server." ]
 } );
+module.exports.clientStatus = clientStatusEnum;
 
 /**
  * Enum for listing the Redis key override modes.
  *
  * @readonly
  * @enum {string}
+ * @typedef {string} TiRedisOverrideMode
  */
 let cacheOverrideModeEnum = tools.enum( {
     DEFAULT: [ "", "default", "Standard Redis behaviour when setting new key." ],
     NX: [ "nx", "nx", "Sets the key only if it does not already exist." ],
     XX: [ "xx", "xx", "Sets the key only if it already exists." ]
 } );
-
-/**
- * @typedef {string} TiRedisCommand
- */
-module.exports.cacheCommands = cacheCommandsEnum;
-/**
- * @typedef {string} TiRedisOverrideMode
- */
 module.exports.cacheOverrideMode = cacheOverrideModeEnum;
-/**
- * @typedef {number} TiRedisClientStatus
- */
-module.exports.clientStatus = clientStatusEnum;
 
 /**
  * Used to create a Redis Cache client.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ti-engine/core",
-  "version": "1.3.13",
+  "version": "1.6.0",
   "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.",
   "keywords": [
     "microservices",
@@ -26,6 +26,9 @@
     "./service-provider": "./components/service-provider.js",
     "./tools": "./utils/tools.js"
   },
+  "scripts": {
+    "test": "node --test"
+  },
   "imports": {
     "#auditing": "./components/auditing.js",
     "#cache": "./utils/cache.js",
@@ -35,7 +38,6 @@
     "#default-message-receiver": "./components/exchange/default/default-message-receiver.js",
     "#default-message-sender": "./components/exchange/default/default-message-sender.js",
     "#exceptions": "./utils/exceptions.js",
-    "#gcloud-integration": "./integrations/gcloud-integration.js",
     "#labels": "./bin/localization/labels.json",
     "#localization": "./utils/localization.js",
     "#logger": "./utils/logger.js",
@@ -57,15 +59,12 @@
     "#tools": "./utils/tools.js"
   },
   "dependencies": {
-    "@dotenvx/dotenvx": "^1.51.1",
-    "blake2": "^5.0.0",
-    "ioredis": "^5.8.2",
-    "lodash": "^4.17.21",
+    "@dotenvx/dotenvx": "^1.73.1",
+    "ioredis": "^5.11.1",
+    "lodash": "^4.18.1",
     "node-schedule": "^2.1.1"
   },
   "optionalDependencies": {
-    "@google-cloud/error-reporting": "^3.0.5",
-    "zeromq": "^6.5.0"
   },
   "files": [
     "bin/",
@@ -75,7 +74,7 @@
     "package.json",
     "README.md",
     "CHANGELOG.md",
-    "LICENSE"
+    "LICENSE.md"
   ],
   "repository": {
     "type": "git",
@@ -87,6 +86,6 @@
   },
   "homepage": "https://github.com/Belleal/ti-engine/tree/master/packages/core#readme",
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=20.0.0"
   }
-}
+}

package/utils/cache.js

@@ -1,6 +1,6 @@
 /*
  * The ti-engine is an open source, free to use—both for personal and commercial projects—framework for the creation of microservice-based solutions using node.js.
- * Copyright © 2021-2025 Boris Kostadinov <kostadinov.boris@gmail.com>
+ * Copyright © 2021-2026 Boris Kostadinov <kostadinov.boris@gmail.com>
  * This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
  * This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
  * You should have received a copy of the GNU General Public License along with this program. If not, see <https://www.gnu.org/licenses/>.
@@ -129,7 +129,7 @@ class CommonMemoryCache extends ConnectionObserver {
      *
      * @method
      * @param {string} identifier The identifier of the observed connection.
-     * @throws {Exception.E_GEN_SYSTEM_CACHE_UNAVAILABLE} If the cache service is no longer available.
+     * @throws {TiException.E_GEN_SYSTEM_CACHE_UNAVAILABLE} If the cache service is no longer available.
      * @override
      * @public
      */
@@ -341,12 +341,7 @@ class CommonMemoryCache extends ConnectionObserver {
     expireValue( key, seconds, name ) {
         return new Promise( ( resolve, reject ) => {
             if ( this.#isOperational === true ) {
-                let commandExpire = [];
-                if ( name ) {
-                    commandExpire = [ redis.cacheCommands.HASH_EXPIRE, name, seconds, "FIELDS", 1, key ];
-                } else {
-                    commandExpire = [ redis.cacheCommands.EXPIRE, key, seconds ];
-                }
+                let commandExpire = ( name ) ? [ redis.cacheCommands.HASH_EXPIRE, name, seconds, "FIELDS", 1, key ] : [ redis.cacheCommands.EXPIRE, key, seconds ];
                 this.#redisClient.executeCommands( [ commandExpire ] ).then( () => {
                     resolve( seconds );
                 } ).catch( ( error ) => {
@@ -632,7 +627,7 @@ class CommonMemoryCache extends ConnectionObserver {
      * @method
      * @param {string} key
      * @param {Object} value
-     * @param {string} [path='&']
+     * @param {string|string[]} [path="$"] A dot-separated JSONPath string, or an array of literal key segments (use the array form when key names may contain dots or other special characters).
      * @param {number} [overrideMode=0] By default this allows full override for existing keys.
      * Option 1 will set the key only if it doesn't already exist. Option 2 will set it only if it already exists.
      * @returns {Promise}
@@ -642,7 +637,7 @@ class CommonMemoryCache extends ConnectionObserver {
         return new Promise( ( resolve, reject ) => {
             if ( this.#isOperational === true ) {
                 if ( this.#redisClient.isJSONSupported ) {
-                    let commandArguments = [ redis.cacheCommands.JSON_SET, key, path, tools.stringifyJSON( value ) ];
+                    let commandArguments = [ redis.cacheCommands.JSON_SET, key, this.#normalizeJSONPath( path ), tools.stringifyJSON( value ) ];
                     if ( overrideMode !== 0 ) {
                         commandArguments.push( overrideMode === 1 ? redis.cacheOverrideMode.NX : redis.cacheOverrideMode.XX );
                     }
@@ -652,7 +647,7 @@ class CommonMemoryCache extends ConnectionObserver {
                         reject( error );
                     } );
                 } else {
-                    reject( exceptions.raise( exceptions.exceptionCode.E_GEN_FEATURE_UNSUPPORTED ), { details: "No RedisJSON module installed on server." } );
+                    reject( exceptions.raise( exceptions.exceptionCode.E_GEN_FEATURE_UNSUPPORTED, { details: "No RedisJSON module installed on server." } ) );
                 }
             } else {
                 reject( exceptions.raise( exceptions.exceptionCode.E_GEN_SYSTEM_CACHE_UNAVAILABLE ) );
@@ -667,7 +662,7 @@ class CommonMemoryCache extends ConnectionObserver {
      *
      * @method
      * @param {string} key
-     * @param {string} path
+     * @param {string|string[]} [path="$"] A dot-separated JSONPath string, or an array of literal key segments (use the array form when key names may contain dots or other special characters).
      * @returns {Promise<Object>}
      * @public
      */
@@ -675,14 +670,45 @@ class CommonMemoryCache extends ConnectionObserver {
         return new Promise( ( resolve, reject ) => {
             if ( this.#isOperational === true ) {
                 if ( this.#redisClient.isJSONSupported ) {
-                    let commandArguments = [ redis.cacheCommands.JSON_GET, key, path ];
+                    let commandArguments = [ redis.cacheCommands.JSON_GET, key, this.#normalizeJSONPath( path ) ];
                     this.#redisClient.callCommand( commandArguments ).then( ( result ) => {
-                        resolve( tools.parseJSON( result ) );
+                        resolve( result != null ? tools.parseJSON( String( result ) ) : null );
+                    } ).catch( ( error ) => {
+                        reject( error );
+                    } );
+                } else {
+                    reject( exceptions.raise( exceptions.exceptionCode.E_GEN_FEATURE_UNSUPPORTED, { details: "No RedisJSON module installed on server." } ) );
+                }
+            } else {
+                reject( exceptions.raise( exceptions.exceptionCode.E_GEN_SYSTEM_CACHE_UNAVAILABLE ) );
+            }
+        } );
+    }
+
+    /**
+     * Used to update/edit an existing JSON variable.
+     * <br/>
+     * NOTE: Requires ReJSON module installed on server to work.
+     *
+     * @method
+     * @param {string} key
+     * @param {Object} value
+     * @param {string|string[]} [path="$"] A dot-separated JSONPath string, or an array of literal key segments (use the array form when key names may contain dots or other special characters).
+     * @returns {Promise}
+     * @public
+     */
+    editJSON( key, value, path = "$" ) {
+        return new Promise( ( resolve, reject ) => {
+            if ( this.#isOperational === true ) {
+                if ( this.#redisClient.isJSONSupported ) {
+                    let commandArguments = [ redis.cacheCommands.JSON_MERGE, key, this.#normalizeJSONPath( path ), tools.stringifyJSON( value ) ];
+                    this.#redisClient.callCommand( commandArguments ).then( () => {
+                        resolve();
                     } ).catch( ( error ) => {
                         reject( error );
                     } );
                 } else {
-                    reject( exceptions.raise( exceptions.exceptionCode.E_GEN_FEATURE_UNSUPPORTED ), { details: "No RedisJSON module installed on server." } );
+                    reject( exceptions.raise( exceptions.exceptionCode.E_GEN_FEATURE_UNSUPPORTED, { details: "No RedisJSON module installed on server." } ) );
                 }
             } else {
                 reject( exceptions.raise( exceptions.exceptionCode.E_GEN_SYSTEM_CACHE_UNAVAILABLE ) );
@@ -698,7 +724,7 @@ class CommonMemoryCache extends ConnectionObserver {
      * @method
      * @param {string} key
      * @param {Object} value
-     * @param {string} path
+     * @param {string|string[]} [path="$"] A dot-separated JSONPath string, or an array of literal key segments (use the array form when key names may contain dots or other special characters).
      * @returns {Promise}
      * @public
      */
@@ -706,14 +732,14 @@ class CommonMemoryCache extends ConnectionObserver {
         return new Promise( ( resolve, reject ) => {
             if ( this.#isOperational === true ) {
                 if ( this.#redisClient.isJSONSupported ) {
-                    let commandArguments = [ redis.cacheCommands.JSON_ARRAY_APPEND, key, path, tools.stringifyJSON( value ) ];
+                    let commandArguments = [ redis.cacheCommands.JSON_ARRAY_APPEND, key, this.#normalizeJSONPath( path ), tools.stringifyJSON( value ) ];
                     this.#redisClient.callCommand( commandArguments ).then( () => {
                         resolve();
                     } ).catch( ( error ) => {
                         reject( error );
                     } );
                 } else {
-                    reject( exceptions.raise( exceptions.exceptionCode.E_GEN_FEATURE_UNSUPPORTED ), { details: "No RedisJSON module installed on server." } );
+                    reject( exceptions.raise( exceptions.exceptionCode.E_GEN_FEATURE_UNSUPPORTED, { details: "No RedisJSON module installed on server." } ) );
                 }
             } else {
                 reject( exceptions.raise( exceptions.exceptionCode.E_GEN_SYSTEM_CACHE_UNAVAILABLE ) );
@@ -721,6 +747,26 @@ class CommonMemoryCache extends ConnectionObserver {
         } );
     }
 
+    /* Private interface */
+
+    /**
+     * Used to normalize a JSON path.
+     * <br/>
+     * NOTE: If "path" is an array, each element is treated as a literal key name and encoded with bracket notation,
+     * which correctly handles key names that contain dots or other JSONPath special characters.
+     *
+     * @method
+     * @param {string|string[]} path
+     * @returns {string}
+     * @private
+     */
+    #normalizeJSONPath( path ) {
+        if ( Array.isArray( path ) ) {
+            return "$" + path.map( ( segment ) => `["${ String( segment ).replace( /\\/g, "\\\\" ).replace( /"/g, '\\"' ) }"]` ).join( "" );
+        }
+        return ( path.startsWith( "$" ) === false ) ? ( "$." + path ) : path;
+    }
+
 }
 
 const instance = new CommonMemoryCache();