@ti-engine/core 1.12.3 → 1.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ti-engine/core",
-  "version": "1.12.3",
+  "version": "1.13.0",
   "description": "Microservice framework for Node.js: a Redis-backed message exchange with end-to-end call tracing, retries and tamper-evident message envelopes.",
   "keywords": [
     "microservices",
@@ -68,6 +68,14 @@
       "types": "./types/utils/cache.d.ts",
       "default": "./utils/cache.js"
     },
+    "#cache-capability": {
+      "types": "./types/components/cache/cache-capability.d.ts",
+      "default": "./components/cache/cache-capability.js"
+    },
+    "#cache-provider": {
+      "types": "./types/components/cache/cache-provider.d.ts",
+      "default": "./components/cache/cache-provider.js"
+    },
     "#config": {
       "types": "./types/utils/config.d.ts",
       "default": "./utils/config.js"
@@ -137,6 +145,10 @@
       "types": "./types/components/exchange/message-tracer.d.ts",
       "default": "./components/exchange/message-tracer.js"
     },
+    "#redis-cache-provider": {
+      "types": "./types/components/cache/redis-cache-provider.d.ts",
+      "default": "./components/cache/redis-cache-provider.js"
+    },
     "#redis-integration": {
       "types": "./types/integrations/redis-integration.d.ts",
       "default": "./integrations/redis-integration.js"

package/types/components/cache/cache-capability.d.ts

@@ -0,0 +1,23 @@
+export { cacheCapabilityEnum as cacheCapability };
+export type TiCacheCapability = string;
+/**
+ * Enum for listing the optional behaviors a cache backend may or may not provide.
+ * <br/>
+ * NOTE: A backend declares what it supports through {@link CacheProvider#capabilities}; an application declares what it
+ * requires through the 'memoryCache.requiredCapabilities' setting. The two are reconciled once, during startup, so that
+ * a backend which cannot do what the application needs fails where somebody is watching rather than inside a request
+ * weeks later.
+ *
+ * @readonly
+ * @enum {string}
+ * @typedef {string} TiCacheCapability
+ */
+declare const cacheCapabilityEnum: import("../definitions.types").TiEnumOf<{
+    KEY_EXPIRY: string[];
+    KEY_PATTERN_MATCH: string[];
+    LISTS: string[];
+    SETS: string[];
+    HASH_FIELDS: string[];
+    JSON_DOCUMENTS: string[];
+    ATOMIC_JSON_EDIT: string[];
+}>;

package/types/components/cache/cache-provider.d.ts

@@ -0,0 +1,326 @@
+export = CacheProvider;
+import type ConnectionObserver from "#connection-observer";
+/** @import ConnectionObserver from "#connection-observer" */
+/**
+ * An abstract class that defines the storage behavior required by the {@link CommonMemoryCache}.
+ * <br/>
+ * NOTE: This sets the contract between the cache and whatever actually holds the values. It has to be inherited and
+ * implemented with the specifics of a given backend. For a working example please see the {@link RedisCacheProvider} class.
+ * <br/>
+ * NOTE: Implementations must NOT check whether the cache is operational. {@link CommonMemoryCache} performs that check
+ * once, before it delegates, so every backend inherits the same guard instead of restating it in each of its methods.
+ *
+ * @class CacheProvider
+ * @abstract
+ * @public
+ */
+declare class CacheProvider {
+    /**
+     * @constructor
+     * @throws {TiException.E_GEN_ABSTRACT_CLASS_INIT} If this class is instantiated directly.
+     */
+    constructor();
+    /**
+     * Property returning the optional behaviors this backend provides.
+     * <br/>
+     * NOTE: Some capabilities can only be established once a connection exists — RedisJSON, for example, is a server-side
+     * module that has to be probed. Read this after {@link CacheProvider#initialize} has resolved, never before.
+     *
+     * @property
+     * @returns {string[]} Values drawn from {@link TiCacheCapability}.
+     * @abstract
+     * @public
+     */
+    get capabilities(): string[];
+    /**
+     * Used to verify whether this backend provides a given capability.
+     *
+     * @method
+     * @param {string} capability A value from {@link TiCacheCapability}.
+     * @returns {boolean}
+     * @public
+     */
+    hasCapability(capability: string): boolean;
+    /**
+     * Used to initialize the backend and establish whatever connection it requires.
+     *
+     * @method
+     * @returns {Promise}
+     * @abstract
+     * @public
+     */
+    initialize(): Promise<any>;
+    /**
+     * Used to gracefully shut the backend down.
+     *
+     * @method
+     * @returns {Promise}
+     * @abstract
+     * @public
+     */
+    shutDown(): Promise<any>;
+    /**
+     * Used to register a new {@link ConnectionObserver} for events related to the backend connection state.
+     *
+     * @method
+     * @param {ConnectionObserver} connectionObserver The {@link ConnectionObserver} that will be notified of any changes.
+     * @abstract
+     * @public
+     */
+    addConnectionObserver(connectionObserver: ConnectionObserver): void;
+    /**
+     * Used to search for keys by a given pattern.
+     *
+     * @method
+     * @param {string} pattern
+     * @returns {Promise<Array>}
+     * @requires {TiCacheCapability.KEY_PATTERN_MATCH}
+     * @abstract
+     * @public
+     */
+    matchKeys(pattern: string): Promise<any[]>;
+    /**
+     * Used to set a specific string value.
+     *
+     * @method
+     * @param {string} key
+     * @param {string} value
+     * @param {number} [expiration] Expiration value is in seconds.
+     * @returns {Promise<string>}
+     * @abstract
+     * @public
+     */
+    setValue(key: string, value: string, expiration?: number): Promise<string>;
+    /**
+     * Used to set multiple string values.
+     *
+     * @method
+     * @param {Object} keyValues
+     * @param {string} [prefix]
+     * @param {number} [expiration] Expiration value is in seconds.
+     * @returns {Promise}
+     * @abstract
+     * @public
+     */
+    setValues(keyValues: Object, prefix?: string, expiration?: number): Promise<any>;
+    /**
+     * Used to get a string value.
+     *
+     * @method
+     * @param {string} key
+     * @returns {Promise}
+     * @abstract
+     * @public
+     */
+    getValue(key: string): Promise<any>;
+    /**
+     * Used to get multiple string values.
+     *
+     * @method
+     * @param {string[]} keys
+     * @param {string} [prefix]
+     * @returns {Promise}
+     * @abstract
+     * @public
+     */
+    getValues(keys: string[], prefix?: string): Promise<any>;
+    /**
+     * Used to delete a value / item.
+     *
+     * @method
+     * @param {string} key
+     * @returns {Promise<boolean>}
+     * @abstract
+     * @public
+     */
+    deleteValue(key: string): Promise<boolean>;
+    /**
+     * Used to set expiration in seconds to an existing key.
+     *
+     * @method
+     * @param {string} key
+     * @param {number} seconds
+     * @param {string} [name] If a field in a hash set is to be expired instead, the name of that set.
+     * @returns {Promise<number>}
+     * @requires {TiCacheCapability.KEY_EXPIRY}
+     * @abstract
+     * @public
+     */
+    expireValue(key: string, seconds: number, name?: string): Promise<number>;
+    /**
+     * Used to add the specified values to a list.
+     *
+     * @method
+     * @param {string} listName
+     * @param {Object[]} values
+     * @returns {Promise<number>}
+     * @requires {TiCacheCapability.LISTS}
+     * @abstract
+     * @public
+     */
+    listPushValue(listName: string, values: Object[]): Promise<number>;
+    /**
+     * Used to add the specified value to a set.
+     *
+     * @method
+     * @param {string} key
+     * @param {string|Object} value
+     * @returns {Promise}
+     * @requires {TiCacheCapability.SETS}
+     * @abstract
+     * @public
+     */
+    addToSet(key: string, value: string | Object): Promise<any>;
+    /**
+     * Used to add multiple values to multiple sets in one transactional request.
+     *
+     * @method
+     * @param {string[]} keys
+     * @param {string[]} values
+     * @returns {Promise}
+     * @requires {TiCacheCapability.SETS}
+     * @abstract
+     * @public
+     */
+    addToSetMulti(keys: string[], values: string[]): Promise<any>;
+    /**
+     * Used to verify whether a value is a member of a set.
+     *
+     * @method
+     * @param {string} setName
+     * @param {string|Object} value
+     * @returns {Promise<boolean>}
+     * @requires {TiCacheCapability.SETS}
+     * @abstract
+     * @public
+     */
+    isSetMember(setName: string, value: string | Object): Promise<boolean>;
+    /**
+     * Used to fetch all members of a set.
+     *
+     * @method
+     * @param {string} key
+     * @returns {Promise<Array>}
+     * @requires {TiCacheCapability.SETS}
+     * @abstract
+     * @public
+     */
+    membersOfSet(key: string): Promise<any[]>;
+    /**
+     * Used to fetch the union of the provided sets.
+     *
+     * @method
+     * @param {string[]} keys
+     * @returns {Promise<Array>}
+     * @requires {TiCacheCapability.SETS}
+     * @abstract
+     * @public
+     */
+    unionOfSets(keys: string[]): Promise<any[]>;
+    /**
+     * Used to set a single field in a hash set.
+     *
+     * @method
+     * @param {string} key
+     * @param {string} name
+     * @param {string|Object} value
+     * @returns {Promise}
+     * @requires {TiCacheCapability.HASH_FIELDS}
+     * @abstract
+     * @public
+     */
+    hashSetField(key: string, name: string, value: string | Object): Promise<any>;
+    /**
+     * Used to set multiple fields in a hash set.
+     *
+     * @method
+     * @param {string} key
+     * @param {Object} fields
+     * @returns {Promise}
+     * @requires {TiCacheCapability.HASH_FIELDS}
+     * @abstract
+     * @public
+     */
+    hashSetFields(key: string, fields: Object): Promise<any>;
+    /**
+     * Used to fetch a single field from a hash set.
+     *
+     * @method
+     * @param {string} key
+     * @param {string} field
+     * @returns {Promise}
+     * @requires {TiCacheCapability.HASH_FIELDS}
+     * @abstract
+     * @public
+     */
+    hashGetField(key: string, field: string): Promise<any>;
+    /**
+     * Used to delete a single field from a hash set.
+     *
+     * @method
+     * @param {string} key
+     * @param {string} field
+     * @returns {Promise}
+     * @requires {TiCacheCapability.HASH_FIELDS}
+     * @abstract
+     * @public
+     */
+    hashDeleteField(key: string, field: string): Promise<any>;
+    /**
+     * Used to store a JSON document, or a branch of one.
+     *
+     * @method
+     * @param {string} key
+     * @param {Object} value
+     * @param {string|string[]} [path="$"] A dot-separated JSONPath string, or an array of literal key segments.
+     * @param {number} [overrideMode=0] 0 allows full override; 1 sets only if absent; 2 sets only if present.
+     * @returns {Promise}
+     * @requires {TiCacheCapability.JSON_DOCUMENTS}
+     * @abstract
+     * @public
+     */
+    setJSON(key: string, value: Object, path?: string | string[], overrideMode?: number): Promise<any>;
+    /**
+     * Used to fetch a JSON document, or a branch of one.
+     *
+     * @method
+     * @param {string} key
+     * @param {string|string[]} [path="$"] A dot-separated JSONPath string, or an array of literal key segments.
+     * @returns {Promise<Object>}
+     * @requires {TiCacheCapability.JSON_DOCUMENTS}
+     * @abstract
+     * @public
+     */
+    getJSON(key: string, path?: string | string[]): Promise<Object>;
+    /**
+     * Used to merge a value into an existing JSON document at the given path.
+     * <br/>
+     * NOTE: Callers rely on this being applied atomically by the backend when {@link TiCacheCapability.ATOMIC_JSON_EDIT}
+     * is declared — two concurrent edits to different paths of the same document must both survive. A backend that can
+     * only read-modify-write must NOT declare that capability, because the loss is silent: nothing throws, and one of
+     * the two writes is simply gone.
+     *
+     * @method
+     * @param {string} key
+     * @param {Object} value
+     * @param {string|string[]} [path="$"] A dot-separated JSONPath string, or an array of literal key segments.
+     * @returns {Promise}
+     * @requires {TiCacheCapability.JSON_DOCUMENTS}
+     * @abstract
+     * @public
+     */
+    editJSON(key: string, value: Object, path?: string | string[]): Promise<any>;
+    /**
+     * Used to append a value to an array inside a JSON document.
+     *
+     * @method
+     * @param {string} key
+     * @param {Object} value
+     * @param {string|string[]} [path="$"] A dot-separated JSONPath string, or an array of literal key segments.
+     * @returns {Promise}
+     * @requires {TiCacheCapability.JSON_DOCUMENTS}
+     * @abstract
+     * @public
+     */
+    arrayAppendJSON(key: string, value: Object, path?: string | string[]): Promise<any>;
+}

package/types/components/cache/redis-cache-provider.d.ts

@@ -0,0 +1,327 @@
+export = RedisCacheProvider;
+import CacheProvider = require("#cache-provider");
+import type ConnectionObserver from "#connection-observer";
+/**
+ * A {@link CacheProvider} backed by Redis, optionally with the RedisJSON module.
+ * <br/>
+ * NOTE: This holds every Redis-specific detail in the engine's cache path — the command names, the
+ * '[ error, value ]' result shape, and the JSONPath encoding. Nothing above it should know that Redis is what is
+ * storing the values.
+ *
+ * @class RedisCacheProvider
+ * @extends CacheProvider
+ * @public
+ */
+declare class RedisCacheProvider extends CacheProvider {
+    #private;
+    /**
+     * @constructor
+     * @param {string} connectionIdentifier The identifier under which this backend's connection is observed.
+     */
+    constructor(connectionIdentifier: string);
+    /**
+     * Decodes one entry of a `multi(...).exec()` result into the value it carries.
+     * <br/>
+     * NOTE: Exposed for testing. The provider builds its own Redis client in its constructor, so `getValues` cannot be
+     * driven without a live server — this is one of the pure halves of it, and it is where the defect was.
+     *
+     * @method
+     * @param {Array} [result] One `[ error, value ]` entry.
+     * @returns {*} The parsed value, or `undefined` when there is none.
+     * @public
+     */
+    static decodeCommandValue(result?: any[]): any;
+    /**
+     * Maps a set of requested keys onto the values a `multi(...).exec()` returned for them, using `null` for a miss.
+     * <br/>
+     * NOTE: Exposed for testing, for the same reason as {@link RedisCacheProvider.decodeCommandValue}.
+     *
+     * @method
+     * @param {string[]} keys The keys that were requested, in command order.
+     * @param {Array} [rawResults] The `multi(...).exec()` result.
+     * @returns {Object} A null-prototype map of key to value, `null` where the key was absent.
+     * @public
+     */
+    static mapCommandValues(keys: string[], rawResults?: any[]): Object;
+    /**
+     * Property returning the connection identifier of this backend.
+     *
+     * @property
+     * @returns {string}
+     * @public
+     */
+    get connectionIdentifier(): string;
+    /**
+     * Property returning the optional behaviors this backend provides.
+     * <br/>
+     * NOTE: The JSON capabilities depend on the RedisJSON module being installed on the server, which is only known
+     * after the client has connected — so this is accurate from {@link RedisCacheProvider#initialize} onward and
+     * reports no JSON support before that.
+     *
+     * @property
+     * @returns {string[]}
+     * @override
+     * @public
+     */
+    get capabilities(): string[];
+    /**
+     * Used to initialize the backend and connect to the Redis server.
+     *
+     * @method
+     * @returns {Promise}
+     * @override
+     * @public
+     */
+    initialize(): Promise<any>;
+    /**
+     * Used to gracefully shut the Redis connection down.
+     *
+     * @method
+     * @returns {Promise}
+     * @override
+     * @public
+     */
+    shutDown(): Promise<any>;
+    /**
+     * Used to register a new {@link ConnectionObserver} for events related to the underlying Redis connection state.
+     *
+     * @method
+     * @param {ConnectionObserver} connectionObserver The {@link ConnectionObserver} that will be notified of any changes.
+     * @override
+     * @public
+     */
+    addConnectionObserver(connectionObserver: ConnectionObserver): void;
+    /**
+     * Used to search for keys by a given pattern.
+     *
+     * @method
+     * @param {string} pattern
+     * @returns {Promise<Array>}
+     * @public
+     */
+    matchKeys(pattern: string): Promise<any[]>;
+    /**
+     * Used to set a specific string value.
+     *
+     * @method
+     * @param {string} key
+     * @param {string} value
+     * @param {number} [expiration] Expiration value is in seconds.
+     * @return {Promise<string>}
+     * @public
+     */
+    setValue(key: string, value: string, expiration?: number): Promise<string>;
+    /**
+     * Used to set multiple string values.
+     *
+     * @method
+     * @param {Object} keyValues
+     * @param {string} [prefix]
+     * @param {number} [expiration]
+     * @return {Promise}
+     * @public
+     */
+    setValues(keyValues: Object, prefix?: string, expiration?: number): Promise<any>;
+    /**
+     * Used to get a string value.
+     *
+     * @method
+     * @param {string} key
+     * @return {Promise}
+     * @public
+     */
+    getValue(key: string): Promise<any>;
+    /**
+     * Used to get multiple string values.
+     *
+     * @method
+     * @param {string[]} keys
+     * @param {string} [prefix]
+     * @return {Promise}
+     * @public
+     */
+    getValues(keys: string[], prefix?: string): Promise<any>;
+    /**
+     * Used to delete a value / item.
+     *
+     * @method
+     * @param {string} key
+     * @returns {Promise<boolean>}
+     * @public
+     */
+    deleteValue(key: string): Promise<boolean>;
+    /**
+     * Used to set expiration in seconds to an existing key.
+     * <br/>
+     * NOTE: For performance optimization reasons, only use this only if the Redis command does not itself support the 'EX' argument.
+     *
+     * @method
+     * @param {string} key
+     * @param {number} seconds
+     * @param {string} [name] If you need to expire a field in a hash set instead, provide the name of the set here.
+     * @returns {Promise<number>} This will resolve with the seconds as provided initially by the caller.
+     * @public
+     */
+    expireValue(key: string, seconds: number, name?: string): Promise<number>;
+    /**
+     * Used to add the specified values to a list.
+     *
+     * @method
+     * @param {string} listName
+     * @param {Object[]} values
+     * @returns {Promise<number>}
+     * @public
+     */
+    listPushValue(listName: string, values: Object[]): Promise<number>;
+    /**
+     * Used to add the specified value to a set.
+     *
+     * @method
+     * @param {string} key
+     * @param {string|Object} value
+     * @returns {Promise}
+     * @public
+     */
+    addToSet(key: string, value: string | Object): Promise<any>;
+    /**
+     * Used to add multiple values to multiple sets in one transactional request.
+     * <br/>
+     * NOTE: The two arrays of keys and values must have correct index relations (i.e., first pair on keys[0] and values[0] and so on)!
+     *
+     * @method
+     * @param {string[]} keys
+     * @param {string[]} values
+     * @returns {Promise}
+     * @public
+     */
+    addToSetMulti(keys: string[], values: string[]): Promise<any>;
+    /**
+     * Used to check if the provided value is a member of the specified set.
+     *
+     * @method
+     * @param {string} setName
+     * @param {string} value
+     * @returns {Promise<boolean>}
+     * @public
+     */
+    isSetMember(setName: string, value: string): Promise<boolean>;
+    /**
+     * Used to get all elements of a set.
+     *
+     * @method
+     * @param {string} key
+     * @returns {Promise<Object[]>}
+     * @public
+     */
+    membersOfSet(key: string): Promise<Object[]>;
+    /**
+     * Used to get a union of all elements in the list of sets.
+     *
+     * @method
+     * @param {string[]} keys
+     * @returns {Promise<Object[]>}
+     * @public
+     */
+    unionOfSets(keys: string[]): Promise<Object[]>;
+    /**
+     * Used to set a single hash field.
+     *
+     * @method
+     * @deprecated
+     * @param {string} key
+     * @param {string} name
+     * @param {*} value
+     * @returns {Promise}
+     * @public
+     */
+    hashSetField(key: string, name: string, value: any): Promise<any>;
+    /**
+     * Used to set multiple hash fields.
+     *
+     * @method
+     * @deprecated
+     * @param {string} key
+     * @param {Object[]} fields
+     * @param {string} fields[].name
+     * @param {*} fields[].value
+     * @returns {Promise}
+     * @public
+     */
+    hashSetFields(key: string, fields: {
+        name: string;
+        value: any;
+    }[]): Promise<any>;
+    /**
+     * Used to get a single field from a hash.
+     *
+     * @method
+     * @param {string} key
+     * @param {string} field
+     * @return {Promise}
+     * @public
+     */
+    hashGetField(key: string, field: string): Promise<any>;
+    /**
+     * Used to remove a single field from a hash.
+     *
+     * @method
+     * @param {string} key
+     * @param {string} field
+     * @return {Promise<boolean>} Will return 'true' if the field was removed, 'false' otherwise.
+     * @public
+     */
+    hashDeleteField(key: string, field: string): Promise<boolean>;
+    /**
+     * Used to store a 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).
+     * @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}
+     * @public
+     */
+    setJSON(key: string, value: Object, path?: string | string[], overrideMode?: number): Promise<any>;
+    /**
+     * Used to fetch a JSON variable.
+     * <br/>
+     * NOTE: Requires ReJSON module installed on server to work.
+     *
+     * @method
+     * @param {string} key
+     * @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
+     */
+    getJSON(key: string, path?: string | string[]): Promise<Object>;
+    /**
+     * 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: string, value: Object, path?: string | string[]): Promise<any>;
+    /**
+     * Used to add an item to a JSON array. That array needs to exist already.
+     * <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
+     */
+    arrayAppendJSON(key: string, value: Object, path?: string | string[]): Promise<any>;
+}