@ti-engine/core 1.12.3 → 1.13.0

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[];