@ti-engine/core 1.12.2 → 1.13.0

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>;
+}

package/types/utils/cache.d.ts

@@ -1,44 +1,32 @@
 declare const _exported: Readonly<CommonMemoryCache>;
 export { _exported as instance };
-export { decodeCommandValue };
-export { mapCommandValues };
+export declare var decodeCommandValue: typeof import("#redis-cache-provider").decodeCommandValue;
+export declare var mapCommandValues: typeof import("#redis-cache-provider").mapCommandValues;
+export { cacheCapability };
+export { findMissingCapabilities };
 import ConnectionObserver = require("#connection-observer");
+import RedisCacheProvider = require("#redis-cache-provider");
+import { cacheCapability } from "#cache-capability";
 /**
- * Decodes one entry of a `multi(...).exec()` result into the value it carries.
+ * Determines which of the required capabilities a backend does not provide.
  * <br/>
- * Each entry is an ioredis `[ error, value ]` pair, so the value sits at index 1 and is a string when the key existed.
- * Returns `undefined` for a miss, an error entry, or a malformed entry.
- * <br/>
- * This lives outside the class, and is shared by {@link CommonMemoryCache#getValue} and
- * {@link CommonMemoryCache#getValues}, because it previously existed as two near-identical inline expressions and one
- * of them drifted: `getValues` inspected its own accumulator instead of the per-key entry, so `.length` was
- * `undefined`, the comparison was always false, and **every key resolved to `null`** whatever Redis returned.
+ * NOTE: This lives outside the class, and is exported, for the same reason the Redis decoders are: the cache singleton
+ * builds its own backend in its constructor, so the reconciliation cannot be driven without a live server. This is the
+ * pure half of it, and it is the half that decides whether an instance starts.
  *
  * @method
- * @param {Array} [result] One `[ error, value ]` entry.
- * @returns {*} The parsed value, or `undefined` when there is none.
- * @private
- */
-declare function 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/>
- * Iterates the requested `keys` rather than the raw results, so a short or absent response still yields one entry per
- * requested key instead of silently omitting some — the caller's map always has the shape it asked for.
- * <br/>
- * The accumulator has no prototype on purpose: the key names come from the caller, and a cache key named `__proto__`
- * written by bracket assignment onto an ordinary `{}` would repoint the accumulator's prototype instead of creating
- * the entry. Same class as the `decycle` defect fixed in `tools.js`; see the 1.11.0 changelog entry.
- *
- * @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.
- * @private
+ * @param {string[]} [required] Capabilities the application declared it needs.
+ * @param {string[]} [available] Capabilities the backend reports it provides.
+ * @returns {string[]} The required capabilities that are absent, in the order they were required.
+ * @public
  */
-declare function mapCommandValues(keys: string[], rawResults?: any[]): Object;
+declare function findMissingCapabilities(required?: string[], available?: string[]): string[];
 /**
  * Used to create and/or return a Common Memory Cache singleton instance.
+ * <br/>
+ * NOTE: This owns the cache's operational state and the connection observation around it; where the values actually
+ * live is the {@link CacheProvider}'s business. Every method here checks that the cache is usable and then delegates,
+ * which is why no provider repeats that check.
  *
  * @class CommonMemoryCache
  * @extends ConnectionObserver
@@ -68,11 +56,31 @@ declare class CommonMemoryCache extends ConnectionObserver {
      * @public
      */
     get connectionIdentifier(): string;
+    /**
+     * Property returning the optional behaviors the configured backend provides.
+     * <br/>
+     * NOTE: Accurate only once {@link CommonMemoryCache#initialize} has resolved — some capabilities cannot be
+     * established until the backend has connected.
+     *
+     * @property
+     * @returns {string[]} Values drawn from {@link TiCacheCapability}.
+     * @public
+     */
+    get capabilities(): string[];
     /**
      * Used to initialize the cache service.
+     * <br/>
+     * NOTE: Once the backend is connected, the capabilities it reports are reconciled against the
+     * 'memoryCache.requiredCapabilities' setting, and startup fails if any of them is missing. That is deliberate: a
+     * backend silently lacking a behavior the application depends on is otherwise discovered from inside a request,
+     * long after the deployment that introduced it.
+     * <br/>
+     * NOTE: A failed reconciliation rolls the cache back to non-operational and shuts the backend down before it
+     * rejects, so a refused startup never leaves a usable cache behind.
      *
      * @method
      * @returns {Promise}
+     * @throws {TiException.E_GEN_FEATURE_UNSUPPORTED} If the backend does not provide every required capability.
      * @public
      */
     initialize(): Promise<any>;
@@ -113,7 +121,7 @@ declare class CommonMemoryCache extends ConnectionObserver {
      */
     onConnectionLost(identifier: string): void;
     /**
-     * Used to register a new {@link ConnectionObserver} for events related to the underlying Redis connection state.
+     * Used to register a new {@link ConnectionObserver} for events related to the underlying backend connection state.
      *
      * @method
      * @param {ConnectionObserver} connectionObserver The {@link ConnectionObserver} that will be notified of any changes.

package/types/utils/config.d.ts

@@ -21,6 +21,7 @@ declare const settingsEnum: import("../components/definitions.types").TiEnumOf<{
     MEMORY_CACHE_REDIS_DB: string[];
     MEMORY_CACHE_REDIS_HOST: string[];
     MEMORY_CACHE_REDIS_PORT: string[];
+    MEMORY_CACHE_REQUIRED_CAPABILITIES: string[];
     MEMORY_CACHE_RETRY_MAX_ATTEMPTS: string[];
     MEMORY_CACHE_RETRY_MAX_INTERVAL: string[];
     MEMORY_CACHE_USER: string[];